Skip to content

HTTPS clone URL

Subversion checkout URL

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