Skip to content

HTTPS clone URL

Subversion checkout URL

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