diff --git a/README.markdown b/README.markdown --- a/README.markdown +++ b/README.markdown @@ -8,6 +8,10 @@ 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. +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 ------- diff --git a/examples/pong.hs b/examples/pong.hs --- a/examples/pong.hs +++ b/examples/pong.hs @@ -33,8 +33,8 @@ windowHeight = 600 ballRadius = 0.02 speedIncrease = 1.2 -losingAccuracy = 0.7 -winningAccuracy = 0.3 +losingAccuracy = 0.9 +winningAccuracy = 0.1 initialSpeed = 0.6 paddleWidth = 0.02 paddleHeight = 0.3 @@ -58,12 +58,6 @@ -- Some nice lenses to go with it makeLenses ''Pong -ahead (i, j) = i <= j - -accuracy p - | ahead (p^.score) = winningAccuracy - | otherwise = losingAccuracy - -- Renamed tuple lenses for enhanced clarity with points/vectors _x = _1 _y = _2 @@ -86,6 +80,15 @@ | n > o = bounce ( 2 *o - n) | n < -o = bounce ((-2)*o - n) | otherwise = n + +-- Difficulty function +accuracy :: Pong -> Float +accuracy p = g . f . fromIntegral $ p^.score._1 - p^.score._2 + where + -- Scaling function + f x = 0.04 * x + 0.5 + -- Clamping function + g = min losingAccuracy . max winningAccuracy -- Game update logic diff --git a/lens.cabal b/lens.cabal --- a/lens.cabal +++ b/lens.cabal @@ -1,6 +1,6 @@ name: lens category: Data, Lenses -version: 1.7.1 +version: 1.8 license: BSD3 cabal-version: >= 1.8 license-file: LICENSE @@ -12,35 +12,70 @@ copyright: Copyright (C) 2012 Edward A. Kmett synopsis: Lenses, Folds and Traversals description: + This package comes \"Batteries Included\" with many useful lenses for the types + commonly used from the Haskell Platform, and with tools for automatically + generating lenses and isomorphisms for user-supplied data types. + . The combinators in @Control.Lens@ provide a highly generic toolbox for composing - families of getters, folds, isomorphisms, traversals, setters and lenses and their indexed variants. + families of getters, folds, isomorphisms, traversals, setters and lenses and their + indexed variants. . - /Lens Families/ + More information on the care and feeding of lenses, including a tutorial and motivation + for their types can be found on the lens wiki. . - For a longer description of why you should care about lens families, and an overview of why we use 4 - parameters a, b, c, and d instead of just 2, see . + . - Sometimes you won't need the flexibility those extra parameters afford you and you can use + A small game that manages its state using lenses can be found in the example folder. . - > type Simple f a b = f a a b b + . - to describe a 'Simple' 'Setter', 'Simple' 'Traversal', 'Simple' 'Lens' or 'Simple' 'Iso'. + /Lenses, Folds and Traversals/ . - /Avoiding Dependencies/ + The core of this hierarchy looks like: . - Note: If you merely want your library to /provide/ lenses you may not - have to actually import /any/ lens library at all. For, say, a - @'Simple' 'Lens' Bar Foo@, just export a function with the signature: + <> . - > foo :: Functor f => (Foo -> f Foo) -> Bar -> f Bar + 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. . - and then you can compose it with other lenses using nothing more than @(.)@ from the Prelude. + The result is their lowest upper bound in the hierarchy (or an error f that bound doesn't exist). . - /Deriving Lenses/ + For instance: . - You can derive lenses automatically for many data types using 'makeLenses', and if a - container is fully characterized by its lenses, you can use 'Representable' to - automatically derive 'Functor', 'Applicative', 'Monad', and 'Distributive'. + * You can use any 'Traversal' as a 'Fold' or as a 'Setter'. + . + * The composition of a 'Traversal' and a 'Getter' yields a 'Fold'. + . + /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. + . + e.g. for a data type: + . + > data Foo a = Foo Int Int a + . + You can define lenses such as + . + > -- bar :: Simple Lens (Foo a) Int + > bar :: Functor f => (Int -> f Int) -> Foo a -> f Foo a + > bar f (Foo a b c) = fmap (\a' -> Foo a' b c) (f a) + . + > -- baz :: Lens (Foo a) (Foo b) a b + > quux :: Functor f => (a -> f b) -> Foo a -> f (Foo b) + > quux f (Foo a b c) = fmap (Foo a b) (f c) + . + without the need to use any type that isn't already defined in the @Prelude@. + . + And you can define a traversal of multiple fields with 'Control.Applicative.Applicative': + . + > -- traverseBarAndBaz :: Simple Traversal (Foo a) Int + > traverseBarAndBaz :: Applicative f => (Int -> f Int) -> Foo a -> f (Foo a) + > traverseBarAndBaz f (Foo a b c) = Foo <$> f a <*> f b <*> pure c + . + What is provided in this library is a number of stock lenses and traversals for + common haskell types, a wide array of combinators for working them, and more + exotic functionality, (e.g. getters, setters, indexed folds, isomorphisms). build-type: Simple tested-with: GHC == 7.4.1 @@ -132,13 +167,15 @@ ghc-options: -Wall -fwarn-tabs -O2 -fdicts-cheap -funbox-strict-fields hs-source-dirs: src --- Verify the results of the '>>>'s distributed throughout +-- Verify the results of the examples test-suite doctests type: exitcode-stdio-1.0 main-is: doctests.hs build-depends: base == 4.*, - doctest >= 0.8 && <= 0.9 + directory >= 1.0 && < 1.2, + doctest >= 0.8 && <= 0.9, + filepath >= 1.3 && < 1.4 ghc-options: -Wall -Werror -threaded hs-source-dirs: tests diff --git a/src/Control/Lens.hs b/src/Control/Lens.hs --- a/src/Control/Lens.hs +++ b/src/Control/Lens.hs @@ -12,39 +12,36 @@ -- Stability : provisional -- Portability : Rank2Types -- --- This package provides lens families, setters, getters, traversals, --- isomorphisms, and folds that 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 . --- --- Note: If you merely want your library to /provide/ lenses you may not --- have to actually import /any/ lens library. For, say, a --- @'Simple' 'Lens' Bar Foo@, just export a function with the signature: --- --- > foo :: Functor f => (Foo -> f Foo) -> Bar -> f Bar --- --- and then you can compose it with other lenses with @(.)@ without needing --- anything from this library at all. --- -- Usage: -- -- You can derive lenses automatically for many data types: -- --- > import Control.Lens --- > data Foo a = Foo { _fooArgs :: [String], _fooValue :: a } --- > makeLenses ''Foo +-- @ +-- import Control.Lens +-- data Foo a = Foo { _fooArgs :: ['String'], _fooValue :: a } +-- 'makeLenses' ''Foo +-- @ -- -- This defines the following lenses: -- --- > fooArgs :: Simple Lens (Foo a) [String] --- > fooValue :: Lens (Foo a) (Foo b) a b +-- @ +-- fooArgs :: 'Simple' 'Lens' (Foo a) ['String'] +-- fooValue :: 'Lens' (Foo a) (Foo b) a b +-- @ -- +-- You can then access the value with ('^.') and set the value of the field +-- with ('.~') and can use almost any other combinator that is re-exported here +-- on those fields. +-- -- The combinators here have unusually specific type signatures, so for --- particularly tricky ones, I've tried to list the simpler type signatures --- you might want to pretend the combinators have. +-- particularly tricky ones, the simpler type signatures you might want to +-- pretend the combinators have are specified as well. +-- +-- More information on how to use lenses is available on the lens wiki: +-- +-- +-- +-- <> ---------------------------------------------------------------------------- module Control.Lens ( module Control.Lens.Type diff --git a/src/Control/Lens/Action.hs b/src/Control/Lens/Action.hs --- a/src/Control/Lens/Action.hs +++ b/src/Control/Lens/Action.hs @@ -49,14 +49,14 @@ -- Every 'Getter' can be used as an 'Action' -- -- You can compose an 'Action' with another 'Action' using ('Prelude..') from the @Prelude@. -type Action m a c = forall f b r d. Effective m r f => (c -> f d) -> a -> f b +type Action m a c = forall f r. Effective m r f => (c -> f c) -> a -> f a -- | A 'MonadicFold' is a 'Fold' enriched with access to a 'Monad' for side-effects. -- -- Every 'Fold' can be used as a 'MonadicFold', that simply ignores the access to the 'Monad'. -- -- You can compose a 'MonadicFold' with another 'MonadicFold' using ('Prelude..') from the @Prelude@. -type MonadicFold m a c = forall f b r d. (Effective m r f, Applicative f) => (c -> f d) -> a -> f b +type MonadicFold m a c = forall f r. (Effective m r f, Applicative f) => (c -> f c) -> a -> f a -- | An 'Effective' 'Functor' ignores its argument and is isomorphic to a monad wrapped around a value. -- @@ -101,13 +101,13 @@ {-# SPECIALIZE effective :: Monad m => Isomorphism (m r) (Effect m r a) #-} -- | Used to evaluate an 'Action'. -type Acting m r a b c d = (c -> Effect m r d) -> a -> Effect m r b +type Acting m r a c = (c -> Effect m r c) -> a -> Effect m r a -- | Perform an 'Action'. -- -- > perform = flip (^!) -- -perform :: Monad m => Acting m c a b c d -> a -> m c +perform :: Monad m => Acting m c a c -> a -> m c perform l = getEffect . l (Effect . return) {-# INLINE perform #-} @@ -119,7 +119,7 @@ -- hello -- world -- -(^!) :: Monad m => a -> Acting m c a b c d -> m c +(^!) :: Monad m => a -> Acting m c a c -> m c a ^! l = getEffect (l (Effect . return) a) {-# INLINE (^!) #-} @@ -141,6 +141,6 @@ {-# INLINE acts #-} -- | Apply a 'Monad' transformer to an 'Action'. -liftAct :: (MonadTrans t, Monad m) => Acting m c a b c d -> Action (t m) a c +liftAct :: (MonadTrans t, Monad m) => Acting m c a c -> Action (t m) a c liftAct l = act (lift . perform l) {-# INLINE liftAct #-} diff --git a/src/Control/Lens/Fold.hs b/src/Control/Lens/Fold.hs --- a/src/Control/Lens/Fold.hs +++ b/src/Control/Lens/Fold.hs @@ -19,11 +19,11 @@ -- Since we want to be able to work with monomorphic containers, we could generalize this signature to -- @forall m. 'Monoid' m => (c -> m) -> a -> m@, and then decorate it with 'Accessor' to obtain -- --- @type 'Fold' a c = forall m b d. 'Monoid' m => 'Getting' m a b c d@ +-- @type 'Fold' a c = forall m. 'Monoid' m => 'Getting' m a c@ -- -- Every 'Getter' is a valid 'Fold' that simply doesn't use the 'Monoid' it is passed. -- --- But in practice the type we use is slightly more complicated to allow for better error messages +-- But in practice the type we use is slightly more complicated to allow for better error messages -- and for it to be transformed by certain 'Applicative' transformers. -- -- Everything you can do with a 'Foldable' container, you can with with a 'Fold' and there are @@ -97,7 +97,7 @@ -- -- Unlike a 'Control.Lens.Traversal.Traversal' a 'Fold' is read-only. Since a 'Fold' cannot be used to write back -- there are no lens laws that apply. -type Fold a c = forall f b d. (Gettable f, Applicative f) => (c -> f d) -> a -> f b +type Fold a c = forall f. (Gettable f, Applicative f) => (c -> f c) -> a -> f a noEffect :: (Applicative f, Gettable f) => f a noEffect = coerce $ pure () @@ -145,7 +145,7 @@ -- >>> import Control.Lens -- >>> take 6 $ toListOf (cycled traverse) [1,2,3] -- [1,2,3,1,2,3] -cycled :: (Applicative f, Gettable f) => LensLike f a b c d -> LensLike f a b c d +cycled :: (Applicative f, Gettable f) => SimpleLensLike f a c -> SimpleLensLike f a c cycled l f a = as where as = l f a *> as -- | Build a fold that unfolds its values from a seed. @@ -166,22 +166,22 @@ go a = g a *> go (f a) {-# INLINE iterated #-} --- | Obtain a 'Fold' by filtering a 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. -filtered :: (Gettable f, Applicative f) => (c -> Bool) -> LensLike f a b c d -> LensLike f a b c d +-- | Obtain a 'Fold' by filtering a 'Lens', 'Control.Lens.Iso.Iso', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. +filtered :: (Gettable f, Applicative f) => (c -> Bool) -> SimpleLensLike f a c -> SimpleLensLike f a c filtered p l f = l $ \c -> if p c then f c else noEffect {-# INLINE filtered #-} -- | This allows you to traverse the elements of a 'Control.Lens.Traversal.Traversal' or 'Fold' in the opposite order. -- --- Note: 'backwards' should have no impact on a 'Getter' 'Setter', 'Control.Lens.Type.Lens' or 'Control.Lens.Iso.Iso'. +-- Note: 'backwards' should have no impact on a 'Getter' 'Setter', 'Lens' or 'Control.Lens.Iso.Iso'. -- -- To change the direction of an 'Control.Lens.Iso.Iso', use 'from'. backwards :: LensLike (Backwards f) a b c d -> LensLike f a b c d backwards l f = forwards . l (Backwards . f) {-# INLINE backwards #-} --- | Obtain a 'Fold' by taking elements from another 'Fold', 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Getter' or 'Control.Lens.Traversal.Traversal' while a predicate holds. +-- | Obtain a 'Fold' by taking elements from another 'Fold', 'Lens', 'Control.Lens.Iso.Iso', 'Getter' or 'Control.Lens.Traversal.Traversal' while a predicate holds. -- -- @'takeWhile' p = 'toListOf' ('takingWhile' p 'folded')@ -- @@ -189,13 +189,13 @@ -- [1,2,3] takingWhile :: (Gettable f, Applicative f) => (c -> Bool) - -> Getting (Endo (f b)) a b c d - -> LensLike f a b c d + -> Getting (Endo (f a)) a c + -> SimpleLensLike f a c takingWhile p l f = foldrOf l (\a r -> if p a then f a *> r else noEffect) noEffect {-# INLINE takingWhile #-} --- | Obtain a 'Fold' by dropping elements from another 'Fold', 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', 'Getter' or 'Control.Lens.Traversal.Traversal' while a predicate holds. +-- | Obtain a 'Fold' by dropping elements from another 'Fold', 'Lens', 'Control.Lens.Iso.Iso', 'Getter' or 'Control.Lens.Traversal.Traversal' while a predicate holds. -- -- @'dropWhile' p = 'toListOf' ('droppingWhile' p 'folded')@ -- @@ -203,8 +203,8 @@ -- [4,5,6] droppingWhile :: (Gettable f, Applicative f) => (c -> Bool) - -> Getting (Endo (f b)) a b c d - -> LensLike f a b c d + -> Getting (Endo (f a)) a c + -> SimpleLensLike f a c droppingWhile p l f = foldrOf l (\a r -> if p a then r else f a *> r) noEffect {-# INLINE droppingWhile #-} @@ -217,12 +217,14 @@ -- -- @'foldMapOf' = 'views'@ -- --- > foldMapOf :: Getter a c -> (c -> r) -> a -> r --- > foldMapOf :: Monoid r => Fold a c -> (c -> r) -> a -> r --- > foldMapOf :: Lens a b c d -> (c -> r) -> a -> r --- > foldMapOf :: Iso a b c d -> (c -> r) -> a -> r --- > foldMapOf :: Monoid r => Traversal a b c d -> (c -> r) -> a -> r -foldMapOf :: Getting r a b c d -> (c -> r) -> a -> r +-- @ +-- foldMapOf :: 'Getter' a c -> (c -> r) -> a -> r +-- foldMapOf :: Monoid r => 'Fold' a c -> (c -> r) -> a -> r +-- foldMapOf :: 'Simple' 'Lens' a c -> (c -> r) -> a -> r +-- foldMapOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> r) -> a -> r +-- foldMapOf :: Monoid r => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> r) -> a -> r +-- @ +foldMapOf :: Getting r a c -> (c -> r) -> a -> r foldMapOf l f = runAccessor . l (Accessor . f) {-# INLINE foldMapOf #-} @@ -231,112 +233,130 @@ -- -- @'foldOf' = 'view'@ -- --- > foldOf :: Getter a m -> a -> m --- > foldOf :: Monoid m => Fold a m -> a -> m --- > foldOf :: Lens a b m d -> a -> m --- > foldOf :: Iso a b m d -> a -> m --- > foldOf :: Monoid m => Traversal a b m d -> a -> m -foldOf :: Getting c a b c d -> a -> c +-- @ +-- foldOf :: 'Getter' a m -> a -> m +-- foldOf :: 'Monoid' m => 'Fold' a m -> a -> m +-- foldOf :: 'Simple' 'Lens' a m -> a -> m +-- foldOf :: 'Simple' 'Control.Lens.Iso.Iso' a m -> a -> m +-- foldOf :: 'Monoid m' => 'Simple' 'Control.Lens.Traversal.Traversal' a m -> a -> m +-- @ +foldOf :: Getting c a c -> a -> c foldOf l = runAccessor . l Accessor {-# INLINE foldOf #-} -- | --- Right-associative fold of parts of a structure that are viewed through a 'Control.Lens.Type.Lens', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. +-- Right-associative fold of parts of a structure that are viewed through a 'Lens', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. -- -- @'Data.Foldable.foldr' = 'foldrOf' 'folded'@ -- --- > foldrOf :: Getter a c -> (c -> e -> e) -> e -> a -> e --- > foldrOf :: Fold a c -> (c -> e -> e) -> e -> a -> e --- > foldrOf :: Lens a b c d -> (c -> e -> e) -> e -> a -> e --- > foldrOf :: Iso a b c d -> (c -> e -> e) -> e -> a -> e --- > foldrOf :: Traversal a b c d -> (c -> e -> e) -> e -> a -> e -foldrOf :: Getting (Endo e) a b c d -> (c -> e -> e) -> e -> a -> e +-- @ +-- foldrOf :: 'Getter' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf :: 'Fold' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf :: 'Simple' 'Lens' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> e -> e) -> e -> a -> e +-- @ +foldrOf :: Getting (Endo e) a c -> (c -> e -> e) -> e -> a -> e foldrOf l f z t = appEndo (foldMapOf l (Endo . f) t) z {-# INLINE foldrOf #-} -- | --- Left-associative fold of the parts of a structure that are viewed through a 'Control.Lens.Type.Lens', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. +-- Left-associative fold of the parts of a structure that are viewed through a 'Lens', 'Getter', 'Fold' or 'Control.Lens.Traversal.Traversal'. -- -- @'Data.Foldable.foldl' = 'foldlOf' 'folded'@ -- --- > foldlOf :: Getter a c -> (e -> c -> e) -> e -> a -> e --- > foldlOf :: Fold a c -> (e -> c -> e) -> e -> a -> e --- > foldlOf :: Lens a b c d -> (e -> c -> e) -> e -> a -> e --- > foldlOf :: Iso a b c d -> (e -> c -> e) -> e -> a -> e --- > foldlOf :: Traversal a b c d -> (e -> c -> e) -> e -> a -> e -foldlOf :: Getting (Dual (Endo e)) a b c d -> (e -> c -> e) -> e -> a -> e +-- @ +-- foldlOf :: 'Getter' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf :: 'Fold' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf :: 'Simple' 'Lens' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (e -> c -> e) -> e -> a -> e +-- @ +foldlOf :: Getting (Dual (Endo e)) a c -> (e -> c -> e) -> e -> a -> e foldlOf l f z t = appEndo (getDual (foldMapOf l (Dual . Endo . flip f) t)) z {-# INLINE foldlOf #-} -- | -- @'Data.Foldable.toList' = 'toListOf' 'folded'@ -- --- > toListOf :: Getter a c -> a -> [c] --- > toListOf :: Fold a c -> a -> [c] --- > toListOf :: Lens a b c d -> a -> [c] --- > toListOf :: Iso a b c d -> a -> [c] --- > toListOf :: Traversal a b c d -> a -> [c] -toListOf :: Getting [c] a b c d -> a -> [c] +-- @ +-- toListOf :: 'Getter' a c -> a -> [c] +-- toListOf :: 'Fold' a c -> a -> [c] +-- toListOf :: 'Simple' 'Lens' a c -> a -> [c] +-- toListOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> [c] +-- toListOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> [c] +-- @ +toListOf :: Getting [c] a c -> a -> [c] toListOf l = foldMapOf l return {-# INLINE toListOf #-} -- | -- @'Data.Foldable.and' = 'andOf' 'folded'@ -- --- > andOf :: Getter a Bool -> a -> Bool --- > andOf :: Fold a Bool -> a -> Bool --- > andOf :: Lens a b Bool d -> a -> Bool --- > andOf :: Iso a b Bool d -> a -> Bool --- > andOf :: Traversl a b Bool d -> a -> Bool -andOf :: Getting All a b Bool d -> a -> Bool +-- @ +-- andOf :: 'Getter' a 'Bool' -> a -> 'Bool' +-- andOf :: 'Fold' a 'Bool' -> a -> 'Bool' +-- andOf :: 'Simple' 'Lens' a 'Bool' -> a -> 'Bool' +-- andOf :: 'Simple' 'Control.Lens.Iso.Iso' a 'Bool' -> a -> 'Bool' +-- andOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a 'Bool' -> a -> 'Bool' +-- @ +andOf :: Getting All a Bool -> a -> Bool andOf l = getAll . foldMapOf l All {-# INLINE andOf #-} -- | -- @'Data.Foldable.or' = 'orOf' 'folded'@ -- --- > orOf :: Getter a Bool -> a -> Bool --- > orOf :: Fold a Bool -> a -> Bool --- > orOf :: Lens a b Bool d -> a -> Bool --- > orOf :: Iso a b Bool d -> a -> Bool --- > orOf :: Traversal a b Bool d -> a -> Bool -orOf :: Getting Any a b Bool d -> a -> Bool +-- @ +-- orOf :: 'Getter' a 'Bool' -> a -> 'Bool' +-- orOf :: 'Fold' a 'Bool' -> a -> 'Bool' +-- orOf :: 'Simple' 'Lens' a 'Bool' -> a -> 'Bool' +-- orOf :: 'Simple' 'Control.Lens.Iso.Iso' a 'Bool' -> a -> 'Bool' +-- orOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a 'Bool' -> a -> 'Bool' +-- @ +orOf :: Getting Any a Bool -> a -> Bool orOf l = getAny . foldMapOf l Any {-# INLINE orOf #-} -- | -- @'Data.Foldable.any' = 'anyOf' 'folded'@ -- --- > anyOf :: Getter a c -> (c -> Bool) -> a -> Bool --- > anyOf :: Fold a c -> (c -> Bool) -> a -> Bool --- > anyOf :: Lens a b c d -> (c -> Bool) -> a -> Bool --- > anyOf :: Iso a b c d -> (c -> Bool) -> a -> Bool --- > anyOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool -anyOf :: Getting Any a b c d -> (c -> Bool) -> a -> Bool +-- @ +-- anyOf :: 'Getter' a c -> (c -> 'Bool') -> a -> 'Bool' +-- anyOf :: 'Fold' a c -> (c -> 'Bool') -> a -> 'Bool' +-- anyOf :: 'Simple' 'Lens' a b c d -> (c -> 'Bool') -> a -> 'Bool' +-- anyOf :: 'Simple' 'Control.Lens.Iso.Iso' a b c d -> (c -> 'Bool') -> a -> 'Bool' +-- anyOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a b c d -> (c -> 'Bool') -> a -> 'Bool' +-- @ +anyOf :: Getting Any a c -> (c -> Bool) -> a -> Bool anyOf l f = getAny . foldMapOf l (Any . f) {-# INLINE anyOf #-} -- | -- @'Data.Foldable.all' = 'allOf' 'folded'@ -- --- > allOf :: Getter a c -> (c -> Bool) -> a -> Bool --- > allOf :: Fold a c -> (c -> Bool) -> a -> Bool --- > allOf :: Lens a b c d -> (c -> Bool) -> a -> Bool --- > allOf :: Iso a b c d -> (c -> Bool) -> a -> Bool --- > allOf :: Traversal a b c d -> (c -> Bool) -> a -> Bool -allOf :: Getting All a b c d -> (c -> Bool) -> a -> Bool +-- @ +-- allOf :: 'Getter' a c -> (c -> 'Bool') -> a -> 'Bool' +-- allOf :: 'Fold' a c -> (c -> 'Bool') -> a -> 'Bool' +-- allOf :: 'Simple' 'Lens' a c -> (c -> 'Bool') -> a -> 'Bool' +-- allOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> 'Bool') -> a -> 'Bool' +-- allOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> 'Bool') -> a -> 'Bool' +-- @ +allOf :: Getting All a c -> (c -> Bool) -> a -> Bool allOf l f = getAll . foldMapOf l (All . f) {-# INLINE allOf #-} -- | -- @'Data.Foldable.product' = 'productOf' 'folded'@ -- --- > productOf :: Getter a c -> a -> c --- > productOf :: Num c => Fold a c -> a -> c --- > productOf :: Lens a b c d -> a -> c --- > productOf :: Iso a b c d -> a -> c --- > productOf :: Num c => Traversal a b c d -> a -> c -productOf :: Getting (Product c) a b c d -> a -> c +-- @ +-- productOf :: 'Getter' a c -> a -> c +-- productOf :: 'Num' c => 'Fold' a c -> a -> c +-- productOf :: 'Control.'Lens'.Type.Simple' 'Lens' a c -> a -> c +-- productOf :: 'Control.'Lens'.Type.Simple' 'Control.Lens.Iso.Iso' a c -> a -> c +-- productOf :: 'Num' c => 'Control.'Lens'.Type.Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> c +-- @ +productOf :: Getting (Product c) a c -> a -> c productOf l = getProduct . foldMapOf l Product {-# INLINE productOf #-} @@ -347,12 +367,14 @@ -- -- @'sumOf' ('folded' . '_1') :: ('Foldable' f, 'Num' a) => f (a, b) -> a@ -- --- > sumOf :: Getter a c -> a -> c --- > sumOf :: Num c => Fold a c -> a -> c --- > sumOf :: Lens a b c d -> a -> c --- > sumOf :: Iso a b c d -> a -> c --- > sumOf :: Num c => Traversal a b c d -> a -> c -sumOf :: Getting (Sum c) a b c d -> a -> c +-- @ +-- sumOf :: 'Getter' a c -> a -> c +-- sumOf :: Num c => 'Fold' a c -> a -> c +-- sumOf :: 'Simple' 'Lens' a c -> a -> c +-- sumOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> c +-- sumOf :: Num c => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> c +-- @ +sumOf :: Getting (Sum c) a c -> a -> c sumOf l = getSum . foldMapOf l Sum {-# INLINE sumOf #-} @@ -370,48 +392,52 @@ -- -- The rather specific signature of traverseOf_ allows it to be used as if the signature was either: -- --- > traverseOf_ :: Functor f => Getter a c -> (c -> f e) -> a -> f () --- > traverseOf_ :: Applicative f => Fold a c -> (c -> f e) -> a -> f () --- > traverseOf_ :: Functor f => Lens a b c d -> (c -> f e) -> a -> f () --- > traverseOf_ :: Functor f => Iso a b c d -> (c -> f e) -> a -> f () --- > traverseOf_ :: Applicative f => Traversal a b c d -> (c -> f e) -> a -> f () -traverseOf_ :: Functor f => Getting (Traversed f) a b c d -> (c -> f e) -> a -> f () +-- @ +-- traverseOf_ :: 'Functor' f => 'Getter' a c -> (c -> f e) -> a -> f () +-- traverseOf_ :: 'Applicative' f => 'Fold' a c -> (c -> f e) -> a -> f () +-- traverseOf_ :: 'Functor' f => 'Simple' 'Lens' a c -> (c -> f e) -> a -> f () +-- traverseOf_ :: 'Functor' f => 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> f e) -> a -> f () +-- traverseOf_ :: 'Applicative' f => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> f e) -> a -> f () +-- @ +traverseOf_ :: Functor f => Getting (Traversed f) a c -> (c -> f e) -> a -> f () traverseOf_ l f = getTraversed . foldMapOf l (Traversed . void . f) {-# INLINE traverseOf_ #-} -- | -- @'for_' = 'forOf_' 'folded'@ -- --- > forOf_ :: Functor f => Getter a c -> a -> (c -> f e) -> f () --- > forOf_ :: Applicative f => Fold a c -> a -> (c -> f e) -> f () --- > forOf_ :: Functor f => Lens a b c d -> a -> (c -> f e) -> f () --- > forOf_ :: Functor f => Iso a b c d -> a -> (c -> f e) -> f () --- > forOf_ :: Applicative f => Traversal a b c d -> a -> (c -> f e) -> f () -forOf_ :: Functor f => Getting (Traversed f) a b c d -> a -> (c -> f e) -> f () +-- @ +-- forOf_ :: 'Functor' f => 'Getter' a c -> a -> (c -> f e) -> f () +-- forOf_ :: 'Applicative' f => 'Fold' a c -> a -> (c -> f e) -> f () +-- forOf_ :: 'Functor' f => 'Simple' 'Lens' a c -> a -> (c -> f e) -> f () +-- forOf_ :: 'Functor' f => 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> (c -> f e) -> f () +-- forOf_ :: 'Applicative' f => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> (c -> f e) -> f () +-- @ +forOf_ :: Functor f => Getting (Traversed f) a c -> a -> (c -> f e) -> f () forOf_ = flip . traverseOf_ {-# INLINE forOf_ #-} -- | -- @'sequenceA_' = 'sequenceAOf_' 'folded'@ -- --- > sequenceAOf_ :: Functor f => Getter a (f ()) -> a -> f () --- > sequenceAOf_ :: Applicative f => Fold a (f ()) -> a -> f () --- > sequenceAOf_ :: Functor f => Lens a b (f ()) d -> a -> f () --- > sequenceAOf_ :: Functor f => Iso a b (f ()) d -> a -> f () --- > sequenceAOf_ :: Applicative f => Traversal a b (f ()) d -> a -> f () -sequenceAOf_ :: Functor f => Getting (Traversed f) a b (f ()) d -> a -> f () +-- sequenceAOf_ :: 'Functor' f => 'Getter' a (f ()) -> a -> f () +-- sequenceAOf_ :: 'Applicative' f => Fold a (f ()) -> a -> f () +-- sequenceAOf_ :: 'Functor' f => 'Simple' 'Lens' a (f ()) -> a -> f () +-- sequenceAOf_ :: 'Functor' f => 'Simple' 'Iso a (f ()) -> a -> f () +-- sequenceAOf_ :: 'Applicative' f => 'Simple' 'Control.Lens.Traversal.Traversal' a (f ()) -> a -> f () +sequenceAOf_ :: Functor f => Getting (Traversed f) a (f ()) -> a -> f () sequenceAOf_ l = getTraversed . foldMapOf l (Traversed . void) {-# INLINE sequenceAOf_ #-} -- | -- @'Data.Foldable.mapM_' = 'mapMOf_' 'folded'@ -- --- > mapMOf_ :: Monad m => Getter a c -> (c -> m e) -> a -> m () --- > mapMOf_ :: Monad m => Fold a c -> (c -> m e) -> a -> m () --- > mapMOf_ :: Monad m => Lens a b c d -> (c -> m e) -> a -> m () --- > mapMOf_ :: Monad m => Iso a b c d -> (c -> m e) -> a -> m () --- > mapMOf_ :: Monad m => Traversal a b c d -> (c -> m e) -> a -> m () -mapMOf_ :: Monad m => Getting (Sequenced m) a b c d -> (c -> m e) -> a -> m () +-- > mapMOf_ :: 'Monad' m => 'Getter' a c -> (c -> m e) -> a -> m () +-- > mapMOf_ :: 'Monad' m => 'Fold' a c -> (c -> m e) -> a -> m () +-- > mapMOf_ :: 'Monad' m => 'Simple' 'Lens' a c -> (c -> m e) -> a -> m () +-- > mapMOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> m e) -> a -> m () +-- > mapMOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> m e) -> a -> m () +mapMOf_ :: Monad m => Getting (Sequenced m) a c -> (c -> m e) -> a -> m () mapMOf_ l f = getSequenced . foldMapOf l (Sequenced . liftM skip . f) {-# INLINE mapMOf_ #-} @@ -422,24 +448,26 @@ -- | -- @'Data.Foldable.forM_' = 'forMOf_' 'folded'@ -- --- > forMOf_ :: Monad m => Getter a c -> a -> (c -> m e) -> m () --- > forMOf_ :: Monad m => Fold a c -> a -> (c -> m e) -> m () --- > forMOf_ :: Monad m => Lens a b c d -> a -> (c -> m e) -> m () --- > forMOf_ :: Monad m => Iso a b c d -> a -> (c -> m e) -> m () --- > forMOf_ :: Monad m => Traversal a b c d -> a -> (c -> m e) -> m () -forMOf_ :: Monad m => Getting (Sequenced m) a b c d -> a -> (c -> m e) -> m () +-- > forMOf_ :: 'Monad' m => 'Getter' a c -> a -> (c -> m e) -> m () +-- > forMOf_ :: 'Monad' m => 'Fold' a c -> a -> (c -> m e) -> m () +-- > forMOf_ :: 'Monad' m => 'Simple' 'Lens' a c -> a -> (c -> m e) -> m () +-- > forMOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> (c -> m e) -> m () +-- > forMOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> (c -> m e) -> m () +forMOf_ :: Monad m => Getting (Sequenced m) a c -> a -> (c -> m e) -> m () forMOf_ = flip . mapMOf_ {-# INLINE forMOf_ #-} -- | -- @'Data.Foldable.sequence_' = 'sequenceOf_' 'folded'@ -- --- > sequenceOf_ :: Monad m => Getter a (m b) -> a -> m () --- > sequenceOf_ :: Monad m => Fold a (m b) -> a -> m () --- > sequenceOf_ :: Monad m => Lens a b (m b) d -> a -> m () --- > sequenceOf_ :: Monad m => Iso a b (m b) d -> a -> m () --- > sequenceOf_ :: Monad m => Traversal a b (m b) d -> a -> m () -sequenceOf_ :: Monad m => Getting (Sequenced m) a b (m c) d -> a -> m () +-- @ +-- sequenceOf_ :: 'Monad' m => 'Getter' a (m b) -> a -> m () +-- sequenceOf_ :: 'Monad' m => 'Fold' a (m b) -> a -> m () +-- sequenceOf_ :: 'Monad' m => 'Simple' 'Lens' a (m b) -> a -> m () +-- sequenceOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a (m b) -> a -> m () +-- sequenceOf_ :: 'Monad' m => 'Simple' 'Control.Lens.Traversal.Traversal' a (m b) -> a -> m () +-- @ +sequenceOf_ :: Monad m => Getting (Sequenced m) a (m c) -> a -> m () sequenceOf_ l = getSequenced . foldMapOf l (Sequenced . liftM skip) {-# INLINE sequenceOf_ #-} @@ -447,12 +475,14 @@ -- -- @'asum' = 'asumOf' 'folded'@ -- --- > asumOf :: Alternative f => Getter a c -> a -> f c --- > asumOf :: Alternative f => Fold a c -> a -> f c --- > asumOf :: Alternative f => Lens a b c d -> a -> f c --- > asumOf :: Alternative f => Iso a b c d -> a -> f c --- > asumOf :: Alternative f => Traversal a b c d -> a -> f c -asumOf :: Alternative f => Getting (Endo (f c)) a b (f c) d -> a -> f c +-- @ +-- asumOf :: 'Alternative' f => 'Getter' a c -> a -> f c +-- asumOf :: 'Alternative' f => 'Fold' a c -> a -> f c +-- asumOf :: 'Alternative' f => 'Simple' 'Lens' a c -> a -> f c +-- asumOf :: 'Alternative' f => 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> f c +-- asumOf :: 'Alternative' f => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> f c +-- @ +asumOf :: Alternative f => Getting (Endo (f c)) a (f c) -> a -> f c asumOf l = foldrOf l (<|>) Applicative.empty {-# INLINE asumOf #-} @@ -460,60 +490,73 @@ -- -- @'msum' = 'msumOf' 'folded'@ -- --- > msumOf :: MonadPlus m => Getter a c -> a -> m c --- > msumOf :: MonadPlus m => Fold a c -> a -> m c --- > msumOf :: MonadPlus m => Lens a b c d -> a -> m c --- > msumOf :: MonadPlus m => Iso a b c d -> a -> m c --- > msumOf :: MonadPlus m => Traversal a b c d -> a -> m c -msumOf :: MonadPlus m => Getting (Endo (m c)) a b (m c) d -> a -> m c +-- @ +-- msumOf :: 'MonadPlus' m => 'Getter' a c -> a -> m c +-- msumOf :: 'MonadPlus' m => 'Fold' a c -> a -> m c +-- msumOf :: 'MonadPlus' m => 'Simple' 'Lens' a c -> a -> m c +-- msumOf :: 'MonadPlus' m => 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> m c +-- msumOf :: 'MonadPlus' m => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> m c +-- @ +msumOf :: MonadPlus m => Getting (Endo (m c)) a (m c) -> a -> m c msumOf l = foldrOf l mplus mzero {-# INLINE msumOf #-} -- | -- @'elem' = 'elemOf' 'folded'@ -- --- > elemOf :: Eq c => Getter a c -> c -> a -> Bool --- > elemOf :: Eq c => Fold a c -> c -> a -> Bool --- > elemOf :: Eq c => Lens a b c d -> c -> a -> Bool --- > elemOf :: Eq c => Iso a b c d -> c -> a -> Bool --- > elemOf :: Eq c => Traversal a b c d -> c -> a -> Bool -elemOf :: Eq c => Getting Any a b c d -> c -> a -> Bool +-- @ +-- elemOf :: 'Eq' c => 'Getter' a c -> c -> a -> 'Bool' +-- elemOf :: 'Eq' c => 'Fold' a c -> c -> a -> 'Bool' +-- elemOf :: 'Eq' c => 'Simple' 'Lens' a c -> c -> a -> 'Bool' +-- elemOf :: 'Eq' c => 'Simple' 'Control.Lens.Iso.Iso' a c -> c -> a -> 'Bool' +-- elemOf :: 'Eq' c => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> c -> a -> 'Bool' +-- @ +elemOf :: Eq c => Getting Any a c -> c -> a -> Bool elemOf l = anyOf l . (==) {-# INLINE elemOf #-} -- | -- @'notElem' = 'notElemOf' 'folded'@ -- --- > notElemOf :: Eq c => Getter a c -> c -> a -> Bool --- > notElemOf :: Eq c => Fold a c -> c -> a -> Bool --- > notElemOf :: Eq c => Iso a b c d -> c -> a -> Bool --- > notElemOf :: Eq c => Lens a b c d -> c -> a -> Bool --- > notElemOf :: Eq c => Traversal a b c d -> c -> a -> Bool -notElemOf :: Eq c => Getting All a b c d -> c -> a -> Bool +-- @ +-- notElemOf :: 'Eq' c => 'Getter' a c -> c -> a -> 'Bool' +-- notElemOf :: 'Eq' c => 'Fold' a c -> c -> a -> 'Bool' +-- notElemOf :: 'Eq' c => 'Simple' 'Control.Lens.Iso.Iso' a c -> c -> a -> 'Bool' +-- notElemOf :: 'Eq' c => 'Simple' 'Lens' a c -> c -> a -> 'Bool' +-- notElemOf :: 'Eq' c => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> c -> a -> 'Bool' +-- @ +notElemOf :: Eq c => Getting All a c -> c -> a -> Bool notElemOf l = allOf l . (/=) {-# INLINE notElemOf #-} -- | -- @'concatMap' = 'concatMapOf' 'folded'@ -- --- > concatMapOf :: Getter a c -> (c -> [e]) -> a -> [e] --- > concatMapOf :: Fold a c -> (c -> [e]) -> a -> [e] --- > concatMapOf :: Lens a b c d -> (c -> [e]) -> a -> [e] --- > concatMapOf :: Iso a b c d -> (c -> [e]) -> a -> [e] --- > concatMapOf :: Traversal a b c d -> (c -> [e]) -> a -> [e] -concatMapOf :: Getting [e] a b c d -> (c -> [e]) -> a -> [e] +-- @ +-- concatMapOf :: 'Getter' a c -> (c -> [e]) -> a -> [e] +-- concatMapOf :: 'Fold' a c -> (c -> [e]) -> a -> [e] +-- concatMapOf :: 'Simple' 'Lens' a c -> (c -> [e]) -> a -> [e] +-- concatMapOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> [e]) -> a -> [e] +-- concatMapOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> [e]) -> a -> [e] +-- @ +concatMapOf :: Getting [e] a c -> (c -> [e]) -> a -> [e] concatMapOf l ces = runAccessor . l (Accessor . ces) {-# INLINE concatMapOf #-} -- | --- @'concat' = 'concatOf' 'folded'@ +-- @ +-- 'concat' = 'concatOf' 'folded' +-- 'concatOf' = 'view' +-- @ -- --- > concatOf :: Getter a [e] -> a -> [e] --- > concatOf :: Fold a [e] -> a -> [e] --- > concatOf :: Iso a b [e] d -> a -> [e] --- > concatOf :: Lens a b [e] d -> a -> [e] --- > concatOf :: Traversal a b [e] d -> a -> [e] -concatOf :: Getting [e] a b [e] d -> a -> [e] +-- @ +-- concatOf :: 'Getter' a [e] -> a -> [e] +-- concatOf :: 'Fold' a [e] -> a -> [e] +-- concatOf :: 'Simple' 'Control.Lens.Iso.Iso' a [e] -> a -> [e] +-- concatOf :: 'Simple' 'Lens' a [e] -> a -> [e] +-- concatOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a [e] -> a -> [e] +-- @ +concatOf :: Getting [e] a [e] -> a -> [e] concatOf = view {-# INLINE concatOf #-} @@ -527,45 +570,51 @@ -- -- @'lengthOf' ('folded' . 'folded') :: 'Foldable' f => f (g a) -> 'Int'@ -- --- > lengthOf :: Getter a c -> a -> Int --- > lengthOf :: Fold a c -> a -> Int --- > lengthOf :: Lens a b c d -> a -> Int --- > lengthOf :: Iso a b c d -> a -> Int --- > lengthOf :: Traversal a b c d -> a -> Int -lengthOf :: Getting (Sum Int) a b c d -> a -> Int +-- @ +-- lengthOf :: 'Getter' a c -> a -> 'Int' +-- lengthOf :: 'Fold' a c -> a -> 'Int' +-- lengthOf :: 'Simple' 'Lens' a c -> a -> 'Int' +-- lengthOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Int' +-- lengthOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Int' +-- @ +lengthOf :: Getting (Sum Int) a c -> a -> Int lengthOf l = getSum . foldMapOf l (\_ -> Sum 1) {-# INLINE lengthOf #-} -- | Perform a safe 'head' of a 'Fold' or 'Control.Lens.Traversal.Traversal' or retrieve 'Just' the result --- from a 'Getter' or 'Control.Lens.Type.Lens'. +-- from a 'Getter' or 'Lens'. -- -- @'Data.Maybe.listToMaybe' . 'toList' = 'headOf' 'folded'@ -- --- > headOf :: Getter a c -> a -> Maybe c --- > headOf :: Fold a c -> a -> Maybe c --- > headOf :: Lens a b c d -> a -> Maybe c --- > headOf :: Iso a b c d -> a -> Maybe c --- > headOf :: Traversal a b c d -> a -> Maybe c -headOf :: Getting (First c) a b c d -> a -> Maybe c +-- @ +-- headOf :: 'Getter' a c -> a -> 'Maybe' c +-- headOf :: 'Fold' a c -> a -> 'Maybe' c +-- headOf :: 'Simple' 'Lens' a c -> a -> 'Maybe' c +-- headOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Maybe' c +-- headOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Maybe' c +-- @ +headOf :: Getting (First c) a c -> a -> Maybe c headOf l = getFirst . foldMapOf l (First . Just) {-# INLINE headOf #-} -- | Perform a safe 'last' of a 'Fold' or 'Control.Lens.Traversal.Traversal' or retrieve 'Just' the result --- from a 'Getter' or 'Control.Lens.Type.Lens'. +-- from a 'Getter' or 'Lens'. -- --- > lastOf :: Getter a c -> a -> Maybe c --- > lastOf :: Fold a c -> a -> Maybe c --- > lastOf :: Lens a b c d -> a -> Maybe c --- > lastOf :: Iso a b c d -> a -> Maybe c --- > lastOf :: Traversal a b c d -> a -> Maybe c -lastOf :: Getting (Last c) a b c d -> a -> Maybe c +-- @ +-- lastOf :: 'Getter' a c -> a -> 'Maybe' c +-- lastOf :: 'Fold' a c -> a -> 'Maybe' c +-- lastOf :: 'Simple' 'Lens' a c -> a -> 'Maybe' c +-- lastOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Maybe' c +-- lastOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Maybe' c +-- @ +lastOf :: Getting (Last c) a c -> a -> Maybe c lastOf l = getLast . foldMapOf l (Last . Just) {-# INLINE lastOf #-} -- | -- Returns 'True' if this 'Fold' or 'Control.Lens.Traversal.Traversal' has no targets in the given container. -- --- Note: 'nullOf' on a valid 'Control.Lens.Iso.Iso', 'Control.Lens.Type.Lens' or 'Getter' should always return 'False' +-- Note: 'nullOf' on a valid 'Control.Lens.Iso.Iso', 'Lens' or 'Getter' should always return 'False' -- -- @'null' = 'nullOf' 'folded'@ -- @@ -576,91 +625,103 @@ -- -- @'nullOf' ('folded' . '_1' . 'folded') :: 'Foldable' f => f (g a, b) -> 'Bool'@ -- --- > nullOf :: Getter a c -> a -> Bool --- > nullOf :: Fold a c -> a -> Bool --- > nullOf :: Iso a b c d -> a -> Bool --- > nullOf :: Lens a b c d -> a -> Bool --- > nullOf :: Traversal a b c d -> a -> Bool -nullOf :: Getting All a b c d -> a -> Bool +-- @ +-- nullOf :: 'Getter' a c -> a -> 'Bool' +-- nullOf :: 'Fold' a c -> a -> 'Bool' +-- nullOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Bool' +-- nullOf :: 'Simple' 'Lens' a c -> a -> 'Bool' +-- nullOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Bool' +-- @ +nullOf :: Getting All a c -> a -> Bool nullOf l = getAll . foldMapOf l (\_ -> All False) {-# INLINE nullOf #-} -- | -- Obtain the maximum element (if any) targeted by a 'Fold' or 'Control.Lens.Traversal.Traversal' -- --- Note: maximumOf on a valid 'Control.Lens.Iso.Iso', 'Control.Lens.Type.Lens' or 'Getter' will always return 'Just' a value. +-- Note: maximumOf on a valid 'Control.Lens.Iso.Iso', 'Lens' or 'Getter' will always return 'Just' a value. -- -- @'maximum' = 'fromMaybe' ('error' "empty") . 'maximumOf' 'folded'@ -- --- > maximumOf :: Getter a c -> a -> Maybe c --- > maximumOf :: Ord c => Fold a c -> a -> Maybe c --- > maximumOf :: Iso a b c d -> a -> Maybe c --- > maximumOf :: Lens a b c d -> a -> Maybe c --- > maximumOf :: Ord c => Traversal a b c d -> a -> Maybe c -maximumOf :: Getting (Max c) a b c d -> a -> Maybe c +-- @ +-- maximumOf :: 'Getter' a c -> a -> 'Maybe' c +-- maximumOf :: 'Ord' c => 'Fold' a c -> a -> 'Maybe' c +-- maximumOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Maybe' c +-- maximumOf :: 'Simple' 'Lens' a c -> a -> 'Maybe' c +-- maximumOf :: 'Ord' c => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Maybe' c +-- @ +maximumOf :: Getting (Max c) a c -> a -> Maybe c maximumOf l = getMax . foldMapOf l Max {-# INLINE maximumOf #-} -- | -- Obtain the minimum element (if any) targeted by a 'Fold' or 'Control.Lens.Traversal.Traversal' -- --- Note: minimumOf on a valid 'Control.Lens.Iso.Iso', 'Control.Lens.Type.Lens' or 'Getter' will always return 'Just' a value. +-- Note: minimumOf on a valid 'Control.Lens.Iso.Iso', 'Lens' or 'Getter' will always return 'Just' a value. -- -- @'minimum' = 'Data.Maybe.fromMaybe' ('error' "empty") . 'minimumOf' 'folded'@ -- --- > minimumOf :: Getter a c -> a -> Maybe c --- > minimumOf :: Ord c => Fold a c -> a -> Maybe c --- > minimumOf :: Iso a b c d -> a -> Maybe c --- > minimumOf :: Lens a b c d -> a -> Maybe c --- > minimumOf :: Ord c => Traversal a b c d -> a -> Maybe c -minimumOf :: Getting (Min c) a b c d -> a -> Maybe c +-- @ +-- minimumOf :: 'Getter' a c -> a -> 'Maybe' c +-- minimumOf :: 'Ord' c => 'Fold' a c -> a -> 'Maybe' c +-- minimumOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> a -> 'Maybe' c +-- minimumOf :: 'Simple' 'Lens' a c -> a -> 'Maybe' c +-- minimumOf :: 'Ord' c => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> a -> 'Maybe' c +-- @ +minimumOf :: Getting (Min c) a c -> a -> Maybe c minimumOf l = getMin . foldMapOf l Min {-# INLINE minimumOf #-} -- | --- Obtain the maximum element (if any) targeted by a 'Fold', 'Control.Lens.Traversal.Traversal', 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso', +-- Obtain the maximum element (if any) targeted by a 'Fold', 'Control.Lens.Traversal.Traversal', 'Lens', 'Control.Lens.Iso.Iso', -- or 'Getter' according to a user supplied ordering. -- -- @'Data.Foldable.maximumBy' cmp = 'Data.Maybe.fromMaybe' ('error' "empty") . 'maximumByOf' 'folded' cmp@ -- --- > maximumByOf :: Getter a c -> (c -> c -> Ordering) -> a -> Maybe c --- > maximumByOf :: Fold a c -> (c -> c -> Ordering) -> a -> Maybe c --- > maximumByOf :: Iso a b c d -> (c -> c -> Ordering) -> a -> Maybe c --- > maximumByOf :: Lens a b c d -> (c -> c -> Ordering) -> a -> Maybe c --- > maximumByOf :: Traversal a b c d -> (c -> c -> Ordering) -> a -> Maybe c -maximumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe c +-- @ +-- maximumByOf :: 'Getter' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- maximumByOf :: 'Fold' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- maximumByOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- maximumByOf :: 'Simple' 'Lens' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- maximumByOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- @ +maximumByOf :: Getting (Endo (Maybe c)) a c -> (c -> c -> Ordering) -> a -> Maybe c maximumByOf l cmp = foldrOf l step Nothing where step a Nothing = Just a step a (Just b) = Just (if cmp a b == GT then a else b) {-# INLINE maximumByOf #-} -- | --- Obtain the minimum element (if any) targeted by a 'Fold', 'Control.Lens.Traversal.Traversal', 'Control.Lens.Type.Lens', 'Control.Lens.Iso.Iso' +-- Obtain the minimum element (if any) targeted by a 'Fold', 'Control.Lens.Traversal.Traversal', 'Lens', 'Control.Lens.Iso.Iso' -- or 'Getter' according to a user supplied ordering. -- -- > minimumBy cmp = fromMaybe (error "empty") . minimumByOf folded cmp -- --- > minimumByOf :: Getter a c -> (c -> c -> Ordering) -> a -> Maybe c --- > minimumByOf :: Fold a c -> (c -> c -> Ordering) -> a -> Maybe c --- > minimumByOf :: Iso a b c d -> (c -> c -> Ordering) -> a -> Maybe c --- > minimumByOf :: Lens a b c d -> (c -> c -> Ordering) -> a -> Maybe c --- > minimumByOf :: Traversal a b c d -> (c -> c -> Ordering) -> a -> Maybe c -minimumByOf :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> Ordering) -> a -> Maybe c +-- @ +-- minimumByOf :: 'Getter' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- minimumByOf :: 'Fold' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- minimumByOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- minimumByOf :: 'Simple' 'Lens' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- minimumByOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> c -> 'Ordering') -> a -> 'Maybe' c +-- @ +minimumByOf :: Getting (Endo (Maybe c)) a c -> (c -> c -> Ordering) -> a -> Maybe c minimumByOf l cmp = foldrOf l step Nothing where step a Nothing = Just a step a (Just b) = Just (if cmp a b == GT then b else a) {-# INLINE minimumByOf #-} --- | The 'findOf' function takes a 'Control.Lens.Type.Lens' (or 'Control.Lens.Getter.Getter', 'Control.Lens.Iso.Iso', 'Control.Lens.Fold.Fold', or 'Control.Lens.Traversal.Traversal'), +-- | The 'findOf' function takes a 'Lens' (or 'Control.Lens.Getter.Getter', 'Control.Lens.Iso.Iso', 'Control.Lens.Fold.Fold', or 'Control.Lens.Traversal.Traversal'), -- a predicate and a structure and returns the leftmost element of the structure -- matching the predicate, or 'Nothing' if there is no such element. -- --- > findOf :: Getter a c -> (c -> Bool) -> a -> Maybe c --- > findOf :: Fold a c -> (c -> Bool) -> a -> Maybe c --- > findOf :: Iso a b c d -> (c -> Bool) -> a -> Maybe c --- > findOf :: Lens a b c d -> (c -> Bool) -> a -> Maybe c --- > findOf :: Traversal a b c d -> (c -> Bool) -> a -> Maybe c -findOf :: Getting (First c) a b c d -> (c -> Bool) -> a -> Maybe c +-- @ +-- findOf :: 'Getter' a c -> (c -> 'Bool') -> a -> 'Maybe' c +-- findOf :: 'Fold' a c -> (c -> 'Bool') -> a -> 'Maybe' c +-- findOf :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> 'Bool') -> a -> 'Maybe' c +-- findOf :: 'Simple' 'Lens' a c -> (c -> 'Bool') -> a -> 'Maybe' c +-- findOf :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> 'Bool') -> a -> 'Maybe' c +-- @ +findOf :: Getting (First c) a c -> (c -> Bool) -> a -> Maybe c findOf l p = getFirst . foldMapOf l step where step c | p c = First (Just c) @@ -676,12 +737,14 @@ -- -- @'Data.Foldable.foldr1' = 'foldr1Of' 'folded'@ -- --- > foldr1Of :: Getter a c -> (c -> c -> c) -> a -> c --- > foldr1Of :: Fold a c -> (c -> c -> c) -> a -> c --- > foldr1Of :: Iso a b c d -> (c -> c -> c) -> a -> c --- > foldr1Of :: Lens a b c d -> (c -> c -> c) -> a -> c --- > foldr1Of :: Traversal a b c d -> (c -> c -> c) -> a -> c -foldr1Of :: Getting (Endo (Maybe c)) a b c d -> (c -> c -> c) -> a -> c +-- @ +-- foldr1Of :: 'Getter' a c -> (c -> c -> c) -> a -> c +-- foldr1Of :: 'Fold' a c -> (c -> c -> c) -> a -> c +-- foldr1Of :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> c -> c) -> a -> c +-- foldr1Of :: 'Simple' 'Lens' a c -> (c -> c -> c) -> a -> c +-- foldr1Of :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> c -> c) -> a -> c +-- @ +foldr1Of :: Getting (Endo (Maybe c)) a c -> (c -> c -> c) -> a -> c foldr1Of l f xs = fromMaybe (error "foldr1Of: empty structure") (foldrOf l mf Nothing xs) where mf x Nothing = Just x @@ -695,12 +758,14 @@ -- -- @'Data.Foldable.foldl1' = 'foldl1Of' 'folded'@ -- --- > foldl1Of :: Getter a c -> (c -> c -> c) -> a -> c --- > foldl1Of :: Fold a c -> (c -> c -> c) -> a -> c --- > foldl1Of :: Iso a b c d -> (c -> c -> c) -> a -> c --- > foldl1Of :: Lens a b c d -> (c -> c -> c) -> a -> c --- > foldl1Of :: Traversal a b c d -> (c -> c -> c) -> a -> c -foldl1Of :: Getting (Dual (Endo (Maybe c))) a b c d -> (c -> c -> c) -> a -> c +-- @ +-- foldl1Of :: 'Getter' a c -> (c -> c -> c) -> a -> c +-- foldl1Of :: 'Fold' a c -> (c -> c -> c) -> a -> c +-- foldl1Of :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> c -> c) -> a -> c +-- foldl1Of :: 'Simple' 'Lens' a c -> (c -> c -> c) -> a -> c +-- foldl1Of :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> c -> c) -> a -> c +-- @ +foldl1Of :: Getting (Dual (Endo (Maybe c))) a c -> (c -> c -> c) -> a -> c foldl1Of l f xs = fromMaybe (error "foldl1Of: empty structure") (foldlOf l mf Nothing xs) where mf Nothing y = Just y mf (Just x) y = Just (f x y) @@ -710,12 +775,14 @@ -- -- @'Data.Foldable.foldr'' = 'foldrOf'' 'folded'@ -- --- > foldrOf' :: Getter a c -> (c -> e -> e) -> e -> a -> e --- > foldrOf' :: Fold a c -> (c -> e -> e) -> e -> a -> e --- > foldrOf' :: Iso a b c d -> (c -> e -> e) -> e -> a -> e --- > foldrOf' :: Lens a b c d -> (c -> e -> e) -> e -> a -> e --- > foldrOf' :: Traversal a b c d -> (c -> e -> e) -> e -> a -> e -foldrOf' :: Getting (Dual (Endo (e -> e))) a b c d -> (c -> e -> e) -> e -> a -> e +-- @ +-- foldrOf' :: 'Getter' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf' :: 'Fold' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf' :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf' :: 'Simple' 'Lens' a c -> (c -> e -> e) -> e -> a -> e +-- foldrOf' :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> e -> e) -> e -> a -> e +-- @ +foldrOf' :: Getting (Dual (Endo (e -> e))) a c -> (c -> e -> e) -> e -> a -> e foldrOf' l f z0 xs = foldlOf l f' id xs z0 where f' k x z = k $! f x z {-# INLINE foldrOf' #-} @@ -724,12 +791,14 @@ -- -- @'Data.Foldable.foldl'' = 'foldlOf'' 'folded'@ -- --- > foldlOf' :: Getter a c -> (e -> c -> e) -> e -> a -> e --- > foldlOf' :: Fold a c -> (e -> c -> e) -> e -> a -> e --- > foldlOf' :: Iso a b c d -> (e -> c -> e) -> e -> a -> e --- > foldlOf' :: Lens a b c d -> (e -> c -> e) -> e -> a -> e --- > foldlOf' :: Traversal a b c d -> (e -> c -> e) -> e -> a -> e -foldlOf' :: Getting (Endo (e -> e)) a b c d -> (e -> c -> e) -> e -> a -> e +-- @ +-- foldlOf' :: 'Getter' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf' :: 'Fold' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf' :: 'Simple' 'Control.Lens.Iso.Iso' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf' :: 'Simple' 'Lens' a c -> (e -> c -> e) -> e -> a -> e +-- foldlOf' :: 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (e -> c -> e) -> e -> a -> e +-- @ +foldlOf' :: Getting (Endo (e -> e)) a c -> (e -> c -> e) -> e -> a -> e foldlOf' l f z0 xs = foldrOf l f' id xs z0 where f' x k z = k $! f z x {-# INLINE foldlOf' #-} @@ -739,13 +808,15 @@ -- -- @'Data.Foldable.foldrM' = 'foldrMOf' 'folded'@ -- --- > foldrMOf :: Monad m => Getter a c -> (c -> e -> m e) -> e -> a -> m e --- > foldrMOf :: Monad m => Fold a c -> (c -> e -> m e) -> e -> a -> m e --- > foldrMOf :: Monad m => Iso a b c d -> (c -> e -> m e) -> e -> a -> m e --- > foldrMOf :: Monad m => Lens a b c d -> (c -> e -> m e) -> e -> a -> m e --- > foldrMOf :: Monad m => Traversal a b c d -> (c -> e -> m e) -> e -> a -> m e +-- @ +-- foldrMOf :: 'Monad' m => 'Getter' a c -> (c -> e -> m e) -> e -> a -> m e +-- foldrMOf :: 'Monad' m => 'Fold' a c -> (c -> e -> m e) -> e -> a -> m e +-- foldrMOf :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a c -> (c -> e -> m e) -> e -> a -> m e +-- foldrMOf :: 'Monad' m => 'Simple' 'Lens' a c -> (c -> e -> m e) -> e -> a -> m e +-- foldrMOf :: 'Monad' m => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> e -> m e) -> e -> a -> m e +-- @ foldrMOf :: Monad m - => Getting (Dual (Endo (e -> m e))) a b c d + => Getting (Dual (Endo (e -> m e))) a c -> (c -> e -> m e) -> e -> a -> m e foldrMOf l f z0 xs = foldlOf l f' return xs z0 where f' k x z = f x z >>= k @@ -756,13 +827,15 @@ -- -- @'Data.Foldable.foldlM' = 'foldlMOf' 'folded'@ -- --- > foldlMOf :: Monad m => Getter a c -> (e -> c -> m e) -> e -> a -> m e --- > foldlMOf :: Monad m => Fold a c -> (e -> c -> m e) -> e -> a -> m e --- > foldlMOf :: Monad m => Iso a b c d -> (e -> c -> m e) -> e -> a -> m e --- > foldlMOf :: Monad m => Lens a b c d -> (e -> c -> m e) -> e -> a -> m e --- > foldlMOf :: Monad m => Traversal a b c d -> (e -> c -> m e) -> e -> a -> m e +-- @ +-- foldlMOf :: 'Monad' m => 'Getter' a c -> (e -> c -> m e) -> e -> a -> m e +-- foldlMOf :: 'Monad' m => 'Fold' a c -> (e -> c -> m e) -> e -> a -> m e +-- foldlMOf :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a c -> (e -> c -> m e) -> e -> a -> m e +-- foldlMOf :: 'Monad' m => 'Simple' 'Lens' a c -> (e -> c -> m e) -> e -> a -> m e +-- foldlMOf :: 'Monad' m => 'Simple' 'Control.Lens.Traversal.Traversal' a c -> (e -> c -> m e) -> e -> a -> m e +-- @ foldlMOf :: Monad m - => Getting (Endo (e -> m e)) a b c d + => Getting (Endo (e -> m e)) a c -> (e -> c -> m e) -> e -> a -> m e foldlMOf l f z0 xs = foldrOf l f' return xs z0 where f' x k z = f z x >>= k diff --git a/src/Control/Lens/Getter.hs b/src/Control/Lens/Getter.hs --- a/src/Control/Lens/Getter.hs +++ b/src/Control/Lens/Getter.hs @@ -12,16 +12,16 @@ -- A @'Getter' a c@ is just any function @(a -> c)@, which we've flipped into continuation -- passing style, @(c -> r) -> a -> r@ and decorated with 'Accessor' to obtain -- --- @type 'Getting' r a b c d = (c -> 'Accessor' r d) -> a -> 'Accessor' r b@ +-- @type 'Getting' r a c = (c -> 'Accessor' r c) -> a -> 'Accessor' r a@ -- -- If we restrict access to knowledge about the type 'r' and can work for any d and b, we could get: -- --- @type 'Getter' a c = forall r b d. 'Getting' r a b c d@ +-- @type 'Getter' a c = forall r. 'Getting' r a c@ -- -- But we actually hide the use of 'Accessor' behind a class 'Gettable' to error messages from -- type class resolution rather than at unification time, where they are much uglier. -- --- @type 'Getter' a c = forall f b d. 'Gettable' f => (c -> f d) -> a -> f b@ +-- @type 'Getter' a c = forall f. 'Gettable' f => (c -> f c) -> a -> f a@ -- -- Everything you can do with a function, you can do with a 'Getter', but note that because of the -- continuation passing style ('.') composes them in the opposite order. @@ -71,7 +71,7 @@ -- there are no lens laws that can be applied to it. In fact, it is isomorphic to an arbitrary function from @(a -> c)@. -- -- Moreover, a 'Getter' can be used directly as a 'Control.Lens.Fold.Fold', since it just ignores the 'Applicative'. -type Getter a c = forall f b d. Gettable f => (c -> f d) -> a -> f b +type Getter a c = forall f. Gettable f => (c -> f c) -> a -> f a -- | Build a 'Getter' from an arbitrary Haskell function. -- @@ -92,10 +92,9 @@ -- extract with 'Const'. To be compatible with 'Control.Lens.Type.Lens', 'Control.Lens.Traversal.Traversal' and 'Control.Lens.Iso.Iso' we also -- restricted choices of the irrelevant b and d parameters. -- --- If a function accepts a @'Getting' m r a b c d@, then when @r@ is a 'Monoid', and @m@ is a --- 'Monad' you can pass a 'Control.Lens.Fold.Fold' (or 'Control.Lens.Traversal.Traversal'), otherwise you can only pass this a +-- If a function accepts a @'Getting' r a c@, then when @r@ is a 'Monoid', then you can pass a 'Control.Lens.Fold.Fold' (or 'Control.Lens.Traversal.Traversal'), otherwise you can only pass this a -- 'Getter' or 'Control.Lens.Type.Lens'. -type Getting r a b c d = (c -> Accessor r d) -> a -> Accessor r b +type Getting r a c = (c -> Accessor r c) -> a -> Accessor r a ----------------------------------------------------------------------------- -- Gettables & Accessors @@ -166,11 +165,11 @@ -- @ -- view :: 'Getter' a c -> a -> c -- view :: 'Monoid' m => 'Control.Lens.Fold.Fold' a m -> a -> m --- view :: 'Control.Lens.Iso.Iso' a b c d -> a -> c --- view :: 'Control.Lens.Type.Lens' a b c d -> a -> c --- view :: 'Monoid' m => 'Control.Lens.Traversal.Traversal' a b m d -> a -> m +-- view :: 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> a -> c +-- view :: 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> a -> c +-- view :: 'Monoid' m => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a m -> a -> m -- @ -view :: Getting c a b c d -> a -> c +view :: Getting c a c -> a -> c view l = runAccessor . l Accessor {-# INLINE view #-} @@ -186,11 +185,11 @@ -- @ -- views :: 'Getter' a c -> (c -> d) -> a -> d -- views :: 'Monoid' m => 'Control.Lens.Fold.Fold' a c -> (c -> m) -> a -> m --- views :: 'Control.Lens.Iso.Iso' a b c d -> (c -> d) -> a -> d --- views :: 'Control.Lens.Type.Lens' a b c d -> (c -> d) -> a -> d --- views :: 'Monoid' m => 'Control.Lens.Traversal.Traversal' a b c d -> (c -> m) -> a -> m +-- views :: 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> (c -> d) -> a -> d +-- views :: 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> (c -> d) -> a -> d +-- views :: 'Monoid' m => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> m) -> a -> m -- @ -views :: Getting m a b c d -> (c -> m) -> a -> m +views :: Getting m a c -> (c -> m) -> a -> m views l f = runAccessor . l (Accessor . f) {-# INLINE views #-} @@ -206,11 +205,11 @@ -- @ -- (^$) :: 'Getter' a c -> a -> c -- (^$) :: 'Monoid' m => 'Control.Lens.Fold.Fold' a m -> a -> m --- (^$) :: 'Control.Lens.Iso.Iso' a b c d -> a -> c --- (^$) :: 'Control.Lens.Type.Lens' a b c d -> a -> c --- (^$) :: 'Monoid' m => 'Control.Lens.Traversal.Traversal' a b m d -> a -> m +-- (^$) :: 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> a -> c +-- (^$) :: 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> a -> c +-- (^$) :: 'Monoid' m => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a m -> a -> m -- @ -(^$) :: Getting c a b c d -> a -> c +(^$) :: Getting c a c -> a -> c l ^$ a = runAccessor (l Accessor a) {-# INLINE (^$) #-} @@ -229,11 +228,11 @@ -- @ -- (^.) :: a -> 'Getter' a c -> c -- (^.) :: 'Monoid' m => a -> 'Control.Lens.Fold.Fold' a m -> m --- (^.) :: a -> 'Control.Lens.Iso.Iso' a b c d -> c --- (^.) :: a -> 'Control.Lens.Type.Lens' a b c d -> c --- (^.) :: 'Monoid' m => a -> 'Control.Lens.Traversal.Traversal' a b m d -> m +-- (^.) :: a -> 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> c +-- (^.) :: a -> 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> c +-- (^.) :: 'Monoid' m => a -> 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a m -> m -- @ -(^.) :: a -> Getting c a b c d -> c +(^.) :: a -> Getting c a c -> c a ^. l = runAccessor (l Accessor a) {-# INLINE (^.) #-} @@ -248,11 +247,11 @@ -- @ -- query :: 'MonadReader' a m => 'Getter' a c -> m c -- query :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Fold.Fold' a c -> m c --- query :: 'MonadReader' a m => 'Control.Lens.Iso.Iso' a b c d -> m c --- query :: 'MonadReader' a m => 'Control.Lens.Type.Lens' a b c d -> m c --- query :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Traversal.Traversal' a b c d -> m c +-- query :: 'MonadReader' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> m c +-- query :: 'MonadReader' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> m c +-- query :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a c -> m c -- @ -query :: MonadReader a m => Getting c a b c d -> m c +query :: MonadReader a m => Getting c a c -> m c query l = Reader.asks (^.l) {-# INLINE query #-} @@ -263,11 +262,11 @@ -- @ -- queries :: 'MonadReader' a m => 'Getter' a c -> (c -> e) -> m e -- queries :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Fold.Fold' a c -> (c -> e) -> m e --- queries :: 'MonadReader' a m => 'Control.Lens.Iso.Iso' a b c d -> (c -> e) -> m e --- queries :: 'MonadReader' a m => 'Control.Lens.Type.Lens' a b c d -> (c -> e) -> m e --- queries :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Traversal.Traversal' a b c d -> (c -> e) -> m e +-- queries :: 'MonadReader' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> (c -> e) -> m e +-- queries :: 'MonadReader' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> (c -> e) -> m e +-- queries :: ('MonadReader' a m, 'Monoid' c) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> e) -> m e -- @ -queries :: MonadReader a m => Getting e a b c d -> (c -> e) -> m e +queries :: MonadReader a m => Getting e a c -> (c -> e) -> m e queries l f = Reader.asks (views l f) {-# INLINE queries #-} @@ -282,11 +281,11 @@ -- @ -- use :: 'MonadState' a m => 'Getter' a c -> m c -- use :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Fold.Fold' a r -> m r --- use :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a b c d -> m c --- use :: 'MonadState' a m => 'Control.Lens.Type.Lens' a b c d -> m c --- use :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Traversal.Traversal' a b r d -> m r +-- use :: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> m c +-- use :: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> m c +-- use :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a r -> m r -- @ -use :: MonadState a m => Getting c a b c d -> m c +use :: MonadState a m => Getting c a c -> m c use l = State.gets (view l) {-# INLINE use #-} @@ -297,10 +296,10 @@ -- @ -- uses :: 'MonadState' a m => 'Getter' a c -> (c -> e) -> m e -- uses :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Fold.Fold' a c -> (c -> r) -> m r --- uses :: 'MonadState' a m => 'Control.Lens.Type.Lens' a b c d -> (c -> e) -> m e --- uses :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a b c d -> (c -> e) -> m e --- uses :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Traversal.Traversal' a b c d -> (c -> r) -> m r +-- uses :: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Type.Lens' a c -> (c -> e) -> m e +-- uses :: 'MonadState' a m => 'Control.Lens.Type.Simple' 'Control.Lens.Iso.Iso' a c -> (c -> e) -> m e +-- uses :: ('MonadState' a m, 'Monoid' r) => 'Control.Lens.Type.Simple' 'Control.Lens.Traversal.Traversal' a c -> (c -> r) -> m r -- @ -uses :: MonadState a m => Getting e a b c d -> (c -> e) -> m e +uses :: MonadState a m => Getting e a c -> (c -> e) -> m e uses l f = State.gets (views l f) {-# INLINE uses #-} diff --git a/src/Control/Lens/IndexedFold.hs b/src/Control/Lens/IndexedFold.hs --- a/src/Control/Lens/IndexedFold.hs +++ b/src/Control/Lens/IndexedFold.hs @@ -48,21 +48,23 @@ ------------------------------------------------------------------------------ -- | Every 'IndexedFold' is a valid 'Control.Lens.Fold.Fold'. -type IndexedFold i a c = forall k f b d. (Indexed i k, Applicative f, Gettable f) => k (c -> f d) (a -> f b) +type IndexedFold i a c = forall k f. (Indexed i k, Applicative f, Gettable f) => k (c -> f c) (a -> f a) -- | -- Fold an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' by mapping indices and values to an arbitrary 'Monoid' with access -- to the index @i@. -- --- When you don't need access to the index then 'foldMapOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldMapOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldMapOf' l = 'ifoldMapOf' l . 'const'@ -- --- > ifoldMapOf :: IndexedGetter i a c -> (i -> c -> m) -> a -> m --- > ifoldMapOf :: Monoid m => IndexedFold i a c -> (i -> c -> m) -> a -> m --- > ifoldMapOf :: IndexedLens i a b c d -> (i -> c -> m) -> a -> m --- > ifoldMapOf :: Monoid m => IndexedTraversal i a b c d -> (i -> c -> m) -> a -> m -ifoldMapOf :: IndexedGetting i m a b c d -> (i -> c -> m) -> a -> m +-- @ +-- ifoldMapOf :: 'IndexedGetter' i a c -> (i -> c -> m) -> a -> m +-- ifoldMapOf :: 'Monoid' m => 'IndexedFold' i a c -> (i -> c -> m) -> a -> m +-- ifoldMapOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> m) -> a -> m +-- ifoldMapOf :: 'Monoid' m => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> m) -> a -> m +-- @ +ifoldMapOf :: IndexedGetting i m a c -> (i -> c -> m) -> a -> m ifoldMapOf l f = runAccessor . withIndex l (\i -> Accessor . f i) {-# INLINE ifoldMapOf #-} @@ -70,15 +72,17 @@ -- Right-associative fold of parts of a structure that are viewed through an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' with -- access to the index @i@. -- --- When you don't need access to the index then 'foldrOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldrOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldrOf' l = 'ifoldrOf' l . 'const'@ -- --- > ifoldrOf :: IndexedGetter i a c -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf :: IndexedFold i a c -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf :: IndexedLens i a b c d -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf :: IndexedTraversal i a b c d -> (i -> c -> e -> e) -> e -> a -> e -ifoldrOf :: IndexedGetting i (Endo e) a b c d -> (i -> c -> e -> e) -> e -> a -> e +-- @ +-- ifoldrOf :: 'IndexedGetter' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf :: 'IndexedFold' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- @ +ifoldrOf :: IndexedGetting i (Endo e) a c -> (i -> c -> e -> e) -> e -> a -> e ifoldrOf l f z t = appEndo (ifoldMapOf l (\i -> Endo . f i) t) z {-# INLINE ifoldrOf #-} @@ -86,15 +90,17 @@ -- Left-associative fold of the parts of a structure that are viewed through an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' with -- access to the index @i@. -- --- When you don't need access to the index then 'foldlOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldlOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldlOf' l = 'ifoldlOf' l . 'const'@ -- --- > ifoldlOf :: IndexedGetter i a c -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf :: IndexedFold i a c -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf :: IndexedLens i a b c d -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf :: IndexedTraversal i a b c d -> (i -> e -> c -> e) -> e -> a -> e -ifoldlOf :: IndexedGetting i (Dual (Endo e)) a b c d -> (i -> e -> c -> e) -> e -> a -> e +-- @ +-- ifoldlOf :: 'IndexedGetter' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf :: 'IndexedFold' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- @ +ifoldlOf :: IndexedGetting i (Dual (Endo e)) a c -> (i -> e -> c -> e) -> e -> a -> e ifoldlOf l f z t = appEndo (getDual (ifoldMapOf l (\i -> Dual . Endo . flip (f i)) t)) z {-# INLINE ifoldlOf #-} @@ -102,15 +108,17 @@ -- Return whether or not any element viewed through an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' -- satisfy a predicate, with access to the index @i@. -- --- When you don't need access to the index then 'anyOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.anyOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.anyOf' l = 'ianyOf' l . 'const'@ -- --- > ianyOf :: IndexedGetter i a c -> (i -> c -> Bool) -> a -> Bool --- > ianyOf :: IndexedFold i a c -> (i -> c -> Bool) -> a -> Bool --- > ianyOf :: IndexedLens i a b c d -> (i -> c -> Bool) -> a -> Bool --- > ianyOf :: IndexedTraversal i a b c d -> (i -> c -> Bool) -> a -> Bool -ianyOf :: IndexedGetting i Any a b c d -> (i -> c -> Bool) -> a -> Bool +-- @ +-- ianyOf :: 'IndexedGetter' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- ianyOf :: 'IndexedFold' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- ianyOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- ianyOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- @ +ianyOf :: IndexedGetting i Any a c -> (i -> c -> Bool) -> a -> Bool ianyOf l f = getAny . ifoldMapOf l (\i -> Any . f i) {-# INLINE ianyOf #-} @@ -118,30 +126,34 @@ -- Return whether or not all elements viewed through an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' -- satisfy a predicate, with access to the index @i@. -- --- When you don't need access to the index then 'allOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.allOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.allOf' l = 'iallOf' l . 'const'@ -- --- > iallOf :: IndexedGetter i a c -> (i -> c -> Bool) -> a -> Bool --- > iallOf :: IndexedFold i a c -> (i -> c -> Bool) -> a -> Bool --- > iallOf :: IndexedLens i a b c d -> (i -> c -> Bool) -> a -> Bool --- > iallOf :: IndexedTraversal i a b c d -> (i -> c -> Bool) -> a -> Bool -iallOf :: IndexedGetting i All a b c d -> (i -> c -> Bool) -> a -> Bool +-- @ +-- iallOf :: 'IndexedGetter' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- iallOf :: 'IndexedFold' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- iallOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- iallOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> 'Bool') -> a -> 'Bool' +-- @ +iallOf :: IndexedGetting i All a c -> (i -> c -> Bool) -> a -> Bool iallOf l f = getAll . ifoldMapOf l (\i -> All . f i) {-# INLINE iallOf #-} -- | -- Traverse the targets of an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' with access to the index @i@, discarding the results. -- --- When you don't need access to the index then 'traverseOf_' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.traverseOf_' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.traverseOf_' l = 'itraverseOf' l . 'const'@ -- --- > itraverseOf_ :: Functor f => IndexedGetter i a c -> (i -> c -> f e) -> a -> f () --- > itraverseOf_ :: Applicative f => IndexedFold i a c -> (i -> c -> f e) -> a -> f () --- > itraverseOf_ :: Functor f => IndexedLens i a b c d -> (i -> c -> f e) -> a -> f () --- > itraverseOf_ :: Applicative f => IndexedTraversal i a b c d -> (i -> c -> f e) -> a -> f () -itraverseOf_ :: Functor f => IndexedGetting i (Traversed f) a b c d -> (i -> c -> f e) -> a -> f () +-- @ +-- itraverseOf_ :: 'Functor' f => 'IndexedGetter' i a c -> (i -> c -> f e) -> a -> f () +-- itraverseOf_ :: 'Applicative' f => 'IndexedFold' i a c -> (i -> c -> f e) -> a -> f () +-- itraverseOf_ :: 'Functor' f => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> f e) -> a -> f () +-- itraverseOf_ :: 'Applicative' f => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> f e) -> a -> f () +-- @ +itraverseOf_ :: Functor f => IndexedGetting i (Traversed f) a c -> (i -> c -> f e) -> a -> f () itraverseOf_ l f = getTraversed . ifoldMapOf l (\i -> Traversed . void . f i) {-# INLINE itraverseOf_ #-} @@ -151,15 +163,17 @@ -- -- @'iforOf_' = 'flip' . 'itraverseOf_'@ -- --- When you don't need access to the index then 'forOf_' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.forOf_' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.forOf_' l a = 'iforOf' l a . 'const'@ -- --- > iforOf_ :: Functor f => IndexedGetter i a c -> a -> (i -> c -> f e) -> f () --- > iforOf_ :: Applicative f => IndexedFold i a c -> a -> (i -> c -> f e) -> f () --- > iforOf_ :: Functor f => IndexedLens i a b c d -> a -> (i -> c -> f e) -> f () --- > iforOf_ :: Applicative f => IndexedTraversal i a b c d -> a -> (i -> c -> f e) -> f () -iforOf_ :: Functor f => IndexedGetting i (Traversed f) a b c d -> a -> (i -> c -> f e) -> f () +-- @ +-- iforOf_ :: 'Functor' f => 'IndexedGetter' i a c -> a -> (i -> c -> f e) -> f () +-- iforOf_ :: 'Applicative' f => 'IndexedFold' i a c -> a -> (i -> c -> f e) -> f () +-- iforOf_ :: 'Functor' f => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> a -> (i -> c -> f e) -> f () +-- iforOf_ :: 'Applicative' f => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> a -> (i -> c -> f e) -> f () +-- @ +iforOf_ :: Functor f => IndexedGetting i (Traversed f) a c -> a -> (i -> c -> f e) -> f () iforOf_ = flip . itraverseOf_ {-# INLINE iforOf_ #-} @@ -167,15 +181,17 @@ -- Run monadic actions for each target of an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' with access to the index, -- discarding the results. -- --- When you don't need access to the index then 'mapMOf_' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.mapMOf_' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.mapMOf_' l = 'imapMOf' l . 'const'@ -- --- > imapMOf_ :: Monad m => IndexedGetter i a c -> (i -> c -> m e) -> a -> m () --- > imapMOf_ :: Monad m => IndexedFold i a c -> (i -> c -> m e) -> a -> m () --- > imapMOf_ :: Monad m => IndexedLens i a b c d -> (i -> c -> m e) -> a -> m () --- > imapMOf_ :: Monad m => IndexedTraversal i a b c d -> (i -> c -> m e) -> a -> m () -imapMOf_ :: Monad m => IndexedGetting i (Sequenced m) a b c d -> (i -> c -> m e) -> a -> m () +-- @ +-- imapMOf_ :: 'Monad' m => 'IndexedGetter' i a c -> (i -> c -> m e) -> a -> m () +-- imapMOf_ :: 'Monad' m => 'IndexedFold' i a c -> (i -> c -> m e) -> a -> m () +-- imapMOf_ :: 'Monad' m => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> m e) -> a -> m () +-- imapMOf_ :: 'Monad' m => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> m e) -> a -> m () +-- @ +imapMOf_ :: Monad m => IndexedGetting i (Sequenced m) a c -> (i -> c -> m e) -> a -> m () imapMOf_ l f = getSequenced . ifoldMapOf l (\i -> Sequenced . liftM skip . f i) {-# INLINE imapMOf_ #-} @@ -189,15 +205,17 @@ -- -- @'iforMOf_' = 'flip' . 'imapMOf_'@ -- --- When you don't need access to the index then 'forMOf_' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.forMOf_' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.forMOf_' l a = 'iforMOf' l a . 'const'@ -- --- > iforMOf_ :: Monad m => IndexedGetter i a c -> a -> (i -> c -> m e) -> m () --- > iforMOf_ :: Monad m => IndexedFold i a c -> a -> (i -> c -> m e) -> m () --- > iforMOf_ :: Monad m => IndexedLens i a b c d -> a -> (i -> c -> m e) -> m () --- > iforMOf_ :: Monad m => IndexedTraversal i a b c d -> a -> (i -> c -> m e) -> m () -iforMOf_ :: Monad m => IndexedGetting i (Sequenced m) a b c d -> a -> (i -> c -> m e) -> m () +-- @ +-- iforMOf_ :: 'Monad' m => 'IndexedGetter' i a c -> a -> (i -> c -> m e) -> m () +-- iforMOf_ :: 'Monad' m => 'IndexedFold' i a c -> a -> (i -> c -> m e) -> m () +-- iforMOf_ :: 'Monad' m => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> a -> (i -> c -> m e) -> m () +-- iforMOf_ :: 'Monad' m => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> a -> (i -> c -> m e) -> m () +-- @ +iforMOf_ :: Monad m => IndexedGetting i (Sequenced m) a c -> a -> (i -> c -> m e) -> m () iforMOf_ = flip . imapMOf_ {-# INLINE iforMOf_ #-} @@ -205,15 +223,17 @@ -- Concatenate the results of a function of the elements of an 'IndexedFold' or 'Control.Lens.IndexedTraversal.IndexedTraversal' -- with access to the index. -- --- When you don't need access to the index then 'concatMapOf_' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.concatMapOf_' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.concatMapOf_' l = 'iconcatMapMOf' l . 'const'@ -- --- > iconcatMapOf :: IndexedGetter i a c -> (i -> c -> [e]) -> a -> [e] --- > iconcatMapOf :: IndexedFold i a c -> (i -> c -> [e]) -> a -> [e] --- > iconcatMapOf :: IndexedLens i a b c d -> (i -> c -> [e]) -> a -> [e] --- > iconcatMapOf :: IndexedTraversal i a b c d -> (i -> c -> [e]) -> a -> [e] -iconcatMapOf :: IndexedGetting i [e] a b c d -> (i -> c -> [e]) -> a -> [e] +-- @ +-- iconcatMapOf :: 'IndexedGetter' i a c -> (i -> c -> [e]) -> a -> [e] +-- iconcatMapOf :: 'IndexedFold' i a c -> (i -> c -> [e]) -> a -> [e] +-- iconcatMapOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> [e]) -> a -> [e] +-- iconcatMapOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> [e]) -> a -> [e] +-- @ +iconcatMapOf :: IndexedGetting i [e] a c -> (i -> c -> [e]) -> a -> [e] iconcatMapOf l ices = runAccessor . withIndex l (\i -> Accessor . ices i) {-# INLINE iconcatMapOf #-} @@ -221,15 +241,17 @@ -- supplied the index, a structure and returns the left-most element of the structure -- matching the predicate, or 'Nothing' if there is no such element. -- --- When you don't need access to the index then 'findOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.findOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.findOf' l = 'ifoldOf' l . 'const'@ -- --- > ifindOf :: IndexedGetter a c -> (i -> c -> Bool) -> a -> Maybe (i, c) --- > ifindOf :: IndexedFold a c -> (i -> c -> Bool) -> a -> Maybe (i, c) --- > ifindOf :: IndexedLens a b c d -> (i -> c -> Bool) -> a -> Maybe (i, c) --- > ifindOf :: IndexedTraversal a b c d -> (i -> c -> Bool) -> a -> Maybe (i, c) -ifindOf :: IndexedGetting i (First (i, c)) a b c d -> (i -> c -> Bool) -> a -> Maybe (i, c) +-- @ +-- ifindOf :: 'IndexedGetter' a c -> (i -> c -> 'Bool') -> a -> 'Maybe' (i, c) +-- ifindOf :: 'IndexedFold' a c -> (i -> c -> 'Bool') -> a -> 'Maybe' (i, c) +-- ifindOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' a c -> (i -> c -> 'Bool') -> a -> 'Maybe' (i, c) +-- ifindOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' a c -> (i -> c -> 'Bool') -> a -> 'Maybe' (i, c) +-- @ +ifindOf :: IndexedGetting i (First (i, c)) a c -> (i -> c -> Bool) -> a -> Maybe (i, c) ifindOf l p = getFirst . ifoldMapOf l step where step i c | p i c = First $ Just (i, c) @@ -238,74 +260,84 @@ -- | /Strictly/ fold right over the elements of a structure with an index. -- --- When you don't need access to the index then 'foldrOf'' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldrOf'' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldrOf'' l = 'ifoldrOf'' l . 'const'@ -- --- > ifoldrOf' :: IndexedGetter i a c -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf' :: IndexedFold i a c -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf' :: IndexedLens i a b c d -> (i -> c -> e -> e) -> e -> a -> e --- > ifoldrOf' :: IndexedTraversal i a b c d -> (i -> c -> e -> e) -> e -> a -> e -ifoldrOf' :: IndexedGetting i (Dual (Endo (e -> e))) a b c d -> (i -> c -> e -> e) -> e -> a -> e +-- @ +-- ifoldrOf' :: 'IndexedGetter' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf' :: 'IndexedFold' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf' :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- ifoldrOf' :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> e -> e) -> e -> a -> e +-- @ +ifoldrOf' :: IndexedGetting i (Dual (Endo (e -> e))) a c -> (i -> c -> e -> e) -> e -> a -> e ifoldrOf' l f z0 xs = ifoldlOf l f' id xs z0 where f' i k x z = k $! f i x z {-# INLINE ifoldrOf' #-} -- | Fold over the elements of a structure with an index, associating to the left, but /strictly/. -- --- When you don't need access to the index then 'foldlOf'' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldlOf'' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldlOf'' l = 'ifoldlOf'' l . 'const'@ -- --- > ifoldlOf' :: IndexedGetter i a c -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf' :: IndexedFold i a c -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf' :: IndexedLens i a b c d -> (i -> e -> c -> e) -> e -> a -> e --- > ifoldlOf' :: IndexedTraversal i a b c d -> (i -> e -> c -> e) -> e -> a -> e -ifoldlOf' :: IndexedGetting i (Endo (e -> e)) a b c d -> (i -> e -> c -> e) -> e -> a -> e +-- @ +-- ifoldlOf' :: 'IndexedGetter' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf' :: 'IndexedFold' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf' :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- ifoldlOf' :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> e -> c -> e) -> e -> a -> e +-- @ +ifoldlOf' :: IndexedGetting i (Endo (e -> e)) a c -> (i -> e -> c -> e) -> e -> a -> e ifoldlOf' l f z0 xs = ifoldrOf l f' id xs z0 where f' i x k z = k $! f i z x {-# INLINE ifoldlOf' #-} -- | Monadic fold right over the elements of a structure with an index. -- --- When you don't need access to the index then 'foldrMOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldrMOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldrMOf' l = 'ifoldrMOf' l . 'const'@ -- --- > ifoldrMOf :: Monad m => IndexedGetter i a c -> (i -> c -> e -> m e) -> e -> a -> e --- > ifoldrMOf :: Monad m => IndexedFold i a c -> (i -> c -> e -> m e) -> e -> a -> e --- > ifoldrMOf :: Monad m => IndexedLens i a b c d -> (i -> c -> e -> m e) -> e -> a -> e --- > ifoldrMOf :: Monad m => IndexedTraversal i a b c d -> (i -> c -> e -> m e) -> e -> a -> e -ifoldrMOf :: Monad m => IndexedGetting i (Dual (Endo (e -> m e))) a b c d -> (i -> c -> e -> m e) -> e -> a -> m e +-- @ +-- ifoldrMOf :: 'Monad' m => 'IndexedGetter' i a c -> (i -> c -> e -> m e) -> e -> a -> e +-- ifoldrMOf :: 'Monad' m => 'IndexedFold' i a c -> (i -> c -> e -> m e) -> e -> a -> e +-- ifoldrMOf :: 'Monad' m => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> c -> e -> m e) -> e -> a -> e +-- ifoldrMOf :: 'Monad' m => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> c -> e -> m e) -> e -> a -> e +-- @ +ifoldrMOf :: Monad m => IndexedGetting i (Dual (Endo (e -> m e))) a c -> (i -> c -> e -> m e) -> e -> a -> m e ifoldrMOf l f z0 xs = ifoldlOf l f' return xs z0 where f' i k x z = f i x z >>= k {-# INLINE ifoldrMOf #-} -- | Monadic fold over the elements of a structure with an index, associating to the left. -- --- When you don't need access to the index then 'foldlMOf' is more flexible in what it accepts. +-- When you don't need access to the index then 'Control.Lens.Fold.foldlMOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.foldlMOf' l = 'ifoldlMOf' l . 'const'@ -- --- > ifoldlOf' :: Monad m => IndexedGetter i a c -> (i -> e -> c -> m e) -> e -> a -> e --- > ifoldlOf' :: Monad m => IndexedFold i a c -> (i -> e -> c -> m e) -> e -> a -> e --- > ifoldlOf' :: Monad m => IndexedLens i a b c d -> (i -> e -> c -> m e) -> e -> a -> e --- > ifoldlOf' :: Monad m => IndexedTraversal i a b c d -> (i -> e -> c -> m e) -> e -> a -> e -ifoldlMOf :: Monad m => IndexedGetting i (Endo (e -> m e)) a b c d -> (i -> e -> c -> m e) -> e -> a -> m e +-- @ +-- ifoldlOf' :: 'Monad' m => 'IndexedGetter' i a c -> (i -> e -> c -> m e) -> e -> a -> e +-- ifoldlOf' :: 'Monad' m => 'IndexedFold' i a c -> (i -> e -> c -> m e) -> e -> a -> e +-- ifoldlOf' :: 'Monad' m => 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> (i -> e -> c -> m e) -> e -> a -> e +-- ifoldlOf' :: 'Monad' m => 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> (i -> e -> c -> m e) -> e -> a -> e +-- @ +ifoldlMOf :: Monad m => IndexedGetting i (Endo (e -> m e)) a c -> (i -> e -> c -> m e) -> e -> a -> m e ifoldlMOf l f z0 xs = ifoldrOf l f' return xs z0 where f' i x k z = f i z x >>= k {-# INLINE ifoldlMOf #-} -- | Extract the key-value pairs from a structure. -- --- When you don't need access to the indices, then 'toListOf' is more flexible in what it accepts. +-- When you don't need access to the indices in the result, then 'Control.Lens.Fold.toListOf' is more flexible in what it accepts. -- -- @'Control.Lens.Fold.toListOf' l = 'map' 'fst' . 'itoListOf' l@ -- --- > itoListOf :: IndexedGetter i a c -> a -> [(i,c)] --- > itoListOf :: IndexedFold i a c -> a -> [(i,c)] --- > itoListOf :: IndexedLens i a b c d -> a -> [(i,c)] --- > itoListOf :: IndexedTraversal i a b c d -> a -> [(i,c)] -itoListOf :: IndexedGetting i [(i,c)] a b c d -> a -> [(i,c)] +-- @ +-- itoListOf :: 'IndexedGetter' i a c -> a -> [(i,c)] +-- itoListOf :: 'IndexedFold' i a c -> a -> [(i,c)] +-- itoListOf :: 'Control.Lens.IndexedLens.SimpleIndexedLens' i a c -> a -> [(i,c)] +-- itoListOf :: 'Control.Lens.IndexedTraversal.SimpleIndexedTraversal' i a c -> a -> [(i,c)] +-- @ +itoListOf :: IndexedGetting i [(i,c)] a c -> a -> [(i,c)] itoListOf l = ifoldMapOf l (\i c -> [(i,c)]) {-# INLINE itoListOf #-} diff --git a/src/Control/Lens/IndexedGetter.hs b/src/Control/Lens/IndexedGetter.hs --- a/src/Control/Lens/IndexedGetter.hs +++ b/src/Control/Lens/IndexedGetter.hs @@ -25,7 +25,7 @@ ------------------------------------------------------------------------------ -- | Every 'IndexedGetter' is a valid 'Control.Lens.IndexedFold.IndexedFold' and 'Getter'. -type IndexedGetter i a c = forall k f b d. (Indexed i k, Gettable f) => k (c -> f d) (a -> f b) +type IndexedGetter i a c = forall k f. (Indexed i k, Gettable f) => k (c -> f c) (a -> f a) -- | Used to consume an 'Control.Lens.IndexedFold.IndexedFold'. -type IndexedGetting i m a b c d = Index i (c -> Accessor m d) (a -> Accessor m b) +type IndexedGetting i m a c = Index i (c -> Accessor m c) (a -> Accessor m a) diff --git a/src/Control/Lens/Iso.hs b/src/Control/Lens/Iso.hs --- a/src/Control/Lens/Iso.hs +++ b/src/Control/Lens/Iso.hs @@ -122,6 +122,13 @@ -- | Build an isomorphism family from two pairs of inverse functions -- +-- @ +-- 'view' ('isos' ac ca bd db) = ac +-- 'view' ('from' ('isos' ac ca bd db)) = ca +-- 'set' ('isos' ac ca bd db) cd = db . cd . ac +-- 'set' ('from' ('isos' ac ca bd db')) ab = bd . ab . ca +-- @ +-- -- @isos :: (a -> c) -> (c -> a) -> (b -> d) -> (d -> b) -> 'Iso' a b c d@ isos :: (Isomorphic k, Functor f) => (a -> c) -> (c -> a) -> (b -> d) -> (d -> b) -> k (c -> f d) (a -> f b) isos ac ca bd db = isomorphic @@ -132,6 +139,14 @@ {-# SPECIALIZE isos :: Functor f => (a -> c) -> (c -> a) -> (b -> d) -> (d -> b) -> Isomorphism (c -> f d) (a -> f b) #-} -- | Build a simple isomorphism from a pair of inverse functions +-- +-- +-- @ +-- 'view' ('iso' f g) = f +-- 'view' ('from' ('iso' f g)) = g +-- 'set' ('isos' f g) h = g . h . f +-- 'set' ('from' ('iso' f g')) h = f . h . g +-- @ -- -- @iso :: (a -> b) -> (b -> a) -> 'Control.Lens.Type.Simple' 'Iso' a b@ iso :: (Isomorphic k, Functor f) => (a -> b) -> (b -> a) -> k (b -> f b) (a -> f a) diff --git a/src/Control/Lens/TH.hs b/src/Control/Lens/TH.hs --- a/src/Control/Lens/TH.hs +++ b/src/Control/Lens/TH.hs @@ -164,6 +164,10 @@ makeLensBody :: Name -> Name -> (Name -> ExpQ) -> (Name -> ExpQ) -> DecQ makeLensBody lensName conName f _ = funD lensName [clause [] (normalB (f conName)) []] +plain :: TyVarBndr -> TyVarBndr +plain (KindedTV t _) = PlainTV t +plain (PlainTV t) = PlainTV t + appArgs :: Type -> [TyVarBndr] -> Type appArgs t [] = t appArgs t (x:xs) = appArgs (AppT t (VarT (x^.name))) xs @@ -197,7 +201,8 @@ -> Maybe Name -> Type -> Q [Dec] -makeIsoLenses cfg ctx tyConName tyArgs dataConName maybeFieldName partTy = do +makeIsoLenses cfg ctx tyConName tyArgs0 dataConName maybeFieldName partTy = do + let tyArgs = map plain tyArgs0 m <- freshMap $ setOf typeVars tyArgs let aty = partTy bty = substTypeVars m aty @@ -291,7 +296,8 @@ -> [TyVarBndr] -- ^ args -> [Con] -> Q [Dec] -makeFieldLenses cfg ctx tyConName tyArgs cons = do +makeFieldLenses cfg ctx tyConName tyArgs0 cons = do + let tyArgs = map plain tyArgs0 x <- newName "x" let maybeLensClass = do guard $ tyArgs == [] diff --git a/src/Control/Lens/Traversal.hs b/src/Control/Lens/Traversal.hs --- a/src/Control/Lens/Traversal.hs +++ b/src/Control/Lens/Traversal.hs @@ -67,7 +67,7 @@ -- -- These have also been known as multilenses, but they have the signature and spirit of -- --- > traverse :: Traversable f => Traversal (f a) (f b) a b +-- @'traverse' :: 'Traversable' f => 'Traversal' (f a) (f b) a b@ -- -- and the more evocative name suggests their application. -- @@ -79,11 +79,11 @@ -- -- 1) Idiomatic naturality: -- --- > t pure = pure +-- @t 'pure' = 'pure'@ -- -- 2) Sequential composition: -- --- > fmap (t f) . t g = getCompose . t (Compose . fmap f . g) +-- @'fmap' (t f) . t g = 'getCompose' . t ('Compose' . 'fmap' f . g)@ -- -- One consequence of this requirement is that a traversal needs to leave the same number of elements as a candidate for -- subsequent traversal as it started with. @@ -92,7 +92,7 @@ -- that you should incur no effect caused by visiting the same element of the container twice. type Traversal a b c d = forall f. Applicative f => (c -> f d) -> a -> f b --- | > type SimpleTraversal = Simple Traversal +-- | @type SimpleTraversal = 'Simple' 'Traversal'@ type SimpleTraversal a b = Traversal a a b b -------------------------- @@ -103,25 +103,33 @@ -- Map each element of a structure targeted by a Lens or Traversal, -- evaluate these actions from left to right, and collect the results. -- --- > traverseOf = id +-- @'traverseOf' = 'id'@ -- --- > traverse = traverseOf traverse +-- @'traverse' = 'traverseOf' 'traverse'@ -- --- > traverseOf :: Iso a b c d -> (c -> f d) -> a -> f b --- > traverseOf :: Lens a b c d -> (c -> f d) -> a -> f b --- > traverseOf :: Traversal a b c d -> (c -> f d) -> a -> f b +-- @ +-- 'traverseOf' :: 'Iso' a b c d -> (c -> f d) -> a -> f b +-- 'traverseOf' :: 'Lens' a b c d -> (c -> f d) -> a -> f b +-- 'traverseOf' :: 'Traversal' a b c d -> (c -> f d) -> a -> f b +-- @ traverseOf :: LensLike f a b c d -> (c -> f d) -> a -> f b traverseOf = id {-# INLINE traverseOf #-} -- | -- --- > forOf l = flip (traverseOf l) +-- @'forOf' l = 'flip' ('traverseOf' l)@ -- --- > for = forOf traverse --- > forOf = morphism flip flip +-- @ +-- 'for' = 'forOf' 'traverse' +-- 'forOf' = 'flip' +-- @ -- --- > forOf :: Lens a b c d -> a -> (c -> f d) -> f b +-- @ +-- forOf :: 'Iso' a b c d -> a -> (c -> f d) -> f b +-- forOf :: 'Lens' a b c d -> a -> (c -> f d) -> f b +-- forOf :: 'Traversal' a b c d -> a -> (c -> f d) -> f b +-- @ forOf :: LensLike f a b c d -> a -> (c -> f d) -> f b forOf = flip {-# INLINE forOf #-} @@ -130,13 +138,17 @@ -- Evaluate each action in the structure from left to right, and collect -- the results. -- --- > sequenceA = sequenceAOf traverse --- > sequenceAOf l = traverseOf l id --- > sequenceAOf l = l id +-- @ +-- 'sequenceA' = 'sequenceAOf' 'traverse' = 'traverse' 'id' +-- 'sequenceAOf' l = 'traverseOf' l id +-- 'sequenceAOf' l = l id +-- @ -- --- > sequenceAOf :: Iso a b (f c) c -> a -> f b --- > sequenceAOf :: Lens a b (f c) c -> a -> f b --- > sequenceAOf :: Applicative f => Traversal a b (f c) c -> a -> f b +-- @ +-- 'sequenceAOf' :: 'Iso' a b (f c) c -> a -> f b +-- 'sequenceAOf' :: 'Lens' a b (f c) c -> a -> f b +-- 'sequenceAOf' :: 'Applicative' f => 'Traversal' a b (f c) c -> a -> f b +-- @ sequenceAOf :: LensLike f a b (f c) c -> a -> f b sequenceAOf l = l id {-# INLINE sequenceAOf #-} @@ -144,75 +156,91 @@ -- | Map each element of a structure targeted by a lens to a monadic action, -- evaluate these actions from left to right, and collect the results. -- --- > mapM = mapMOf traverse +-- @'mapM' = 'mapMOf' 'traverse'@ -- --- > mapMOf :: Iso a b c d -> (c -> m d) -> a -> m b --- > mapMOf :: Lens a b c d -> (c -> m d) -> a -> m b --- > mapMOf :: Monad m => Traversal a b c d -> (c -> m d) -> a -> m b +-- @ +-- 'mapMOf :: 'Iso' a b c d -> (c -> m d) -> a -> m b +-- 'mapMOf :: 'Lens' a b c d -> (c -> m d) -> a -> m b +-- 'mapMOf :: 'Monad' m => 'Traversal' a b c d -> (c -> m d) -> a -> m b +-- @ mapMOf :: LensLike (WrappedMonad m) a b c d -> (c -> m d) -> a -> m b mapMOf l cmd = unwrapMonad . l (WrapMonad . cmd) {-# INLINE mapMOf #-} -- | --- > forM = forMOf traverse --- > forMOf l = flip (mapMOf l) +-- @ +-- 'forM' = 'forMOf' 'traverse' +-- 'forMOf' l = 'flip' ('mapMOf' l) +-- @ -- --- > forMOf :: Iso a b c d -> a -> (c -> m d) -> m b --- > forMOf :: Lens a b c d -> a -> (c -> m d) -> m b --- > forMOf :: Monad m => Traversal a b c d -> a -> (c -> m d) -> m b +-- @ +-- forMOf :: 'Iso' a b c d -> a -> (c -> m d) -> m b +-- forMOf :: 'Lens' a b c d -> a -> (c -> m d) -> m b +-- forMOf :: 'Monad' m => 'Traversal' a b c d -> a -> (c -> m d) -> m b +-- @ forMOf :: LensLike (WrappedMonad m) a b c d -> a -> (c -> m d) -> m b forMOf l a cmd = unwrapMonad (l (WrapMonad . cmd) a) {-# INLINE forMOf #-} -- | --- > sequence = sequenceOf traverse --- > sequenceOf l = mapMOf l id --- > sequenceOf l = unwrapMonad . l WrapMonad +-- @ +-- 'sequence' = 'sequenceOf' 'traverse' +-- sequenceOf l = 'mapMOf' l id +-- sequenceOf l = 'unwrapMonad' . l 'WrapMonad' +-- @ -- --- > sequenceOf :: Iso a b (m c) c -> a -> m b --- > sequenceOf :: Lens a b (m c) c -> a -> m b --- > sequenceOf :: Monad m => Traversal a b (m c) c -> a -> m b +-- @ +-- sequenceOf :: 'Iso' a b (m c) c -> a -> m b +-- sequenceOf :: 'Lens' a b (m c) c -> a -> m b +-- sequenceOf :: 'Monad' m => 'Traversal' a b (m c) c -> a -> m b +-- @ sequenceOf :: LensLike (WrappedMonad m) a b (m c) c -> a -> m b sequenceOf l = unwrapMonad . l WrapMonad {-# INLINE sequenceOf #-} -- | This generalizes 'Data.List.transpose' to an arbitrary 'Traversal'. -- --- > transpose = transposeOf traverse +-- Note: 'Data.List.transpose' handles ragged inputs more intelligently, but for non-ragged inputs: -- --- > ghci> transposeOf traverse [[1,2,3],[4,5,6]] --- > [[1,4],[2,5],[3,6]] +-- @'Data.List.transpose' = 'transposeOf' 'traverse'@ -- --- Since every 'Lens' is a Traversal, we can use this as a form of --- monadic strength. +-- >>> transposeOf traverse [[1,2,3],[4,5,6]] +-- [[1,4],[2,5],[3,6]] -- --- > transposeOf _2 :: (b, [a]) -> [(b, a)] +-- Since every 'Lens' is a 'Traversal', we can use this as a form of +-- monadic strength as well: +-- +-- @'transposeOf' '_2' :: (b, [a]) -> [(b, a)]@ transposeOf :: LensLike ZipList a b [c] c -> a -> [b] transposeOf l = getZipList . l ZipList {-# INLINE transposeOf #-} -- | Generalizes 'Data.Traversable.mapAccumR' to an arbitrary 'Traversal'. -- --- > mapAccumR = mapAccumROf traverse +-- @'mapAccumR' = 'mapAccumROf' 'traverse'@ -- -- 'mapAccumROf' accumulates state from right to left. -- --- > mapAccumROf :: Iso a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) --- > mapAccumROf :: Lens a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) --- > mapAccumROf :: Traversal a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- @ +-- mapAccumROf :: 'Iso' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- mapAccumROf :: 'Lens' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- mapAccumROf :: 'Traversal' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- @ mapAccumROf :: LensLike (Lazy.State s) a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) mapAccumROf l f s0 a = swap (Lazy.runState (l (\c -> State.state (\s -> swap (f s c))) a) s0) {-# INLINE mapAccumROf #-} -- | Generalized 'Data.Traversable.mapAccumL' to an arbitrary 'Traversal'. -- --- > mapAccumL = mapAccumLOf traverse +-- @'mapAccumL' = 'mapAccumLOf' 'traverse'@ -- -- 'mapAccumLOf' accumulates state from left to right. -- --- > mapAccumLOf :: Iso a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) --- > mapAccumLOf :: Lens a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) --- > mapAccumLOf :: Traversal a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- @ +-- mapAccumLOf :: 'Iso' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- mapAccumLOf :: 'Lens' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- mapAccumLOf :: 'Traversal' a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) +-- @ mapAccumLOf :: LensLike (Backwards (Lazy.State s)) a b c d -> (s -> c -> (s, d)) -> s -> a -> (s, b) mapAccumLOf = mapAccumROf . backwards {-# INLINE mapAccumLOf #-} @@ -223,11 +251,13 @@ -- | Permit the use of 'scanr1' over an arbitrary 'Traversal' or 'Lens'. -- --- > scanr1 = scanr1Of traverse +-- @'scanr1' = 'scanr1Of' 'traverse'@ -- --- > scanr1Of :: Iso a b c c -> (c -> c -> c) -> a -> b --- > scanr1Of :: Lens a b c c -> (c -> c -> c) -> a -> b --- > scanr1Of :: Traversal a b c c -> (c -> c -> c) -> a -> b +-- @ +-- scanr1Of :: 'Iso' a b c c -> (c -> c -> c) -> a -> b +-- scanr1Of :: 'Lens' a b c c -> (c -> c -> c) -> a -> b +-- scanr1Of :: 'Traversal' a b c c -> (c -> c -> c) -> a -> b +-- @ scanr1Of :: LensLike (Lazy.State (Maybe c)) a b c c -> (c -> c -> c) -> a -> b scanr1Of l f = snd . mapAccumROf l step Nothing where step Nothing c = (Just c, c) @@ -236,11 +266,13 @@ -- | Permit the use of 'scanl1' over an arbitrary 'Traversal' or 'Lens'. -- --- > scanl1 = scanl1Of traverse +-- @'scanl1' = 'scanl1Of' 'traverse'@ -- --- > scanr1Of :: Iso a b c c -> (c -> c -> c) -> a -> b --- > scanr1Of :: Lens a b c c -> (c -> c -> c) -> a -> b --- > scanr1Of :: Traversal a b c c -> (c -> c -> c) -> a -> b +-- @ +-- scanr1Of :: Iso a b c c -> (c -> c -> c) -> a -> b +-- scanr1Of :: Lens a b c c -> (c -> c -> c) -> a -> b +-- scanr1Of :: Traversal a b c c -> (c -> c -> c) -> a -> b +-- @ scanl1Of :: LensLike (Backwards (Lazy.State (Maybe c))) a b c c -> (c -> c -> c) -> a -> b scanl1Of l f = snd . mapAccumLOf l step Nothing where step Nothing c = (Just c, c) @@ -255,8 +287,9 @@ -- -- Attempts to access beyond the range of the 'Traversal' will cause an error. -- --- > ghci> [[1],[3,4]]^.elementOf (traverse.traverse) 1 --- > 3 +-- >>> import Control.Lens +-- >>> [[1],[3,4]]^.elementOf (traverse.traverse) 1 +-- 3 elementOf :: Functor f => LensLike (ElementOf f) a b c c -> Int -> LensLike f a b c c elementOf l i f a = case getElementOf (l go a) 0 of Found _ fb -> fb @@ -269,7 +302,7 @@ -- -- Attempts to access beyond the range of the 'Traversal' will cause an error. -- --- > element = elementOf traverse +-- @'element' = 'elementOf' 'traverse'@ element :: Traversable t => Int -> Simple Lens (t a) a element = elementOf traverse @@ -279,7 +312,7 @@ -- | This is the traversal that just doesn't return anything -- --- > traverseNothing :: Applicative f => (c -> f d) -> a -> f a +-- @'traverseNothing' :: 'Applicative' f => (c -> f d) -> a -> f a@ traverseNothing :: Traversal a a c d traverseNothing = const pure {-# INLINE traverseNothing #-} diff --git a/src/Control/Lens/Type.hs b/src/Control/Lens/Type.hs --- a/src/Control/Lens/Type.hs +++ b/src/Control/Lens/Type.hs @@ -191,18 +191,22 @@ -- -- @('%%~') = 'id'@ -- --- > (%%~) :: Functor f => Iso a b c d -> (c -> f d) -> a -> f b --- > (%%~) :: Functor f => Lens a b c d -> (c -> f d) -> a -> f b --- > (%%~) :: Applicative f => Traversal a b c d -> (c -> f d) -> a -> f b +-- @ +-- (%%~) :: 'Functor' f => 'Control.Lens.Iso.Iso' a b c d -> (c -> f d) -> a -> f b +-- (%%~) :: 'Functor' f => 'Lens' a b c d -> (c -> f d) -> a -> f b +-- (%%~) :: 'Applicative' f => 'Control.Lens.Traversal.Traversal' a b c d -> (c -> f d) -> a -> f b +-- @ -- -- It may be beneficial to think about it as if it had these even more restrictive types, however: -- -- When applied to a 'Control.Lens.Traversal.Traversal', it can edit the targets of the 'Traversals', extracting a -- supplemental monoidal summary of its actions, by choosing f = ((,) m) -- --- > (%%~) :: Iso a b c d -> (c -> (e, d)) -> a -> (e, b) --- > (%%~) :: Lens a b c d -> (c -> (e, d)) -> a -> (e, b) --- > (%%~) :: Monoid m => Traversal a b c d -> (c -> (m, d)) -> a -> (m, b) +-- @ +-- (%%~) :: 'Control.Lens.Iso.Iso' a b c d -> (c -> (e, d)) -> a -> (e, b) +-- (%%~) :: 'Lens' a b c d -> (c -> (e, d)) -> a -> (e, b) +-- (%%~) :: 'Monoid' m => 'Control.Lens.Traversal.Traversal' a b c d -> (c -> (m, d)) -> a -> (m, b) +-- @ (%%~) :: LensLike f a b c d -> (c -> f d) -> a -> f b (%%~) = id {-# INLINE (%%~) #-} @@ -216,9 +220,11 @@ -- It may be useful to think of ('%%='), instead, as having either of the following more restricted -- type signatures: -- --- > (%%=) :: MonadState a m => Iso a a c d -> (c -> (e, d) -> m e --- > (%%=) :: MonadState a m => Lens a a c d -> (c -> (e, d) -> m e --- > (%%=) :: (MonadState a m, Monoid e) => Traversal a a c d -> (c -> (e, d) -> m e +-- @ +-- (%%=) :: 'MonadState' a m => 'Control.Lens.Iso.Iso' a a c d -> (c -> (e, d) -> m e +-- (%%=) :: 'MonadState' a m => 'Lens' a a c d -> (c -> (e, d) -> m e +-- (%%=) :: ('MonadState' a m, 'Monoid' e) => 'Control.Lens.Traversal.Traversal' a a c d -> (c -> (e, d) -> m e +-- @ (%%=) :: MonadState a m => LensLike ((,) e) a a c d -> (c -> (e, d)) -> m e #if MIN_VERSION_mtl(2,1,1) l %%= f = State.state (l f) @@ -241,16 +247,20 @@ -- and a monoidal summary -- of the result is given. -- - -- > focus :: Monad m => Simple Iso a b -> st b m c -> st a m c - -- > 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 => 'Simple' 'Control.Lens.Iso.Iso' a b -> st b m c -> st a m c + -- focus :: 'Monad' m => 'Simple' 'Lens' a b -> st b m c -> st a m c + -- focus :: ('Monad' m, 'Monoid' c) => 'Simple' 'Control.Lens.Traversal.Traversal' a b -> st b m c -> st a m c + -- @ focus :: Monad m => LensLike (Focusing m c) a a b b -> st b m c -> st a m c -- | Like 'focus', but discarding any accumulated results as you go. -- - -- > focus_ :: Monad m => Simple Iso a b -> st b m c -> st a m () - -- > focus_ :: Monad m => Simple Lens a b -> st b m c -> st a m () - -- > focus_ :: (Monad m, Monoid c) => Simple Traversal a b -> st b m c -> st a m () + -- @ + -- focus_ :: 'Monad' m => 'Simple' 'Control.Lens.Iso.Iso' a b -> st b m c -> st a m () + -- focus_ :: 'Monad' m => 'Simple' 'Lens' a b -> st b m c -> st a m () + -- focus_ :: ('Monad' m, 'Monoid' c) => 'Simple' 'Control.Lens.Traversal.Traversal' a b -> st b m c -> st a m () + -- @ focus_ :: Monad m => LensLike (Focusing m ()) a a b b -> st b m c -> st a m () -- | A much more limited version of 'focus' that can work with a 'Setter'. @@ -275,7 +285,6 @@ setFocus l m = Lazy.state $ (,) () . runIdentity . l (Identity . snd . Lazy.runState m) instance Focus ReaderT where - --focus l m = ReaderT $ \a -> liftM fst $ unfocusing $ l (\b -> Focusing $ (\c -> (c,b)) `liftM` runReaderT m b) a focus l m = ReaderT $ liftM fst . unfocusing . l (\b -> Focusing $ (\c -> (c,b)) `liftM` runReaderT m b) {-# INLINE focus #-} focus_ l m = ReaderT $ \a -> liftM skip $ unfocusing $ l (\b -> Focusing $ (\_ -> ((),b)) `liftM` runReaderT m b) a @@ -290,7 +299,6 @@ -- a pair. -- -- >>> import Control.Lens --- -- >>> (1,2)^._1 -- 1 -- @@ -330,7 +338,7 @@ merged _ r f (Right a') = Right <$> r f a' {-# INLINE merged #-} --- | 'bothLenses' makes a lens from two other lenses (or isomorphisms) +-- | 'bothLenses' makes a 'Lens' from two other lenses (or isomorphisms) bothLenses :: Lens a b c d -> Lens a' b' c' d' -> Lens (a,a') (b,b') (c,c') (d,d') bothLenses l r f (a, a') = case l (IndexedStore id) a of IndexedStore db c -> case r (IndexedStore id) a' of diff --git a/src/Control/Parallel/Strategies/Lens.hs b/src/Control/Parallel/Strategies/Lens.hs --- a/src/Control/Parallel/Strategies/Lens.hs +++ b/src/Control/Parallel/Strategies/Lens.hs @@ -34,7 +34,7 @@ -- evalTraversal :: 'Simple' 'Traversal' a b -> 'Strategy' b -> 'Strategy' a -- evalTraversal :: (b -> 'Eval' b) -> a -> 'Eval' a) -> 'Strategy' b -> 'Strategy' a -- @ -evalOf :: LensLike Eval a a b b -> Strategy b -> Strategy a +evalOf :: SimpleLensLike Eval a b -> Strategy b -> Strategy a evalOf l = l -- | Evaluate the targets of a 'Lens' or 'Traversal' according into a @@ -47,7 +47,7 @@ -- parTraversal :: 'Simple' 'Traversal' a b -> 'Strategy' b -> 'Strategy' a -- parTraversal :: ((b -> 'Eval' b) -> a -> 'Eval' a) -> 'Strategy' b -> 'Strategy' a -- @ -parOf :: LensLike Eval a a b b -> Strategy b -> Strategy a +parOf :: SimpleLensLike Eval a b -> Strategy b -> Strategy a parOf l s = l (rparWith s) -- | Transform a 'Lens', 'Fold', 'Getter', 'Setter' or 'Traversal' to diff --git a/src/Control/Seq/Lens.hs b/src/Control/Seq/Lens.hs --- a/src/Control/Seq/Lens.hs +++ b/src/Control/Seq/Lens.hs @@ -20,5 +20,5 @@ -- 'Getter' or 'Fold' according to the given strategy. -- -- > seqFoldable = seqOf folded -seqOf :: Getting [c] a b c d -> Strategy c -> Strategy a +seqOf :: Getting [c] a c -> Strategy c -> Strategy a seqOf l s = seqList s . toListOf l diff --git a/src/Data/IntSet/Lens.hs b/src/Data/IntSet/Lens.hs --- a/src/Data/IntSet/Lens.hs +++ b/src/Data/IntSet/Lens.hs @@ -24,7 +24,7 @@ -- > ghci> contains 3 +~ False $ fromList [1,2,3,4] -- > fromList [1,2,4] -- --- > contains :: Int -> (Bool -> f Bool) -> IntSet -> f IntSet +-- @contains :: 'Functor' f => 'Int' -> ('Bool' -> f 'Bool') -> 'IntSet' -> f 'IntSet'@ contains :: Int -> Simple Lens IntSet Bool contains k f s = go <$> f (IntSet.member k s) where go False = IntSet.delete k s @@ -47,15 +47,21 @@ -- -- >>> adjust setmapped (+1) (fromList [1,2,3,4]) -- fromList [2,3,4,5] -setmapped :: Setter IntSet IntSet Int Int +setmapped :: Simple Setter IntSet Int setmapped = sets IntSet.map -- | Construct an 'IntSet' from a 'Getter', 'Fold', 'Traversal', 'Lens' or 'Iso'. -- --- > setOf :: Getter a Int -> a -> IntSet --- > setOf :: Fold a Int -> a -> IntSet --- > setOf :: Iso a b Int d -> a -> IntSet --- > setOf :: Lens a b Int d -> a -> IntSet --- > setOf :: Traversal a b Int d -> a -> IntSet -setOf :: Getting IntSet a b Int d -> a -> IntSet +-- >>> :m + Data.IntSet.Lens Control.Lens +-- >>> setOf (folded._2) [("hello",1),("world",2),("!!!",3)] +-- fromList [1,2,3] +-- +-- @ +-- setOf :: 'Getter' a 'Int' -> a -> 'IntSet' +-- setOf :: 'Fold' a 'Int' -> a -> 'IntSet' +-- setOf :: 'Simple' 'Iso' a 'Int' -> a -> 'IntSet' +-- setOf :: 'Simple' 'Lens' a 'Int' -> a -> 'IntSet' +-- setOf :: 'Simple' 'Traversal' a 'Int' -> a -> 'IntSet' +-- @ +setOf :: Getting IntSet a Int -> a -> IntSet setOf l = runAccessor . l (Accessor . IntSet.singleton) diff --git a/src/Data/Set/Lens.hs b/src/Data/Set/Lens.hs --- a/src/Data/Set/Lens.hs +++ b/src/Data/Set/Lens.hs @@ -51,10 +51,12 @@ -- >>> setOf (folded._2) [("hello",1),("world",2),("!!!",3)] -- fromList [1,2,3] -- --- > setOf :: Getter a c -> a -> Set c --- > setOf :: Ord c => Fold a c -> a -> Set c --- > setOf :: Iso a b c d -> a -> Set c --- > setOf :: Lens a b c d -> a -> Set c --- > setOf :: Ord c => Traversal a b c d -> a -> Set c -setOf :: Getting (Set c) a b c d -> a -> Set c +-- @ +-- setOf :: 'Getter' a c -> a -> 'Set' c +-- setOf :: 'Ord' c => 'Fold' a c -> a -> 'Set' c +-- setOf :: 'Simple' 'Iso' a c -> a -> 'Set' c +-- setOf :: 'Simple' 'Lens' a c -> a -> 'Set' c +-- setOf :: 'Ord' c => 'Simple' 'Traversal' a c -> a -> 'Set' c +-- @ +setOf :: Getting (Set c) a c -> a -> Set c setOf l = runAccessor . l (Accessor . Set.singleton) diff --git a/src/Language/Haskell/TH/Lens.hs b/src/Language/Haskell/TH/Lens.hs --- a/src/Language/Haskell/TH/Lens.hs +++ b/src/Language/Haskell/TH/Lens.hs @@ -1,4 +1,8 @@ +{-# LANGUAGE CPP #-} {-# LANGUAGE TemplateHaskell #-} +#if defined(__GLASGOW_HASKELL__) && __GLASGOW_HASKELL__ >= 704 +{-# LANGUAGE Trustworthy #-} +#endif ----------------------------------------------------------------------------- -- | -- Module : Language.Haskell.TH.Lens diff --git a/tests/doctests.hs b/tests/doctests.hs --- a/tests/doctests.hs +++ b/tests/doctests.hs @@ -1,22 +1,28 @@ module Main where import Test.DocTest +import System.Directory +import System.FilePath +import Control.Applicative +import Control.Monad +import Data.List main :: IO () -main = doctest [ +main = getSources >>= \sources -> doctest $ "-isrc" - , "-idist/build/autogen" - , "-optP-include", "-optPdist/build/autogen/cabal_macros.h" - , "src/Control/Lens/Action.hs" - , "src/Control/Lens/Fold.hs" - , "src/Control/Lens/Getter.hs" - , "src/Control/Lens/Setter.hs" - , "src/Data/Array/Lens.hs" - , "src/Data/Bits/Lens.hs" - , "src/Data/IntMap/Lens.hs" - , "src/Data/IntSet/Lens.hs" - , "src/Data/List/Lens.hs" - , "src/Data/Map/Lens.hs" - , "src/Data/Set/Lens.hs" - , "src/GHC/Generics/Lens.hs" - ] + : "-idist/build/autogen" + : "-optP-include" + : "-optPdist/build/autogen/cabal_macros.h" + : sources + +getSources :: IO [FilePath] +getSources = filter (isSuffixOf ".hs") <$> go "src" + where + go dir = do + (dirs, files) <- getFilesAndDirectories dir + (files ++) . concat <$> mapM go dirs + +getFilesAndDirectories :: FilePath -> IO ([FilePath], [FilePath]) +getFilesAndDirectories dir = do + c <- map (dir ) . filter (`notElem` ["..", "."]) <$> getDirectoryContents dir + (,) <$> filterM doesDirectoryExist c <*> filterM doesFileExist c diff --git a/tests/properties.hs b/tests/properties.hs --- a/tests/properties.hs +++ b/tests/properties.hs @@ -74,8 +74,6 @@ prop_mapped = isSetter (mapped :: Simple Setter [Int] Int) prop_mapped_mapped = isSetter (mapped.mapped :: Simple Setter [Maybe Int] Int) - - prop_both = isTraversal (both :: Simple Traversal (Int,Int) Int) prop_value (Fun _ k :: Fun Int Bool) = isTraversal (value k :: Simple Traversal (Int,Int) Int) prop_traverseLeft = isTraversal (traverseLeft :: Simple Traversal (Either Int Bool) Int)