lens 1.8 → 1.9

raw patch · 4 files changed

+455/−138 lines, 4 files

Files

README.markdown +127/−9
lens.cabal +3/−3
src/Control/Lens/Setter.hs +324/−125
src/GHC/Generics/Lens.hs +1/−1

README.markdown view

@@ -3,21 +3,139 @@  [![Build Status](https://secure.travis-ci.org/ekmett/lens.png?branch=master)](http://travis-ci.org/ekmett/lens) -This package provides families of lenses, isomorphisms, folds, traversals, getters and setters.--These lenses are compatible with those from lens-family, lens-family-core and lens-family-th,-but they provide a great deal of additional flexibility in their composition.+This package provides families of [lenses](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Type.hs), [isomorphisms](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Iso.hs), [folds](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Fold.hs), [traversals](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Traversal.hs), [getters](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Getter.hs) and [setters](https://github.com/ekmett/lens/blob/master/src/Control/Lens/Setter.hs).  An overview of the derivation of setters, folds, traversals, getters and lenses can be found on the lens wiki under [Tutorial](https://github.com/ekmett/lens/wiki/Tutorial).  [![Lens Hierarchy](https://s3.amazonaws.com/creately-published/h5nyo9ne1)](https://creately.com/diagram/h5nyo9ne1/LBbRz63yg4yQsTXGLtub1bQU4%3D) -Example--------+Examples+-------- -    ghci> :m + Control.Lens Data.Text.Lens-    ghci> anyOf (traverse.text) (=='y') ["hello"^.packed, "goodbye"^.packed]-    True+You can read from lenses (or other getters) and they compose in the order an imperative programmer would expect.++```haskell+ghci> :m + Control.Lens+ghci> ("hello",("world","!!!"))^._2._1+"world"+```++You can make getters out of pure functions with `to`.+++```haskell+ghci> ("hello",("world","!!!"))^._2._1.to length+5+```++You can write to lenses and these writes can change the type of the container.++```haskell+ghci> _1 .~ "hello" $ ((),"world")+("hello","world)+```++You can let the library automatically derive lenses for fields of your data type++```haskell+import Control.Lens++data Foo a = Foo { _bar :: Int, _baz :: Int, _quux :: a }+makeLenses ''Foo+```++This will automatically generate the following lenses:++```haskell+bar, baz :: Simple Lens (Foo a) Int+quux :: Lens (Foo a) (Foo b) a b+```++You can also write to setters that target multiple parts of a structure, or their composition with other+lenses or setters.++```haskell+ghci> _1.mapped._2.mapped %~ succ $ ([(42, "hello")],"world")+([(42, "ifmmp")],"world")+```++```haskell+ghci> both *~ 2 $ (1,2)+(2,4)+```++There are combinators for manipulating the current state in a state monad as well++```haskell+fresh :: MonadState Int m => m Int+fresh = id <+= 1+```++Anything you know how to do with a `Foldable` container, you can do with a `Fold`++```haskell+ghci> :m + Data.Char Data.Text.Lens+ghci> allOf (folded.text) isLower ["hello"^.packed, "goodbye"^.packed]+True+```++You can also use this for generic programming:++```haskell+ghci> :m + GHC.Generics.Lens+ghci> anyOf every (=="world") ("hello",(),[(2::Int,"world")])+True+```++Anything you know how to do with a `Traversable` you can do with a `Traversal`.++```haskell+ghci> mapMOf (traverse._2) (\xs -> length xs <$ putStrLn xs) [(42,"hello"),(56,"world")]+"hello"+"world"+[(42,5),(56,5)]+```++Many of the lenses supplied are isomorphisms, that means you can use them directly as a lens:++```haskell+ghci> let hello = "hello"^.packed+"hello"+ghci> :t hello+hello :: Text+```++but you can also flip them around and use them as a lens the other way with `from`++```haskell+ghci> hello^.from packed.to length+5+```++You can automatically derive isomorphisms for your own newtypes with `makeIso`. e.g.++```haskell+newtype Neither a b = Neither { _nor :: Either a b } deriving (Show)+makeIso ''Neither+```++will automatically derive++```haskell+neither :: Iso (Neither a b) (Neither c d) (Either a b) (Either c d)+nor :: Iso (Either a b) (Either c d) (Neither a b) (Neither c d)+```++such that++```haskell+from neither = nor+from nor = neither+neither.nor = id+nor.neither = id+```++There is also a fully operational, but simple game of [Pong](https://github.com/ekmett/lens/blob/master/examples/Pong.hs) in the [examples/](https://github.com/ekmett/lens/blob/master/examples/) folder.  Contact Information -------------------

lens.cabal view

@@ -1,6 +1,6 @@ name:          lens category:      Data, Lenses-version:       1.8+version:       1.9 license:       BSD3 cabal-version: >= 1.8 license-file:  LICENSE@@ -33,7 +33,7 @@   .   The core of this hierarchy looks like:   .-  <<https://github.com/ekmett/lens/wiki/images/Hierarchy-1.8.png>>+  <<https://github.com/ekmett/lens/wiki/images/Hierarchy-1.9.png>>   .   You can compose any two elements of the hierarchy above using (.) from the Prelude, and you can   use any element of the hierarchy as any type it links to above it.@@ -49,7 +49,7 @@   /Minimizing Dependencies/   .   If you want to provide lenses and traversals for your own types in your own libraries, then you-  can do so without incurring a dependency on this (or any other) lens package at all. +  can do so without incurring a dependency on this (or any other) lens package at all.   .   e.g. for a data type:   .

src/Control/Lens/Setter.hs view

@@ -26,9 +26,6 @@   -- * Setters     Setter   , Settable(..)-  -- * Consuming Setters-  , Setting-  , Mutator(..)   -- * Building Setters   , sets   -- * Common Setters@@ -43,17 +40,17 @@   , (.=), (%=)   , (+=), (-=), (*=), (//=), (^=), (^^=), (**=), (||=), (&&=), (<>=), (<.=)   , (<~)-  -- * MonadWriter-  , whisper+  -- * Setter Internals+  , Setting+  , Mutator(..)+  , SimpleSetting   -- * Simplicity   , SimpleSetter-  , SimpleSetting   ) where  import Control.Applicative import Control.Applicative.Backwards import Control.Monad.State.Class        as State-import Control.Monad.Writer.Class       as Writer import Data.Functor.Compose import Data.Functor.Identity import Data.Monoid@@ -62,7 +59,6 @@ infix  4 .=, +=, *=, -=, //=, ^=, ^^=, **=, &&=, ||=, %=, <>=, <.= infixr 2 <~ - ------------------------------------------------------------------------------ -- Setters ------------------------------------------------------------------------------@@ -70,59 +66,82 @@ -- | -- The only 'Control.Lens.Type.Lens'-like law that can apply to a 'Setter' @l@ is that ----- > set l c (set l b a) = set l c a+-- @'set' l c ('set' l b a) = 'set' l c a@ -- -- You can't 'view' a 'Setter' in general, so the other two laws are irrelevant. ----- However, two functor laws apply to a 'Setter':------ 1. @'adjust' l id = id@+-- However, two 'Functor' laws apply to a 'Setter': ----- 2. @'adjust' l f . 'adjust' l g = 'adjust' l (f . g)@+-- @+-- 'adjust' l id = id+-- 'adjust' l f . 'adjust' l g = 'adjust' l (f . g)+-- @ -- -- These an be stated more directly: ----- 1. @l 'pure' = 'pure'@------ 2. @l f . 'run' . l g = l (f . 'run' . g)@+-- @+-- l 'pure' = 'pure'+-- l f . 'untainted' . l g = l (f . 'untainted' . g)+-- @ -- -- You can compose a 'Setter' with a 'Control.Lens.Type.Lens' or a 'Control.Lens.Traversal.Traversal' using ('.') from the Prelude -- and the result is always only a 'Setter' and nothing more. type Setter a b c d = forall f. Settable f => (c -> f d) -> a -> f b  -- |--- Running a Setter instantiates it to a concrete type.+-- Running a 'Setter' instantiates it to a concrete type. ----- When consuming a setter, use this type.+-- When consuming a setter directly to perform a mapping, you can use this type, but most+-- user code will not need to use this type.+--+-- By choosing 'Mutator' rather than 'Identity', we get nicer error messages. type Setting a b c d = (c -> Mutator d) -> a -> Mutator b  -- |--- > 'SimpleSetter' = 'Simple' 'Setter'+--+-- A Simple Setter is just a 'Setter' that doesn't change the types.+--+-- These are particularly common when talking about monomorphic containers. e.g.+--+-- @'sets' Data.Text.map :: 'SimpleSetter' 'Data.Text.Internal.Text' 'Char'@+--+-- @type 'SimpleSetter' = 'Control.Lens.Type.Simple' 'Setter'@ type SimpleSetter a b = Setter a a b b  -- |--- > 'SimpleSetting' m = 'Simple' 'Setting'+-- This is a useful alias for use when consuming a 'SimpleSetter'.+--+-- Most user code will never have to use this type.+--+-- @type 'SimpleSetting' m = 'Control.Lens.Type.Simple' 'Setting'@ type SimpleSetting a b = Setting a a b b  ----------------------------------------------------------------------------- -- Settables & Mutators ----------------------------------------------------------------------------- --- | Anything Settable must be isomorphic to the Identity Functor.+-- | Anything 'Settable' must be isomorphic to the 'Identity' 'Functor'. class Applicative f => Settable f where-  run :: f a -> a+  untainted :: f a -> a +-- | so you can pass our a 'Setter' into combinators from other lens libraries instance Settable Identity where-  run = runIdentity+  untainted = runIdentity+  {-# INLINE untainted #-} +-- | 'Control.Lens.Fold.backwards' instance Settable f => Settable (Backwards f) where-  run = run . forwards+  untainted = untainted . forwards+  {-# INLINE untainted #-}  instance (Settable f, Settable g) => Settable (Compose f g) where-  run = run . run . getCompose+  untainted = untainted . untainted . getCompose+  {-# INLINE untainted #-}  -- | 'Mutator' is just a renamed 'Identity' functor to give better error -- messages when someone attempts to use a getter as a setter.+--+-- Most user code will never need to see this type. newtype Mutator a = Mutator { runMutator :: a }  instance Functor Mutator where@@ -133,7 +152,8 @@   Mutator f <*> Mutator a = Mutator (f a)  instance Settable Mutator where-  run = runMutator+  untainted = runMutator+  {-# INLINE untainted #-}  ----------------------------------------------------------------------------- -- Setters@@ -141,11 +161,11 @@  -- | This setter can be used to map over all of the values in a 'Functor'. ----- @'fmap'        = 'adjust' 'mapped'@------ @'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'@------ @('<$')        = 'set' 'mapped'@+-- @+-- 'fmap' = 'adjust' 'mapped'+-- 'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'+-- ('<$') = 'set' 'mapped'+-- @ mapped :: Functor f => Setter (f a) (f b) a b mapped = sets fmap {-# INLINE mapped #-}@@ -154,19 +174,22 @@ -- -- Your supplied function @f@ is required to satisfy: ----- @f 'id' = 'id'@--- @f g '.' f h = f (g '.' h)@+-- @+-- f 'id' = 'id'+-- f g '.' f h = f (g '.' h)+-- @ -- -- Equational reasoning: ----- @'sets' . 'adjust' = 'id'@------ @'adjust' . 'sets' = 'id'@+-- @+-- 'sets' . 'adjust' = 'id'+-- 'adjust' . 'sets' = 'id'+-- @ -- -- Another way to view 'sets' is that it takes a \"semantic editor combinator\" -- and transforms it into a 'Setter'. sets :: ((c -> d) -> a -> b) -> Setter a b c d-sets f g = pure . f (run . g)+sets f g = pure . f (untainted . g) {-# INLINE sets #-}  -----------------------------------------------------------------------------@@ -176,15 +199,12 @@ -- | Modify the target of a 'Control.Lens.Type.Lens' or all the targets of a 'Setter' or 'Control.Lens.Traversal.Traversal' -- with a function. ----- @'fmap'        = 'adjust' 'mapped'@------ @'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'@------ Free Theorems:------ 1. @'sets' . 'adjust' = 'id'@------ 2. @'adjust' . 'sets' = 'id'@+-- @+-- 'fmap' = 'adjust' 'mapped'+-- 'Data.Traversable.fmapDefault' = 'adjust' 'Data.Traversable.traverse'+-- 'sets' . 'adjust' = 'id'+-- 'adjust' . 'sets' = 'id'+-- @ -- -- Another way to view 'adjust' is to say that it transformers a 'Setter' into a -- \"semantic editor combinator\".@@ -197,22 +217,20 @@ -- | Modify the target of a 'Control.Lens.Type.Lens' or all the targets of a 'Setter' or 'Control.Lens.Traversal.Traversal' -- with a function. This is an alias for adjust that is provided for consistency. ----- @'mapOf'       = 'adjust'@------ @'fmap'        = 'mapOf' 'mapped'@------ @'fmapDefault' = 'mapOf' 'traverse'@------ Free Theorems:------ 1. @'sets' . 'mapOf' = 'id'@------ 2. @'mapOf' . 'sets' = 'id'@+-- @+-- 'mapOf' = 'adjust'+-- 'fmap' = 'mapOf' 'mapped'+-- 'fmapDefault' = 'mapOf' 'traverse'+-- 'sets' . 'mapOf' = 'id'+-- 'mapOf' . 'sets' = 'id'+-- @ ----- > mapOf :: Setter a b c d      -> (c -> d) -> a -> b--- > mapOf :: Iso a b c d         -> (c -> d) -> a -> b--- > mapOf :: Lens a b c d        -> (c -> d) -> a -> b--- > mapOf :: Traversal a b c d   -> (c -> d) -> a -> b+-- @+-- mapOf :: 'Setter' a b c d      -> (c -> d) -> a -> b+-- mapOf :: 'Control.Lens.Iso.Iso' a b c d         -> (c -> d) -> a -> b+-- mapOf :: 'Control.Lens.Type.Lens' a b c d        -> (c -> d) -> a -> b+-- mapOf :: 'Control.Lens.Traversal.Traversal' a b c d   -> (c -> d) -> a -> b+-- @ mapOf :: Setting a b c d -> (c -> d) -> a -> b mapOf = adjust {-# INLINE mapOf #-}@@ -222,10 +240,22 @@ -- -- @('<$') = 'set' 'mapped'@ ----- > set :: Setter a b c d    -> d -> a -> b--- > set :: Iso a b c d       -> d -> a -> b--- > set :: Lens a b c d      -> d -> a -> b--- > set :: Traversal a b c d -> d -> a -> b+-- >>> import Control.Lens+-- >>> set _2 "hello" (1,())+-- (1,"hello")+--+-- >>> set mapped () [1,2,3,4]+-- [(),(),(),()]+--+-- Note: Attempting to 'set' a 'Fold' or 'Getter' will fail at compile time with an +-- relatively nice error message.+--+-- @+-- set :: 'Setter' a b c d    -> d -> a -> b+-- set :: 'Control.Lens.Iso.Iso' a b c d       -> d -> a -> b+-- set :: 'Control.Lens.Type.Lens' a b c d      -> d -> a -> b+-- set :: 'Control.Lens.Traversal.Traversal' a b c d -> d -> a -> b+-- @ set :: Setting a b c d -> d -> a -> b set l d = runMutator . l (\_ -> Mutator d) {-# INLINE set #-}@@ -235,18 +265,21 @@ -- -- This is an infix version of 'adjust' ----- @'fmap' f = 'mapped' '%~' f@------ @'Data.Traversable.fmapDefault' f = 'traverse' '%~' f@+-- @+-- 'fmap' f = 'mapped' '%~' f+-- 'Data.Traversable.fmapDefault' f = 'traverse' '%~' f+-- @ -- -- >>> import Control.Lens -- >>> _2 %~ length $ (1,"hello") -- (1,5) ----- > (%~) :: Setter a b c d    -> (c -> d) -> a -> b--- > (%~) :: Iso a b c d       -> (c -> d) -> a -> b--- > (%~) :: Lens a b c d      -> (c -> d) -> a -> b--- > (%~) :: Traversal a b c d -> (c -> d) -> a -> b+-- @+-- (%~) :: 'Setter' a b c d    -> (c -> d) -> a -> b+-- (%~) :: 'Control.Lens.Iso.Iso' a b c d       -> (c -> d) -> a -> b+-- (%~) :: 'Control.Lens.Type.Lens' a b c d      -> (c -> d) -> a -> b+-- (%~) :: 'Control.Lens.Traversal.Traversal' a b c d -> (c -> d) -> a -> b+-- @ (%~) :: Setting a b c d -> (c -> d) -> a -> b (%~) = adjust {-# INLINE (%~) #-}@@ -262,10 +295,12 @@ -- >>> _1 .~ "hello" $ (42,"world") -- ("hello","world") ----- > (.~) :: Setter a b c d    -> d -> a -> b--- > (.~) :: Iso a b c d       -> d -> a -> b--- > (.~) :: Lens a b c d      -> d -> a -> b--- > (.~) :: Traversal a b c d -> d -> a -> b+-- @+-- (.~) :: 'Setter' a b c d    -> d -> a -> b+-- (.~) :: 'Control.Lens.Iso.Iso' a b c d       -> d -> a -> b+-- (.~) :: 'Control.Lens.Type.Lens' a b c d      -> d -> a -> b+-- (.~) :: 'Control.Lens.Traversal.Traversal' a b c d -> d -> a -> b+-- @ (.~) :: Setting a b c d -> d -> a -> b (.~) = set {-# INLINE (.~) #-}@@ -275,6 +310,13 @@ -- This is mostly present for consistency, but may be useful for for chaining assignments -- -- If you do not need a copy of the intermediate result, then using @l .~ d@ directly is a good idea.+--+-- @+-- (<.~) :: 'Setter' a b c d    -> d -> a -> (d, b)+-- (<.~) :: 'Control.Lens.Iso.Iso' a b c d       -> d -> a -> (d, b)+-- (<.~) :: 'Control.Lens.Type.Lens' a b c d      -> d -> a -> (d, b)+-- (<.~) :: 'Control.Lens.Traversal.Traversal' a b c d -> d -> a -> (d, b)+-- @ (<.~) :: Setting a b c d -> d -> a -> (d, b) l <.~ d = \a -> (d, l .~ d $ a) {-# INLINE (<.~) #-}@@ -284,6 +326,13 @@ -- >>> import Control.Lens -- >>> _1 +~ 1 $ (1,2) -- (2,2)+--+-- @+-- (+~) :: Num c => 'Setter' a b c c -> c -> a -> b+-- (+~) :: Num c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (+~) :: Num c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (+~) :: Num c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (+~) :: Num c => Setting a b c c -> c -> a -> b l +~ n = adjust l (+ n) {-# INLINE (+~) #-}@@ -293,6 +342,13 @@ -- >>> import Control.Lens -- >>> _2 *~ 4 $ (1,2) -- (1,8)+--+-- @+-- (*~) :: 'Num' c => 'Setter' a b c c -> c -> a -> b+-- (*~) :: 'Num' c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (*~) :: 'Num' c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (*~) :: 'Num' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (*~) :: Num c => Setting a b c c -> c -> a -> b l *~ n = adjust l (* n) {-# INLINE (*~) #-}@@ -302,11 +358,28 @@ -- >>> import Control.Lens -- >>> _1 -~ 2 $ (1,2) -- (-1,2)+--+-- @+-- (-~) :: 'Num' c => 'Setter' a b c c -> c -> a -> b+-- (-~) :: 'Num' c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (-~) :: 'Num' c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (-~) :: 'Num' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (-~) :: Num c => Setting a b c c -> c -> a -> b l -~ n = adjust l (subtract n) {-# INLINE (-~) #-}  -- | Divide the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal'+-- >>> import Control.Lens+-- >>> id //~ 2 $ 1+-- 0.5+--+-- @+-- (//~) :: 'Fractional' c => 'Setter' a b c c -> c -> a -> b+-- (//~) :: 'Fractional' c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (//~) :: 'Fractional' c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (//~) :: 'Fractional' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (//~) :: Fractional c => Setting a b c c -> c -> a -> b l //~ n = adjust l (/ n) @@ -324,6 +397,14 @@ -- >>> import Control.Lens -- >>> _2 ^^~ (-1) $ (1,2) -- (1,0.5)+--+-- @+-- (^^~) :: ('Fractional' c, 'Integral' e) => 'Setter' a b c c -> e -> a -> b+-- (^^~) :: ('Fractional' c, 'Integral' e) => 'Control.Lens.Iso.Iso' a b c c -> e -> a -> b+-- (^^~) :: ('Fractional' c, 'Integral' e) => 'Control.Lens.Type.Lens' a b c c -> e -> a -> b+-- (^^~) :: ('Fractional' c, 'Integral' e) => 'Control.Lens.Traversal.Traversal' a b c c -> e -> a -> b+-- @+-- (^^~) :: (Fractional c, Integral e) => Setting a b c c -> e -> a -> b l ^^~ n = adjust l (^^ n) {-# INLINE (^^~) #-}@@ -333,23 +414,71 @@ -- >>> import Control.Lens -- >>> _2 **~ pi $ (1,3) -- (1,31.54428070019754)+--+-- @+-- (**~) :: 'Floating' c => 'Setter' a b c c -> c -> a -> b+-- (**~) :: 'Floating' c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (**~) :: 'Floating' c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (**~) :: 'Floating' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (**~) :: Floating c => Setting a b c c -> c -> a -> b l **~ n = adjust l (** n) {-# INLINE (**~) #-}  -- | Logically '||' the target(s) of a 'Bool'-valued 'Control.Lens.Type.Lens' or 'Setter'+--+-- >>> :m + Control.Lens Data.Pair.Lens+--+-- >>> both ||~ True $ (False,True)+-- (True,True)+--+-- >>> both ||~ False $ (False,True)+-- (False,True)+--+-- @+-- (||~):: 'Setter' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (||~):: 'Control.Lens.Iso.Iso' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (||~):: 'Control.Lens.Type.Lens' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (||~):: 'Control.Lens.Traversal.Traversal' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- @ (||~):: Setting a b Bool Bool -> Bool -> a -> b l ||~ n = adjust l (|| n) {-# INLINE (||~) #-}  -- | Logically '&&' the target(s) of a 'Bool'-valued 'Control.Lens.Type.Lens' or 'Setter'+--+-- >>> :m + Control.Lens Data.Pair.Lens+--+-- >>> both &&~ True $ (False, True)+-- (False,True)+--+-- >>> both &&~ False $ (False, True)+-- (False,False)+--+-- @+-- (&&~):: 'Setter' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (&&~):: 'Control.Lens.Iso.Iso' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (&&~):: 'Control.Lens.Type.Lens' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- (&&~):: 'Control.Lens.Traversal.Traversal' a b 'Bool' 'Bool' -> 'Bool' -> a -> b+-- @ (&&~) :: Setting a b Bool Bool -> Bool -> a -> b l &&~ n = adjust l (&& n) {-# INLINE (&&~) #-}  -- | Modify the target of a monoidally valued by 'mappend'ing another value.+--+-- >>> :m + Control.Lens Data.Pair.Lens+-- >>> both <>~ "!!!" $ ("hello","world")+-- ("hello!!!","world!!!")+--+-- @+-- (<>~) :: 'Monoid' c => 'Setter' a b c c -> c -> a -> b+-- (<>~) :: 'Monoid' c => 'Control.Lens.Iso.Iso' a b c c -> c -> a -> b+-- (<>~) :: 'Monoid' c => 'Control.Lens.Type.Lens' a b c c -> c -> a -> b+-- (<>~) :: 'Monoid' c => 'Control.Lens.Traversal.Traversal' a b c c -> c -> a -> b+-- @ (<>~) :: Monoid c => Setting a b c c -> c -> a -> b-l <>~ n = adjust l (mappend n)+l <>~ n = adjust l (`mappend` n) {-# INLINE (<>~) #-}  ------------------------------------------------------------------------------@@ -359,10 +488,12 @@ -- | Replace the target of a 'Control.Lens.Type.Lens' or all of the targets of a 'Setter' or 'Control.Lens.Traversal.Traversal' in our monadic -- state with a new value, irrespective of the old. ----- > (.=) :: MonadState a m => Iso a a c d             -> d -> m ()--- > (.=) :: MonadState a m => Lens a a c d            -> d -> m ()--- > (.=) :: MonadState a m => Traversal a a c d       -> d -> m ()--- > (.=) :: MonadState a m => Setter a a c d          -> d -> m ()+-- @+-- (.=) :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a a c d             -> d -> m ()+-- (.=) :: 'MonadState' a m => 'Control.Lens.Type.Lens' a a c d            -> d -> m ()+-- (.=) :: 'MonadState' a m => 'Control.Lens.Traversal.Traversal' a a c d       -> d -> m ()+-- (.=) :: 'MonadState' a m => 'Setter' a a c d          -> d -> m ()+-- @ -- -- "It puts the state in the monad or it gets the hose again." (.=) :: MonadState a m => Setting a a c d -> d -> m ()@@ -371,76 +502,155 @@  -- | Map over the target of a 'Control.Lens.Type.Lens' or all of the targets of a 'Setter' or 'Control.Lens.Traversal.Traversal' in our monadic state. ----- > (%=) :: MonadState a m => Iso a a c d             -> (c -> d) -> m ()--- > (%=) :: MonadState a m => Lens a a c d            -> (c -> d) -> m ()--- > (%=) :: MonadState a m => Traversal a a c d       -> (c -> d) -> m ()--- > (%=) :: MonadState a m => Setter a a c d          -> (c -> d) -> m ()+-- @+-- (%=) :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a a c d             -> (c -> d) -> m ()+-- (%=) :: 'MonadState' a m => 'Control.Lens.Type.Lens' a a c d            -> (c -> d) -> m ()+-- (%=) :: 'MonadState' a m => 'Control.Lens.Traversal.Traversal' a a c d       -> (c -> d) -> m ()+-- (%=) :: 'MonadState' a m => 'Setter' a a c d          -> (c -> d) -> m ()+-- @ (%=) :: MonadState a m => Setting a a c d -> (c -> d) -> m () l %= f = State.modify (l %~ f) {-# INLINE (%=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by adding a value+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by adding a value -- -- Example: ----- > fresh = do--- >   id += 1--- >   access id+-- @+-- fresh :: MonadState Int m => m Int+-- fresh = do+--   'id' '+=' 1+--   'use' 'id'+-- @+--+-- @+-- (+=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (+=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (+=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (+=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @ (+=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m () l += b = State.modify (l +~ b) {-# INLINE (+=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by subtracting a value+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by subtracting a value+--+-- @+-- (-=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (-=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (-=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (-=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @ (-=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m () l -= b = State.modify (l -~ b) {-# INLINE (-=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by multiplying by value+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by multiplying by value.+--+-- @ballSpeed '.' 'Data.Pair.Lens.both' '*=' speedMultiplier@+--+-- @+-- (*=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (*=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (*=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (*=) :: ('MonadState' a m, 'Num' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @ (*=) :: (MonadState a m, Num b) => SimpleSetting a b -> b -> m () l *= b = State.modify (l *~ b) {-# INLINE (*=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by dividing by a value-(//=) ::  (MonadState a m, Fractional b) => SimpleSetting a b -> b -> m ()+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by dividing by a value.+--+-- @+-- (//=) :: ('MonadState' a m, 'Fractional' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (//=) :: ('MonadState' a m, 'Fractional' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (//=) :: ('MonadState' a m, 'Fractional' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (//=) :: ('MonadState' a m, 'Fractional' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @+(//=) :: (MonadState a m, Fractional b) => SimpleSetting a b -> b -> m () l //= b = State.modify (l //~ b) {-# INLINE (//=) #-} --- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to a non-negative integral power-(^=) ::  (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()+-- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to a non-negative integral power.+--+-- @+-- (^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Setter' a b -> c -> m ()+-- (^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> c -> m ()+-- (^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> c -> m ()+-- (^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> c -> m ()+-- @+(^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m () l ^= c = State.modify (l ^~ c) {-# INLINE (^=) #-} --- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to an integral power-(^^=) ::  (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m ()+-- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to an integral power.+--+-- @+-- (^^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Setter' a b -> c -> m ()+-- (^^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> c -> m ()+-- (^^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> c -> m ()+-- (^^=) ::  ('MonadState' a m, 'Fractional' b, 'Integral' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> c -> m ()+-- @+(^^=) :: (MonadState a m, Fractional b, Integral c) => SimpleSetting a b -> c -> m () l ^^= c = State.modify (l ^^~ c) {-# INLINE (^^=) #-}  -- | Raise the target(s) of a numerically valued 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to an arbitrary power-(**=) ::  (MonadState a m, Floating b) => SimpleSetting a b -> b -> m ()+--+-- @+-- (**=) ::  ('MonadState' a m, 'Floating' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (**=) ::  ('MonadState' a m, 'Floating' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (**=) ::  ('MonadState' a m, 'Floating' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (**=) ::  ('MonadState' a m, 'Floating' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @+(**=) :: (MonadState a m, Floating b) => SimpleSetting a b -> b -> m () l **= b = State.modify (l **~ b) {-# INLINE (**=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by taking their logical '&&' with a value+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by taking their logical '&&' with a value+--+-- @+-- (&&=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Setter' a 'Bool' -> 'Bool' -> m ()+-- (&&=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a 'Bool' -> 'Bool' -> m ()+-- (&&=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a 'Bool' -> 'Bool' -> m ()+-- (&&=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a 'Bool' -> 'Bool' -> m ()+-- @ (&&=):: MonadState a m => SimpleSetting a Bool -> Bool -> m () l &&= b = State.modify (l &&~ b) {-# INLINE (&&=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Iso, 'Setter' or 'Control.Lens.Traversal.Traversal' by taking their logical '||' with a value+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Iso, 'Setter' or 'Control.Lens.Traversal.Traversal' by taking their logical '||' with a value+--+-- @+-- (||=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Setter' a 'Bool' -> 'Bool' -> m ()+-- (||=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a 'Bool' -> 'Bool' -> m ()+-- (||=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a 'Bool' -> 'Bool' -> m ()+-- (||=):: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a 'Bool' -> 'Bool' -> m ()+-- @ (||=) :: MonadState a m => SimpleSetting a Bool -> Bool -> m () l ||= b = State.modify (l ||~ b) {-# INLINE (||=) #-} --- | Modify the target(s) of a 'Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by 'mappend'ing a value.+-- | Modify the target(s) of a 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Setter' or 'Control.Lens.Traversal.Traversal' by 'mappend'ing a value.+--+-- @+-- (<>=) :: ('MonadState' a m, 'Monoid' b) => 'Control.Lens.Type.Simple' 'Setter' a b -> b -> m ()+-- (<>=) :: ('MonadState' a m, 'Monoid' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a b -> b -> m ()+-- (<>=) :: ('MonadState' a m, 'Monoid' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a b -> b -> m ()+-- (<>=) :: ('MonadState' a m, 'Monoid' b) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a b -> b -> m ()+-- @ (<>=) :: (MonadState a m, Monoid b) => SimpleSetting a b -> b -> m () l <>= b = State.modify (l <>~ b) {-# INLINE (<>=) #-}  -- | Run a monadic action, and set all of the targets of a 'Control.Lens.Type.Lens', 'Setter' or 'Control.Lens.Traversal.Traversal' to its result. ----- > (<~) :: MonadState a m => Iso a a c d       -> m d -> m ()--- > (<~) :: MonadState a m => Lens a a c d      -> m d -> m ()--- > (<~) :: MonadState a m => Traversal a a c d -> m d -> m ()--- > (<~) :: MonadState a m => Setter a a c d    -> m d -> m ()+-- @+-- (<~) :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a a c d       -> m d -> m ()+-- (<~) :: 'MonadState' a m => 'Control.Lens.Type.Lens' a a c d      -> m d -> m ()+-- (<~) :: 'MonadState' a m => 'Control.Lens.Traversal.Traversal' a a c d -> m d -> m ()+-- (<~) :: 'MonadState' a m => 'Setter' a a c d    -> m d -> m ()+-- @ -- -- As a reasonable mnemonic, this lets you store the result of a monadic action in a lens rather than -- in a local variable.@@ -460,31 +670,20 @@  -- | Set with pass-through ----- This is useful for chaining assignment+-- This is useful for chaining assignment without round-tripping through your monad stack. ----- > do x <- _2 <.= (an expensive expression)+-- @do x <- '_2' <.= ninety_nine_bottles_of_beer_on_the_wall@ -- -- If you do not need a copy of the intermediate result, then using @l .= d@ will avoid unused binding warnings+--+-- @+-- (<.=) :: 'MonadState' a m => 'Setter' a a c d -> d -> m d+-- (<.=) :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a a c d -> d -> m d+-- (<.=) :: 'MonadState' a m => 'Control.Lens.Type.Lens' a a c d -> d -> m d+-- (<.=) :: 'MonadState' a m => 'Control.Lens.Traversal.Traversal' a a c d -> d -> m d+-- @ (<.=) :: MonadState a m => Setting a a c d -> d -> m d l <.= d = do   l .= d   return d {-# INLINE (<.=) #-}----------------------------------------------------------------------------------- MonadWriter----------------------------------------------------------------------------------- | Tell a part of a value to a 'MonadWriter', filling in the rest from 'mempty'------ > whisper l d = tell (set l d mempty)---- > whisper :: (MonadWriter b m, Monoid a) => Iso a b c d       -> d -> m ()--- > whisper :: (MonadWriter b m, Monoid a) => Lens a b c d      -> d -> m ()--- > whisper :: (MonadWriter b m, Monoid a) => Traversal a b c d -> d -> m ()--- > whisper :: (MonadWriter b m, Monoid a) => Setter a b c d    -> d -> m ()------ > whisper :: (MonadWriter b m, Monoid a) => ((c -> Identity d) -> a -> Identity b) -> d -> m ()-whisper :: (MonadWriter b m, Monoid a) => Setting a b c d -> d -> m ()-whisper l d = tell (set l d mempty)-{-# INLINE whisper #-}

src/GHC/Generics/Lens.hs view

@@ -27,7 +27,7 @@   -- * Isomorphisms for @GHC.Generics@     generic   , generic1-  -- * 'Generic' 'Traversal'+  -- * Generic Traversal   , every   , GTraversal   ) where