lens 0.7 → 0.8

raw patch · 2 files changed

+112/−77 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

• lens.cabal +3/−3
• src/Control/Lens.hs +109/−74

@@ -1,6 +1,6 @@ name:          lens category:      Data, Lenses-version:       0.7+version:       0.8 license:       BSD3 cabal-version: >= 1.6 license-file:  LICENSE@@ -10,8 +10,8 @@ homepage:      http://github.com/ekmett/lens/ bug-reports:   http://github.com/ekmett/lens/issues copyright:     Copyright (C) 2012 Edward A. Kmett-synopsis:      Lenses and Lens Families-description:   Lenses and Lens Families+synopsis:      Families of Lenses, Folds and Traversals+description:   Families of Lenses, Folds and Traversals build-type:    Simple tested-with:   GHC == 7.4.1 extra-source-files: .travis.yml

@@ -18,7 +18,7 @@ -- can all be composed automatically with each other (and other lenses from -- other van Laarhoven lens libraries) using @(.)@ from Prelude, while -- reducing the complexity of the API.-+-- -- For a longer description and motivation of why you should care about lens families, -- see <http://comonad.com/reader/2012/mirrored-lenses/>. --@@ -79,7 +79,7 @@   -- ** Setting Values   , adjust   , set-  , (^%=), (^=), (^+=), (^-=), (^*=), (^/=), (^||=), (^&&=), (^|=), (^&=)+  , (=%=), (=~=), (=+=), (=-=), (=*=), (=/=), (=||=), (=&&=), (=|=), (=&=)    -- * Manipulating State   , access@@ -186,7 +186,7 @@ import           Data.Word (Word8)  infixl 8 ^.-infixr 4 ^%=, ^=, ^+=, ^*=, ^-=, ^/=, ^&&=, ^||=, ^&=, ^|=+infixr 4 =~=, =%=, =+=, =*=, =-=, =/=, =&&=, =||=, =&=, =|= infix  4 ~=, %=, %%=, +=, -=, *=, //=, &&=, ||=, &=, |= infixr 0 ^$ @@ -255,6 +255,8 @@ type Getter a b c d = forall z. (c -> Const z d) -> a -> Const z b  -- | Build a 'Getter'+--+-- > to f . to g = to (g . f) to :: (a -> c) -> Getter a b c d to f g a = Const (getConst (g (f a))) {-# INLINE to #-}@@ -268,9 +270,9 @@ -- -- It may be useful to think of 'view' as having these more restrictive signatures: ----- > view :: Lens a b c d -> a -> c--- > view :: Getter a b c d -> a -> c--- > view :: Monoid m => Fold a b m d -> a -> m+-- > view ::             Lens a b c d      -> a -> c+-- > view ::             Getter a b c d    -> a -> c+-- > view :: Monoid m => Fold a b m d      -> a -> m -- > view :: Monoid m => Traversal a b m d -> a -> m view :: ((c -> Const c d) -> a -> Const c b) -> a -> c view l a = getConst (l Const a)@@ -281,9 +283,9 @@ -- -- It may be useful to think of 'views' as having these more restrictive signatures: ----- > views :: Getter a b c d -> (c -> d) -> a -> d--- > views :: Lens a b c d -> (c -> d) -> a -> d--- > views :: Monoid m => Fold a b c d -> (c -> m) -> a -> m+-- > views ::             Getter a b c d    -> (c -> d) -> a -> d+-- > views ::             Lens a b c d      -> (c -> d) -> a -> d+-- > views :: Monoid m => Fold a b c d      -> (c -> m) -> a -> m -- > views :: Monoid m => Traversal a b c d -> (c -> m) -> a -> m views :: ((c -> Const m d) -> a -> Const m b) -> (c -> m) -> a -> m views l f = getConst . l (Const . f)@@ -293,6 +295,11 @@ -- all the results of a 'Fold' or 'Traversal' that points at a monoidal values. -- -- This is the same operation as 'view', only infix.+--+-- > (^$) ::             Lens a b c d      -> a -> c+-- > (^$) ::             Getter a b c d    -> a -> c+-- > (^$) :: Monoid m => Fold a b m d      -> a -> m+-- > (^$) :: Monoid m => Traversal a b m d -> a -> m (^$) :: ((c -> Const c d) -> a -> Const c b) -> a -> c l ^$ a = getConst (l Const a) {-# INLINE (^$) #-}@@ -307,6 +314,11 @@ -- -- > ghci> ((0, 1 :+ 2), 3)^._1._2.to magnitude -- > 2.23606797749979+--+-- > (^$) ::             a -> Lens a b c d      -> c+-- > (^$) ::             a -> Getter a b c d    -> c+-- > (^$) :: Monoid m => a -> Fold a b m d      -> m+-- > (^$) :: Monoid m => a -> Traversal a b m d -> m (^.) :: a -> ((c -> Const c d) -> a -> Const c b) -> c a ^. l = getConst (l Const a) {-# INLINE (^.) #-}@@ -322,8 +334,8 @@ -- -- You can't 'view' a 'Setter' in general, so the other two laws do not apply. ----- You can compose a 'Setter' with a 'Lens' or a 'Traversal' using (.) from the Prelude--- but the result is always only a 'Setter'.+-- You can compose a 'Setter' with a 'Lens' or a 'Traversal' using @(.)@ from the Prelude+-- and the result is always only a 'Setter' and nothing more. type Setter a b c d = (c -> Identity d) -> a -> Identity b  -- | This setter can be used to map over all of the values in a container.@@ -339,7 +351,6 @@ sets f g a = Identity (f (runIdentity . g) a) {-# INLINE sets #-} - -- | Modify the target of a 'Lens' or all the targets of a 'Setter' or 'Traversal' -- with a function. --@@ -370,88 +381,88 @@ -- -- This is an infix version of 'adjust' ----- > fmap f = traverse ^%= f+-- > fmap f = traverse =%= f ----- > (^%=) :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b-(^%=) :: Setter a b c d -> (c -> d) -> a -> b-l ^%= f = runIdentity . l (Identity . f)-{-# INLINE (^%=) #-}+-- > (=%=) :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b+(=%=) :: Setter a b c d -> (c -> d) -> a -> b+l =%= f = runIdentity . l (Identity . f)+{-# INLINE (=%=) #-}  -- | Replace the target of a 'Lens' or all of the targets of a 'Setter' -- or 'Traversal' with a constant value. -- -- This is an infix version of 'set' ----- > f <$ a = traverse ^= f $ a+-- > f <$ a = traverse =~= f $ a ----- > (^=) :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b-(^=) :: Setter a b c d -> d -> a -> b-l ^= v = runIdentity . l (Identity . const v)-{-# INLINE (^=) #-}+-- > (=~=) :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b+(=~=) :: Setter a b c d -> d -> a -> b+l =~= v = runIdentity . l (Identity . const v)+{-# INLINE (=~=) #-}  -- | Increment the target(s) of a numerically valued 'Lens', Setter' or 'Traversal' ----- > ghci> _1 ^+= 1 $ (1,2)+-- > ghci> _1 =+= 1 $ (1,2) -- > (2,2) ----- > (^+=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b-(^+=) :: Num c => Setter a b c c -> c -> a -> b-l ^+= n = adjust l (+ n)-{-# INLINE (^+=) #-}+-- > (=+=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b+(=+=) :: Num c => Setter a b c c -> c -> a -> b+l =+= n = adjust l (+ n)+{-# INLINE (=+=) #-}  -- | Multiply the target(s) of a numerically valued 'Lens', 'Setter' or 'Traversal' ----- > ghci> _2 ^*= 4 $ (1,2)+-- > ghci> _2 =*= 4 $ (1,2) -- > (1,8) ----- > (^*=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b-(^*=) :: Num c => Setter a b c c -> c -> a -> b-l ^*= n = adjust l (* n)-{-# INLINE (^*=) #-}+-- > (=*=) :: Num c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b+(=*=) :: Num c => Setter a b c c -> c -> a -> b+l =*= n = adjust l (* n)+{-# INLINE (=*=) #-}  -- | Decrement the target(s) of a numerically valued 'Lens', 'Setter' or 'Traversal' ----- > ghci> _1 ^-= 2 $ (1,2)+-- > ghci> _1 =-= 2 $ (1,2) -- > (-1,2) ----- > (^-=) :: ((c -> Identity c) -> a -> Identity b) -> c -> a -> b-(^-=) :: Num c => Setter a b c c -> c -> a -> b-l ^-= n = adjust l (subtract n)-{-# INLINE (^-=) #-}+-- > (=-=) :: ((c -> Identity c) -> a -> Identity b) -> c -> a -> b+(=-=) :: Num c => Setter a b c c -> c -> a -> b+l =-= n = adjust l (subtract n)+{-# INLINE (=-=) #-}  -- | Divide the target(s) of a numerically valued 'Lens', 'Setter' or 'Traversal' ----- > (^/=) :: Fractional c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b-(^/=) :: Fractional c => Setter a b c c -> c -> a -> b-l ^/= n = adjust l (/ n)+-- > (=/=) :: Fractional c => ((c -> Identity c) -> a -> Identity b) -> c -> a -> b+(=/=) :: Fractional c => Setter a b c c -> c -> a -> b+l =/= n = adjust l (/ n)  -- | Logically '||' the target(s) of a 'Bool'-valued 'Lens' or 'Setter' ----- > (^||=):: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b-(^||=):: Setter a b Bool Bool -> Bool -> a -> b-l ^||= n = adjust l (|| n)-{-# INLINE (^||=) #-}+-- > (=||=):: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b+(=||=):: Setter a b Bool Bool -> Bool -> a -> b+l =||= n = adjust l (|| n)+{-# INLINE (=||=) #-}  -- | Logically '&&' the target(s) of a 'Bool'-valued 'Lens' or 'Setter' ----- (^&&=) :: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b-(^&&=) :: Setter a b Bool Bool -> Bool -> a -> b-l ^&&= n = adjust l (&& n)-{-# INLINE (^&&=) #-}+-- (=&&=) :: ((Bool -> Identity Bool) -> a -> Identity b) -> Bool -> a -> b+(=&&=) :: Setter a b Bool Bool -> Bool -> a -> b+l =&&= n = adjust l (&& n)+{-# INLINE (=&&=) #-}  -- | Bitwise '.|.' the target(s) of a 'Bool'-valued 'Lens' or 'Setter' ----- > (^|=):: Bits c => ((c -> Identity c) -> a -> Identity b) -> Bool -> a -> b-(^|=):: Bits c => Setter a b c c -> c -> a -> b-l ^|= n = adjust l (.|. n)-{-# INLINE (^|=) #-}+-- > (=|=):: Bits c => ((c -> Identity c) -> a -> Identity b) -> Bool -> a -> b+(=|=):: Bits c => Setter a b c c -> c -> a -> b+l =|= n = adjust l (.|. n)+{-# INLINE (=|=) #-}  -- | Bitwise '.&.' the target(s) of a 'Bool'-valued 'Lens' or 'Setter' ----- > (^&=) :: Bits c => ((b -> Identity b) -> a -> Identity a) -> c -> a -> b-(^&=) :: Bits c => Setter a b c c -> c -> a -> b-l ^&= n = adjust l (.&. n)-{-# INLINE (^&=) #-}+-- > (=&=) :: Bits c => ((b -> Identity b) -> a -> Identity a) -> c -> a -> b+(=&=) :: Bits c => Setter a b c c -> c -> a -> b+l =&= n = adjust l (.&. n)+{-# INLINE (=&=) #-}  ------------------------------------------------------------------------------ -- Common Lenses@@ -463,7 +474,7 @@ -- > ghci> (1,2)^._1 -- > 1 ----- > ghci> _1 ^= "hello" $ (1,2)+-- > ghci> _1 =+= "hello" $ (1,2) -- > ("hello",2) -- -- > _1 :: Functor f => (a -> f b) -> (a,c) -> f (a,c)@@ -499,7 +510,7 @@ -- > ghci> IntMap.fromList [(1,"hello")]  ^. valueAtInt 1 -- > Just "hello" ----- > ghci> valueAtInt 2 ^= "goodbye" $ IntMap.fromList [(1,"hello")]+-- > ghci> valueAtInt 2 =+= "goodbye" $ IntMap.fromList [(1,"hello")] -- > fromList [(1,"hello"),(2,"goodbye")] -- -- > valueAtInt :: Int -> (Maybe v -> f (Maybe v)) -> IntMap v -> f (IntMap v)@@ -511,7 +522,7 @@  -- | This 'Lens' can be used to read, write or delete a member of a 'Set' ----- > ghci> contains 3 ^= False $ Set.fromList [1,2,3,4]+-- > ghci> contains 3 =+= False $ Set.fromList [1,2,3,4] -- > fromList [1,2,4] -- -- > contains :: Ord k => k -> (Bool -> f Bool) -> Set k -> f (Set k)@@ -523,7 +534,7 @@  -- | This 'Lens' can be used to read, write or delete a member of an 'IntSet' ----- > ghci> containsInt 3 ^= False $ IntSet.fromList [1,2,3,4]+-- > ghci> containsInt 3 =+= False $ IntSet.fromList [1,2,3,4] -- > fromList [1,2,4] -- -- > containsInt :: Int -> (Bool -> f Bool) -> IntSet -> f IntSet@@ -563,29 +574,53 @@ -- Access the target of a 'Lens' or 'Getter' in the current state, or access a -- summary of a 'Fold' or 'Traversal' that points to a monoidal value. --+-- > access :: MonadState a m             => Getter a b c d    -> m c+-- > access :: MonadState a m             => Lens a b c d      -> m c+-- > access :: (MonadState a m, Monoid c) => Fold a b c d      -> m c+-- > access :: (MonadState a m, Monoid c) => Traversal a b c d -> m c access :: MonadState a m => ((c -> Const c d) -> a -> Const c b) -> m c access l = gets (^. l) {-# INLINE access #-}  -- | This class allows us to use 'focus' on a number of different monad transformers. class Focus st where-  -- | Use a lens to lift an operation with simpler context into a larger context+  -- | Run a monadic action in a larger context than it was defined in, using a 'Simple' 'Lens' or 'Simple Traversal'.   --   -- This is commonly used to lift actions in a simpler state monad into a state monad with a larger state type.+  --+  -- When applied to a 'Simple 'Traversal' over multiple values, the actions for each target are executed sequentially+  -- and the results are aggregated monoidally+  -- and a monoidal summary+  -- of the result is given.+  --+  -- > focus :: Monad m => Simple Lens a b -> st b m c -> st a m c+  -- > focus :: (Monad m, Monoid c) => Simple Traversal a b -> st b m c -> st a m c   focus :: Monad m => ((b -> Focusing m c b) -> a -> Focusing m c a) -> st b m c -> st a m c +  -- | 'focus', discarding any accumulated results as you go.+  focus_ :: Monad m => ((b -> Focusing m () b) -> a -> Focusing m () a) -> st b m c -> st a m ()++skip :: a -> ()+skip _ = ()+ instance Focus Strict.StateT where-  focus l (Strict.StateT m) = Strict.StateT $ \a -> unfocusing (l (Focusing . m) a)+  focus l m = Strict.StateT $ \a -> unfocusing (l (Focusing . Strict.runStateT m) a)   {-# INLINE focus #-}+  focus_ l m = Strict.StateT $ \a -> unfocusing (l (Focusing . Strict.runStateT (liftM skip m)) a)+  {-# INLINE focus_ #-}  instance Focus Lazy.StateT where-  focus l (Lazy.StateT m) = Lazy.StateT $ \a -> unfocusing (l (Focusing . m) a)+  focus l m = Lazy.StateT $ \a -> unfocusing (l (Focusing . Lazy.runStateT m) a)   {-# INLINE focus #-}+  focus_ l m = Lazy.StateT $ \a -> unfocusing (l (Focusing . Lazy.runStateT (liftM skip m)) a)+  {-# INLINE focus_ #-}  -- | We can focus Reader environments, too! instance Focus ReaderT where-  focus l (ReaderT m) = ReaderT $ \a -> liftM undefined $  unfocusing $ l (\b -> Focusing $ (\c -> (c,b)) `liftM` m b) a+  focus l m = ReaderT $ \a -> liftM undefined $  unfocusing $ l (\b -> Focusing $ (\c -> (c,b)) `liftM` runReaderT m b) a   {-# INLINE focus #-}+  focus_ l m = ReaderT $ \a -> liftM undefined $  unfocusing $ l (\b -> Focusing $ (\_ -> ((),b)) `liftM` runReaderT m b) a+  {-# INLINE focus_ #-}  -- | Modify the target of a 'Lens' in the current state returning some extra information of @c@ or -- modify all targets of a 'Traversal' in the current state, extracting extra information of type @c@@@ -603,52 +638,52 @@ -- | Replace the target of a 'Lens' or all of the targets of a 'Setter' or 'Traversal' in our monadic -- state with a new value, irrespective of the old. (~=) :: MonadState a m => Setter a a c d -> d -> m ()-l ~= b = modify $ l ^= b+l ~= b = modify $ l =~= b {-# INLINE (~=) #-}  -- | Map over the target of a 'Lens' or all of the targets of a 'Setter' or 'Traversal in our monadic state. (%=) :: MonadState a m => Setter a a c d -> (c -> d) -> m ()-l %= f = modify $ l ^%= f+l %= f = modify $ l =%= f {-# INLINE (%=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by adding a value (+=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()-l += b = modify $ l ^+= b+l += b = modify $ l =+= b {-# INLINE (+=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by subtracting a value (-=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()-l -= b = modify $ l ^-= b+l -= b = modify $ l =-= b {-# INLINE (-=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by multiplying by value (*=) :: (MonadState a m, Num b) => Simple Setter a b -> b -> m ()-l *= b = modify $ l ^*= b+l *= b = modify $ l =*= b {-# INLINE (*=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by dividing by a value (//=) ::  (MonadState a m, Fractional b) => Simple Setter a b -> b -> m ()-l //= b = modify $ l ^/= b+l //= b = modify $ l =/= b {-# INLINE (//=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by taking their logical '&&' with a value (&&=):: MonadState a m => Simple Setter a Bool -> Bool -> m ()-l &&= b = modify $ l ^&&= b+l &&= b = modify $ l =&&= b {-# INLINE (&&=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by taking their logical '||' with a value (||=) :: MonadState a m => Simple Setter a Bool -> Bool -> m ()-l ||= b = modify $ l ^||= b+l ||= b = modify $ l =||= b {-# INLINE (||=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by computing its bitwise '.&.' with another value. (&=):: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()-l &= b = modify $ l ^&= b+l &= b = modify $ l =&= b {-# INLINE (&=) #-}  -- | Modify the target(s) of a 'Simple' 'Lens', 'Setter' or 'Traversal' by computing its bitwise '.|.' with another value. (|=) :: (MonadState a m, Bits b) => Simple Setter a b -> b -> m ()-l |= b = modify $ l ^|= b+l |= b = modify $ l =|= b {-# INLINE (|=) #-}  --------------------------