-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A tiny lens library with no dependencies. If you're writing an app, you probably want microlens-platform, not this.
--   
--   NOTE: If you're writing an app, you probably want
--   <a>microlens-platform</a> – it has the most features. <a>microlens</a>
--   is intended more for library writers who want a tiny lens library
--   (after all, lenses are pretty useful for everything, not just for
--   updating records!).
--   
--   This library is an extract from <a>lens</a> (with no dependencies).
--   It's not a toy lenses library, unsuitable for “real world”, but merely
--   a small one. It is compatible with lens, and should have same
--   performance. It also has better documentation.
--   
--   There's a longer readme <a>on Github</a>. It has a migration guide for
--   lens users, a description of other packages in the family, a
--   discussion of other lens libraries you could use instead, and so on.
--   
--   Here are some usecases for this library:
--   
--   <ul>
--   <li>You want to define lenses or traversals in your own library, but
--   don't want to depend on lens. Having lenses available often make
--   working with a library more pleasant.</li>
--   <li>You just want to be able to use lenses to transform data (or even
--   just use <tt>over _1</tt> to change the first element of a
--   tuple).</li>
--   <li>You are new to lenses and want a small library to play with.</li>
--   </ul>
--   
--   However, don't use this library if:
--   
--   <ul>
--   <li>You need <tt>Iso</tt>s, <tt>Prism</tt>s, indexed traversals, or
--   actually anything else which isn't defined here (tho some indexed
--   functions are available elsewhere – containers and vector provide them
--   for their types, and <a>ilist</a> provides indexed functions for
--   lists).</li>
--   <li>You want a library with a clean, understandable implementation (in
--   which case you're looking for <a>lens-simple</a>).</li>
--   </ul>
--   
--   As already mentioned, if you're writing an application which uses
--   lenses more extensively, look at <a>microlens-platform</a> – it
--   combines features of most other microlens packages
--   (<a>microlens-mtl</a>, <a>microlens-th</a>, <a>microlens-ghc</a>).
--   
--   If you want to export getters or folds and don't mind the
--   <a>contravariant</a> dependency, please consider using
--   <a>microlens-contra</a>.
--   
--   If you haven't ever used lenses before, read <a>this tutorial</a>.
--   (It's for lens, but it applies to microlens just as well.)
--   
--   Note that microlens has no dependencies starting from GHC 7.10
--   (base-4.8). Prior to that, it depends on transformers-0.2 or above.
@package microlens
@version 0.4.7.0


-- | This module provides just the types (<a>Lens</a>, <a>Traversal</a>,
--   etc). It's needed to break the dependency cycle – <a>Lens.Micro</a>
--   depends on <a>Lens.Micro.Internal</a>, but <a>Lens.Micro.Internal</a>
--   needs types like <a>Lens</a>, so <a>Lens</a> can't be defined in
--   <a>Lens.Micro</a>.
module Lens.Micro.Type

-- | <tt>ASetter s t a b</tt> is something that turns a function modifying
--   a value into a function modifying a <i>structure</i>. If you ignore
--   <a>Identity</a> (as <tt>Identity a</tt> is the same thing as
--   <tt>a</tt>), the type is:
--   
--   <pre>
--   type ASetter s t a b = (a -&gt; b) -&gt; s -&gt; t
--   </pre>
--   
--   The reason <a>Identity</a> is used here is for <a>ASetter</a> to be
--   composable with other types, such as <a>Lens</a>.
--   
--   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 <tt><a>Setter</a></tt>, but it is not provided by this package
--   (because then it'd have to depend on <a>distributive</a>). It's
--   completely alright, however, to export functions which take an
--   <a>ASetter</a> as an argument.
type ASetter s t a b = (a -> Identity b) -> s -> Identity t

-- | 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 <tt><a>ASetter'</a></tt> and
--   <tt><a>Setter'</a></tt>.
type ASetter' s a = ASetter s s a a

-- | A <tt>SimpleGetter s a</tt> extracts <tt>a</tt> from <tt>s</tt>; so,
--   it's the same thing as <tt>(s -&gt; a)</tt>, but you can use it in
--   lens chains because its type looks like this:
--   
--   <pre>
--   type SimpleGetter s a =
--     forall r. (a -&gt; Const r a) -&gt; s -&gt; Const r s
--   </pre>
--   
--   Since <tt>Const r</tt> is a functor, <a>SimpleGetter</a> has the same
--   shape as other lens types and can be composed with them. To get <tt>(s
--   -&gt; a)</tt> out of a <a>SimpleGetter</a>, choose <tt>r ~ a</tt> and
--   feed <tt>Const :: a -&gt; Const a a</tt> to the getter:
--   
--   <pre>
--   -- the actual signature is more permissive:
--   -- <a>view</a> :: <a>Getting</a> a s a -&gt; s -&gt; a
--   <a>view</a> :: <a>SimpleGetter</a> s a -&gt; s -&gt; a
--   <a>view</a> getter = <a>getConst</a> . getter <a>Const</a>
--   </pre>
--   
--   The actual <tt><a>Getter</a></tt> from lens is more general:
--   
--   <pre>
--   type Getter s a =
--     forall f. (Contravariant f, Functor f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   I'm not currently aware of any functions that take lens's
--   <tt>Getter</tt> but won't accept <a>SimpleGetter</a>, but you should
--   try to avoid exporting <a>SimpleGetter</a>s anyway to minimise
--   confusion. Alternatively, look at <a>microlens-contra</a>, which
--   provides a fully lens-compatible <tt>Getter</tt>.
--   
--   Lens users: you can convert a <a>SimpleGetter</a> to <tt>Getter</tt>
--   by applying <tt>to . view</tt> to it.
type SimpleGetter s a = forall r. Getting r s a

-- | Functions that operate on getters and folds – such as (<a>^.</a>),
--   (<a>^..</a>), (<a>^?</a>) – use <tt>Getter r s a</tt> (with different
--   values of <tt>r</tt>) to describe what kind of result they need. For
--   instance, (<a>^.</a>) needs the getter to be able to return a single
--   value, and so it accepts a getter of type <tt>Getting a s a</tt>.
--   (<a>^..</a>) wants the getter to gather values together, so it uses
--   <tt>Getting (Endo [a]) s a</tt> (it could've used <tt>Getting [a] s
--   a</tt> instead, but it's faster with <a>Endo</a>). The choice of
--   <tt>r</tt> depends on what you want to do with elements you're
--   extracting from <tt>s</tt>.
type Getting r s a = (a -> Const r a) -> s -> Const r s

-- | A <tt>SimpleFold s a</tt> extracts several <tt>a</tt>s from
--   <tt>s</tt>; so, it's pretty much the same thing as <tt>(s -&gt;
--   [a])</tt>, but you can use it with lens operators.
--   
--   The actual <tt>Fold</tt> from lens is more general:
--   
--   <pre>
--   type Fold s a =
--     forall f. (Contravariant f, Applicative f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   There are several functions in lens that accept lens's <tt>Fold</tt>
--   but won't accept <a>SimpleFold</a>; I'm aware of
--   <tt><a>takingWhile</a></tt>, <tt><a>droppingWhile</a></tt>,
--   <tt><a>backwards</a></tt>, <tt><a>foldByOf</a></tt>,
--   <tt><a>foldMapByOf</a></tt>. For this reason, try not to export
--   <a>SimpleFold</a>s if at all possible. <a>microlens-contra</a>
--   provides a fully lens-compatible <tt>Fold</tt>.
--   
--   Lens users: you can convert a <a>SimpleFold</a> to <tt>Fold</tt> by
--   applying <tt>folded . toListOf</tt> to it.
type SimpleFold s a = forall r. Monoid r => Getting r s a

-- | <tt>Lens s t a b</tt> is the lowest common denominator of a setter and
--   a getter, something that has the power of both; it has a
--   <a>Functor</a> constraint, and since both <a>Const</a> and
--   <a>Identity</a> are functors, it can be used whenever a getter or a
--   setter is needed.
--   
--   <ul>
--   <li><tt>a</tt> is the type of the value inside of structure</li>
--   <li><tt>b</tt> is the type of the replaced value</li>
--   <li><tt>s</tt> is the type of the whole structure</li>
--   <li><tt>t</tt> is the type of the structure after replacing <tt>a</tt>
--   in it with <tt>b</tt></li>
--   </ul>
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

-- | This is a type alias for monomorphic lenses which don't change the
--   type of the container (or of the value inside).
type Lens' s a = Lens s s a a

-- | <tt>Traversal s t a b</tt> is a generalisation of <a>Lens</a> which
--   allows many targets (possibly 0). It's achieved by changing the
--   constraint to <a>Applicative</a> instead of <a>Functor</a> – indeed,
--   the point of <a>Applicative</a> is that you can combine effects, which
--   is just what we need to have many targets.
--   
--   Ultimately, traversals should follow 2 laws:
--   
--   <pre>
--   t pure ≡ pure
--   fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)
--   </pre>
--   
--   The 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 <a>this blog
--   post</a> (if you prefer rambling blog posts), or <a>The Essence Of The
--   Iterator Pattern</a> (if you prefer papers).
--   
--   Traversing any value twice is a violation of traversal laws. You can,
--   however, traverse values in any order.
type Traversal s t a b = forall f. Applicative f => (a -> f b) -> s -> f t

-- | This is a type alias for monomorphic traversals which don't change the
--   type of the container (or of the values inside).
type Traversal' s a = Traversal s s a a

-- | <a>LensLike</a> is a type that is often used to make combinators as
--   general as possible. For instance, take (<a>&lt;&lt;%~</a>), which
--   only requires the passed lens to be able to work with the <tt>(,)
--   a</tt> functor (lenses and traversals can do that). The fully expanded
--   type is as follows:
--   
--   <pre>
--   (<a>&lt;&lt;%~</a>) :: ((a -&gt; (a, b)) -&gt; s -&gt; (a, t)) -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   </pre>
--   
--   With <a>LensLike</a>, the intent to use the <tt>(,) a</tt> functor can
--   be made a bit clearer:
--   
--   <pre>
--   (<a>&lt;&lt;%~</a>) :: LensLike ((,) a) s t a b -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   </pre>
type LensLike f s t a b = (a -> f b) -> s -> f t

-- | A type alias for monomorphic <a>LensLike</a>s.
type LensLike' f s a = LensLike f s s a a


-- | This module is needed to give other packages from the microlens family
--   (like <a>microlens-ghc</a>) access to functions and classes that don't
--   need to be exported from <a>Lens.Micro</a> (because they just clutter
--   the namespace). Also:
--   
--   <ul>
--   <li><a>traversed</a> is here because otherwise there'd be a dependency
--   cycle</li>
--   <li><a>sets</a> is here because it's used in RULEs</li>
--   </ul>
--   
--   Classes like <a>Each</a>, <a>Ixed</a>, etc are provided for
--   convenience – you're not supposed to export functions that work on all
--   members of <a>Ixed</a>, for instance. Only microlens can do that. You
--   mustn't declare instances of those classes for other types, either;
--   these classes are incompatible with lens's classes, and by doing so
--   you would divide the ecosystem.
--   
--   If you absolutely need to define an instance (e.g. for internal use),
--   only do it for your own types, because otherwise I might add an
--   instance to one of the microlens packages later and if our instances
--   are different it might lead to subtle bugs.
module Lens.Micro.Internal

-- | <a>traversed</a> traverses any <a>Traversable</a> container (list,
--   vector, <tt>Map</tt>, <a>Maybe</a>, you name it):
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^.. traversed
--   [1]
--   </pre>
--   
--   <a>traversed</a> is the same as <a>traverse</a>, but can be faster
--   thanks to magic rewrite rules.
traversed :: Traversable f => Traversal (f a) (f b) a b

-- | <a>folded</a> is a fold for anything <a>Foldable</a>. In a way, it's
--   an opposite of <tt>mapped</tt> – the most powerful getter, but can't
--   be used as a setter.
folded :: Foldable f => SimpleFold (f a) a
foldring :: Monoid r => ((a -> Const r a -> Const r a) -> Const r a -> s -> Const r a) -> (a -> Const r b) -> s -> Const r t
foldrOf :: Getting (Endo r) s a -> (a -> r -> r) -> r -> s -> r
foldMapOf :: Getting r s a -> (a -> r) -> s -> r

-- | <a>sets</a> creates an <a>ASetter</a> from an ordinary function. (The
--   only thing it does is wrapping and unwrapping <a>Identity</a>.)
sets :: ((a -> b) -> s -> t) -> ASetter s t a b
(#.) :: Coercible c b => (b -> c) -> (a -> b) -> (a -> c)
infixr 9 #.
(.#) :: Coercible b a => (b -> c) -> (a -> b) -> (a -> c)
infixl 8 .#
phantom :: Const r a -> Const r b
class Each s t a b | s -> a, t -> b, s b -> t, t a -> s

-- | <a>each</a> tries to be a universal <a>Traversal</a> – it behaves like
--   <a>traversed</a> in most situations, but also adds support for e.g.
--   tuples with same-typed values:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) &amp; each %~ succ
--   (2,3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ["x", "y", "z"] ^. each
--   "xyz"
--   </pre>
--   
--   However, note that <a>each</a> doesn't work on <i>every</i> instance
--   of <a>Traversable</a>. If you have a <a>Traversable</a> which isn't
--   supported by <a>each</a>, you can use <a>traversed</a> instead.
--   Personally, I like using <a>each</a> instead of <a>traversed</a>
--   whenever possible – it's shorter and more descriptive.
--   
--   You can use <a>each</a> with these things:
--   
--   <pre>
--   <a>each</a> :: <a>Traversal</a> [a] [b] a b
--   
--   <a>each</a> :: <a>Traversal</a> (<a>Maybe</a> a) (<a>Maybe</a> b) a b
--   
--   <a>each</a> :: <a>Traversal</a> (a,a) (b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a) (b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a) (b,b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a,a) (b,b,b,b,b) a b
--   
--   <a>each</a> :: (<a>RealFloat</a> a, <a>RealFloat</a> b) =&gt; <a>Traversal</a> (<a>Complex</a> a) (<a>Complex</a> b) a b
--   </pre>
--   
--   You can also use <a>each</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
each :: Each s t a b => Traversal s t a b
class Ixed m

-- | This traversal lets you access (and update) an arbitrary element in a
--   list, array, <tt>Map</tt>, etc. (If you want to insert or delete
--   elements as well, look at <a>at</a>.)
--   
--   An example for lists:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] &amp; ix 3 .~ 10
--   [0,1,2,10,4,5]
--   </pre>
--   
--   You can use it for getting, too:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 3
--   Just 3
--   </pre>
--   
--   Of course, the element may not be present (which means that you can
--   use <a>ix</a> as a safe variant of (<a>!!</a>)):
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 10
--   Nothing
--   </pre>
--   
--   Another useful instance is the one for functions – it lets you modify
--   their outputs for specific inputs. For instance, here's <a>maximum</a>
--   that returns 0 when the list is empty (instead of throwing an
--   exception):
--   
--   <pre>
--   maximum0 = <a>maximum</a> <a>&amp;</a> <a>ix</a> [] <a>.~</a> 0
--   </pre>
--   
--   The following instances are provided in this package:
--   
--   <pre>
--   <a>ix</a> :: <a>Int</a> -&gt; <a>Traversal'</a> [a] a
--   
--   <a>ix</a> :: (<a>Eq</a> e) =&gt; e -&gt; <a>Traversal'</a> (e -&gt; a) a
--   </pre>
--   
--   You can also use <a>ix</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
ix :: Ixed m => Index m -> Traversal' m (IxValue m)
class Ixed m => At m

-- | This lens lets you read, write, or delete elements in
--   <tt>Map</tt>-like structures. It returns <a>Nothing</a> when the value
--   isn't found, just like <tt>lookup</tt>:
--   
--   <pre>
--   Data.Map.lookup k m = m <a>^.</a> at k
--   </pre>
--   
--   However, it also lets you insert and delete values by setting the
--   value to <tt><a>Just</a> value</tt> or <a>Nothing</a>:
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>.~</a> Just a
--   
--   Data.Map.delete k m = m <a>&amp;</a> at k <a>.~</a> Nothing
--   </pre>
--   
--   Or you could use (<a>?~</a>) instead of (<a>.~</a>):
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>?~</a> a
--   </pre>
--   
--   Note that <a>at</a> doesn't work for arrays or lists. You can't delete
--   an arbitrary element from an array (what would be left in its place?),
--   and you can't set an arbitrary element in a list because if the index
--   is out of list's bounds, you'd have to somehow fill the stretch
--   between the last element and the element you just inserted (i.e.
--   <tt>[1,2,3] &amp; at 10 .~ 5</tt> is undefined). If you want to modify
--   an already existing value in an array or list, you should use
--   <a>ix</a> instead.
--   
--   <a>at</a> is often used with <a>non</a>. See the documentation of
--   <a>non</a> for examples.
--   
--   Note that <a>at</a> isn't strict for <tt>Map</tt>, even if you're
--   using <tt>Data.Map.Strict</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Map.Strict.size (Data.Map.Strict.empty &amp; at 1 .~ Just undefined)
--   1
--   </pre>
--   
--   The reason for such behavior is that there's actually no “strict
--   <tt>Map</tt>” type; <tt>Data.Map.Strict</tt> just provides some strict
--   functions for ordinary <tt>Map</tt>s.
--   
--   This package doesn't actually provide any instances for <a>at</a>, but
--   there are instances for <tt>Map</tt> and <tt>IntMap</tt> in
--   <a>microlens-ghc</a> and an instance for <tt>HashMap</tt> in
--   <a>microlens-platform</a>.
at :: At m => Index m -> Lens' m (Maybe (IxValue m))
ixAt :: At m => Index m -> Traversal' m (IxValue m)
class Field1 s t a b | s -> a, t -> b, s b -> t, t a -> s

-- | Gives access to the 1st field of a tuple (up to 5-tuples).
--   
--   Getting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4,5) ^. _1
--   1
--   </pre>
--   
--   Setting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3) &amp; _1 .~ 10
--   (10,2,3)
--   </pre>
--   
--   Note that this lens is lazy, and can set fields even of
--   <a>undefined</a>:
--   
--   <pre>
--   &gt;&gt;&gt; set _1 10 undefined :: (Int, Int)
--   (10,*** Exception: Prelude.undefined
--   </pre>
--   
--   This is done to avoid violating a lens law stating that you can get
--   back what you put:
--   
--   <pre>
--   &gt;&gt;&gt; view _1 . set _1 10 $ (undefined :: (Int, Int))
--   10
--   </pre>
--   
--   The implementation (for 2-tuples) is:
--   
--   <pre>
--   <a>_1</a> f t = (,) <a>&lt;$&gt;</a> f    (<a>fst</a> t)
--                <a>&lt;*&gt;</a> <a>pure</a> (<a>snd</a> t)
--   </pre>
--   
--   or, alternatively,
--   
--   <pre>
--   <a>_1</a> f ~(a,b) = (\a' -&gt; (a',b)) <a>&lt;$&gt;</a> f a
--   </pre>
--   
--   (where <tt>~</tt> means a <a>lazy pattern</a>).
--   
--   <a>_2</a>, <a>_3</a>, <a>_4</a>, and <a>_5</a> are also available (see
--   below).
_1 :: Field1 s t a b => Lens s t a b
class Field2 s t a b | s -> a, t -> b, s b -> t, t a -> s
_2 :: Field2 s t a b => Lens s t a b
class Field3 s t a b | s -> a, t -> b, s b -> t, t a -> s
_3 :: Field3 s t a b => Lens s t a b
class Field4 s t a b | s -> a, t -> b, s b -> t, t a -> s
_4 :: Field4 s t a b => Lens s t a b
class Field5 s t a b | s -> a, t -> b, s b -> t, t a -> s
_5 :: Field5 s t a b => Lens s t a b
class Cons s t a b | s -> a, t -> b, s b -> t, t a -> s
_Cons :: Cons s t a b => Traversal s t (a, s) (b, t)
class Snoc s t a b | s -> a, t -> b, s b -> t, t a -> s
_Snoc :: Snoc s t a b => Traversal s t (s, a) (t, b)
class Strict lazy strict | lazy -> strict, strict -> lazy

-- | <a>strict</a> lets you convert between strict and lazy versions of a
--   datatype:
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "hello" :: Lazy.Text
--   
--   &gt;&gt;&gt; someText ^. strict
--   "hello" :: Strict.Text
--   </pre>
--   
--   It can also be useful if you have a function that works on a strict
--   type but your type is lazy:
--   
--   <pre>
--   stripDiacritics :: Strict.Text -&gt; Strict.Text
--   stripDiacritics = ...
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "Paul Erdős" :: Lazy.Text
--   
--   &gt;&gt;&gt; someText &amp; strict %~ stripDiacritics
--   "Paul Erdos" :: Lazy.Text
--   </pre>
--   
--   <a>strict</a> works on <tt>ByteString</tt> and
--   <tt>StateT</tt>/<tt>WriterT</tt>/<tt>RWST</tt> if you use
--   <a>microlens-ghc</a>, and additionally on <tt>Text</tt> if you use
--   <a>microlens-platform</a>.
strict :: Strict lazy strict => Lens' lazy strict

-- | <a>lazy</a> is like <a>strict</a> but works in opposite direction:
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "hello" :: Strict.Text
--   
--   &gt;&gt;&gt; someText ^. lazy
--   "hello" :: Lazy.Text
--   </pre>
lazy :: Strict lazy strict => Lens' strict lazy
instance (a ~ b, q ~ r) => Lens.Micro.Internal.Each (a, b) (q, r) a q
instance (a ~ b, a ~ c, q ~ r, q ~ s) => Lens.Micro.Internal.Each (a, b, c) (q, r, s) a q
instance (a ~ b, a ~ c, a ~ d, q ~ r, q ~ s, q ~ t) => Lens.Micro.Internal.Each (a, b, c, d) (q, r, s, t) a q
instance (a ~ b, a ~ c, a ~ d, a ~ e, q ~ r, q ~ s, q ~ t, q ~ u) => Lens.Micro.Internal.Each (a, b, c, d, e) (q, r, s, t, u) a q
instance Lens.Micro.Internal.Each (Data.Complex.Complex a) (Data.Complex.Complex b) a b
instance Lens.Micro.Internal.Each [a] [b] a b
instance Lens.Micro.Internal.Each (GHC.Base.Maybe a) (GHC.Base.Maybe b) a b
instance GHC.Classes.Eq e => Lens.Micro.Internal.Ixed (e -> a)
instance Lens.Micro.Internal.Ixed [a]
instance Lens.Micro.Internal.Field1 (a, b) (a', b) a a'
instance Lens.Micro.Internal.Field1 (a, b, c) (a', b, c) a a'
instance Lens.Micro.Internal.Field1 (a, b, c, d) (a', b, c, d) a a'
instance Lens.Micro.Internal.Field1 (a, b, c, d, e) (a', b, c, d, e) a a'
instance Lens.Micro.Internal.Field2 (a, b) (a, b') b b'
instance Lens.Micro.Internal.Field2 (a, b, c) (a, b', c) b b'
instance Lens.Micro.Internal.Field2 (a, b, c, d) (a, b', c, d) b b'
instance Lens.Micro.Internal.Field2 (a, b, c, d, e) (a, b', c, d, e) b b'
instance Lens.Micro.Internal.Field3 (a, b, c) (a, b, c') c c'
instance Lens.Micro.Internal.Field3 (a, b, c, d) (a, b, c', d) c c'
instance Lens.Micro.Internal.Field3 (a, b, c, d, e) (a, b, c', d, e) c c'
instance Lens.Micro.Internal.Field4 (a, b, c, d) (a, b, c, d') d d'
instance Lens.Micro.Internal.Field4 (a, b, c, d, e) (a, b, c, d', e) d d'
instance Lens.Micro.Internal.Field5 (a, b, c, d, e) (a, b, c, d, e') e e'
instance Lens.Micro.Internal.Cons [a] [b] a b
instance Lens.Micro.Internal.Snoc [a] [b] a b


-- | This module provides the essential functionality. There are other
--   packages in the microlens family – mix and match them at will. If
--   you're writing an app, you want <a>microlens-platform</a> – it
--   provides the most functionality.
--   
--   <ul>
--   <li><a>microlens-mtl</a> – (<tt>+=</tt>) and friends, <tt>use</tt>,
--   <tt>zoom</tt>/<tt>magnify</tt></li>
--   <li><a>microlens-th</a> – <tt>makeLenses</tt> and
--   <tt>makeFields</tt></li>
--   <li><a>microlens-ghc</a> – everything in microlens + instances to make
--   <tt>each</tt>/<tt>at</tt>/<tt>ix</tt> usable with arrays,
--   <tt>ByteString</tt>, and containers</li>
--   <li><a>microlens-platform</a> – microlens-ghc + microlens-mtl +
--   microlens-th + instances for <tt>Text</tt>, <tt>Vector</tt>, and
--   <tt>HashMap</tt></li>
--   <li><a>microlens-contra</a> – <tt>Fold</tt> and <tt>Getter</tt> that
--   are exact copies of types in lens</li>
--   </ul>
--   
--   Unofficial:
--   
--   <ul>
--   <li><a>microlens-aeson</a> – a port of <a>lens-aeson</a></li>
--   </ul>
module Lens.Micro

-- | <a>&amp;</a> is a reverse application operator. This provides
--   notational convenience. Its precedence is one higher than that of the
--   forward application operator <a>$</a>, which allows <a>&amp;</a> to be
--   nested in <a>$</a>.
(&) :: a -> (a -> b) -> b
infixl 1 &

-- | (<a>&lt;&amp;&gt;</a>) is flipped (<a>&lt;$&gt;</a>):
--   
--   <pre>
--   x <a>&lt;&amp;&gt;</a> f = f <a>&lt;$&gt;</a> x
--   </pre>
--   
--   It's often useful when writing lenses. For instance, let's say you're
--   writing <a>ix</a> for <tt>Map</tt>; if the key is found in the map,
--   you have to apply a function to it and then change the map based on
--   the new value – which requires a lambda, like this:
--   
--   <pre>
--   <a>ix</a> key f map = case Map.lookup key map of
--        Just val -&gt; (\val' -&gt; Map.insert key val' map) <a>&lt;$&gt;</a> f val
--        Nothing  -&gt; <a>pure</a> map
--   </pre>
--   
--   With (<a>&lt;&amp;&gt;</a>) you can get rid of parentheses and move
--   the long lambda expression to the right of the value (like when you
--   use <a>&gt;&gt;=</a>):
--   
--   <pre>
--   <a>ix</a> key f map = case Map.lookup key map of
--        Just val -&gt; f val <a>&lt;&amp;&gt;</a> \val' -&gt; Map.insert key val' map
--        Nothing  -&gt; <a>pure</a> map
--   </pre>
(<&>) :: Functor f => f a -> (a -> b) -> f b
infixl 1 <&>

-- | <tt>ASetter s t a b</tt> is something that turns a function modifying
--   a value into a function modifying a <i>structure</i>. If you ignore
--   <a>Identity</a> (as <tt>Identity a</tt> is the same thing as
--   <tt>a</tt>), the type is:
--   
--   <pre>
--   type ASetter s t a b = (a -&gt; b) -&gt; s -&gt; t
--   </pre>
--   
--   The reason <a>Identity</a> is used here is for <a>ASetter</a> to be
--   composable with other types, such as <a>Lens</a>.
--   
--   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 <tt><a>Setter</a></tt>, but it is not provided by this package
--   (because then it'd have to depend on <a>distributive</a>). It's
--   completely alright, however, to export functions which take an
--   <a>ASetter</a> as an argument.
type ASetter s t a b = (a -> Identity b) -> s -> Identity t

-- | 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 <tt><a>ASetter'</a></tt> and
--   <tt><a>Setter'</a></tt>.
type ASetter' s a = ASetter s s a a

-- | <a>sets</a> creates an <a>ASetter</a> from an ordinary function. (The
--   only thing it does is wrapping and unwrapping <a>Identity</a>.)
sets :: ((a -> b) -> s -> t) -> ASetter s t a b

-- | (<a>%~</a>) applies a function to the target; an alternative
--   explanation is that it is an inverse of <a>sets</a>, which turns a
--   setter into an ordinary function. <tt><a>mapped</a> <a>%~</a>
--   <a>reverse</a></tt> is the same thing as <tt><a>fmap</a>
--   <a>reverse</a></tt>.
--   
--   See <a>over</a> if you want a non-operator synonym.
--   
--   Negating the 1st element of a pair:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) &amp; _1 %~ negate
--   (-1,2)
--   </pre>
--   
--   Turning all <tt>Left</tt>s in a list to upper case:
--   
--   <pre>
--   &gt;&gt;&gt; (mapped._Left.mapped %~ toUpper) [Left "foo", Right "bar"]
--   [Left "FOO",Right "bar"]
--   </pre>
(%~) :: ASetter s t a b -> (a -> b) -> s -> t
infixr 4 %~

-- | <a>over</a> is a synonym for (<a>%~</a>).
--   
--   Getting <a>fmap</a> in a roundabout way:
--   
--   <pre>
--   <a>over</a> <a>mapped</a> :: <a>Functor</a> f =&gt; (a -&gt; b) -&gt; f a -&gt; f b
--   <a>over</a> <a>mapped</a> = <a>fmap</a>
--   </pre>
--   
--   Applying a function to both components of a pair:
--   
--   <pre>
--   <a>over</a> <a>both</a> :: (a -&gt; b) -&gt; (a, a) -&gt; (b, b)
--   <a>over</a> <a>both</a> = \f t -&gt; (f (fst t), f (snd t))
--   </pre>
--   
--   Using <tt><a>over</a> <a>_2</a></tt> as a replacement for
--   <a>second</a>:
--   
--   <pre>
--   &gt;&gt;&gt; over _2 show (10,20)
--   (10,"20")
--   </pre>
over :: ASetter s t a b -> (a -> b) -> s -> t

-- | (<a>.~</a>) assigns a value to the target. It's the same thing as
--   using (<a>%~</a>) with <a>const</a>:
--   
--   <pre>
--   l <a>.~</a> x = l <a>%~</a> <a>const</a> x
--   </pre>
--   
--   See <a>set</a> if you want a non-operator synonym.
--   
--   Here it is used to change 2 fields of a 3-tuple:
--   
--   <pre>
--   &gt;&gt;&gt; (0,0,0) &amp; _1 .~ 1 &amp; _3 .~ 3
--   (1,0,3)
--   </pre>
(.~) :: ASetter s t a b -> b -> s -> t
infixr 4 .~

-- | <a>set</a> is a synonym for (<a>.~</a>).
--   
--   Setting the 1st component of a pair:
--   
--   <pre>
--   <a>set</a> <a>_1</a> :: x -&gt; (a, b) -&gt; (x, b)
--   <a>set</a> <a>_1</a> = \x t -&gt; (x, snd t)
--   </pre>
--   
--   Using it to rewrite (<a>&lt;$</a>):
--   
--   <pre>
--   <a>set</a> <a>mapped</a> :: <a>Functor</a> f =&gt; a -&gt; f b -&gt; f a
--   <a>set</a> <a>mapped</a> = (<a>&lt;$</a>)
--   </pre>
set :: ASetter s t a b -> b -> s -> t

-- | (<a>?~</a>) is a version of (<a>.~</a>) that wraps the value into
--   <a>Just</a> before setting.
--   
--   <pre>
--   l ?~ b = l .~ Just b
--   </pre>
--   
--   It can be useful in combination with <a>at</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Map.empty &amp; at 3 ?~ x
--   fromList [(3,x)]
--   </pre>
(?~) :: ASetter s t a (Maybe b) -> b -> s -> t
infixr 4 ?~

-- | This is a version of (<a>%~</a>) which modifies the structure and
--   returns it along with the new value:
--   
--   <pre>
--   &gt;&gt;&gt; (1, 2) &amp; _1 &lt;%~ negate
--   (-1, (-1, 2))
--   </pre>
--   
--   Simpler type signatures:
--   
--   <pre>
--   (<a>&lt;%~</a>) ::             <a>Lens</a> s t a b      -&gt; (a -&gt; b) -&gt; s -&gt; (b, t)
--   (<a>&lt;%~</a>) :: <a>Monoid</a> b =&gt; <a>Traversal</a> s t a b -&gt; (a -&gt; b) -&gt; s -&gt; (b, t)
--   </pre>
--   
--   Since it does getting in addition to setting, you can't use it with
--   <a>ASetter</a> (but you can use it with lens and traversals).
(<%~) :: LensLike ((,) b) s t a b -> (a -> b) -> s -> (b, t)

-- | This is a version of (<a>%~</a>) which modifies the structure and
--   returns it along with the old value:
--   
--   <pre>
--   &gt;&gt;&gt; (1, 2) &amp; _1 &lt;&lt;%~ negate
--   (1, (-1, 2))
--   </pre>
--   
--   Simpler type signatures:
--   
--   <pre>
--   (<a>&lt;&lt;%~</a>) ::             <a>Lens</a> s t a b      -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   (<a>&lt;&lt;%~</a>) :: <a>Monoid</a> a =&gt; <a>Traversal</a> s t a b -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   </pre>
(<<%~) :: LensLike ((,) a) s t a b -> (a -> b) -> s -> (a, t)

-- | This is a version of (<a>.~</a>) which modifies the structure and
--   returns it along with the old value:
--   
--   <pre>
--   &gt;&gt;&gt; (1, 2) &amp; _1 &lt;&lt;.~ 0
--   (1, (0, 2))
--   </pre>
--   
--   Simpler type signatures:
--   
--   <pre>
--   (<a>&lt;&lt;.~</a>) ::             <a>Lens</a> s t a b      -&gt; b -&gt; s -&gt; (a, t)
--   (<a>&lt;&lt;.~</a>) :: <a>Monoid</a> a =&gt; <a>Traversal</a> s t a b -&gt; b -&gt; s -&gt; (a, t)
--   </pre>
(<<.~) :: LensLike ((,) a) s t a b -> b -> s -> (a, t)

-- | <a>mapped</a> is a setter for everything contained in a functor. You
--   can use it to map over lists, <tt>Maybe</tt>, or even <tt>IO</tt>
--   (which is something you can't do with <a>traversed</a> or
--   <a>each</a>).
--   
--   Here <a>mapped</a> is used to turn a value to all non-<a>Nothing</a>
--   values in a list:
--   
--   <pre>
--   &gt;&gt;&gt; [Just 3,Nothing,Just 5] &amp; mapped.mapped .~ 0
--   [Just 0,Nothing,Just 0]
--   </pre>
--   
--   Keep in mind that while <a>mapped</a> is a more powerful setter than
--   <a>each</a>, it can't be used as a getter! This won't work (and will
--   fail with a type error):
--   
--   <pre>
--   [(1,2),(3,4),(5,6)] <a>^..</a> <a>mapped</a> . <a>both</a>
--   </pre>
mapped :: Functor f => ASetter (f a) (f b) a b

-- | A <tt>SimpleGetter s a</tt> extracts <tt>a</tt> from <tt>s</tt>; so,
--   it's the same thing as <tt>(s -&gt; a)</tt>, but you can use it in
--   lens chains because its type looks like this:
--   
--   <pre>
--   type SimpleGetter s a =
--     forall r. (a -&gt; Const r a) -&gt; s -&gt; Const r s
--   </pre>
--   
--   Since <tt>Const r</tt> is a functor, <a>SimpleGetter</a> has the same
--   shape as other lens types and can be composed with them. To get <tt>(s
--   -&gt; a)</tt> out of a <a>SimpleGetter</a>, choose <tt>r ~ a</tt> and
--   feed <tt>Const :: a -&gt; Const a a</tt> to the getter:
--   
--   <pre>
--   -- the actual signature is more permissive:
--   -- <a>view</a> :: <a>Getting</a> a s a -&gt; s -&gt; a
--   <a>view</a> :: <a>SimpleGetter</a> s a -&gt; s -&gt; a
--   <a>view</a> getter = <a>getConst</a> . getter <a>Const</a>
--   </pre>
--   
--   The actual <tt><a>Getter</a></tt> from lens is more general:
--   
--   <pre>
--   type Getter s a =
--     forall f. (Contravariant f, Functor f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   I'm not currently aware of any functions that take lens's
--   <tt>Getter</tt> but won't accept <a>SimpleGetter</a>, but you should
--   try to avoid exporting <a>SimpleGetter</a>s anyway to minimise
--   confusion. Alternatively, look at <a>microlens-contra</a>, which
--   provides a fully lens-compatible <tt>Getter</tt>.
--   
--   Lens users: you can convert a <a>SimpleGetter</a> to <tt>Getter</tt>
--   by applying <tt>to . view</tt> to it.
type SimpleGetter s a = forall r. Getting r s a

-- | Functions that operate on getters and folds – such as (<a>^.</a>),
--   (<a>^..</a>), (<a>^?</a>) – use <tt>Getter r s a</tt> (with different
--   values of <tt>r</tt>) to describe what kind of result they need. For
--   instance, (<a>^.</a>) needs the getter to be able to return a single
--   value, and so it accepts a getter of type <tt>Getting a s a</tt>.
--   (<a>^..</a>) wants the getter to gather values together, so it uses
--   <tt>Getting (Endo [a]) s a</tt> (it could've used <tt>Getting [a] s
--   a</tt> instead, but it's faster with <a>Endo</a>). The choice of
--   <tt>r</tt> depends on what you want to do with elements you're
--   extracting from <tt>s</tt>.
type Getting r s a = (a -> Const r a) -> s -> Const r s

-- | (<a>^.</a>) 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:
--   
--   <pre>
--   (<a>^.</a> <a>_1</a>) :: (a, b) -&gt; a
--   (<a>^.</a> <a>_1</a>) = <a>fst</a>
--   </pre>
--   
--   When (<a>^.</a>) is used with a traversal, it combines all results
--   using the <a>Monoid</a> instance for the resulting type. For instance,
--   for lists it would be simple concatenation:
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") ^. each
--   "string"
--   </pre>
--   
--   The reason for this is that traversals use <a>Applicative</a>, and the
--   <a>Applicative</a> instance for <a>Const</a> uses monoid concatenation
--   to combine “effects” of <a>Const</a>.
--   
--   A non-operator version of (<a>^.</a>) is called <tt>view</tt>, and
--   it's a bit more general than (<a>^.</a>) (it works in
--   <tt>MonadReader</tt>). If you need the general version, you can get it
--   from <a>microlens-mtl</a>; otherwise there's <a>view</a> available in
--   <a>Lens.Micro.Extras</a>.
(^.) :: s -> Getting a s a -> a
infixl 8 ^.

-- | <a>to</a> creates a getter from any function:
--   
--   <pre>
--   a <a>^.</a> <a>to</a> f = f a
--   </pre>
--   
--   It's most useful in chains, because it lets you mix lenses and
--   ordinary functions. Suppose you have a record which comes from some
--   third-party library and doesn't have any lens accessors. You want to
--   do something like this:
--   
--   <pre>
--   value ^. _1 . field . at 2
--   </pre>
--   
--   However, <tt>field</tt> isn't a getter, and you have to do this
--   instead:
--   
--   <pre>
--   field (value ^. _1) ^. at 2
--   </pre>
--   
--   but now <tt>value</tt> is in the middle and it's hard to read the
--   resulting code. A variant with <a>to</a> is prettier and more
--   readable:
--   
--   <pre>
--   value ^. _1 . to field . at 2
--   </pre>
to :: (s -> a) -> SimpleGetter s a

-- | A <tt>SimpleFold s a</tt> extracts several <tt>a</tt>s from
--   <tt>s</tt>; so, it's pretty much the same thing as <tt>(s -&gt;
--   [a])</tt>, but you can use it with lens operators.
--   
--   The actual <tt>Fold</tt> from lens is more general:
--   
--   <pre>
--   type Fold s a =
--     forall f. (Contravariant f, Applicative f) =&gt; (a -&gt; f a) -&gt; s -&gt; f s
--   </pre>
--   
--   There are several functions in lens that accept lens's <tt>Fold</tt>
--   but won't accept <a>SimpleFold</a>; I'm aware of
--   <tt><a>takingWhile</a></tt>, <tt><a>droppingWhile</a></tt>,
--   <tt><a>backwards</a></tt>, <tt><a>foldByOf</a></tt>,
--   <tt><a>foldMapByOf</a></tt>. For this reason, try not to export
--   <a>SimpleFold</a>s if at all possible. <a>microlens-contra</a>
--   provides a fully lens-compatible <tt>Fold</tt>.
--   
--   Lens users: you can convert a <a>SimpleFold</a> to <tt>Fold</tt> by
--   applying <tt>folded . toListOf</tt> to it.
type SimpleFold s a = forall r. Monoid r => Getting r s a

-- | <tt>s ^.. t</tt> returns the list of all values that <tt>t</tt> gets
--   from <tt>s</tt>.
--   
--   A <a>Maybe</a> contains either 0 or 1 values:
--   
--   <pre>
--   &gt;&gt;&gt; Just 3 ^.. _Just
--   [3]
--   </pre>
--   
--   Gathering all values in a list of tuples:
--   
--   <pre>
--   &gt;&gt;&gt; [(1,2),(3,4)] ^.. each.each
--   [1,2,3,4]
--   </pre>
(^..) :: s -> Getting (Endo [a]) s a -> [a]
infixl 8 ^..

-- | <a>toListOf</a> is a synonym for (<a>^..</a>).
toListOf :: Getting (Endo [a]) s a -> s -> [a]

-- | <tt>s ^? t</tt> returns the 1st element <tt>t</tt> returns, or
--   <a>Nothing</a> if <tt>t</tt> doesn't return anything. It's trivially
--   implemented by passing the <a>First</a> monoid to the getter.
--   
--   Safe <a>head</a>:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^? each
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1..3] ^? each
--   Just 1
--   </pre>
--   
--   Converting <a>Either</a> to <a>Maybe</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Left 1 ^? _Right
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Right 1 ^? _Right
--   Just 1
--   </pre>
--   
--   A non-operator version of (<a>^?</a>) is called <tt>preview</tt>, and
--   – like <tt>view</tt> – it's a bit more general than (<a>^?</a>) (it
--   works in <tt>MonadReader</tt>). If you need the general version, you
--   can get it from <a>microlens-mtl</a>; otherwise there's <a>preview</a>
--   available in <a>Lens.Micro.Extras</a>.
(^?) :: s -> Getting (First a) s a -> Maybe a
infixl 8 ^?

-- | (<a>^?!</a>) is an unsafe variant of (<a>^?</a>) – instead of using
--   <a>Nothing</a> to indicate that there were no elements returned, it
--   throws an exception.
(^?!) :: s -> Getting (Endo a) s a -> a
infixl 8 ^?!

-- | Apply an action to all targets and discard the result (like
--   <a>mapM_</a> or <a>traverse_</a>):
--   
--   <pre>
--   &gt;&gt;&gt; traverseOf_ both putStrLn ("hello", "world")
--   hello
--   world
--   </pre>
--   
--   Works with anything that allows getting, including lenses and getters
--   (so, anything except for <a>ASetter</a>). Should be faster than
--   <a>traverseOf</a> when you don't need the result.
traverseOf_ :: Functor f => Getting (Traversed r f) s a -> (a -> f r) -> s -> f ()

-- | <a>has</a> checks whether a getter (any getter, including lenses,
--   traversals, and folds) returns at least 1 value.
--   
--   Checking whether a list is non-empty:
--   
--   <pre>
--   &gt;&gt;&gt; has each []
--   False
--   </pre>
--   
--   You can also use it with e.g. <a>_Left</a> (and other 0-or-1
--   traversals) as a replacement for <a>isNothing</a>, <a>isJust</a> and
--   other <tt>isConstructorName</tt> functions:
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Left 1)
--   True
--   </pre>
has :: Getting Any s a -> s -> Bool

-- | <a>folded</a> is a fold for anything <a>Foldable</a>. In a way, it's
--   an opposite of <tt>mapped</tt> – the most powerful getter, but can't
--   be used as a setter.
folded :: Foldable f => SimpleFold (f a) a

-- | <a>folding</a> creates a fold out of any function that returns a
--   <a>Foldable</a> container (for instance, a list):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^.. folding tail
--   [2,3,4,5]
--   </pre>
folding :: Foldable f => (s -> f a) -> SimpleFold s a

-- | <tt>Lens s t a b</tt> is the lowest common denominator of a setter and
--   a getter, something that has the power of both; it has a
--   <a>Functor</a> constraint, and since both <a>Const</a> and
--   <a>Identity</a> are functors, it can be used whenever a getter or a
--   setter is needed.
--   
--   <ul>
--   <li><tt>a</tt> is the type of the value inside of structure</li>
--   <li><tt>b</tt> is the type of the replaced value</li>
--   <li><tt>s</tt> is the type of the whole structure</li>
--   <li><tt>t</tt> is the type of the structure after replacing <tt>a</tt>
--   in it with <tt>b</tt></li>
--   </ul>
type Lens s t a b = forall f. Functor f => (a -> f b) -> s -> f t

-- | This is a type alias for monomorphic lenses which don't change the
--   type of the container (or of the value inside).
type Lens' s a = Lens s s a a

-- | <a>lens</a> creates a <a>Lens</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:
--   
--   <pre>
--   ix :: Int -&gt; <a>Lens'</a> [a] a
--   ix i = <a>lens</a> (<a>!!</a> i)                                   -- getter
--               (\s b -&gt; take i s ++ b : drop (i+1) s)   -- setter
--   </pre>
--   
--   Usage:
--   
--   <pre>
--   &gt;&gt;&gt; [1..9] <a>^.</a> ix 3
--   4
--   
--   &gt;&gt;&gt; [1..9] &amp; ix 3 <a>%~</a> negate
--   [1,2,3,-4,5,6,7,8,9]
--   </pre>
--   
--   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 <a>undefined</a>. Then we use
--   the resulting lens for <i>setting</i> and it works, which proves that
--   the getter wasn't used:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &amp; lens undefined (\s b -&gt; b : tail s) .~ 10
--   [10,2,3]
--   </pre>
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b

-- | This lens lets you read, write, or delete elements in
--   <tt>Map</tt>-like structures. It returns <a>Nothing</a> when the value
--   isn't found, just like <tt>lookup</tt>:
--   
--   <pre>
--   Data.Map.lookup k m = m <a>^.</a> at k
--   </pre>
--   
--   However, it also lets you insert and delete values by setting the
--   value to <tt><a>Just</a> value</tt> or <a>Nothing</a>:
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>.~</a> Just a
--   
--   Data.Map.delete k m = m <a>&amp;</a> at k <a>.~</a> Nothing
--   </pre>
--   
--   Or you could use (<a>?~</a>) instead of (<a>.~</a>):
--   
--   <pre>
--   Data.Map.insert k a m = m <a>&amp;</a> at k <a>?~</a> a
--   </pre>
--   
--   Note that <a>at</a> doesn't work for arrays or lists. You can't delete
--   an arbitrary element from an array (what would be left in its place?),
--   and you can't set an arbitrary element in a list because if the index
--   is out of list's bounds, you'd have to somehow fill the stretch
--   between the last element and the element you just inserted (i.e.
--   <tt>[1,2,3] &amp; at 10 .~ 5</tt> is undefined). If you want to modify
--   an already existing value in an array or list, you should use
--   <a>ix</a> instead.
--   
--   <a>at</a> is often used with <a>non</a>. See the documentation of
--   <a>non</a> for examples.
--   
--   Note that <a>at</a> isn't strict for <tt>Map</tt>, even if you're
--   using <tt>Data.Map.Strict</tt>:
--   
--   <pre>
--   &gt;&gt;&gt; Data.Map.Strict.size (Data.Map.Strict.empty &amp; at 1 .~ Just undefined)
--   1
--   </pre>
--   
--   The reason for such behavior is that there's actually no “strict
--   <tt>Map</tt>” type; <tt>Data.Map.Strict</tt> just provides some strict
--   functions for ordinary <tt>Map</tt>s.
--   
--   This package doesn't actually provide any instances for <a>at</a>, but
--   there are instances for <tt>Map</tt> and <tt>IntMap</tt> in
--   <a>microlens-ghc</a> and an instance for <tt>HashMap</tt> in
--   <a>microlens-platform</a>.
at :: At m => Index m -> Lens' m (Maybe (IxValue m))

-- | Gives access to the 1st field of a tuple (up to 5-tuples).
--   
--   Getting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4,5) ^. _1
--   1
--   </pre>
--   
--   Setting the 1st component:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3) &amp; _1 .~ 10
--   (10,2,3)
--   </pre>
--   
--   Note that this lens is lazy, and can set fields even of
--   <a>undefined</a>:
--   
--   <pre>
--   &gt;&gt;&gt; set _1 10 undefined :: (Int, Int)
--   (10,*** Exception: Prelude.undefined
--   </pre>
--   
--   This is done to avoid violating a lens law stating that you can get
--   back what you put:
--   
--   <pre>
--   &gt;&gt;&gt; view _1 . set _1 10 $ (undefined :: (Int, Int))
--   10
--   </pre>
--   
--   The implementation (for 2-tuples) is:
--   
--   <pre>
--   <a>_1</a> f t = (,) <a>&lt;$&gt;</a> f    (<a>fst</a> t)
--                <a>&lt;*&gt;</a> <a>pure</a> (<a>snd</a> t)
--   </pre>
--   
--   or, alternatively,
--   
--   <pre>
--   <a>_1</a> f ~(a,b) = (\a' -&gt; (a',b)) <a>&lt;$&gt;</a> f a
--   </pre>
--   
--   (where <tt>~</tt> means a <a>lazy pattern</a>).
--   
--   <a>_2</a>, <a>_3</a>, <a>_4</a>, and <a>_5</a> are also available (see
--   below).
_1 :: Field1 s t a b => Lens s t a b
_2 :: Field2 s t a b => Lens s t a b
_3 :: Field3 s t a b => Lens s t a b
_4 :: Field4 s t a b => Lens s t a b
_5 :: Field5 s t a b => Lens s t a b

-- | <a>strict</a> lets you convert between strict and lazy versions of a
--   datatype:
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "hello" :: Lazy.Text
--   
--   &gt;&gt;&gt; someText ^. strict
--   "hello" :: Strict.Text
--   </pre>
--   
--   It can also be useful if you have a function that works on a strict
--   type but your type is lazy:
--   
--   <pre>
--   stripDiacritics :: Strict.Text -&gt; Strict.Text
--   stripDiacritics = ...
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "Paul Erdős" :: Lazy.Text
--   
--   &gt;&gt;&gt; someText &amp; strict %~ stripDiacritics
--   "Paul Erdos" :: Lazy.Text
--   </pre>
--   
--   <a>strict</a> works on <tt>ByteString</tt> and
--   <tt>StateT</tt>/<tt>WriterT</tt>/<tt>RWST</tt> if you use
--   <a>microlens-ghc</a>, and additionally on <tt>Text</tt> if you use
--   <a>microlens-platform</a>.
strict :: Strict lazy strict => Lens' lazy strict

-- | <a>lazy</a> is like <a>strict</a> but works in opposite direction:
--   
--   <pre>
--   &gt;&gt;&gt; let someText = "hello" :: Strict.Text
--   
--   &gt;&gt;&gt; someText ^. lazy
--   "hello" :: Lazy.Text
--   </pre>
lazy :: Strict lazy strict => Lens' strict lazy

-- | <a>non</a> lets you “relabel” a <a>Maybe</a> by equating
--   <a>Nothing</a> to an arbitrary value (which you can choose):
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^. non 0
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Nothing ^. non 0
--   0
--   </pre>
--   
--   The most useful thing about <a>non</a> is that relabeling also works
--   in other direction. If you try to <a>set</a> the “forbidden” value,
--   it'll be turned to <a>Nothing</a>:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 .~ 0
--   Nothing
--   </pre>
--   
--   Setting anything else works just fine:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 .~ 5
--   Just 5
--   </pre>
--   
--   Same happens if you try to modify a value:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 %~ subtract 1
--   Nothing
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 &amp; non 0 .~ (+ 1)
--   Just 2
--   </pre>
--   
--   <a>non</a> is often useful when combined with <a>at</a>. For instance,
--   if you have a map of songs and their playcounts, it makes sense not to
--   store songs with 0 plays in the map; <a>non</a> can act as a filter
--   that wouldn't pass such entries.
--   
--   Decrease playcount of a song to 0, and it'll be gone:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Soon",1),("Yesterday",3)] &amp; at "Soon" . non 0 %~ subtract 1
--   fromList [("Yesterday",3)]
--   </pre>
--   
--   Try to add a song with 0 plays, and it won't be added:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Yesterday",3)] &amp; at "Soon" . non 0 .~ 0
--   fromList [("Yesterday",3)]
--   </pre>
--   
--   But it will be added if you set any other number:
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Yesterday",3)] &amp; at "Soon" . non 0 .~ 1
--   fromList [("Soon",1),("Yesterday",3)]
--   </pre>
--   
--   <a>non</a> is also useful when working with nested maps. Here a nested
--   map is created when it's missing:
--   
--   <pre>
--   &gt;&gt;&gt; Map.empty &amp; at "Dez Mona" . non Map.empty . at "Soon" .~ Just 1
--   fromList [("Dez Mona",fromList [("Soon",1)])]
--   </pre>
--   
--   and here it is deleted when its last entry is deleted (notice that
--   <a>non</a> is used twice here):
--   
--   <pre>
--   &gt;&gt;&gt; fromList [("Dez Mona",fromList [("Soon",1)])] &amp; at "Dez Mona" . non Map.empty . at "Soon" . non 0 %~ subtract 1
--   fromList []
--   </pre>
--   
--   To understand the last example better, observe the flow of values in
--   it:
--   
--   <ul>
--   <li>the map goes into <tt>at "Dez Mona"</tt></li>
--   <li>the nested map (wrapped into <tt>Just</tt>) goes into <tt>non
--   Map.empty</tt></li>
--   <li><tt>Just</tt> is unwrapped and the nested map goes into <tt>at
--   "Soon"</tt></li>
--   <li><tt>Just 1</tt> is unwrapped by <tt>non 0</tt></li>
--   </ul>
--   
--   Then the final value – i.e. 1 – is modified by <tt>subtract 1</tt> and
--   the result (which is 0) starts flowing backwards:
--   
--   <ul>
--   <li><tt>non 0</tt> sees the 0 and produces a <tt>Nothing</tt></li>
--   <li><tt>at "Soon"</tt> sees <tt>Nothing</tt> and deletes the
--   corresponding value from the map</li>
--   <li>the resulting empty map is passed to <tt>non Map.empty</tt>, which
--   sees that it's empty and thus produces <tt>Nothing</tt></li>
--   <li><tt>at "Dez Mona"</tt> sees <tt>Nothing</tt> and removes the key
--   from the map</li>
--   </ul>
non :: Eq a => a -> Lens' (Maybe a) a

-- | <tt>Traversal s t a b</tt> is a generalisation of <a>Lens</a> which
--   allows many targets (possibly 0). It's achieved by changing the
--   constraint to <a>Applicative</a> instead of <a>Functor</a> – indeed,
--   the point of <a>Applicative</a> is that you can combine effects, which
--   is just what we need to have many targets.
--   
--   Ultimately, traversals should follow 2 laws:
--   
--   <pre>
--   t pure ≡ pure
--   fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)
--   </pre>
--   
--   The 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 <a>this blog
--   post</a> (if you prefer rambling blog posts), or <a>The Essence Of The
--   Iterator Pattern</a> (if you prefer papers).
--   
--   Traversing any value twice is a violation of traversal laws. You can,
--   however, traverse values in any order.
type Traversal s t a b = forall f. Applicative f => (a -> f b) -> s -> f t

-- | This is a type alias for monomorphic traversals which don't change the
--   type of the container (or of the values inside).
type Traversal' s a = Traversal s s a a

-- | Apply an action to all targets (like <a>mapM</a> or <a>traverse</a>):
--   
--   <pre>
--   &gt;&gt;&gt; traverseOf both readFile ("file1", "file2")
--   (&lt;contents of file1&gt;, &lt;contents of file2&gt;)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; traverseOf _1 id (Just 1, 2)
--   Just (1, 2)
--   
--   &gt;&gt;&gt; traverseOf _1 id (Nothing, 2)
--   Nothing
--   </pre>
--   
--   You can also just apply the lens/traversal directly (but
--   <a>traverseOf</a> might be more readable):
--   
--   <pre>
--   &gt;&gt;&gt; both readFile ("file1", "file2")
--   (&lt;contents of file1&gt;, &lt;contents of file2&gt;)
--   </pre>
--   
--   If you don't need the result, use <a>traverseOf_</a>.
traverseOf :: LensLike f s t a b -> (a -> f b) -> s -> f t

-- | <a>singular</a> turns a traversal into a lens that behaves like a
--   single-element traversal:
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] ^. signular each
--   1
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [1,2,3] &amp; singular each %~ negate
--   [-1,2,3]
--   </pre>
--   
--   If there is nothing to return, it'll throw an error:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^. singular each
--   *** Exception: Lens.Micro.singular: empty traversal
--   </pre>
--   
--   However, it won't fail if you are merely setting the value:
--   
--   <pre>
--   &gt;&gt;&gt; [] &amp; singular each %~ negate
--   </pre>
singular :: Traversal s t a a -> Lens s t a a

-- | <a>failing</a> lets you chain traversals together; if the 1st
--   traversal fails, the 2nd traversal will be used.
--   
--   <pre>
--   &gt;&gt;&gt; ([1,2],[3]) &amp; failing (_1.each) (_2.each) .~ 0
--   ([0,0],[3])
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ([],[3]) &amp; failing (_1.each) (_2.each) .~ 0
--   ([],[0])
--   </pre>
--   
--   Note that the resulting traversal won't be valid unless either both
--   traversals don't touch each others' elements, or both traversals
--   return exactly the same results. To see an example of how
--   <a>failing</a> can generate invalid traversals, see <a>this
--   Stackoverflow question</a>.
failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b
infixl 5 `failing`

-- | <a>filtered</a> is a traversal that filters elements “passing” thru
--   it:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) ^.. each
--   [1,2,3,4]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) ^.. each . filtered even
--   [2,4]
--   </pre>
--   
--   It also can be used to modify elements selectively:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2,3,4) &amp; each . filtered even %~ (*100)
--   (1,200,3,400)
--   </pre>
--   
--   The implementation of <a>filtered</a> is very simple. Consider this
--   traversal, which always “traverses” just the value it's given:
--   
--   <pre>
--   id :: <a>Traversal'</a> a a
--   id f s = f s
--   </pre>
--   
--   And this traversal, which traverses nothing (in other words,
--   <i>doesn't</i> traverse the value it's given):
--   
--   <pre>
--   ignored :: <a>Traversal'</a> a a
--   ignored f s = <a>pure</a> s
--   </pre>
--   
--   And now combine them into a traversal that conditionally traverses the
--   value it's given, and you get <a>filtered</a>:
--   
--   <pre>
--   filtered :: (a -&gt; Bool) -&gt; <a>Traversal'</a> a a
--   filtered p s = if p s then f s else <a>pure</a> s
--   </pre>
--   
--   By the way, note that <a>filtered</a> can generate illegal traversals
--   – sometimes this can bite you. In particular, an optimisation that
--   should be safe becomes unsafe. (To the best of my knowledge, this
--   optimisation never happens automatically. If you just use
--   <a>filtered</a> to modify/view something, you're safe. If you don't
--   define any traversals that use <a>filtered</a>, you're safe too.)
--   
--   Let's use <tt>evens</tt> as an example:
--   
--   <pre>
--   evens = <a>filtered</a> <a>even</a>
--   </pre>
--   
--   If <tt>evens</tt> was a legal traversal, you'd be able to fuse several
--   applications of <tt>evens</tt> like this:
--   
--   <pre>
--   <a>over</a> evens f <a>.</a> <a>over</a> evens g = <a>over</a> evens (f <a>.</a> g)
--   </pre>
--   
--   Unfortunately, in case of <tt>evens</tt> this isn't a correct
--   optimisation:
--   
--   <ul>
--   <li>the left-side variant applies <tt>g</tt> to all even numbers, and
--   then applies <tt>f</tt> to all even numbers that are left after
--   <tt>f</tt> (because <tt>f</tt> might've turned some even numbers into
--   odd ones)</li>
--   <li>the right-side variant applies <tt>f</tt> and <tt>g</tt> to all
--   even numbers</li>
--   </ul>
--   
--   Of course, when you are careful and know what you're doing, you won't
--   try to make such an optimisation. However, if you export an illegal
--   traversal created with <a>filtered</a> and someone tries to use it,
--   they might mistakenly assume that it's legal, do the optimisation, and
--   silently get an incorrect result.
--   
--   If you are using <a>filtered</a> with some another traversal that
--   doesn't overlap with -whatever the predicate checks-, the resulting
--   traversal will be legal. For instance, here the predicate looks at the
--   1st element of a tuple, but the resulting traversal only gives you
--   access to the 2nd:
--   
--   <pre>
--   pairedWithEvens :: <a>Traversal</a> [(Int, a)] [(Int, b)] a b
--   pairedWithEvens = <a>each</a> <a>.</a> <a>filtered</a> (<a>even</a> <a>.</a> <a>fst</a>) <a>.</a> <a>_2</a>
--   </pre>
--   
--   Since you can't do anything with the 1st components thru this
--   traversal, the following holds for any <tt>f</tt> and <tt>g</tt>:
--   
--   <pre>
--   <a>over</a> pairedWithEvens f <a>.</a> <a>over</a> pairedWithEvens g = <a>over</a> pairedWithEvens (f <a>.</a> g)
--   </pre>
filtered :: (a -> Bool) -> Traversal' a a

-- | <a>both</a> traverses both fields of a tuple. Unlike
--   <tt><a>both</a></tt> from lens, it only works for pairs – not for
--   triples or <a>Either</a>.
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") ^. both
--   "string"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ("str","ing") &amp; both %~ reverse
--   ("rts","gni")
--   </pre>
both :: Traversal (a, a) (b, b) a b

-- | <a>traversed</a> traverses any <a>Traversable</a> container (list,
--   vector, <tt>Map</tt>, <a>Maybe</a>, you name it):
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^.. traversed
--   [1]
--   </pre>
--   
--   <a>traversed</a> is the same as <a>traverse</a>, but can be faster
--   thanks to magic rewrite rules.
traversed :: Traversable f => Traversal (f a) (f b) a b

-- | <a>each</a> tries to be a universal <a>Traversal</a> – it behaves like
--   <a>traversed</a> in most situations, but also adds support for e.g.
--   tuples with same-typed values:
--   
--   <pre>
--   &gt;&gt;&gt; (1,2) &amp; each %~ succ
--   (2,3)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; ["x", "y", "z"] ^. each
--   "xyz"
--   </pre>
--   
--   However, note that <a>each</a> doesn't work on <i>every</i> instance
--   of <a>Traversable</a>. If you have a <a>Traversable</a> which isn't
--   supported by <a>each</a>, you can use <a>traversed</a> instead.
--   Personally, I like using <a>each</a> instead of <a>traversed</a>
--   whenever possible – it's shorter and more descriptive.
--   
--   You can use <a>each</a> with these things:
--   
--   <pre>
--   <a>each</a> :: <a>Traversal</a> [a] [b] a b
--   
--   <a>each</a> :: <a>Traversal</a> (<a>Maybe</a> a) (<a>Maybe</a> b) a b
--   
--   <a>each</a> :: <a>Traversal</a> (a,a) (b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a) (b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a) (b,b,b,b) a b
--   <a>each</a> :: <a>Traversal</a> (a,a,a,a,a) (b,b,b,b,b) a b
--   
--   <a>each</a> :: (<a>RealFloat</a> a, <a>RealFloat</a> b) =&gt; <a>Traversal</a> (<a>Complex</a> a) (<a>Complex</a> b) a b
--   </pre>
--   
--   You can also use <a>each</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
each :: Each s t a b => Traversal s t a b

-- | This traversal lets you access (and update) an arbitrary element in a
--   list, array, <tt>Map</tt>, etc. (If you want to insert or delete
--   elements as well, look at <a>at</a>.)
--   
--   An example for lists:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] &amp; ix 3 .~ 10
--   [0,1,2,10,4,5]
--   </pre>
--   
--   You can use it for getting, too:
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 3
--   Just 3
--   </pre>
--   
--   Of course, the element may not be present (which means that you can
--   use <a>ix</a> as a safe variant of (<a>!!</a>)):
--   
--   <pre>
--   &gt;&gt;&gt; [0..5] ^? ix 10
--   Nothing
--   </pre>
--   
--   Another useful instance is the one for functions – it lets you modify
--   their outputs for specific inputs. For instance, here's <a>maximum</a>
--   that returns 0 when the list is empty (instead of throwing an
--   exception):
--   
--   <pre>
--   maximum0 = <a>maximum</a> <a>&amp;</a> <a>ix</a> [] <a>.~</a> 0
--   </pre>
--   
--   The following instances are provided in this package:
--   
--   <pre>
--   <a>ix</a> :: <a>Int</a> -&gt; <a>Traversal'</a> [a] a
--   
--   <a>ix</a> :: (<a>Eq</a> e) =&gt; e -&gt; <a>Traversal'</a> (e -&gt; a) a
--   </pre>
--   
--   You can also use <a>ix</a> with types from <a>array</a>,
--   <a>bytestring</a>, and <a>containers</a> by using
--   <a>microlens-ghc</a>, or additionally with types from <a>vector</a>,
--   <a>text</a>, and <a>unordered-containers</a> by using
--   <a>microlens-platform</a>.
ix :: Ixed m => Index m -> Traversal' m (IxValue m)

-- | <a>_head</a> traverses the 1st element of something (usually a list,
--   but can also be a <tt>Seq</tt>, etc):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^? _head
--   Just 1
--   </pre>
--   
--   It can be used to modify too, as in this example where the 1st letter
--   of a sentence is capitalised:
--   
--   <pre>
--   &gt;&gt;&gt; "mary had a little lamb." &amp; _head %~ toTitle
--   "Mary had a little lamb."
--   </pre>
--   
--   The reason it's a traversal and not a lens is that there's nothing to
--   traverse when the list is empty:
--   
--   <pre>
--   &gt;&gt;&gt; [] ^? _head
--   Nothing
--   </pre>
--   
--   This package only lets you use <a>_head</a> on lists, but if you use
--   <a>microlens-ghc</a> you get instances for <tt>ByteString</tt> and
--   <tt>Seq</tt>, and if you use <a>microlens-platform</a> you
--   additionally get instances for <tt>Text</tt> and <tt>Vector</tt>.
_head :: Cons s s a a => Traversal' s a

-- | <a>_tail</a> gives you access to the tail of a list (or <tt>Seq</tt>,
--   etc):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^? _tail
--   Just [2,3,4,5]
--   </pre>
--   
--   You can modify the tail as well:
--   
--   <pre>
--   &gt;&gt;&gt; [4,1,2,3] &amp; _tail %~ reverse
--   [4,3,2,1]
--   </pre>
--   
--   Since lists are monoids, you can use <a>_tail</a> with plain
--   (<a>^.</a>) (and then it'll return an empty list if you give it an
--   empty list):
--   
--   <pre>
--   &gt;&gt;&gt; [1..5] ^. _tail
--   [2,3,4,5]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; [] ^. _tail
--   []
--   </pre>
--   
--   If you want to traverse each <i>element</i> of the tail, use
--   <a>_tail</a> with <a>each</a>:
--   
--   <pre>
--   &gt;&gt;&gt; "I HATE CAPS." &amp; _tail.each %~ toLower
--   "I hate caps."
--   </pre>
--   
--   This package only lets you use <a>_tail</a> on lists, but if you use
--   <a>microlens-ghc</a> you get instances for <tt>ByteString</tt> and
--   <tt>Seq</tt>, and if you use <a>microlens-platform</a> you
--   additionally get instances for <tt>Text</tt> and <tt>Vector</tt>.
_tail :: Cons s s a a => Traversal' s s

-- | <a>_init</a> gives you access to all-but-the-last elements of the
--   list:
--   
--   <pre>
--   &gt;&gt;&gt; "Hello." ^. _init
--   "Hello"
--   </pre>
--   
--   See documentation for <a>_tail</a>, as <a>_init</a> and <a>_tail</a>
--   are pretty similar.
_init :: Snoc s s a a => Traversal' s s

-- | <a>_last</a> gives you access to the last element of the list:
--   
--   <pre>
--   &gt;&gt;&gt; "Hello." ^? _last
--   '.'
--   </pre>
--   
--   See documentation for <a>_head</a>, as <a>_last</a> and <a>_head</a>
--   are pretty similar.
_last :: Snoc s s a a => Traversal' s a

-- | This generalizes <a>mapAccumL</a> to an arbitrary <a>Traversal</a>.
--   (Note that it doesn't work on folds, only traversals.)
--   
--   <pre>
--   <tt>mapAccumL</tt> ≡ <a>mapAccumLOf</a> <a>traverse</a>
--   </pre>
mapAccumLOf :: LensLike (State acc) s t a b -> (acc -> a -> (acc, b)) -> acc -> s -> (acc, t)

-- | <a>_Left</a> targets the value contained in an <a>Either</a>, provided
--   it's a <a>Left</a>.
--   
--   Gathering all <tt>Left</tt>s in a structure (like the <a>lefts</a>
--   function, but not necessarily just for lists):
--   
--   <pre>
--   &gt;&gt;&gt; [Left 1, Right 'c', Left 3] ^.. each._Just
--   [1,3]
--   </pre>
--   
--   Checking whether an <a>Either</a> is a <a>Left</a> (like
--   <a>isLeft</a>):
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Left 1)
--   True
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; has _Left (Right 1)
--   False
--   </pre>
--   
--   Extracting a value (if you're sure it's a <a>Left</a>):
--   
--   <pre>
--   &gt;&gt;&gt; Left 1 ^?! _Left
--   1
--   </pre>
--   
--   Mapping over all <a>Left</a>s:
--   
--   <pre>
--   &gt;&gt;&gt; (each._Left %~ map toUpper) [Left "foo", Right "bar"]
--   [Left "FOO",Right "bar"]
--   </pre>
--   
--   Implementation:
--   
--   <pre>
--   <a>_Left</a> f (Left a)  = <a>Left</a> <a>&lt;$&gt;</a> f a
--   <a>_Left</a> _ (Right b) = <a>pure</a> (<a>Right</a> b)
--   </pre>
_Left :: Traversal (Either a b) (Either a' b) a a'

-- | <a>_Right</a> targets the value contained in an <a>Either</a>,
--   provided it's a <a>Right</a>.
--   
--   See documentation for <a>_Left</a>.
_Right :: Traversal (Either a b) (Either a b') b b'

-- | <a>_Just</a> targets the value contained in a <a>Maybe</a>, provided
--   it's a <a>Just</a>.
--   
--   See documentation for <a>_Left</a> (as these 2 are pretty similar). In
--   particular, it can be used to write these:
--   
--   <ul>
--   <li>Unsafely extracting a value from a <a>Just</a>:</li>
--   </ul>
--   
--   <pre>
--   <a>fromJust</a> = (<a>^?!</a> <a>_Just</a>)
--   
--   </pre>
--   
--   <ul>
--   <li>Checking whether a value is a <a>Just</a>:</li>
--   </ul>
--   
--   <pre>
--   <a>isJust</a> = <a>has</a> <a>_Just</a>
--   
--   </pre>
--   
--   <ul>
--   <li>Converting a <a>Maybe</a> to a list (empty or consisting of a
--   single element):</li>
--   </ul>
--   
--   <pre>
--   <a>maybeToList</a> = (<a>^..</a> <a>_Just</a>)
--   
--   </pre>
--   
--   <ul>
--   <li>Gathering all <a>Just</a>s in a list:</li>
--   </ul>
--   
--   <pre>
--   <a>catMaybes</a> = (<a>^..</a> <a>each</a> <a>.</a> <a>_Just</a>)
--   
--   </pre>
_Just :: Traversal (Maybe a) (Maybe a') a a'

-- | <a>_Nothing</a> targets a <tt>()</tt> if the <a>Maybe</a> is a
--   <a>Nothing</a>, and doesn't target anything otherwise:
--   
--   <pre>
--   &gt;&gt;&gt; Just 1 ^.. _Nothing
--   []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; Nothing ^.. _Nothing
--   [()]
--   </pre>
--   
--   It's not particularly useful (unless you want to use <tt><a>has</a>
--   <a>_Nothing</a></tt> as a replacement for <a>isNothing</a>), and
--   provided mainly for consistency.
--   
--   Implementation:
--   
--   <pre>
--   <a>_Nothing</a> f Nothing = <a>const</a> <a>Nothing</a> <a>&lt;$&gt;</a> f ()
--   <a>_Nothing</a> _ j       = <a>pure</a> j
--   </pre>
_Nothing :: Traversal' (Maybe a) ()

-- | <a>LensLike</a> is a type that is often used to make combinators as
--   general as possible. For instance, take (<a>&lt;&lt;%~</a>), which
--   only requires the passed lens to be able to work with the <tt>(,)
--   a</tt> functor (lenses and traversals can do that). The fully expanded
--   type is as follows:
--   
--   <pre>
--   (<a>&lt;&lt;%~</a>) :: ((a -&gt; (a, b)) -&gt; s -&gt; (a, t)) -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   </pre>
--   
--   With <a>LensLike</a>, the intent to use the <tt>(,) a</tt> functor can
--   be made a bit clearer:
--   
--   <pre>
--   (<a>&lt;&lt;%~</a>) :: LensLike ((,) a) s t a b -&gt; (a -&gt; b) -&gt; s -&gt; (a, t)
--   </pre>
type LensLike f s t a b = (a -> f b) -> s -> f t

-- | A type alias for monomorphic <a>LensLike</a>s.
type LensLike' f s a = LensLike f s s a a
instance GHC.Base.Applicative f => GHC.Base.Monoid (Lens.Micro.Traversed a f)
instance GHC.Base.Functor (Lens.Micro.Bazaar a b)
instance GHC.Base.Applicative (Lens.Micro.Bazaar a b)
instance GHC.Base.Functor m => GHC.Base.Functor (Lens.Micro.StateT s m)
instance (GHC.Base.Functor m, GHC.Base.Monad m) => GHC.Base.Applicative (Lens.Micro.StateT s m)
instance GHC.Base.Monad m => GHC.Base.Monad (Lens.Micro.StateT s m)
instance Control.Monad.Fail.MonadFail m => Control.Monad.Fail.MonadFail (Lens.Micro.StateT s m)


module Lens.Micro.Extras

-- | <a>view</a> is a synonym for (<a>^.</a>):
--   
--   <pre>
--   &gt;&gt;&gt; view _1 (1, 2)
--   1
--   </pre>
--   
--   The reason it's not in <a>Lens.Micro</a> is that <tt>view</tt> in lens
--   has a more general signature:
--   
--   <pre>
--   view :: MonadReader s m =&gt; Getting a s a -&gt; m a
--   </pre>
--   
--   So, you would be able to use this <a>view</a> with functions, but not
--   in various reader monads. For most people this shouldn't be an issue;
--   if it is for you, use <tt>view</tt> from <a>microlens-mtl</a>.
view :: Getting a s a -> s -> a

-- | <a>preview</a> is a synonym for (<a>^?</a>):
--   
--   <pre>
--   &gt;&gt;&gt; preview _head [1,2,3]
--   Just 1
--   </pre>
--   
--   The reason it's not in <a>Lens.Micro</a> is that <tt>preview</tt> in
--   lens has a more general signature:
--   
--   <pre>
--   preview :: MonadReader s m =&gt; Getting (First a) s a -&gt; m (Maybe a)
--   </pre>
--   
--   Just like with <a>view</a>, you would be able to use this
--   <a>preview</a> with functions, but not in reader monads; if this is an
--   issue for you, use <tt>preview</tt> from <a>microlens-mtl</a>.
preview :: Getting (First a) s a -> s -> Maybe a
