Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 510 lines (449 sloc) 20.976 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.
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
125 type IndexPreservingLens s t a b = forall p f. (SelfAdjoint p, Functor f) => p a (f b) -> p s (f t)
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.
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
177 type IndexPreservingTraversal s t a b = forall p f. (SelfAdjoint p, Applicative f) => p a (f b) -> p s (f t)
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
186 -- |
187 -- The only 'Lens'-like law that can apply to a 'Setter' @l@ is that
188 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
189 -- @'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
190 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
191 -- 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
192 --
193 -- However, two 'Functor' laws apply to a 'Setter':
194 --
195 -- @
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
196 -- 'Control.Lens.Setter.over' l 'id' ≡ 'id'
197 -- '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
198 -- @
199 --
9eaef5c @basdirks haddocks: misc
basdirks authored
200 -- These can be stated more directly:
6be7786 @ekmett Factoring out Control.Lens.Type
authored
201 --
202 -- @
203 -- l 'pure' ≡ 'pure'
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
204 -- l f '.' 'untainted' '.' l g ≡ l (f '.' 'untainted' '.' g)
6be7786 @ekmett Factoring out Control.Lens.Type
authored
205 -- @
206 --
f5f1b94 @basdirks haddocks: linking in Setter and Type
basdirks authored
207 -- You can compose a 'Setter' with a 'Lens' or a 'Traversal' using ('.') from the @Prelude@
6be7786 @ekmett Factoring out Control.Lens.Type
authored
208 -- and the result is always only a 'Setter' and nothing more.
209 --
210 -- >>> over traverse f [a,b,c,d]
211 -- [f a,f b,f c,f d]
212 --
213 -- >>> over _1 f (a,b)
214 -- (f a,b)
215 --
216 -- >>> over (traverse._1) f [(a,b),(c,d)]
217 -- [(f a,b),(f c,d)]
218 --
219 -- >>> over both f (a,b)
220 -- (f a,f b)
221 --
222 -- >>> over (traverse.both) f [(a,b),(c,d)]
223 -- [(f a,f b),(f c,f d)]
224 type Setter s t a b = forall f. Settable f => (a -> f b) -> s -> f t
225
226 -- |
227 --
228 -- A 'Setter'' is just a 'Setter' that doesn't change the types.
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
243 -- |
244 -- @type 'IndexedSetter'' i = 'Simple' ('IndexedSetter' i)@
245 type IndexedSetter' i s a = IndexedSetter i s s a a
246
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
247 -- | An 'IndexPreservingSetter' can be composed with a 'IndexedSetter', 'IndexedTraversal' or 'IndexedLens'
248 -- and leaves the index intact, yielding an 'IndexedSetter'.
2e40da2 @ekmett switched to self-adjoint in signatures
authored
249 type IndexPreservingSetter s t a b = forall p f. (SelfAdjoint p, Settable f) => p a (f b) -> p s (f t)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
250
f47d227 @ekmett Added cloneIndexPreservingLens, cloneIndexPreservingTraversal, cloneI…
authored
251 type IndexPreservingSetter' s a = IndexPreservingSetter s s a a
252
6be7786 @ekmett Factoring out Control.Lens.Type
authored
253 -----------------------------------------------------------------------------
254 -- Isomorphisms
255 -----------------------------------------------------------------------------
256
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
257 -- | 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
258 --
a2cd8c1 @ekmett lots of new types
authored
259 -- Note: Composition with an 'Iso' is index- and measure- preserving.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
260 type Iso s t a b = forall p f. (Profunctor p, Functor f) => p a (f b) -> p s (f t)
261
262 -- |
263 -- @type 'Iso'' = 'Control.Lens.Type.Simple' 'Iso'@
264 type Iso' s a = Iso s s a a
265
266 ------------------------------------------------------------------------------
267 -- Prism Internals
268 ------------------------------------------------------------------------------
269
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
270 -- | A 'Prism' @l@ is a 0-or-1 target 'Traversal' that can also be turned
271 -- around with 'Control.Lens.Review.remit' to obtain a 'Getter' in the
272 -- opposite direction.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
273 --
274 -- There are two laws that a 'Prism' should satisfy:
275 --
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
276 -- 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
277 --
278 -- * @'Control.Lens.Prism.preview' l ('Control.Lens.Prism.review' l b) ≡ 'Just' b@
279 --
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
280 -- 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
281 --
282 -- * If @'Control.Lens.Prism.preview' l s ≡ 'Just' a@ then @'Control.Lens.Prism.review' l a ≡ s@
283 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
284 -- 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
285 --
286 -- @'Control.Lens.Fold.lengthOf' l x '<=' 1@
287 --
288 -- It may help to think of this as a 'Iso' that can be partial in one direction.
289 --
290 -- Every 'Prism' is a valid 'Traversal'.
291 --
292 -- Every 'Iso' is a valid 'Prism'.
293 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
294 -- For example, you might have a @'Prism'' 'Integer' 'Numeric.Natural.Natural'@ allows you to always
295 -- go from a 'Numeric.Natural.Natural' to an 'Integer', and provide you with tools to check if an 'Integer' is
296 -- a 'Numeric.Natural.Natural' and/or to edit one if it is.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
297 --
298 --
299 -- @
300 -- 'nat' :: 'Prism'' 'Integer' 'Numeric.Natural.Natural'
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
301 -- 'nat' = 'Control.Lens.Prism.prism' 'toInteger' '$' \\ i ->
6be7786 @ekmett Factoring out Control.Lens.Type
authored
302 -- if i '<' 0
303 -- then 'Left' i
304 -- else 'Right' ('fromInteger' i)
305 -- @
306 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
307 -- Now we can ask if an 'Integer' is a 'Numeric.Natural.Natural'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
308 --
309 -- >>> 5^?nat
310 -- Just 5
311 --
312 -- >>> (-5)^?nat
313 -- Nothing
314 --
315 -- We can update the ones that are:
316 --
317 -- >>> (-3,4) & both.nat *~ 2
318 -- (-3,8)
319 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
320 -- And we can then convert from a 'Numeric.Natural.Natural' to an 'Integer'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
321 --
322 -- >>> 5 ^. remit nat -- :: Natural
323 -- 5
324 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
325 -- Similarly we can use a 'Prism' to 'Data.Traversable.traverse' the left half of an 'Either':
6be7786 @ekmett Factoring out Control.Lens.Type
authored
326 --
327 -- >>> Left "hello" & _left %~ length
328 -- Left 5
329 --
330 -- or to construct an 'Either':
331 --
332 -- >>> 5^.remit _left
333 -- Left 5
334 --
335 -- such that if you query it with the 'Prism', you will get your original input back.
336 --
337 -- >>> 5^.remit _left ^? _left
338 -- Just 5
339 --
340 -- 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
341 -- -- 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
342 --
ffe3253 @ekmett s/Iso/Prism
authored
343 -- Note: Composition with a 'Prism' is index-preserving.
ad03738 @ekmett Revert "Switched from Prismatic to Prismal."
authored
344 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
345
215d32b @basdirks haddocks cosmetics in Prism, Reified, Type
basdirks authored
346 -- | A 'Simple' 'Prism'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
347 type Prism' s a = Prism s s a a
348
349 -------------------------------------------------------------------------------
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
350 -- Equality
351 -------------------------------------------------------------------------------
352
a142679 @basdirks haddocks: more linking
basdirks authored
353 -- | A witness that @(a ~ s, b ~ t)@.
5291c96 @ekmett Added notes about the index-preserving nature of Iso, Prism and Equal…
authored
354 --
355 -- Note: Composition with an 'Equality' is index-preserving.
b54e109 @shachaf (f :: * -> *) in the definition of Equality
shachaf authored
356 type Equality s t a b = forall p (f :: * -> *). p a (f b) -> p s (f t)
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
357
9eaef5c @basdirks haddocks: misc
basdirks authored
358 -- | A 'Simple' 'Equality'.
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
359 type Equality' s a = Equality s s a a
360
361 -------------------------------------------------------------------------------
6be7786 @ekmett Factoring out Control.Lens.Type
authored
362 -- Getters
363 -------------------------------------------------------------------------------
364
365 -- | A 'Getter' describes how to retrieve a single value in a way that can be
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
366 -- composed with other 'Lens'-like constructions.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
367 --
368 -- Unlike a 'Lens' a 'Getter' is read-only. Since a 'Getter'
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
369 -- cannot be used to write back there are no 'Lens' laws that can be applied to
6be7786 @ekmett Factoring out Control.Lens.Type
authored
370 -- it. In fact, it is isomorphic to an arbitrary function from @(a -> s)@.
371 --
372 -- Moreover, a 'Getter' can be used directly as a 'Control.Lens.Fold.Fold',
373 -- since it just ignores the 'Applicative'.
374 type Getter s a = forall f. Gettable f => (a -> f a) -> s -> f s
375
70c7f3e @basdirks Getter.hs haddocks formatting, punctuation and linking.
basdirks authored
376 -- | 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
377 type IndexedGetter i s a = forall p f. (Indexable i p, Gettable f) => p a (f a) -> s -> f s
378
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
379 -- | An 'IndexPreservingGetter' can be used as a 'Getter', but when composed with an 'IndexedTraversal',
380 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold', 'IndexedFold' or 'IndexedGetter' respectively.
2e40da2 @ekmett switched to self-adjoint in signatures
authored
381 type IndexPreservingGetter s a = forall p f. (SelfAdjoint p, Gettable f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
382
6be7786 @ekmett Factoring out Control.Lens.Type
authored
383 --------------------------
384 -- Folds
385 --------------------------
386
387 -- | A 'Fold' describes how to retrieve multiple values in a way that can be composed
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
388 -- with other 'Lens'-like constructions.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
389 --
a142679 @basdirks haddocks: more linking
basdirks authored
390 -- A @'Fold' s a@ provides a structure with operations very similar to those of the 'Data.Foldable.Foldable'
391 -- typeclass, see 'Control.Lens.Fold.foldMapOf' and the other 'Fold' combinators.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
392 --
a142679 @basdirks haddocks: more linking
basdirks authored
393 -- 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
394 -- @fooOf@ method that takes a @'Fold' s a@ and a value of type @s@.
395 --
a142679 @basdirks haddocks: more linking
basdirks authored
396 -- A 'Getter' is a legal 'Fold' that just ignores the supplied 'Data.Monoid.Monoid'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
397 --
398 -- 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
399 -- there are no 'Lens' laws that apply.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
400 type Fold s a = forall f. (Gettable f, Applicative f) => (a -> f a) -> s -> f s
401
a142679 @basdirks haddocks: more linking
basdirks authored
402 -- | Every 'IndexedFold' is a valid 'Control.Lens.Fold.Fold' and can be used for 'Control.Lens.Getter.Getting'.
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
403 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
404
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
405 -- | An 'IndexPreservingFold' can be used as a 'Fold', but when composed with an 'IndexedTraversal',
406 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold' respectively.
2e40da2 @ekmett switched to self-adjoint in signatures
authored
407 type IndexPreservingFold s a = forall p f. (SelfAdjoint p, Gettable f, Applicative f) => p a (f a) -> p s (f s)
3ce55f4 @ekmett Added 'Control.Lens.Equality'
authored
408
6be7786 @ekmett Factoring out Control.Lens.Type
authored
409 -------------------------------------------------------------------------------
410 -- Actions
411 -------------------------------------------------------------------------------
412
413 -- | An 'Action' is a 'Getter' enriched with access to a 'Monad' for side-effects.
414 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
415 -- Every 'Getter' can be used as an 'Action'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
416 --
417 -- You can compose an 'Action' with another 'Action' using ('Prelude..') from the @Prelude@.
418 type Action m s a = forall f r. Effective m r f => (a -> f a) -> s -> f s
419
420 -- | An 'IndexedAction' is an 'IndexedGetter' enriched with access to a 'Monad' for side-effects.
421 --
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
422 -- Every 'Getter' can be used as an 'Action'.
6be7786 @ekmett Factoring out Control.Lens.Type
authored
423 --
424 -- You can compose an 'Action' with another 'Action' using ('Prelude..') from the @Prelude@.
425 type IndexedAction i m s a = forall p f r. (Indexable i p, Effective m r f) => p a (f a) -> s -> f s
426
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
427 -- | An 'IndexPreservingAction' can be used as a 'Action', but when composed with an 'IndexedTraversal',
428 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedMonadicFold', 'IndexedMonadicFold' or 'IndexedAction' respectively.
2e40da2 @ekmett switched to self-adjoint in signatures
authored
429 type IndexPreservingAction m s a = forall p f r. (SelfAdjoint p, Effective m r f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
430
6be7786 @ekmett Factoring out Control.Lens.Type
authored
431 -------------------------------------------------------------------------------
432 -- MonadicFolds
433 -------------------------------------------------------------------------------
434
435 -- | A 'MonadicFold' is a 'Fold' enriched with access to a 'Monad' for side-effects.
436 --
437 -- Every 'Fold' can be used as a 'MonadicFold', that simply ignores the access to the 'Monad'.
438 --
439 -- You can compose a 'MonadicFold' with another 'MonadicFold' using ('Prelude..') from the @Prelude@.
440 type MonadicFold m s a = forall f r. (Effective m r f, Applicative f) => (a -> f a) -> s -> f s
441
442 -- | An 'IndexedMonadicFold' is an 'IndexedFold' enriched with access to a 'Monad' for side-effects.
443 --
444 -- Every 'IndexedFold' can be used as an 'IndexedMonadicFold', that simply ignores the access to the 'Monad'.
445 --
446 -- You can compose an 'IndexedMonadicFold' with another 'IndexedMonadicFold' using ('Prelude..') from the @Prelude@.
447 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
448
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
449 -- | An 'IndexPreservingFold' can be used as a 'Fold', but when composed with an 'IndexedTraversal',
450 -- 'IndexedFold', or 'IndexedLens' yields an 'IndexedFold' respectively.
2e40da2 @ekmett switched to self-adjoint in signatures
authored
451 type IndexPreservingMonadicFold m s a = forall p f r. (SelfAdjoint p, Effective m r f, Applicative f) => p a (f a) -> p s (f s)
918cd2d @ekmett IndexPreservingGetters, IndexPreservingFolds, IndexPreservingSetters,…
authored
452
6be7786 @ekmett Factoring out Control.Lens.Type
authored
453 -------------------------------------------------------------------------------
454 -- Simple Overloading
455 -------------------------------------------------------------------------------
456
457 -- | A 'Simple' 'Lens', 'Simple' 'Traversal', ... can
458 -- be used instead of a 'Lens','Traversal', ...
459 -- whenever the type variables don't change upon setting a value.
460 --
461 -- @
462 -- 'Data.Complex.Lens.imaginary' :: 'Simple' 'Lens' ('Data.Complex.Complex' a) a
d5b5a70 @basdirks haddocks: linking in Type
basdirks authored
463 -- 'Data.List.Lens._head' :: 'Simple' 'IndexedTraversal' 'Int' [a] a
6be7786 @ekmett Factoring out Control.Lens.Type
authored
464 -- @
465 --
466 -- Note: To use this alias in your own code with @'LensLike' f@ or
467 -- 'Setter', you may have to turn on @LiberalTypeSynonyms@.
468 --
469 -- This is commonly abbreviated as a \"prime\" marker, /e.g./ 'Lens'' = 'Simple' 'Lens'.
470 type Simple f s a = f s s a a
471
472 -- | @type 'LensLike' f s t a b = 'Overloading' (->) (->) f s t a b@
473 type Overloading p q f s t a b = p a (f b) -> q s (f t)
474
475 -- | @type 'Overloading'' p q f s a = 'Simple' ('Overloading' p q f) s a@
476 type Overloading' p q f s a = Overloading p q f s s a a
477
6687426 @ekmett more equalities and docfixes
authored
478 -- | @type 'LensLike' f s t a b = 'Overloaded' (->) f s t a b@
479 type Overloaded p f s t a b = p a (f b) -> p s (f t)
480
481 -- | @type 'Overloaded'' p q f s a = 'Simple' ('Overloaded' p q f) s a@
482 type Overloaded' p f s a = Overloaded p f s s a a
483
6be7786 @ekmett Factoring out Control.Lens.Type
authored
484 -- |
485 -- Many combinators that accept a 'Lens' can also accept a
486 -- 'Traversal' in limited situations.
487 --
488 -- They do so by specializing the type of 'Functor' that they require of the
489 -- caller.
490 --
491 -- If a function accepts a @'LensLike' f s t a b@ for some 'Functor' @f@,
492 -- then they may be passed a 'Lens'.
493 --
494 -- Further, if @f@ is an 'Applicative', they may also be passed a
495 -- 'Traversal'.
496 type LensLike f s t a b = (a -> f b) -> s -> f t
497
498 -- | @type 'LensLike'' f = 'Simple' ('LensLike' f)@
499 type LensLike' f s a = LensLike f s s a a
500
9eaef5c @basdirks haddocks: misc
basdirks authored
501 -- | Convenient alias for constructing 'IndexedLens'es and their ilk.
3fe8e0b @ekmett Removed more q Profunctor references
authored
502 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
503
9eaef5c @basdirks haddocks: misc
basdirks authored
504 -- | Convenient alias for constructing simple 'IndexedLens'es and their ilk.
3fe8e0b @ekmett Removed more q Profunctor references
authored
505 type IndexedLensLike' i f s a = IndexedLensLike i f s s a a
506
507 type Lensing p f s t a b = p a (f b) -> s -> f t
508
509 type Lensing' p f s a = Lensing p f s s a a
Something went wrong with that request. Please try again.