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