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