W/N      !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~TemplateHaskell experimentalEdward Kmett <ekmett@gmail.com> Trustworthy*Derive lenses for the record selectors in ( a single-constructor data declaration, 6 or for the record selector in a newtype declaration. 7 Lenses will only be generated for record fields which " are prefixed with an underscore. Example usage:  makeLenses ''Foo /Derive lenses, specifying explicit pairings of (fieldName, lensName). Example usage: < makeLensesFor [("_foo", "fooLens"), ("bar", "lbar")] ''Foo 4Derive lenses with the provided name transformation ! and filtering function. Produce  Just lensName to generate a lens  of the resultant name, or Nothing to not generate a lens  for the input record name. Example usage: , makeLensesBy (\n -> Just (n ++ "L")) ''Foo the name transformer  Rank2Types provisionalEdward Kmett <ekmett@gmail.com>SafeUsed internally by  traverseOf_,  and the like. Applicative composition of  State Int with a , used  by  elementOf,  elementsOf, traverseElement, traverseElementsOf 0The indexed store can be used to characterize a  LensFamily  and is used by clone Used by Focus        Rank2Types provisionalEdward Kmett <ekmett@gmail.com>Safeh=Types that support traversal of the value of the maximal key This is separate from TraverseValueAtMn because a min-heap < or max-heap may be able to support one, but not the other. 'Traverse the value for the maximal key =Types that support traversal of the value of the minimal key This is separate from  because a min-heap < or max-heap may be able to support one, but not the other. 'Traverse the value for the minimal key  Provides ad hoc overloading for  .Traverse the individual bytes in a ByteString H anyOf traverseByteString (==0x80) :: TraverseByteString b => b -> Bool A  can be used directly as a  or a  and provides W the ability to both read and update multiple fields, subject to the (relatively weak)  laws. These are also known as  MultiLens5 families, but they have the signature and spirit of  = traverse :: Traversable f => TraversalFamiy (f a) (f b) a b 8and the more evocative name suggests their application. Every  can be used as a  or a  or &, so it can transitively be used as a   or  as well. : type Traversal a b = TraversalFamily a a b b A I describes how to retrieve multiple values in a way that can be composed % with other lens-like constructions. A  a b c dC provides a structure with operations very similar to those of the   typeclass, see L and the other  combinators. !By convention, if there exists a foo method that expects a  (f c), then there should be a  fooOf method that takes a  a b c d and a value of type a. Every  can be used directly as a % (and you should probably be using a   instead.) . type Fold a b = FoldFamily a b c d This class allows us to use . on a number of different monad transformers. KUse a lens to lift an operation with simpler context into a larger context A c describes a way to perform polymorphic update to potentially multiple fields in a way that can be C composed with other lens-like constructions that can be used as a . The typical way to obtain a  is to build one with ' or to compose some other -like construction  with a . *Note: the only lens law that applies to a  is  - writing l c (writing l b a) = writing l c a # a  doesn'?t work in general, so the other two laws can never be invoked. Every  can be used directly as a . *Note: the only lens law that applies to a  is  - writing l c (writing l b a) = writing l c a # a  doesn'?t work in general, so the other two laws can never be invoked. 7 type Setter a b = SetterFamily a a b b A M describes how to retrieve a single value in a way that can be composed with  other lens-like constructions. A  can be used directly as a , since it just ignores the . A  can be used directly as a  or as a , and hence it can be as a . 0In general while your combinators may produce a  it is better to consume any . 2 type Getter a b = GetterFamily a a b b A  is a more general form of a ( that permits polymorphic field updates 3With great power comes great responsibility, and a  is subject to the lens laws:  ! reading l (writing l b a) = b ! writing l (reading l a) a = a - writing l c (writing l b a) = writing l c a =These laws are strong enough that the 4 type parameters of a . cannot vary fully independently. For more on  how they interact, read the Why is it a Lens Family? section of  /http://comonad.com/reader/2012/mirrored-lenses/. Every  can be used as a , a  or a %, which transitively means it can be  used as a . ADespite the complicated signature the pattern for implementing a  is the same as a . ! in fact the implementation doesn'1t change, the type signature merely generalizes. 6 identity :: LensFamily (Identity a) (Identity b) a b , identity f (Identity a) = Identity <$> f a A Lens is a purely functional reference to part of a data structure. It can be used to read or write to that part of the whole. 3With great power comes great responsibility, and a  is subject to the lens laws:  ! reading l (writing l b a) = b ! writing l (reading l a) a = a - writing l c (writing l b a) = writing l c a Every  can be used directly as a  or as a , , or ,, which transitively mens it can be used as  almost anything! Such as a , a , a , a , or a .  Example:   import Data.Complex ! imaginary :: Lens (Complex a) a ' imaginary f (e :+ i) = (e :+) <$> f i 0 type Lens a b = LensFamily a a b b Build a  or  from a getter and a setter. J lens :: Functor f => (a -> c) -> (d -> a -> b) -> (c -> f d) -> a -> f b !Built a  or . from an isomorphism or an isomorphism family D iso :: Functor f => (a -> c) -> (d -> b) -> (c -> f d) -> a -> f b "Build a  or  #Get the value of a ,  or  or the fold of a  ,  or  that points at monoidal  values. + reading :: GetterFamily a b c d -> a -> c $Get the value of a ,  or  or the fold of a  ,  or # that points to something you want  to map to a monoidal value %Read the value of a ,  or .  This is the same operation as #. &Read a field from a ,  or . I The fixity and semantics are such that subsequent field accesses can be : performed with (Prelude..) This is the same operation as ' flip reading' 1 ghci> ((0, 1 :+ 2), 3)^._1._2.getting magnitude  2.23606797749979 'Build a Setter or SetterFamily  setting . modifying = id  modifying . setting = id (;This setter will replace all of the values in a container. )Modify the target of a ,  or all the targets of a  , ,  or    fmap = modifying traverse  setting . modifying = id  modifying . setting = id K modifying :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b *Replace the target of a , ,  or    (<$) = writing traverse B writing :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b +Modifies the target of a , , , or . This is an infix version of )   fmap f = traverse ^%= f G (^%=) :: ((c -> Identity d) -> a -> Identity b) -> (c -> d) -> a -> b ,Replaces the target(s) of a , ,  or . This is an infix version of *   f <$ a = traverse ^= f $ a ? (^=) :: ((c -> Identity d) -> a -> Identity b) -> d -> a -> b -0Increment the target(s) of a numerically valued  or Setter'   ghci> _1 ^+= 1 $ (1,2)  (2,2) I (^+=) :: Num c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a ./Multiply the target(s) of a numerically valued  or Setter'   ghci> _2 ^*= 4 $ (1,2)  (1,8) I (^*=) :: Num c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a /0Decrement the target(s) of a numerically valued  or    ghci> _1 ^-= 2 $ (1,2)  (-1,2) @ (^-=) :: ((c -> Identity c) -> a -> Identity a) -> c -> a -> a 0-Divide the target(s) of a numerically valued  P (^/=) :: Fractional c => ((c -> Identity c) -> a -> Identity a) -> c -> a -> a 1 Logically  the target(s) of a -valued  or  I (^||=):: ((Bool -> Identity Bool) -> a -> Identity a) -> Bool -> a -> a 2 Logically  the target(s) of a -valued  or   (^&&E=) :: ((Bool -> Identity Bool) -> a -> Identity a) -> Bool -> a -> a 3Bitwise  the target(s) of a -valued  or  L (^|=):: Bits b => ((b -> Identity b) -> a -> Identity a) -> Bool -> a -> a 4Bitwise  the target(s) of a -valued  or   (^&F=) :: Bits b => ((b -> Identity b) -> a -> Identity a) -> b -> a -> a 5QThis is a lens family that can change the value (and type) of the first field of  a pair.   ghci> (1,2)^._1  1  ghci> _1 ^= "hello" $ (1,2)  ("hello",2) 6As 5&, but for the second field of a pair. + anyOf _2 :: (c -> Bool) -> (a, c) -> Bool Y traverse._2 :: (Applicative f, Traversable t) => (a -> f b) -> t (c, a) -> f (t (c, b)) S foldMapOf (traverse._2) :: (Traversable t, Monoid m) => (c -> m) -> t (b, c) -> m 7=This lens can be used to read, write or delete a member of a . 6 ghci> Map.fromList [("hello",12)] ^. valueAt "hello"  Just 12 8>This lens can be used to read, write or delete a member of an .  3 ghci> IntMap.fromList [(1,"hello")] ^. valueAt 1  Just "hello" > ghci> valueAt 2 ^= "goodbye" $ IntMap.fromList [(1,"hello")] & fromList [(1,"hello"),(2,"goodbye")] 9=This lens can be used to read, write or delete a member of a  4 ghci> contains 3 ^= False $ Set.fromList [1,2,3,4]  fromList [1,2,4] :>This lens can be used to read, write or delete a member of an  : ghci> containsInt 3 ^= False $ IntSet.fromList [1,2,3,4]  fromList [1,2,4] ;CThis lens can be used to access the contents of the Identity monad <FThis lens can be used to access the value of the nth bit in a number. bitsAt n is only a legal  into b if 0 <= n < bitSize (undefined :: b) =HThis lens can be used to change the result of a function but only where $ the arguments match the key given. > Access a field of a state monad ?VModify the value of a field in our monadic state and return some information about it @.Set the value of a field in our monadic state A1Modify the value of a field in our monadic state B<Modify a numeric field in our monadic state by adding to it CCModify a numeric field in our monadic state by subtracting from it D>Modify a numeric field in our monadic state by multiplying it E;Modify a numeric field in our monadic state by dividing it FEModify a boolean field in our monadic state by computing its logical  with another value. GEModify a boolean field in our monadic state by computing its logical  with another value. HEModify a numeric field in our monadic state by computing its bitwise  with another value. IEModify a boolean field in our monadic state by computing its bitwise  with another value. J Obtain a  from any  KBuilding a FoldFamily L  foldMap = foldMapOf folded   foldMapOf = readings 9 foldMapOf :: GetterFamily a b c d -> (c -> m) -> a -> m C foldMapOf :: Monoid m => FoldFamily a b c d -> (c -> m) -> a -> m M  fold = foldOf folded   foldOf = reading * foldOf :: GetterFamily a b m d -> a -> m 4 foldOf :: Monoid m => FoldFamily a b m d -> a -> m N  foldr = foldrOf folded A foldrOf :: GetterFamily a b c d -> (c -> e -> e) -> e -> a -> e ? foldrOf :: FoldFamily a b c d -> (c -> e -> e) -> e -> a -> e O  toList = toListOf folded . toListOf :: GetterFamily a b c d -> a -> [c] , toListOf :: FoldFamily a b c d -> a -> [c] P  and = andOf folded / andOf :: GetterFamily a b Bool d -> a -> Bool - andOf :: FoldFamily a b Bool d -> a -> Bool Q  or = orOf folded . orOf :: GetterFamily a b Bool d -> a -> Bool , orOf :: FoldFamily a b Bool d -> a -> Bool R  any = anyOf folded ; anyOf :: GetterFamily a b c d -> (c -> Bool) -> a -> Bool 9 anyOf :: FoldFamily a b c d -> (c -> Bool) -> a -> Bool S  all = allOf folded ; allOf :: GetterFamily a b c d -> (c -> Bool) -> a -> Bool 9 allOf :: FoldFamily a b c d -> (c -> Bool) -> a -> Bool T  product = productOf folded - productOf :: GetterFamily a b c d -> a -> c 4 productOf :: Num c => FoldFamily a b c d -> a -> c U  sum = sumOf folded   sumOf _1 :: (a, b) -> a ; sumOf (folded._1) :: (Foldable f, Num a) => f (a, b) -> a ) sumOf :: GetterFamily a b c d -> a -> c 0 sumOf :: Num c => FoldFamily a b c d -> a -> c VWhen passed a , V can work over a . When passed a , V requires an .  traverse_ = traverseOf_ folded W  for_ = forOf_ folded H forOf_ :: Functor f => GetterFamily a b c d -> a -> (c -> f e) -> f () J forOf_ :: Applicative f => FoldFamily a b c d -> a -> (c -> f e) -> f () X " sequenceA_ = sequenceAOf_ folded E sequenceAOf_ :: Functor f => GetterFamily a b (f ()) d -> a -> f () G sequenceAOf_ :: Applicative f => FoldFamily a b (f ()) d -> a -> f () Y  mapM_ = mapMOf_ folded G mapMOf_ :: Monad m => GetterFamily a b c d -> (c -> m e) -> a -> m () E mapMOf_ :: Monad m => FoldFamily a b c d -> (c -> m e) -> a -> m () Z  forM_ = forMOf_ folded G forMOf_ :: Monad m => GetterFamily a b c d -> a -> (c -> m e) -> m () E forMOf_ :: Monad m => FoldFamily a b c d -> a -> (c -> m e) -> m () [  sequence_ = sequenceOf_ folded A sequenceOf_ :: Monad m => GetterFamily a b (m b) d -> a -> m () ? sequenceOf_ :: Monad m => FoldFamily a b (m b) d -> a -> m () \1The sum of a collection of actions, generalizing a.   asum = asumOf folded = asumOf :: Alternative f => GetterFamily a b c d -> a -> f c ; asumOf :: Alternative f => FoldFamily a b c d -> a -> f c ]1The sum of a collection of actions, generalizing a.   msum = msumOf folded ; msumOf :: MonadPlus m => GetterFamily a b c d -> a -> m c 9 msumOf :: MonadPlus m => FoldFamily a b c d -> a -> m c ^  elem = elemOf folded : elemOf :: Eq c => GetterFamily a b c d -> c -> a -> Bool 8 elemOf :: Eq c => FoldFamily a b c d -> c -> a -> Bool _  notElem = notElemOf folded = notElemOf :: Eq c => GetterFamily a b c d -> c -> a -> Bool ; notElemOf :: Eq c => FoldFamily a b c d -> c -> a -> Bool `  concatMap = concatMapOf folded ? concatMapOf :: GetterFamily a b c d -> (c -> [e]) -> a -> [e] = concatMapOf :: FoldFamily a b c d -> (c -> [e]) -> a -> [e] a  concat = concatOf folded 0 concatOf :: GetterFamily a b [e] d -> a -> [e] . concatOf :: FoldFamily a b [e] d -> a -> [e] b  mapM = mapMOf traverse C mapMOf :: Monad m => LensFamily a b c d -> (c -> m d) -> a -> m b H mapMOf :: Monad m => TraversalFamily a b c d -> (c -> m d) -> a -> m b c " sequenceA = sequenceAOf traverse H sequenceAOf :: Applicative f => LensFamily a b (f c) (f c) -> a -> f b M sequenceAOf :: Applicative f => TraversalFamily a b (f c) (f c) -> a -> f b d  sequence = sequenceOf traverse A sequenceOf :: Monad m => LensFamily a b (m c) (m c) -> a -> m b F sequenceOf :: Monad m => TraversalFamily a b (m c) (m c) -> a -> m b e.A Traversal of the nth element of a Traversal % traverseHead = elementOf traverse 0 f`A Traversal of the elements at positions in a Traversal where the positions satisfy a predicate ) traverseTail = elementsOf traverse (>0) g = transpose = transposeOf traverse -- (for not ragged arrays) ( transposeOf _2 :: (b, [a]) -> [(b, a)] hBThis is the traversal that never succeeds at returning any values < traverseNothing :: Applicative f => (c -> f d) -> a -> f a i = traverseHead :: Applicative f => (a -> f a) -> [a] -> f [a] j A traverseTail :: Applicative f => ([a] -> f [a]) -> [a] -> f [a] k%Traverse the last element in a list.  # traverseLast = traverseValueAtMax = traverseLast :: Applicative f => (a -> f a) -> [a] -> f [a] l,Traverse all but the last element of a list A traverseInit :: Applicative f => ([a] -> f [a]) -> [a] -> f [a] m;A traversal for tweaking the left-hand value in an Either: M traverseLeft :: Applicative f => (a -> f b) -> Either a c -> f (Either b c) n,traverse the right-hand value in an Either:  N traverseRight :: Applicative f => (a -> f b) -> Either c a -> f (Either c a)  traverseRight = traverse Unfortunately the instance for 'Traversable (Either c)' is still missing from  base, so this can' t just be  o+Traverse the value at a given key in a Map X traverseValueAt :: (Applicative f, Ord k) => k -> (v -> f v) -> Map k v -> f (Map k v) * traverseValueAt k = valueAt k . traverse p/Traverse the value at a given key in an IntMap V traverseValueAtInt :: Applicative f => Int -> (v -> f v) -> IntMap v -> f (IntMap v) 0 traverseValueAtInt k = valueAtInt k . traverse q6Traverse a single element in a traversable container. Z traverseElement :: (Applicative f, Traversable t) => Int -> (a -> f a) -> t a -> f (t a) rWTraverse elements where a predicate holds on their position in a traversable container d traverseElements :: Applicative f, Traversable t) => (Int -> Bool) -> (a -> f a) -> t a -> f (t a) s*Traverse over all bits in a numeric type.  * ghci> toListOf traverseBits (5 :: Word8) 1 [True,False,True,False,False,False,False,False] %If you supply this an Integer, it won't crash, but the result will = be an infinite traversal that can be productively consumed.  ghci> toListOf traverseBits 5 K [True,False,True,False,False,False,False,False,False,False,False,False... t Cloning a  or ) is one way to make sure you arent given  something weaker, such as a  or , and can be used ? as a way to pass around lenses that have to be monomorphic in f. 'We can focus Reader environments, too! t !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstg !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstg !t"#$&%'()*+,-/.01234>A@BCDEGFIH?JKLNMORSPQTUVWXYZ[\]`a^_hopijklmnqrsbcdefg5678<9:;=p !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrst RankNTypes provisionalEdward Kmett <ekmett@gmail.com>SafeuGSometimes you need to store a path lens into a container, but at least F at this time, impredicative polymorphism in GHC is somewhat lacking. FThis type provides a way to, say, store a list of polymorphic lenses. xRepresentable Functors. A  f is x if it is isomorphic to (x -> a) > for some x. All such functors can be represented by choosing x to be ? the set of lenses that are polymorphic in the contents of the ,  that is to say  x = Rep f is a valid choice of x for every  x . @Note: Some sources refer to covariant representable functors as ) corepresentable functors, and leave the " representable" name to 1 contravariant functors (those are isomorphic to (a -> x) for some x). LAs the covariant case is vastly more common, and both are often referred to = as representable functors, we choose to call these functors x  here. zThe representation of a x  as Lenses {{# is a valid default definition for  for a representable  functor.  $ fmapRep f m = rep $ \i -> f (m^.i) "Usage for a representable functor Foo:  instance Functor Foo where  fmap = fmapRep ||# is a valid default definition for  and  for a  representable functor.   pureRep = rep . const "Usage for a representable functor Foo:   instance Applicative Foo where  pure = pureRep  (<*>) = apRep  instance Monad Foo where  return = pureRep  (>>=) = bindRep }}# is a valid default definition for '( *)' for a representable  functor.  ) apRep mf ma = rep $ \i -> mf^.i $ ma^.i "Usage for a representable functor Foo:  instance Applicative Foo where  pure = pureRep  (<*>) = apRep ~~+ is a valid default default definition for '(>>=)' for a  representable functor.  & bindRep m f = rep $ \i -> f(m^.i)^.i "Usage for a representable functor Foo:  instance Monad ... where  return = pureRep  (>>=) = bindRep A default definition for  for a x   . distributeRep wf = rep $ \i -> fmap (^.i) wf Typical Usage: ! instance Distributive ... where  distribute = distributeRep A x . has a fixed shape. This fills each position  in it with a u  Map over a x " with access to the lens for the  current position ) mapWithKey f m = rep $ \i -> f i (m^.i)  Traverse a x ! with access to the current path  Traverse a x ! with access to the current path " as a lens, discarding the result  Traverse a x ! with access to the current path ( and a lens (and the arguments flipped)  over a x ! with access to the current path  as a lens  over a x ! with access to the current path " as a lens, discarding the result  over a x ! with access to the current path ( as a lens (with the arguments flipped)  Fold over a x ! with access to the current path  as a lens, yielding a   Fold over a x ! with access to the current path  as a lens. CNB: The Eq requirement on this instance is a consequence of a lens  rather than e as the representation. uvwxyz{|}~uvwxyz{|}~xyz{|}~uvwuvwxyz{|}~        !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxxyz{|}~lens-0.6Control.Lens.THControl.Lens.Internal Control.LensControl.Lens.RepData.Distributive distribute makeLenses makeLensesFor makeLensesBy Traversed getTraversed AppliedStaterunAppliedState IndexedStoreFocusing unfocusingTraverseValueAtMaxtraverseValueAtMaxTraverseValueAtMintraverseValueAtMinTraverseByteStringtraverseByteStringTraversalFamily Traversal FoldFamilyFoldFocusfocus SetterFamilySetter GetterFamilyGetter LensFamilyLenslensisogettingreadingreadings^$^.settingmapped modifyingwriting^%=^=^+=^*=^-=^/=^||=^&&=^|=^&=_1_2valueAt valueAtIntcontains containsIntidentitybitAtresultAtaccess%%=~=%=+=-=*=//=&&=||=&=|=foldedfolding foldMapOffoldOffoldrOftoListOfandOforOfanyOfallOf productOfsumOf traverseOf_forOf_ sequenceAOf_mapMOf_forMOf_ sequenceOf_asumOfmsumOfelemOf notElemOf concatMapOfconcatOfmapMOf sequenceAOf sequenceOf elementOf elementsOf transposeOftraverseNothing traverseHead traverseTail traverseLast traverseInit traverseLeft traverseRighttraverseValueAttraverseValueAtInttraverseElementtraverseElements traverseBitscloneKeyturn RepresentablerepRepfmapReppureRepapRepbindRep distributeRepkeys mapWithReptraverseWithReptraverseWithRep_ forWithRep mapMWithRep mapMWithRep_ forMWithRepfoldMapWithRep foldrWithRepbase Control.MonadmapM_GHC.BaseFunctor$fMonoidTraversed$fApplicativeAppliedState$fFunctorAppliedState$fFunctorIndexedStore$fApplicativeFocusing$fFunctorFocusing Data.FoldableFoldable Data.MonoidMonoidghc-prim GHC.Classes|| GHC.TypesBool&& Data.Bits.|..&.containers-0.4.2.1Data.MapMap Data.IntMapIntMapData.SetSet Data.IntSetIntSetControl.Applicative ApplicativeData.Traversabletraverse$fFocusReaderT$fTraverseValueAtMaxSeq$fTraverseValueAtMax[]$fTraverseValueAtMaxIntMap$fTraverseValueAtMaxMap$fTraverseValueAtMinSeq$fTraverseValueAtMin[]$fTraverseValueAtMinIntMap$fTraverseValueAtMinMap$fTraverseByteStringByteString$fTraverseByteStringByteString0 $fFocusStateT$fFocusStateT0fmappurereturnmapM$fRepresentable(->)$fRepresentableIdentity