DY==      !"#$%&'()*+,-./0123456789:;<SafeINwThis is a type alias for monomorphic traversals which don't change the type of the container (or of the values inside).ZTraversals in a nutshell: they're like lenses but they can point at multiple values. Use () to get all values, () to get the 1st value, () to set values, () to modify them. (=3) composes traversals just as it composes lenses. (B) can be used with traversals as well, but don't confuse it with ().Traversal s t a b is a generalisation of U which allows many targets (possibly 0). It's achieved by changing the constraint to > instead of ?  indeed, the point of >R is that you can combine effects, which is just what we need to have many targets.RTraversals don't differ from lenses when it comes to setting  you can use usual () and () to modify and set values. Getting is a bit different, because you have to decide what to do in the case of multiple values. In particular, you can use these combinators (as well as everything else in the Folds  section):() gets a list of values() gets the 1st value (or @ if there are no values)( C) gets the 1st value and throws an exception if there are no valuesIn addition, (I) works for traversals as well  it combines traversed values using the ( ,) operation (if the values are instances of A).lTraversing any value twice is a violation of traversal laws. You can, however, traverse values in any order.,Ultimately, traversals should follow 2 laws: Gt pure "a pure fmap (t f) . t g "a getCompose . t (Compose . fmap f . g) JThe 1st law states that you can't change the shape of the structure or do anything funny with elements (traverse elements which aren't in the structure, create new elements out of thin air, etc.). The 2nd law states that you should be able to fuse 2 identical traversals into one. For a more detailed explanation of the laws, see  /http://artyom.me/lens-over-tea-2#traversal-lawsthis blog post) (if you prefer rambling blog posts), or  @https://www.cs.ox.ac.uk/jeremy.gibbons/publications/iterator.pdf#The Essence Of The Iterator Pattern (if you prefer papers).rThis is a type alias for monomorphic lenses which don't change the type of the container (or of the value inside).Lenses in a nutshell: use ( ) to get, ( ) to set, () to modify. (=) composes lenses (i.e. if a B is a part of A, and a C is a part of in B, then b.c lets you operate on C inside A). You can create lenses with  ,, or you can write them by hand (see below). Lens s t a bk is the lowest common denominator of a setter and a getter, something that has the power of both; it has a ? constraint, and since both B and CF are functors, it can be used whenever a getter or a setter is needed.a- is the type of the value inside of structureb" is the type of the replaced values# is the type of the whole structuret. is the type of the structure after replacing a in it with bA ? can only point at a single value inside a structure (unlike a ).=It is easy to write lenses manually. The generic template is: ksomelens :: Lens s t a b -- f  is the a -> f b  function, s  is the structure. somelens f s = let a = ... -- Extract the value from s . rebuildWith b = ... -- Write a function which would -- combine s  and modified value -- to produce new structure. in rebuildWith Di f a -- Apply the structure-producing -- function to the modified value.  Here's the   lens:   ::  (a, x) (b, x) a b   f (a, x) = (\b -> (b, x)) D f a /Here's a more complicated lens, which extracts several& values from a structure (in a tuple): type Age = Int type City = String type Country = String data Person = Person Age City Country -- This lens lets you access all location-related information about a person. location :: s Person (City, Country) location f (Person age city country) = (\(city', country') -> Person age city' country') D f (city, country) -You even can choose to use a lens to present allU information contained in the structure (in a different way). Such lenses are called  Hhttp://hackage.haskell.org/package/lens/docs/Control-Lens-Iso.html#t:IsoIso in lens's terminology. For instance (assuming you don't mind functions that can error out), here's a lens which lets you act on the string representation of a value: string :: (Read a, Show a) =>  a String string f s = read D f (show s) Using it to reverse a number: >>> 123  string  reverse 321 -If you take a lens or a traversal and choose B r as your functor, you will get  Getting r s aQ. This can be used to get something out of the structure instead of modifying it: s  l = E (l B s) -Functions that operate on getters  such as (), (), ()  use  Getter r s a (with different values of r<) to describe what kind of getter they need. For instance, ([) needs the getter to be able to return a single value, and so it accepts a getter of type  Getting a s a. (9) wants the getter to gather values together, so it uses Getting (Endo [a]) s a (it could've used Getting [a] s a instead, but it's faster with  ). The choice of rE depends on what you want to do with elements you're extracting from s.This is a type alias for monomorphic setters which don't change the type of the container (or of the value inside). It's useful more often than the same type in lens, because we can't provide real setters and so it does the job of both  Shttp://hackage.haskell.org/package/lens/docs/Control-Lens-Setter.html#t:ASetter-39-ASetter' and  Rhttp://hackage.haskell.org/package/lens/docs/Control-Lens-Setter.html#t:Setter-39-Setter'.ASetter s t a bR is something that turns a function modifying a value into a function modifying a  structure. If you ignore C (as  Identity a is the same thing as a), the type is: *type ASetter s t a b = (a -> b) -> s -> t BThis means that examples of setters you might've already seen are: F :: (a -> b) -> [a] -> [b](which corresponds to ) G :: ? f => (a -> b) -> f a -> f b(which corresponds to  as well)  :: (a -> b) -> (a, x) -> (b, x)(which corresponds to  )  :: (a -> b) -> H a x -> H b x(which corresponds to ) The reason C is used here is for , to be composable with other types, such as .Technically, if you're writing a library, you shouldn't use this type for setters you are exporting from your library; the right type to use is  Nhttp://hackage.haskell.org/package/lens/docs/Control-Lens-Setter.html#t:SetterSetterN, but it is not provided by this package (because then we'd have to depend on  /http://hackage.haskell.org/package/distributive distributiveG). It's completely alright, however, to export functions which take an  as an argument.None134579>ILN:Gives access to the 1st field of a tuple (up to 5-tuples).Getting the 1st component:(1,2,3,4,5) ^. _11Setting the 1st component:(1,2,3) & _1 .~ 10(10,2,3)8Note that this lens is lazy, and can set fields even of I:!set _1 10 undefined :: (Int, Int)$(10,*** Exception: Prelude.undefinedVThis is done to avoid violating a lens law stating that you can get back what you put:/view _1 . set _1 10 $ (undefined :: (Int, Int))10%The implementation (for 2-tuples) is:  f t = (,) D f (J t) K L (M t) or, alternatively,  f ~(a,b) = (\a' -> (a',b)) D f a (where ~ means a  +https://wiki.haskell.org/Lazy_pattern_match lazy pattern)., , , and   are also available (see below).6This lens lets you read, write, or delete elements in Map-like structures. It returns @' when the value isn't found, just like lookup: Data.Map.lookup k m = m  at k KHowever, it also lets you insert and delete values by setting the value to N value or @: Data.Map.insert k a m = m  at k ! Just a Data.Map.delete k m = m  at k  Nothing V doesn't work for arrays, because you can't delete an arbitrary element from an array.@If you want to modify an already existing value, you should use 2 instead because then you won't have to deal with O (& is available for all types that have ). Note that  isn't strict for Map, even if you're using Data.Map.Strict:EData.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)1AThe reason for such behavior is that there's actually no strict Map  type; Data.Map.Strict2 just provides some strict functions for ordinary Maps.8This package doesn't actually provide any instances for , but you can import Lens.Micro.GHC from the  0http://hackage.haskell.org/package/microlens-ghc microlens-ghc package and get instances for Map and IntMap.SThis traversal lets you access (and update) an arbitrary element in a list, array, MapB, etc. (If you want to insert or delete elements as well, look at .)An example for lists:[0..5] & ix 3 .~ 10[0,1,2,10,4,5] You can use it for getting, too:[0..5] ^? ix 3Just 3HOf course, the element may not be present (which means that you can use  as a safe variant of (P)):[0..5] ^? ix 10Nothing~Another useful instance is the one for functions  it lets you modify their outputs for specific inputs. For instance, here's QJ that returns 0 when the list is empty (instead of throwing an exception):  maximum0 = Q   []  0 5The following instances are provided in this package:  :: R ->  [a] a  :: (S e) => e ->  (e -> a) a Additionally, you can use  with types from  (http://hackage.haskell.org/package/arrayarray,  -http://hackage.haskell.org/package/bytestring bytestring, and  -http://hackage.haskell.org/package/containers containers by importing Lens.Micro.GHC from the  0http://hackage.haskell.org/package/microlens-ghc microlens-ghc package. tries to be a universal   it behaves like R in most situations, but also adds support for e.g. tuples with same-typed values:(1,2) & each %~ succ(2,3)["x", "y", "z"] ^. each"xyz"However, note that  doesn't work on every instance of T. If you have a T which isn't supported by , you can use # instead. Personally, I like using  instead of 7 whenever possible  it's shorter and more descriptive. You can use  with these things:  ::  [a] [b] a b  ::  (O a) (O b) a b  ::  (a,a) (b,b) a b  ::  (a,a,a) (b,b,b) a b  ::  (a,a,a,a) (b,b,b,b) a b  ::  (a,a,a,a,a) (b,b,b,b,b) a b  :: (U a, U b) =>  (V a) (V b) a b Additionally, you can use  with types from  (http://hackage.haskell.org/package/arrayarray,  -http://hackage.haskell.org/package/bytestring bytestring, and  -http://hackage.haskell.org/package/containers containers by importing Lens.Micro.GHC from the  0http://hackage.haskell.org/package/microlens-ghc microlens-ghc package. traverses any T container (list, vector, Map, O, you name it):Just 1 ^.. traversed[1] is the same as W2, but can be faster thanks to magic rewrite rules. is a fold for anything X . In a way, it's an opposite of mapped;  the most powerful getter, but can't be used as a setter.## creates an O from an ordinary function. (The only thing it does is wrapping and unwrapping C.)>  !"#YZ$%[\]^_`abcdefghijklmnopqrstuvwx  !"#$% !"#$%  4    !"#YZ$%[\]^_`abcdefghijklmnopqrstuvwxNone345IN&(&[) applies a function to the target; an alternative explanation is that it is an inverse of #2, which turns a setter into an ordinary function. * & y is the same thing as G y.See '$ if you want a non-operator synonym.#Negating the 1st element of a pair:(1,2) & _1 %~ negate(-1,2) Turning all Lefts in a list to upper case::(mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"][Left "FOO",Right "bar"]'' is a synonym for (&).Getting G in a roundabout way: ' * :: ? f => (a -> b) -> f a -> f b ' * = G 1Applying a function to both components of a pair: ' 4! :: (a -> b) -> (a, a) -> (b, b) ' 4" = \f t -> (f (fst t), f (snd t)) Using '  as a replacement for :over _2 show (10,20) (10,"20")(((6) assigns a value to the target. These are equivalent: l ( x l & z xSee )$ if you want a non-operator synonym.0Here it is used to change 2 fields of a 3-tuple:(0,0,0) & _1 .~ 1 & _3 .~ 3(1,0,3))) is a synonym for (().$Setting the 1st component of a pair: )  :: x -> (a, b) -> (x, b) )  = \x t -> (x, snd t) Using it to rewrite (): ) * :: ? f => a -> f b -> f a ) * = () **V is a setter for everything contained in a functor. You can use it to map over lists, Maybe , or even IO' (which is something you can't do with  or ).Here *$ is used to turn a value to all non-@ values in a list:,[Just 3,Nothing,Just 5] & mapped.mapped .~ 0[Just 0,Nothing,Just 0]Keep in mind that while * is a more powerful setter than R, it can't be used as a getter! This won't work (and will fail with a type error): [(1,2),(3,4),(5,6)] / * . 4 +This is a version of (&G) which modifies the structure and returns it along with the new value:(1, 2) & _1 <%~ negate (-1, (-1, 2))Simpler type signatures: (+) :: * s t a b -> (a -> b) -> s -> (b, t) (+) :: A b => $ s t a b -> (a -> b) -> s -> (b, t) ,This is a version of (&G) which modifies the structure and returns it along with the old value:(1, 2) & _1 <<%~ negate (1, (-1, 2))Simpler type signatures: (,) :: * s t a b -> (a -> b) -> s -> (a, t) (,) :: A a => $ s t a b -> (a -> b) -> s -> (a, t) -This is a version of ((G) which modifies the structure and returns it along with the old value:(1, 2) & _1 <<.~ 0 (1, (0, 2))Simpler type signatures: (-) :: # s t a b -> b -> s -> (a, t) (-) :: A a =>  s t a b -> b -> s -> (a, t) .(.) applies a getter to a value; in other words, it gets a value out of a structure using a getter (which can be a lens, traversal, fold, etc.).Getting 1st field of a tuple: (. ) :: (a, b) -> a (. ) = J When (.>) is used with a traversal, it combines all results using the A[ instance for the resulting type. For instance, for lists it would be simple concatenation:("str","ing") ^. each"string"+The reason for this is that traversals use > , and the > instance for B3 uses monoid concatenation to combine effects  of B.A non-operator version of (. ) is called viewV, and it's not included in this package because it is a bit more general (it works in  MonadReader and thus requires a  &http://hackage.haskell.org/package/mtlmtl" dependency). You can get it from  0http://hackage.haskell.org/package/microlens-mtl microlens-mtl./s ^.. t% returns the list of all values that t gets from s.A O contains either 0 or 1 values:Just 3 ^.. _Just[3])Gathering all values in a list of tuples:[(1,2),(3,4)] ^.. each.each [1,2,3,4]0s ^? t returns the 1st element t returns, or @ if tD doesn't return anything. It's trivially implemented by passing the { monoid to the getter.Safe |: [] ^? eachNothing[1..3] ^? eachJust 1 Converting H to O:Left 1 ^? _RightNothingRight 1 ^? _RightJust 1A non-operator version of (0 ) is called preview , and  like viewN  it's not included in this package because it's more general and requires a  &http://hackage.haskell.org/package/mtlmtl dependency). As with view, you can get it from  0http://hackage.haskell.org/package/microlens-mtl microlens-mtl.1(1) is an unsafe variant of (0)  instead of using @J to indicate that there were no elements returned, it throws an exception.22h checks whether a getter (any getter, including lenses, traversals, and folds) returns at least 1 value.%Checking whether a list is non-empty: has each []FalseYou can also use it with e.g. 94 (and other 0-or-1 traversals) as a replacement for ,  and other isConstructorName functions:has _Left (Left 1)True33 creates a  from a getter and a setter. The resulting lens isn't the most effective one (because of having to traverse the structure twice when modifying), but it shouldn't matter much.#A (partial) lens for list indexing:  ix :: Int ->  [a] a ix i = 3 (Po i) -- getter (\s b -> take i s ++ b : drop (i+1) s) -- setter Usage:  >>> [1..9] . ix 3 4 >>> [1..9] & ix 3 & negate [1,2,3,-4,5,6,7,8,9] When getting, the setter is completely unused; when setting, the getter is unused. Both are used only when the value is being modified. For instance, here we define a lens for the 1st element of a list, but instead of a legitimate getter we use I%. Then we use the resulting lens for setting8 and it works, which proves that the getter wasn't used:3[1,2,3] & lens undefined (\s b -> b : tail s) .~ 10[10,2,3]44* traverses both fields of a tuple. Unlike  Ohttp://hackage.haskell.org/package/lens/docs/Control-Lens-Traversal.html#v:bothboth9 from lens, it only works for pairs  not for triples or H.("str","ing") ^. both"string"("str","ing") & both %~ reverse ("rts","gni")55K traverses the 1st element of something (usually a list, but can also be a Seq, etc):[1..5] ^? _headJust 1cIt can be used to modify too, as in this example where the 1st letter of a sentence is capitalised:,"mary had a little lamb." & _head %~ toTitle"Mary had a little lamb."fThe reason it's a traversal and not a lens is that there's nothing to traverse when the list is empty: [] ^? _headNothingThis package only lets you use 5 on lists, but you can import Lens.Micro.GHC from the  0http://hackage.haskell.org/package/microlens-ghc microlens-ghc package and get instances for  ByteString and Seq.66, gives you access to the tail of a list (or Seq, etc):[1..5] ^? _tailJust [2,3,4,5] You can modify the tail as well:[4,1,2,3] & _tail %~ reverse [4,3,2,1]%Since lists are monoids, you can use 6 with plain (.E) (and then it'll return an empty list if you give it an empty list):[1..5] ^. _tail [2,3,4,5] [] ^. _tail[]If you want to traverse each element of the tail, use 6 with :&"I HATE CAPS." & _tail.each %~ toLower"I hate caps."This package only lets you use 6 on lists, but you can import Lens.Micro.GHC from the  0http://hackage.haskell.org/package/microlens-ghc microlens-ghc package and get instances for  ByteString and Seq.77; gives you access to all-but-the-last elements of the list:"Hello." ^. _init"Hello"See documentation for 6, as 7 and 6 are pretty similar.882 gives you access to the last element of the list:"Hello." ^? _last'.'See documentation for 5, as 8 and 5 are pretty similar.99# targets the value contained in an H, provided it's a }.Gathering all Lefts in a structure (like the / function, but not necessarily just for lists):*[Left 1, Right 'c', Left 3] ^.. each._Just[1,3]Checking whether an H is a } (like ):has _Left (Left 1)Truehas _Left (Right 1)False*Extracting a value (if you're sure it's a }):Left 1 ^?! _Left1Mapping over all }s:5(each._Left %~ map toUpper) [Left "foo", Right "bar"][Left "FOO",Right "bar"]Implementation: 9 f (Left a) = } D f a 9 _ (Right b) = L (~ b) ::# targets the value contained in an H, provided it's a ~.See documentation for 9.;;" targets the value contained in a O, provided it's a N.See documentation for 9O (as these 2 are pretty similar). In particular, it can be used to write these:#Unsafely extracting a value from a N:  = (1 ;) Checking whether a value is a N:  = 2 ;  Converting a O5 to a list (empty or consisting of a single element):  = (/ ;) Gathering all N s in a list:   = (/  = ;) << targets a () if the O is a @(, and doesn't target anything otherwise:Just 1 ^.. _Nothing[]Nothing ^.. _Nothing[()]5It's not particularly useful (unless you want to use 2 < as a replacement for '), and provided mainly for consistency.Implementation: < f Nothing = z @ D f () < _ j = L j &'()*+,-./0123456789:;<* #&'()*+,-./0123456789:;<*#&'()+,-*./0123 456789:;<&'()*+,-./0123456789:;<&(./01!"#$%&'()*+,-./0123456 789:;<=>?@ABCDEFGHIJK L MNOPQRST!UV!UW!UX!UY!UZ![\!]^!_![`!Ua!Ub!c!de!fg!Uh!Ui!fj!Uk!Ul!mn!opqrsqtu!vw!xy!z{!v|!o}~!m!U! !m!!micro_8jYrwUyFNzcI986G8Jldru Lens.MicroLens.Micro.TypeLens.Micro.Internal^..^?.~%~^.^?! Data.Monoid<>lens_1&Endomapped Control.Arrowfirstleft_Leftsecond Data.Functor<$ Data.Maybe isNothingisJust Data.EitherleftsisLeftfromJust maybeToList catMaybesbase Data.Function Traversal' TraversalLens'LensGettingASetter'ASetterSnoc_SnocCons_ConsField5_5Field4_4Field3_3Field2_2Field1AtatIxedixIxValueIndexEacheach traversedfoldedfoldringfoldrOf foldMapOfsets#..#overset<%~<<%~<<.~hasboth_head_tail_init_last_Right_Just_NothingGHC.Base. ApplicativeFunctorNothingMonoidControl.ApplicativeConstData.Functor.IdentityIdentity<$>getConstmapfmapEitherGHC.Err undefined Data.Tuplefst<*>puresndJustMaybeGHC.List!! Data.Foldablemaximumghc-prim GHC.TypesInt GHC.ClassesEqData.Traversable Traversable GHC.Float RealFloat Data.ComplexComplextraverseFoldablephantomnoEffectixAt $fSnoc[][]ab $fCons[][]ab$fField5(,,,,)(,,,,)ee'$fField4(,,,,)(,,,,)dd'$fField4(,,,)(,,,)dd'$fField3(,,,,)(,,,,)cc'$fField3(,,,)(,,,)cc'$fField3(,,)(,,)cc'$fField2(,,,,)(,,,,)bb'$fField2(,,,)(,,,)bb'$fField2(,,)(,,)bb'$fField2(,)(,)bb'$fField1(,,,,)(,,,,)aa'$fField1(,,,)(,,,)aa'$fField1(,,)(,,)aa'$fField1(,)(,)aa'$fIxed[] $fIxed(->)TFCo:R:IxValue[]TFCo:R:Index[]TFCo:R:IxValue(->)TFCo:R:Index(->)$fEachMaybeMaybeab $fEach[][]ab$fEachComplexComplexab$fEach(,,,,)(,,,,)aq$fEach(,,,)(,,,)aq$fEach(,,)(,,)aq$fEach(,)(,)aqreverseconstFirstheadLeftRight