Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 507 lines (446 sloc) 21.037 kb
6be7786 @ekmett Factoring out Control.Lens.Type
authored
1 {-# LANGUAGE CPP #-}
2 {-# LANGUAGE GADTs #-}
3 {-# LANGUAGE Rank2Types #-}
4 {-# LANGUAGE FlexibleContexts #-}
5 {-# LANGUAGE FlexibleInstances #-}
6 {-# LANGUAGE ScopedTypeVariables #-}
7 {-# LANGUAGE MultiParamTypeClasses #-}
b54e109 @shachaf (f :: * -> *) in the definition of Equality
shachaf authored
8 {-# LANGUAGE KindSignatures #-}
6be7786 @ekmett Factoring out Control.Lens.Type
authored
9 -------------------------------------------------------------------------------
10 -- |
11 -- Module : Control.Lens.Type
12 -- Copyright : (C) 2012 Edward Kmett
13 -- License : BSD-style (see the file LICENSE)
14 -- Maintainer : Edward Kmett <ekmett@gmail.com>
15 -- Stability : provisional
16 -- Portability : Rank2Types
17 --
d7a3589 @ekmett more docs
authored
18 -- This module exports the majority of the types that need to appear in user
19 -- signatures or in documentation when talking about lenses. The remaining types
20 -- for consuming lenses are distributed across various modules in the hierarchy.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
21 -------------------------------------------------------------------------------
22 module Control.Lens.Type
23 (
a2cd8c1 @ekmett lots of new types
authored
24 -- * Other
25 Equality, Equality'
6be7786 @ekmett Factoring out Control.Lens.Type
authored
26 , Iso, Iso'
27 , Prism , Prism'
a2cd8c1 @ekmett lots of new types
authored
28 -- * Lenses, Folds and Traversals
29 , Lens, Lens'
30 , Traversal, Traversal'
6be7786 @ekmett Factoring out Control.Lens.Type
authored
31 , Setter, Setter'
a2cd8c1 @ekmett lots of new types
authored
32 , Getter, Fold
33 , Action, MonadicFold
34 -- * Indexed
35 , IndexedLens, IndexedLens'
36 , IndexedTraversal, IndexedTraversal'
37 , IndexedSetter, IndexedSetter'
38 , IndexedGetter, IndexedFold
39 , IndexedAction, IndexedMonadicFold
40 -- * Index-Preserving
41 , IndexPreservingLens, IndexPreservingLens'
42 , IndexPreservingTraversal, IndexPreservingTraversal'
43 , IndexPreservingSetter, IndexPreservingSetter'
44 , IndexPreservingGetter, IndexPreservingFold
45 , IndexPreservingAction, IndexPreservingMonadicFold
6be7786 @ekmett Factoring out Control.Lens.Type
authored
46 -- * Common
47 , Simple
48 , LensLike, LensLike'
3fe8e0b @ekmett Removed more q Profunctor references
authored
49 , Lensing, Lensing'
6be7786 @ekmett Factoring out Control.Lens.Type
authored
50 , IndexedLensLike, IndexedLensLike'
51 , Overloading, Overloading'
6687426 @ekmett more equalities and docfixes
authored
52 , Overloaded, Overloaded'
6be7786 @ekmett Factoring out Control.Lens.Type
authored
53 ) where
54
55 import Control.Applicative
0983498 @ekmett Split up the rest of the Control.Lens.Internal dependencies from Cont…
authored
56 import Control.Lens.Internal.Action
57 import Control.Lens.Internal.Getter
58 import Control.Lens.Internal.Setter
59 import Control.Lens.Internal.Indexed
6be7786 @ekmett Factoring out Control.Lens.Type
authored
60 import Data.Profunctor
61
62 -- $setup
63 -- >>> import Control.Lens
64 -- >>> import Debug.SimpleReflect.Expr
65 -- >>> import Debug.SimpleReflect.Vars as Vars hiding (f,g,h)
66 -- >>> let f :: Expr -> Expr; f = Debug.SimpleReflect.Vars.f
67 -- >>> let g :: Expr -> Expr; g = Debug.SimpleReflect.Vars.g
68 -- >>> let h :: Expr -> Expr -> Expr; h = Debug.SimpleReflect.Vars.h
69 -- >>> let getter :: Expr -> Expr; getter = fun "getter"
70 -- >>> let setter :: Expr -> Expr -> Expr; setter = fun "setter"
5095463 @ekmett fixed prism test
authored
71 -- >>> import Numeric.Natural
e95b155 @ion1 Prism, Type: Apply the previous fix to the right place; remove $setup…
ion1 authored
72 -- >>> let nat :: Prism' Integer Natural; nat = prism toInteger $ \i -> if i < 0 then Left i else Right (fromInteger i)
6be7786 @ekmett Factoring out Control.Lens.Type
authored
73
74 -------------------------------------------------------------------------------
75 -- Lenses
76 -------------------------------------------------------------------------------
77
78 -- | A 'Lens' is actually a lens family as described in
79 -- <http://comonad.com/reader/2012/mirrored-lenses/>.
80 --
81 -- With great power comes great responsibility and a 'Lens' is subject to the
9eaef5c @basdirks haddocks: misc
basdirks authored
82 -- three common sense 'Lens' laws:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
83 --
84 -- 1) You get back what you put in:
85 --
86 -- @'Control.Lens.Getter.view' l ('Control.Lens.Setter.set' l b a) ≡ b@
87 --
88 -- 2) Putting back what you got doesn't change anything:
89 --
90 -- @'Control.Lens.Setter.set' l ('Control.Lens.Getter.view' l a) a ≡ a@
91 --
92 -- 3) Setting twice is the same as setting once:
93 --
94 -- @'Control.Lens.Setter.set' l c ('Control.Lens.Setter.set' l b a) ≡ 'Control.Lens.Setter.set' l c a@
95 --
96 -- These laws are strong enough that the 4 type parameters of a 'Lens' cannot
97 -- vary fully independently. For more on how they interact, read the \"Why is
98 -- it a Lens Family?\" section of
99 -- <http://comonad.com/reader/2012/mirrored-lenses/>.
100 --
101 -- Every 'Lens' can be used directly as a 'Control.Lens.Setter.Setter' or
102 -- 'Traversal'.
103 --
104 -- You can also use a 'Lens' for 'Control.Lens.Getter.Getting' as if it were a
105 -- 'Fold' or 'Getter'.
106 --
40e0b6c @basdirks haddocks: formatting, punctuation and linking
basdirks authored
107 -- Since every 'Lens' is a valid 'Traversal', the
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
108 -- 'Traversal' laws are required of any 'Lens' you create:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
109 --
110 -- @
111 -- l 'pure' ≡ 'pure'
112 -- 'fmap' (l f) '.' l g ≡ 'Data.Functor.Compose.getCompose' '.' l ('Data.Functor.Compose.Compose' '.' 'fmap' f '.' g)
113 -- @
114 --
115 -- @type 'Lens' s t a b = forall f. 'Functor' f => 'LensLike' f s t a b@
116 type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t
117
118 -- | @type 'Lens'' = 'Simple' 'Lens'@
119 type Lens' s a = Lens s s a a
120
121 -- | Every 'IndexedLens' is a valid 'Lens' and a valid 'Control.Lens.Traversal.IndexedTraversal'.
122 type IndexedLens i s t a b = forall f p. (Indexable i p, Functor f) => p a (f b) -> s -> f t
123
124 -- | @type 'IndexedLens'' i = 'Simple' ('IndexedLens' i)@
125 type IndexedLens' i s a = IndexedLens i s s a a
126
d7a3589 @ekmett more docs
authored
127 -- | An 'IndexPreservingLens' leaves any index it is composed with alone.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
128 type IndexPreservingLens s t a b = forall p f. (Conjoined p, Functor f) => p a (f b) -> p s (f t)
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
129
d7a3589 @ekmett more docs
authored
130 -- | @type 'IndexPreservingLens'' = 'Simple' 'IndexPreservingLens'@
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
131 type IndexPreservingLens' s a = IndexPreservingLens s s a a
132
6be7786 @ekmett Factoring out Control.Lens.Type
authored
133 ------------------------------------------------------------------------------
134 -- Traversals
135 ------------------------------------------------------------------------------
136
137 -- | A 'Traversal' can be used directly as a 'Control.Lens.Setter.Setter' or a 'Fold' (but not as a 'Lens') and provides
138 -- the ability to both read and update multiple fields, subject to some relatively weak 'Traversal' laws.
139 --
140 -- These have also been known as multilenses, but they have the signature and spirit of
141 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
142 -- @'Data.Traversable.traverse' :: 'Data.Traversable.Traversable' f => 'Traversal' (f a) (f b) a b@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
143 --
144 -- and the more evocative name suggests their application.
145 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
146 -- Most of the time the 'Traversal' you will want to use is just 'Data.Traversable.traverse', but you can also pass any
6be7786 @ekmett Factoring out Control.Lens.Type
authored
147 -- 'Lens' or 'Iso' as a 'Traversal', and composition of a 'Traversal' (or 'Lens' or 'Iso') with a 'Traversal' (or 'Lens' or 'Iso')
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
148 -- using ('.') forms a valid 'Traversal'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
149 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
150 -- The laws for a 'Traversal' @t@ follow from the laws for 'Data.Traversable.Traversable' as stated in \"The Essence of the Iterator Pattern\".
6be7786 @ekmett Factoring out Control.Lens.Type
authored
151 --
152 -- @
153 -- t 'pure' ≡ 'pure'
154 -- 'fmap' (t f) '.' t g ≡ 'Data.Functor.Compose.getCompose' '.' t ('Data.Functor.Compose.Compose' '.' 'fmap' f '.' g)
155 -- @
156 --
157 -- One consequence of this requirement is that a 'Traversal' needs to leave the same number of elements as a
158 -- candidate for subsequent 'Traversal' that it started with. Another testament to the strength of these laws
159 -- is that the caveat expressed in section 5.5 of the \"Essence of the Iterator Pattern\" about exotic
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
160 -- 'Data.Traversable.Traversable' instances that 'Data.Traversable.traverse' the same entry multiple times was actually already ruled out by the
6be7786 @ekmett Factoring out Control.Lens.Type
authored
161 -- second law in that same paper!
162 type Traversal s t a b = forall f. Applicative f => (a -> f b) -> s -> f t
163
164 -- | @type 'Traversal'' = 'Simple' 'Traversal'@
165 type Traversal' s a = Traversal s s a a
166
9eaef5c @basdirks haddocks: misc
basdirks authored
167 -- | Every 'IndexedTraversal' is a valid 'Control.Lens.Traversal.Traversal' or
6be7786 @ekmett Factoring out Control.Lens.Type
authored
168 -- 'Control.Lens.Fold.IndexedFold'.
169 --
170 -- The 'Indexed' constraint is used to allow an 'IndexedTraversal' to be used
171 -- directly as a 'Control.Lens.Traversal.Traversal'.
172 --
173 -- The 'Control.Lens.Traversal.Traversal' laws are still required to hold.
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
174 type IndexedTraversal i s t a b = forall p f. (Indexable i p, Applicative f) => p a (f b) -> s -> f t
6be7786 @ekmett Factoring out Control.Lens.Type
authored
175
176 -- | @type 'IndexedTraversal'' i = 'Simple' ('IndexedTraversal' i)@
177 type IndexedTraversal' i s a = IndexedTraversal i s s a a
178
d7a3589 @ekmett more docs
authored
179 -- | An 'IndexPreservingLens' leaves any index it is composed with alone.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
180 type IndexPreservingTraversal s t a b = forall p f. (Conjoined p, Applicative f) => p a (f b) -> p s (f t)
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
181
d7a3589 @ekmett more docs
authored
182 -- | @type 'IndexPreservingTraversal'' = 'Simple' 'IndexPreservingTraversal'@
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
183 type IndexPreservingTraversal' s a = IndexPreservingTraversal s s a a
184
6be7786 @ekmett Factoring out Control.Lens.Type
authored
185 ------------------------------------------------------------------------------
186 -- Setters
187 ------------------------------------------------------------------------------
188
7a1c95e @basdirks haddocks: post-"Internalization" clean-up, round 3
basdirks authored
189 -- | The only 'LensLike' law that can apply to a 'Setter' @l@ is that
6be7786 @ekmett Factoring out Control.Lens.Type
authored
190 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
191 -- @'Control.Lens.Setter.set' l y ('Control.Lens.Setter.set' l x a) ≡ 'Control.Lens.Setter.set' l y a@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
192 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
193 -- You can't 'Control.Lens.Getter.view' a 'Setter' in general, so the other two laws are irrelevant.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
194 --
195 -- However, two 'Functor' laws apply to a 'Setter':
196 --
197 -- @
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
198 -- 'Control.Lens.Setter.over' l 'id' ≡ 'id'
199 -- 'Control.Lens.Setter.over' l f '.' 'Control.Lens.Setter.over' l g ≡ 'Control.Lens.Setter.over' l (f '.' g)
6be7786 @ekmett Factoring out Control.Lens.Type
authored
200 -- @
201 --
9eaef5c @basdirks haddocks: misc
basdirks authored
202 -- These can be stated more directly:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
203 --
204 -- @
205 -- l 'pure' ≡ 'pure'
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
206 -- l f '.' 'untainted' '.' l g ≡ l (f '.' 'untainted' '.' g)
6be7786 @ekmett Factoring out Control.Lens.Type
authored
207 -- @
208 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
209 -- You can compose a 'Setter' with a 'Lens' or a 'Traversal' using ('.') from the @Prelude@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
210 -- and the result is always only a 'Setter' and nothing more.
211 --
212 -- >>> over traverse f [a,b,c,d]
213 -- [f a,f b,f c,f d]
214 --
215 -- >>> over _1 f (a,b)
216 -- (f a,b)
217 --
218 -- >>> over (traverse._1) f [(a,b),(c,d)]
219 -- [(f a,b),(f c,d)]
220 --
221 -- >>> over both f (a,b)
222 -- (f a,f b)
223 --
224 -- >>> over (traverse.both) f [(a,b),(c,d)]
225 -- [(f a,f b),(f c,f d)]
226 type Setter s t a b = forall f. Settable f => (a -> f b) -> s -> f t
227
be96579 @basdirks haddocks: linking, formatting and periods in Cons, Each, Equality, Fo…
basdirks authored
228 -- | A 'Setter'' is just a 'Setter' that doesn't change the types.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
229 --
230 -- These are particularly common when talking about monomorphic containers. /e.g./
231 --
232 -- @'sets' Data.Text.map :: 'Setter'' 'Data.Text.Internal.Text' 'Char'@
233 --
234 -- @type 'Setter'' = 'Setter''@
235 type Setter' s a = Setter s s a a
236
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
237 -- | Every 'IndexedSetter' is a valid 'Setter'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
238 --
239 -- The 'Setter' laws are still required to hold.
240 type IndexedSetter i s t a b = forall f p.
241 (Indexable i p, Settable f) => p a (f b) -> s -> f t
242
be96579 @basdirks haddocks: linking, formatting and periods in Cons, Each, Equality, Fo…
basdirks authored
243 -- | @type 'IndexedSetter'' i = 'Simple' ('IndexedSetter' i)@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
244 type IndexedSetter' i s a = IndexedSetter i s s a a
245
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
246 -- | An 'IndexPreservingSetter' can be composed with a 'IndexedSetter', 'IndexedTraversal' or 'IndexedLens'
247 -- and leaves the index intact, yielding an 'IndexedSetter'.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
248 type IndexPreservingSetter s t a b = forall p f. (Conjoined p, Settable f) => p a (f b) -> p s (f t)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
249
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
250 type IndexPreservingSetter' s a = IndexPreservingSetter s s a a
251
6be7786 @ekmett Factoring out Control.Lens.Type
authored
252 -----------------------------------------------------------------------------
253 -- Isomorphisms
254 -----------------------------------------------------------------------------
255
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
256 -- | Isomorphism families can be composed with another 'Lens' using ('.') and 'id'.
5291c96 @ekmett Added notes about the index-preserving nature of Iso, Prism and Equal…
authored
257 --
a2cd8c1 @ekmett lots of new types
authored
258 -- Note: Composition with an 'Iso' is index- and measure- preserving.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
259 type Iso s t a b = forall p f. (Profunctor p, Functor f) => p a (f b) -> p s (f t)
260
be96579 @basdirks haddocks: linking, formatting and periods in Cons, Each, Equality, Fo…
basdirks authored
261 -- | @type 'Iso'' = 'Control.Lens.Type.Simple' 'Iso'@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
262 type Iso' s a = Iso s s a a
263
264 ------------------------------------------------------------------------------
265 -- Prism Internals
266 ------------------------------------------------------------------------------
267
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
268 -- | A 'Prism' @l@ is a 0-or-1 target 'Traversal' that can also be turned
544cdaa @ehird Remove references to remit from the documentation
ehird authored
269 -- around with 'Control.Lens.Review.re' to obtain a 'Getter' in the
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
270 -- opposite direction.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
271 --
272 -- There are two laws that a 'Prism' should satisfy:
273 --
544cdaa @ehird Remove references to remit from the documentation
ehird authored
274 -- First, if I 'Control.Lens.Review.re' or 'Control.Lens.Prism.review' a value with a 'Prism' and then 'Control.Lens.Prism.preview' or use ('Control.Lens.Fold.^?'), I will get it back:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
275 --
276 -- * @'Control.Lens.Prism.preview' l ('Control.Lens.Prism.review' l b) ≡ 'Just' b@
277 --
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
278 -- Second, if you can extract a value @a@ using a 'Prism' @l@ from a value @s@, then the value @s@ is completely described my @l@ and @a@:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
279 --
280 -- * If @'Control.Lens.Prism.preview' l s ≡ 'Just' a@ then @'Control.Lens.Prism.review' l a ≡ s@
281 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
282 -- These two laws imply that the 'Traversal' laws hold for every 'Prism' and that we 'Data.Traversable.traverse' at most 1 element:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
283 --
284 -- @'Control.Lens.Fold.lengthOf' l x '<=' 1@
285 --
286 -- It may help to think of this as a 'Iso' that can be partial in one direction.
287 --
288 -- Every 'Prism' is a valid 'Traversal'.
289 --
290 -- Every 'Iso' is a valid 'Prism'.
291 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
292 -- For example, you might have a @'Prism'' 'Integer' 'Numeric.Natural.Natural'@ allows you to always
293 -- go from a 'Numeric.Natural.Natural' to an 'Integer', and provide you with tools to check if an 'Integer' is
294 -- a 'Numeric.Natural.Natural' and/or to edit one if it is.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
295 --
296 --
297 -- @
298 -- 'nat' :: 'Prism'' 'Integer' 'Numeric.Natural.Natural'
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
299 -- 'nat' = 'Control.Lens.Prism.prism' 'toInteger' '$' \\ i ->
6be7786 @ekmett Factoring out Control.Lens.Type
authored
300 -- if i '<' 0
301 -- then 'Left' i
302 -- else 'Right' ('fromInteger' i)
303 -- @
304 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
305 -- Now we can ask if an 'Integer' is a 'Numeric.Natural.Natural'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
306 --
307 -- >>> 5^?nat
308 -- Just 5
309 --
310 -- >>> (-5)^?nat
311 -- Nothing
312 --
313 -- We can update the ones that are:
314 --
315 -- >>> (-3,4) & both.nat *~ 2
316 -- (-3,8)
317 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
318 -- And we can then convert from a 'Numeric.Natural.Natural' to an 'Integer'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
319 --
1d79c2d @ekmett Converted `remit` to `re` in doctests and other test suites.
authored
320 -- >>> 5 ^. re nat -- :: Natural
6be7786 @ekmett Factoring out Control.Lens.Type
authored
321 -- 5
322 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
323 -- Similarly we can use a 'Prism' to 'Data.Traversable.traverse' the left half of an 'Either':
6be7786 @ekmett Factoring out Control.Lens.Type
authored
324 --
78a1d4f @ekmett Renamed _left -> _Left, _right -> _Right, _just -> _Just for consistency
authored
325 -- >>> Left "hello" & _Left %~ length
6be7786 @ekmett Factoring out Control.Lens.Type
authored
326 -- Left 5
327 --
328 -- or to construct an 'Either':
329 --
78a1d4f @ekmett Renamed _left -> _Left, _right -> _Right, _just -> _Just for consistency
authored
330 -- >>> 5^.re _Left
6be7786 @ekmett Factoring out Control.Lens.Type
authored
331 -- Left 5
332 --
333 -- such that if you query it with the 'Prism', you will get your original input back.
334 --
78a1d4f @ekmett Renamed _left -> _Left, _right -> _Right, _just -> _Just for consistency
authored
335 -- >>> 5^.re _Left ^? _Left
6be7786 @ekmett Factoring out Control.Lens.Type
authored
336 -- Just 5
337 --
338 -- Another interesting way to think of a 'Prism' is as the categorical dual of a 'Lens'
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
339 -- -- a /co/-'Lens', so to speak. This is what permits the construction of 'Control.Lens.Prism.outside'.
5291c96 @ekmett Added notes about the index-preserving nature of Iso, Prism and Equal…
authored
340 --
ffe3253 @ekmett s/Iso/Prism
authored
341 -- Note: Composition with a 'Prism' is index-preserving.
90bef20 @ekmett Converted to using Choice and Strong
authored
342 type Prism s t a b = forall p f. (Choice p, Applicative f) => p a (f b) -> p s (f t)
6be7786 @ekmett Factoring out Control.Lens.Type
authored
343
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
344 -- | A 'Simple' 'Prism'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
345 type Prism' s a = Prism s s a a
346
347 -------------------------------------------------------------------------------
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
348 -- Equality
349 -------------------------------------------------------------------------------
350
a142679 @basdirks haddocks: more linking
basdirks authored
351 -- | A witness that @(a ~ s, b ~ t)@.
5291c96 @ekmett Added notes about the index-preserving nature of Iso, Prism and Equal…
authored
352 --
353 -- Note: Composition with an 'Equality' is index-preserving.
b54e109 @shachaf (f :: * -> *) in the definition of Equality
shachaf authored
354 type Equality s t a b = forall p (f :: * -> *). p a (f b) -> p s (f t)
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
355
9eaef5c @basdirks haddocks: misc
basdirks authored
356 -- | A 'Simple' 'Equality'.
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
357 type Equality' s a = Equality s s a a
358
359 -------------------------------------------------------------------------------
6be7786 @ekmett Factoring out Control.Lens.Type
authored
360 -- Getters
361 -------------------------------------------------------------------------------
362
363 -- | A 'Getter' describes how to retrieve a single value in a way that can be
7a1c95e @basdirks haddocks: post-"Internalization" clean-up, round 3
basdirks authored
364 -- composed with other 'LensLike' constructions.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
365 --
366 -- Unlike a 'Lens' a 'Getter' is read-only. Since a 'Getter'
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
367 -- cannot be used to write back there are no 'Lens' laws that can be applied to
6be7786 @ekmett Factoring out Control.Lens.Type
authored
368 -- it. In fact, it is isomorphic to an arbitrary function from @(a -> s)@.
369 --
370 -- Moreover, a 'Getter' can be used directly as a 'Control.Lens.Fold.Fold',
371 -- since it just ignores the 'Applicative'.
372 type Getter s a = forall f. Gettable f => (a -> f a) -> s -> f s
373
70c7f3e @basdirks Getter.hs haddocks formatting, punctuation and linking.
basdirks authored
374 -- | Every 'IndexedGetter' is a valid 'Control.Lens.Fold.IndexedFold' and can be used for 'Control.Lens.Getter.Getting' like a 'Getter'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
375 type IndexedGetter i s a = forall p f. (Indexable i p, Gettable f) => p a (f a) -> s -> f s
376
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
377 -- | An 'IndexPreservingGetter' can be used as a 'Getter', but when composed with an 'IndexedTraversal',
378 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold', 'IndexedFold' or 'IndexedGetter' respectively.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
379 type IndexPreservingGetter s a = forall p f. (Conjoined p, Gettable f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
380
6be7786 @ekmett Factoring out Control.Lens.Type
authored
381 --------------------------
382 -- Folds
383 --------------------------
384
385 -- | A 'Fold' describes how to retrieve multiple values in a way that can be composed
7a1c95e @basdirks haddocks: post-"Internalization" clean-up, round 3
basdirks authored
386 -- with other 'LensLike' constructions.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
387 --
a142679 @basdirks haddocks: more linking
basdirks authored
388 -- A @'Fold' s a@ provides a structure with operations very similar to those of the 'Data.Foldable.Foldable'
389 -- typeclass, see 'Control.Lens.Fold.foldMapOf' and the other 'Fold' combinators.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
390 --
a142679 @basdirks haddocks: more linking
basdirks authored
391 -- By convention, if there exists a 'foo' method that expects a @'Data.Foldable.Foldable' (f a)@, then there should be a
6be7786 @ekmett Factoring out Control.Lens.Type
authored
392 -- @fooOf@ method that takes a @'Fold' s a@ and a value of type @s@.
393 --
a142679 @basdirks haddocks: more linking
basdirks authored
394 -- A 'Getter' is a legal 'Fold' that just ignores the supplied 'Data.Monoid.Monoid'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
395 --
396 -- Unlike a 'Control.Lens.Traversal.Traversal' a 'Fold' is read-only. Since a 'Fold' cannot be used to write back
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
397 -- there are no 'Lens' laws that apply.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
398 type Fold s a = forall f. (Gettable f, Applicative f) => (a -> f a) -> s -> f s
399
a142679 @basdirks haddocks: more linking
basdirks authored
400 -- | Every 'IndexedFold' is a valid 'Control.Lens.Fold.Fold' and can be used for 'Control.Lens.Getter.Getting'.
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
401 type IndexedFold i s a = forall p f. (Indexable i p, Applicative f, Gettable f) => p a (f a) -> s -> f s
6be7786 @ekmett Factoring out Control.Lens.Type
authored
402
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
403 -- | An 'IndexPreservingFold' can be used as a 'Fold', but when composed with an 'IndexedTraversal',
404 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold' respectively.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
405 type IndexPreservingFold s a = forall p f. (Conjoined p, Gettable f, Applicative f) => p a (f a) -> p s (f s)
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
406
6be7786 @ekmett Factoring out Control.Lens.Type
authored
407 -------------------------------------------------------------------------------
408 -- Actions
409 -------------------------------------------------------------------------------
410
411 -- | An 'Action' is a 'Getter' enriched with access to a 'Monad' for side-effects.
412 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
413 -- Every 'Getter' can be used as an 'Action'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
414 --
415 -- You can compose an 'Action' with another 'Action' using ('Prelude..') from the @Prelude@.
416 type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s
417
418 -- | An 'IndexedAction' is an 'IndexedGetter' enriched with access to a 'Monad' for side-effects.
419 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
420 -- Every 'Getter' can be used as an 'Action'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
421 --
422 -- You can compose an 'Action' with another 'Action' using ('Prelude..') from the @Prelude@.
423 type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s
424
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
425 -- | An 'IndexPreservingAction' can be used as a 'Action', but when composed with an 'IndexedTraversal',
426 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedMonadicFold', 'IndexedMonadicFold' or 'IndexedAction' respectively.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
427 type IndexPreservingAction m s a = forall p f r. (Conjoined p, Effective m r f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
428
6be7786 @ekmett Factoring out Control.Lens.Type
authored
429 -------------------------------------------------------------------------------
430 -- MonadicFolds
431 -------------------------------------------------------------------------------
432
433 -- | A 'MonadicFold' is a 'Fold' enriched with access to a 'Monad' for side-effects.
434 --
435 -- Every 'Fold' can be used as a 'MonadicFold', that simply ignores the access to the 'Monad'.
436 --
437 -- You can compose a 'MonadicFold' with another 'MonadicFold' using ('Prelude..') from the @Prelude@.
438 type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s
439
440 -- | An 'IndexedMonadicFold' is an 'IndexedFold' enriched with access to a 'Monad' for side-effects.
441 --
442 -- Every 'IndexedFold' can be used as an 'IndexedMonadicFold', that simply ignores the access to the 'Monad'.
443 --
444 -- You can compose an 'IndexedMonadicFold' with another 'IndexedMonadicFold' using ('Prelude..') from the @Prelude@.
445 type IndexedMonadicFold i m s a = forall p f r. (Indexable i p, Effective m r f, Applicative f) => p a (f a) -> s -> f s
446
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
447 -- | An 'IndexPreservingFold' can be used as a 'Fold', but when composed with an 'IndexedTraversal',
448 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold' respectively.
a8f2396 @ekmett Split Control.Lens.Internal into several modules. Added many missing …
authored
449 type IndexPreservingMonadicFold m s a = forall p f r. (Conjoined p, Effective m r f, Applicative f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
450
6be7786 @ekmett Factoring out Control.Lens.Type
authored
451 -------------------------------------------------------------------------------
452 -- Simple Overloading
453 -------------------------------------------------------------------------------
454
455 -- | A 'Simple' 'Lens', 'Simple' 'Traversal', ... can
456 -- be used instead of a 'Lens','Traversal', ...
457 -- whenever the type variables don't change upon setting a value.
458 --
459 -- @
460 -- 'Data.Complex.Lens.imaginary' :: 'Simple' 'Lens' ('Data.Complex.Complex' a) a
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
461 -- 'Data.List.Lens._head' :: 'Simple' 'IndexedTraversal' 'Int' [a] a
6be7786 @ekmett Factoring out Control.Lens.Type
authored
462 -- @
463 --
464 -- Note: To use this alias in your own code with @'LensLike' f@ or
465 -- 'Setter', you may have to turn on @LiberalTypeSynonyms@.
466 --
467 -- This is commonly abbreviated as a \"prime\" marker, /e.g./ 'Lens'' = 'Simple' 'Lens'.
468 type Simple f s a = f s s a a
469
470 -- | @type 'LensLike' f s t a b = 'Overloading' (->) (->) f s t a b@
471 type Overloading p q f s t a b = p a (f b) -> q s (f t)
472
473 -- | @type 'Overloading'' p q f s a = 'Simple' ('Overloading' p q f) s a@
474 type Overloading' p q f s a = Overloading p q f s s a a
475
6687426 @ekmett more equalities and docfixes
authored
476 -- | @type 'LensLike' f s t a b = 'Overloaded' (->) f s t a b@
477 type Overloaded p f s t a b = p a (f b) -> p s (f t)
478
479 -- | @type 'Overloaded'' p q f s a = 'Simple' ('Overloaded' p q f) s a@
480 type Overloaded' p f s a = Overloaded p f s s a a
481
be96579 @basdirks haddocks: linking, formatting and periods in Cons, Each, Equality, Fo…
basdirks authored
482 -- | Many combinators that accept a 'Lens' can also accept a
6be7786 @ekmett Factoring out Control.Lens.Type
authored
483 -- 'Traversal' in limited situations.
484 --
485 -- They do so by specializing the type of 'Functor' that they require of the
486 -- caller.
487 --
488 -- If a function accepts a @'LensLike' f s t a b@ for some 'Functor' @f@,
489 -- then they may be passed a 'Lens'.
490 --
491 -- Further, if @f@ is an 'Applicative', they may also be passed a
492 -- 'Traversal'.
493 type LensLike f s t a b = (a -> f b) -> s -> f t
494
495 -- | @type 'LensLike'' f = 'Simple' ('LensLike' f)@
496 type LensLike' f s a = LensLike f s s a a
497
105b1b4 @basdirks haddocks: post-"Internalization" clean-up, round 4
basdirks authored
498 -- | Convenient alias for constructing indexed lenses and their ilk.
3fe8e0b @ekmett Removed more q Profunctor references
authored
499 type IndexedLensLike i f s t a b = forall p. Indexable i p => p a (f b) -> s -> f t
6be7786 @ekmett Factoring out Control.Lens.Type
authored
500
105b1b4 @basdirks haddocks: post-"Internalization" clean-up, round 4
basdirks authored
501 -- | Convenient alias for constructing simple indexed lenses and their ilk.
3fe8e0b @ekmett Removed more q Profunctor references
authored
502 type IndexedLensLike' i f s a = IndexedLensLike i f s s a a
503
504 type Lensing p f s t a b = p a (f b) -> s -> f t
505
506 type Lensing' p f s a = Lensing p f s s a a
Something went wrong with that request. Please try again.