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

-- | A tiny lens library with no dependencies
--   
--   NOTE: If you're writing an app, you probably want
--   microlens-platform – it has the most features. microlens
--   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 lens (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 on Github. 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:
--   
--   
--   
- 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.
--   
- You just want to be able to use lenses to transform data (or even
--   just use over _1 to change the first element of a
--   tuple).
--   
- You are new to lenses and want a small library to play with.
--   
--   
--   However, don't use this library if:
--   
--   
--   
- You need Isos, Prisms, indexed traversals, or
--   actually anything else which isn't defined here (though some indexed
--   functions are available elsewhere – containers and vector provide them
--   for their types, and ilist provides indexed functions for
--   lists).
--   
- You want a library with a clean, understandable implementation (in
--   which case you're looking for lens-simple).
--   
--   
--   As already mentioned, if you're writing an application which uses
--   lenses more extensively, look at microlens-platform – it
--   combines features of most other microlens packages
--   (microlens-mtl, microlens-th, microlens-ghc).
--   
--   If you want to export getters or folds and don't mind the
--   contravariant dependency, please consider using
--   microlens-contra.
--   
--   If you haven't ever used lenses before, read this tutorial.
--   (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.13.1

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

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

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

-- | Functions that operate on getters and folds – such as (^.),
--   (^..), (^?) – use Getter r s a (with different
--   values of r) to describe what kind of result 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.
--   (^..) 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 Endo). The choice of
--   r depends on what you want to do with elements you're
--   extracting from s.
type Getting r s a = (a -> Const r a) -> s -> Const r s

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

-- | Lens s t a b is the lowest common denominator of a setter and
--   a getter, something that has the power of both; it has a
--   Functor constraint, and since both Const and
--   Identity are functors, it can be used whenever a getter or a
--   setter is needed.
--   
--   
--   
- a is the type of the value inside of structure
--   
- b is the type of the replaced value
--   
- s is the type of the whole structure
--   
- t is the type of the structure after replacing a
--   in it with b
--   
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

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

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

-- | A type alias for monomorphic LensLikes.
type LensLike' f s a = LensLike f s s a a

-- | This module is needed to give other packages from the microlens family
--   (like microlens-ghc) access to functions and classes that don't
--   need to be exported from Lens.Micro (because they just clutter
--   the namespace). Also:
--   
--   
--   
- traversed is here because otherwise there'd be a dependency
--   cycle
--   
- sets is here because it's used in RULEs
--   
--   
--   Classes like Each, Ixed, etc are provided for
--   convenience – you're not supposed to export functions that work on all
--   members of Ixed, 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

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

-- | folded is a fold for anything Foldable. In a way, it's
--   an opposite of mapped – 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

-- | sets creates an ASetter from an ordinary function. (The
--   only thing it does is wrapping and unwrapping Identity.)
sets :: ((a -> b) -> s -> t) -> ASetter s t a b
phantom :: Const r a -> Const r b
class Each s t a b | s -> a, t -> b, s b -> t, t a -> s

-- | each tries to be a universal Traversal – it behaves like
--   traversed 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 each doesn't work on every instance
--   of Traversable. If you have a Traversable which isn't
--   supported by each, you can use traversed instead.
--   Personally, I like using each instead of traversed
--   whenever possible – it's shorter and more descriptive.
--   
--   You can use each with these things:
--   
--   
--   each :: Traversal [a] [b] a b
--   
--   each :: Traversal (Maybe a) (Maybe b) a b
--   each :: Traversal (Either a a) (Either b b) a b  -- since 0.4.11
--   
--   each :: Traversal (a,a) (b,b) a b
--   each :: Traversal (a,a,a) (b,b,b) a b
--   each :: Traversal (a,a,a,a) (b,b,b,b) a b
--   each :: Traversal (a,a,a,a,a) (b,b,b,b,b) a b
--   
--   each :: (RealFloat a, RealFloat b) => Traversal (Complex a) (Complex b) a b
--   
--   
--   You can also use each with types from array,
--   bytestring, and containers by using
--   microlens-ghc, or additionally with types from vector,
--   text, and unordered-containers by using
--   microlens-platform.
each :: Each s t a b => Traversal s t a b
type family Index (s :: Type) :: Type
type family IxValue (m :: Type) :: Type
class Ixed m

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

-- | This lens lets you read, write, or delete elements in
--   Map-like structures. It returns Nothing when the value
--   isn't found, just like lookup:
--   
--   
--   Data.Map.lookup k m = m ^. at k
--   
--   
--   However, it also lets you insert and delete values by setting the
--   value to Just value or Nothing:
--   
--   
--   Data.Map.insert k a m = m & at k .~ Just a
--   
--   Data.Map.delete k m = m & at k .~ Nothing
--   
--   
--   Or you could use (?~) instead of (.~):
--   
--   
--   Data.Map.insert k a m = m & at k ?~ a
--   
--   
--   Note that at 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.
--   [1,2,3] & at 10 .~ 5 is undefined). If you want to modify
--   an already existing value in an array or list, you should use
--   ix instead.
--   
--   at is often used with non. See the documentation of
--   non for examples.
--   
--   Note that at isn't strict for Map, even if you're
--   using Data.Map.Strict:
--   
--   
--   >>> Data.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)
--   1
--   
--   
--   The reason for such behavior is that there's actually no “strict
--   Map” type; Data.Map.Strict just provides some strict
--   functions for ordinary Maps.
--   
--   This package doesn't actually provide any instances for at, but
--   there are instances for Map and IntMap in
--   microlens-ghc and an instance for HashMap in
--   microlens-platform.
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:
--   
--   
--   >>> (1,2,3,4,5) ^. _1
--   1
--   
--   
--   Setting the 1st component:
--   
--   
--   >>> (1,2,3) & _1 .~ 10
--   (10,2,3)
--   
--   
--   Note that this lens is lazy, and can set fields even of
--   undefined:
--   
--   
--   >>> set _1 10 undefined :: (Int, Int)
--   (10,*** Exception: Prelude.undefined
--   
--   
--   This 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:
--   
--   
--   _1 f t = (,) <$> f    (fst t)
--                <*> pure (snd t)
--   
--   
--   or, alternatively,
--   
--   
--   _1 f ~(a,b) = (\a' -> (a',b)) <$> f a
--   
--   
--   (where ~ means a lazy pattern).
--   
--   _2, _3, _4, and _5 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

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

-- | lazy is like strict but works in opposite direction:
--   
--   
--   >>> let someText = "hello" :: Strict.Text
--   
--   >>> someText ^. lazy
--   "hello" :: Lazy.Text
--   
lazy :: Strict lazy strict => Lens' strict lazy

-- | Request a CallStack.
--   
--   NOTE: The implicit parameter ?callStack :: CallStack is an
--   implementation detail and should not be considered part of the
--   CallStack API, we may decide to change the implementation in
--   the future.
type HasCallStack = ?callStack :: CallStack

-- | The function coerce allows you to safely convert between values
--   of types that have the same representation with no run-time overhead.
--   In the simplest case you can use it instead of a newtype constructor,
--   to go from the newtype's concrete type to the abstract type. But it
--   also works in more complicated settings, e.g. converting a list of
--   newtypes to a list of concrete types.
--   
--   When used in conversions involving a newtype wrapper, make sure the
--   newtype constructor is in scope.
--   
--   This function is representation-polymorphic, but the
--   RuntimeRep type argument is marked as Inferred,
--   meaning that it is not available for visible type application. This
--   means the typechecker will accept coerce @Int @Age
--   42.
--   
--   
Examples
--   
--   
--   >>> newtype TTL = TTL Int deriving (Eq, Ord, Show)
--   
--   >>> newtype Age = Age Int deriving (Eq, Ord, Show)
--   
--   >>> coerce (Age 42) :: TTL
--   TTL 42
--   
--   >>> coerce (+ (1 :: Int)) (Age 42) :: TTL
--   TTL 43
--   
--   >>> coerce (map (+ (1 :: Int))) [Age 42, Age 24] :: [TTL]
--   [TTL 43,TTL 25]
--   
coerce :: forall {k :: RuntimeRep} (a :: TYPE k) (b :: TYPE k). Coercible a b => a -> b
(#.) :: Coercible c b => (b -> c) -> (a -> b) -> a -> c
infixr 9 #.
(.#) :: Coercible b a => (b -> c) -> (a -> b) -> a -> c
infixl 8 .#
instance Lens.Micro.Internal.Snoc [a] [b] a b
instance Lens.Micro.Internal.Cons [a] [b] a b
instance Lens.Micro.Internal.Field5 (a, b, c, d, e) (a, b, c, d, e') e e'
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.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.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.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 GHC.Classes.Eq e => Lens.Micro.Internal.Ixed (e -> a)
instance Lens.Micro.Internal.Ixed [a]
instance Lens.Micro.Internal.Ixed (GHC.Base.NonEmpty a)
instance (a GHC.Types.~ b, q GHC.Types.~ r) => Lens.Micro.Internal.Each (a, b) (q, r) a q
instance (a GHC.Types.~ b, a GHC.Types.~ c, q GHC.Types.~ r, q GHC.Types.~ s) => Lens.Micro.Internal.Each (a, b, c) (q, r, s) a q
instance (a GHC.Types.~ b, a GHC.Types.~ c, a GHC.Types.~ d, q GHC.Types.~ r, q GHC.Types.~ s, q GHC.Types.~ t) => Lens.Micro.Internal.Each (a, b, c, d) (q, r, s, t) a q
instance (a GHC.Types.~ b, a GHC.Types.~ c, a GHC.Types.~ d, a GHC.Types.~ e, q GHC.Types.~ r, q GHC.Types.~ s, q GHC.Types.~ t, q GHC.Types.~ 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.Maybe.Maybe a) (GHC.Maybe.Maybe b) a b
instance (a GHC.Types.~ a', b GHC.Types.~ b') => Lens.Micro.Internal.Each (Data.Either.Either a a') (Data.Either.Either b b') a b
instance Lens.Micro.Internal.Each (GHC.Base.NonEmpty a) (GHC.Base.NonEmpty 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 microlens-platform – it
--   provides the most functionality.
--   
--   
--   
- microlens-mtl – (+=) and friends, use,
--   zoom/magnify
--   
- microlens-th – makeLenses and
--   makeFields
--   
- microlens-ghc – everything in microlens + instances to make
--   each/at/ix usable with arrays,
--   ByteString, and containers
--   
- microlens-platform – microlens-ghc + microlens-mtl +
--   microlens-th + instances for Text, Vector, and
--   HashMap
--   
- microlens-contra – Fold and Getter that
--   are exact copies of types in lens
--   
--   
--   Unofficial:
--   
--   
--   
- microlens-aeson – a port of lens-aeson
--   
- microlens-process - a port of lens-process
--   
module Lens.Micro

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

-- | Flipped version of <$>.
--   
--   
--   (<&>) = flip fmap
--   
--   
--   
Examples
--   
--   Apply (+1) to a list, a Just and a Right:
--   
--   
--   >>> Just 2 <&> (+1)
--   Just 3
--   
--   
--   
--   >>> [1,2,3] <&> (+1)
--   [2,3,4]
--   
--   
--   
--   >>> Right 3 <&> (+1)
--   Right 4
--   
(<&>) :: Functor f => f a -> (a -> b) -> f b
infixl 1 <&>

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

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

-- | (%~) applies a function to the target; an alternative
--   explanation is that it is an inverse of sets, which turns a
--   setter into an ordinary function. mapped %~
--   reverse is the same thing as fmap
--   reverse.
--   
--   See over 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"]
--   
(%~) :: ASetter s t a b -> (a -> b) -> s -> t
infixr 4 %~

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

-- | Increment the target(s) of a numerically valued Lens or
--   Traversal.
--   
--   
--   >>> (a,b) & _1 +~ c
--   (a + c,b)
--   
--   
--   
--   >>> (a,b) & both +~ c
--   (a + c,b + c)
--   
--   
--   
--   >>> (1,2) & _2 +~ 1
--   (1,3)
--   
--   
--   
--   >>> [(a,b),(c,d)] & traverse.both +~ e
--   [(a + e,b + e),(c + e,d + e)]
--   
--   
--   
--   (+~) :: Num a => Lens' s a      -> a -> s -> s
--   (+~) :: Num a => Traversal' s a -> a -> s -> s
--   
(+~) :: Num a => ASetter s t a a -> a -> s -> t
infixr 4 +~

-- | Decrement the target(s) of a numerically valued Lens, or
--   Traversal.
--   
--   
--   >>> (a,b) & _1 -~ c
--   (a - c,b)
--   
--   
--   
--   >>> (a,b) & both -~ c
--   (a - c,b - c)
--   
--   
--   
--   >>> _1 -~ 2 $ (1,2)
--   (-1,2)
--   
--   
--   
--   >>> mapped.mapped -~ 1 $ [[4,5],[6,7]]
--   [[3,4],[5,6]]
--   
--   
--   
--   (-~) :: Num a => Lens' s a      -> a -> s -> s
--   (-~) :: Num a => Traversal' s a -> a -> s -> s
--   
(-~) :: Num a => ASetter s t a a -> a -> s -> t
infixr 4 -~

-- | (<>~) appends a value monoidally to the target.
--   
--   
--   >>> ("hello", "goodbye") & both <>~ " world!"
--   ("hello world!", "goodbye world!")
--   
(<>~) :: Monoid a => ASetter s t a a -> a -> s -> t
infixr 4 <>~

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

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

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

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

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

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

-- | mapped 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 traversed or
--   each).
--   
--   Here mapped is used to turn a value to all non-Nothing
--   values in a list:
--   
--   
--   >>> [Just 3,Nothing,Just 5] & mapped.mapped .~ 0
--   [Just 0,Nothing,Just 0]
--   
--   
--   Keep in mind that while mapped is a more powerful setter than
--   each, 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)] ^.. mapped . both
--   
mapped :: Functor f => ASetter (f a) (f b) a b

-- | → See an example on GitHub.
--   
--   Rewrite by applying a rule everywhere you can. Ensures that the rule
--   cannot be applied anywhere in the result.
--   
--   Usually transformOf is more appropriate, but rewriteOf
--   can give better compositionality. Given two single transformations
--   f and g, you can construct \a -> f a
--   <|> g a which performs both rewrites until a fixed
--   point.
rewriteOf :: ASetter a b a b -> (b -> Maybe a) -> a -> b

-- | Transform every element by recursively applying a given ASetter
--   in a bottom-up manner.
transformOf :: ASetter a b a b -> (b -> b) -> a -> b

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

-- | Functions that operate on getters and folds – such as (^.),
--   (^..), (^?) – use Getter r s a (with different
--   values of r) to describe what kind of result 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.
--   (^..) 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 Endo). The choice of
--   r depends on what you want to do with elements you're
--   extracting from s.
type Getting r s a = (a -> Const r a) -> s -> Const r s

-- | (^.) 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:
--   
--   
--   (^. _1) :: (a, b) -> a
--   (^. _1) = fst
--   
--   
--   When (^.) is used with a traversal, it combines all results
--   using the Monoid 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 Applicative, and the
--   Applicative instance for Const uses monoid concatenation
--   to combine “effects” of Const.
--   
--   A non-operator version of (^.) is called view, and
--   it's a bit more general than (^.) (it works in
--   MonadReader). If you need the general version, you can get it
--   from microlens-mtl; otherwise there's view available in
--   Lens.Micro.Extras.
(^.) :: s -> Getting a s a -> a
infixl 8 ^.

-- | to creates a getter from any function:
--   
--   
--   a ^. to f = f a
--   
--   
--   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:
--   
--   
--   value ^. _1 . field . at 2
--   
--   
--   However, field isn't a getter, and you have to do this
--   instead:
--   
--   
--   field (value ^. _1) ^. at 2
--   
--   
--   but now value is in the middle and it's hard to read the
--   resulting code. A variant with to is prettier and more
--   readable:
--   
--   
--   value ^. _1 . to field . at 2
--   
to :: (s -> a) -> SimpleGetter s a

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

-- | s ^.. t returns the list of all values that t gets
--   from s.
--   
--   A Maybe 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]
--   
(^..) :: s -> Getting (Endo [a]) s a -> [a]
infixl 8 ^..

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

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

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

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

-- | traverseOf_ with flipped arguments. Useful if the “loop body”
--   is a lambda or a do block, or in some other cases – for
--   instance, you can avoid accidentally using for_ on a tuple or
--   Either by switching to forOf_ each. Or
--   you can write custom loops like these:
--   
--   
--   forOf_ both (a, b) $ \x ->
--     ...
--   forOf_ each [1..10] $ \x ->
--     ...
--   forOf_ (each . _Right) $ \x ->
--     ...
--   
forOf_ :: Functor f => Getting (Traversed r f) s a -> s -> (a -> f r) -> f ()

-- | has 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 []
--   False
--   
--   
--   You can also use it with e.g. _Left (and other 0-or-1
--   traversals) as a replacement for isNothing, isJust and
--   other isConstructorName functions:
--   
--   
--   >>> has _Left (Left 1)
--   True
--   
has :: Getting Any s a -> s -> Bool

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

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

-- | Lens s t a b is the lowest common denominator of a setter and
--   a getter, something that has the power of both; it has a
--   Functor constraint, and since both Const and
--   Identity are functors, it can be used whenever a getter or a
--   setter is needed.
--   
--   
--   
- a is the type of the value inside of structure
--   
- b is the type of the replaced value
--   
- s is the type of the whole structure
--   
- t is the type of the structure after replacing a
--   in it with b
--   
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

-- | lens creates a Lens 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 -> Lens' [a] a
--   ix i = lens (!! 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 undefined. Then we use
--   the resulting lens for setting and it works, which proves that
--   the getter wasn't used:
--   
--   
--   >>> [1,2,3] & lens undefined (\s b -> b : tail s) .~ 10
--   [10,2,3]
--   
lens :: (s -> a) -> (s -> b -> t) -> Lens s t a b

-- | This lens lets you read, write, or delete elements in
--   Map-like structures. It returns Nothing when the value
--   isn't found, just like lookup:
--   
--   
--   Data.Map.lookup k m = m ^. at k
--   
--   
--   However, it also lets you insert and delete values by setting the
--   value to Just value or Nothing:
--   
--   
--   Data.Map.insert k a m = m & at k .~ Just a
--   
--   Data.Map.delete k m = m & at k .~ Nothing
--   
--   
--   Or you could use (?~) instead of (.~):
--   
--   
--   Data.Map.insert k a m = m & at k ?~ a
--   
--   
--   Note that at 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.
--   [1,2,3] & at 10 .~ 5 is undefined). If you want to modify
--   an already existing value in an array or list, you should use
--   ix instead.
--   
--   at is often used with non. See the documentation of
--   non for examples.
--   
--   Note that at isn't strict for Map, even if you're
--   using Data.Map.Strict:
--   
--   
--   >>> Data.Map.Strict.size (Data.Map.Strict.empty & at 1 .~ Just undefined)
--   1
--   
--   
--   The reason for such behavior is that there's actually no “strict
--   Map” type; Data.Map.Strict just provides some strict
--   functions for ordinary Maps.
--   
--   This package doesn't actually provide any instances for at, but
--   there are instances for Map and IntMap in
--   microlens-ghc and an instance for HashMap in
--   microlens-platform.
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:
--   
--   
--   >>> (1,2,3,4,5) ^. _1
--   1
--   
--   
--   Setting the 1st component:
--   
--   
--   >>> (1,2,3) & _1 .~ 10
--   (10,2,3)
--   
--   
--   Note that this lens is lazy, and can set fields even of
--   undefined:
--   
--   
--   >>> set _1 10 undefined :: (Int, Int)
--   (10,*** Exception: Prelude.undefined
--   
--   
--   This 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:
--   
--   
--   _1 f t = (,) <$> f    (fst t)
--                <*> pure (snd t)
--   
--   
--   or, alternatively,
--   
--   
--   _1 f ~(a,b) = (\a' -> (a',b)) <$> f a
--   
--   
--   (where ~ means a lazy pattern).
--   
--   _2, _3, _4, and _5 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

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

-- | lazy is like strict but works in opposite direction:
--   
--   
--   >>> let someText = "hello" :: Strict.Text
--   
--   >>> someText ^. lazy
--   "hello" :: Lazy.Text
--   
lazy :: Strict lazy strict => Lens' strict lazy

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

-- | Traversal s t a b is a generalisation of Lens which
--   allows many targets (possibly 0). It's achieved by changing the
--   constraint to Applicative instead of Functor – indeed,
--   the point of Applicative is that you can combine effects, which
--   is just what we need to have many targets.
--   
--   Ultimately, traversals should follow 2 laws:
--   
--   
--   t pure ≡ pure
--   fmap (t f) . t g ≡ getCompose . t (Compose . fmap f . g)
--   
--   
--   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 this blog
--   post (if you prefer rambling blog posts), or The Essence Of The
--   Iterator Pattern (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 mapM or traverse):
--   
--   
--   >>> traverseOf both readFile ("file1", "file2")
--   (<contents of file1>, <contents of file2>)
--   
--   
--   
--   >>> traverseOf _1 id (Just 1, 2)
--   Just (1, 2)
--   
--   >>> traverseOf _1 id (Nothing, 2)
--   Nothing
--   
--   
--   You can also just apply the lens/traversal directly (but
--   traverseOf might be more readable):
--   
--   
--   >>> both readFile ("file1", "file2")
--   (<contents of file1>, <contents of file2>)
--   
--   
--   If you don't need the result, use traverseOf_.
traverseOf :: LensLike f s t a b -> (a -> f b) -> s -> f t

-- | traverseOf with flipped arguments. Useful if the “loop body” is
--   a lambda or a do block.
forOf :: LensLike f s t a b -> s -> (a -> f b) -> f t

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

-- | failing lets you chain traversals together; if the 1st
--   traversal fails, the 2nd traversal will be used.
--   
--   
--   >>> ([1,2],[3]) & failing (_1.each) (_2.each) .~ 0
--   ([0,0],[3])
--   
--   
--   
--   >>> ([],[3]) & failing (_1.each) (_2.each) .~ 0
--   ([],[0])
--   
--   
--   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
--   failing can generate invalid traversals, see this
--   Stackoverflow question.
failing :: Traversal s t a b -> Traversal s t a b -> Traversal s t a b
infixl 5 `failing`

-- | filtered is a traversal that filters elements “passing” through
--   it:
--   
--   
--   >>> (1,2,3,4) ^.. each
--   [1,2,3,4]
--   
--   
--   
--   >>> (1,2,3,4) ^.. each . filtered even
--   [2,4]
--   
--   
--   It also can be used to modify elements selectively:
--   
--   
--   >>> (1,2,3,4) & each . filtered even %~ (*100)
--   (1,200,3,400)
--   
--   
--   The implementation of filtered is very simple. Consider this
--   traversal, which always “traverses” just the value it's given:
--   
--   
--   id :: Traversal' a a
--   id f s = f s
--   
--   
--   And this traversal, which traverses nothing (in other words,
--   doesn't traverse the value it's given):
--   
--   
--   ignored :: Traversal' a a
--   ignored f s = pure s
--   
--   
--   And now combine them into a traversal that conditionally traverses the
--   value it's given, and you get filtered:
--   
--   
--   filtered :: (a -> Bool) -> Traversal' a a
--   filtered p f s = if p s then f s else pure s
--   
--   
--   By the way, note that filtered 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
--   filtered to modify/view something, you're safe. If you don't
--   define any traversals that use filtered, you're safe too.)
--   
--   Let's use evens as an example:
--   
--   
--   evens = filtered even
--   
--   
--   If evens was a legal traversal, you'd be able to fuse several
--   applications of evens like this:
--   
--   
--   over evens f . over evens g = over evens (f . g)
--   
--   
--   Unfortunately, in case of evens this isn't a correct
--   optimisation:
--   
--   
--   
- the left-side variant applies g to all even numbers, and
--   then applies f to all even numbers that are left after
--   f (because f might've turned some even numbers into
--   odd ones)
--   
- the right-side variant applies f and g to all
--   even numbers
--   
--   
--   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 filtered 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 filtered 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:
--   
--   
--   pairedWithEvens :: Traversal [(Int, a)] [(Int, b)] a b
--   pairedWithEvens = each . filtered (even . fst) . _2
--   
--   
--   Since you can't do anything with the 1st components through this
--   traversal, the following holds for any f and g:
--   
--   
--   over pairedWithEvens f . over pairedWithEvens g = over pairedWithEvens (f . g)
--   
filtered :: (a -> Bool) -> Traversal' a a

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

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

-- | each tries to be a universal Traversal – it behaves like
--   traversed 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 each doesn't work on every instance
--   of Traversable. If you have a Traversable which isn't
--   supported by each, you can use traversed instead.
--   Personally, I like using each instead of traversed
--   whenever possible – it's shorter and more descriptive.
--   
--   You can use each with these things:
--   
--   
--   each :: Traversal [a] [b] a b
--   
--   each :: Traversal (Maybe a) (Maybe b) a b
--   each :: Traversal (Either a a) (Either b b) a b  -- since 0.4.11
--   
--   each :: Traversal (a,a) (b,b) a b
--   each :: Traversal (a,a,a) (b,b,b) a b
--   each :: Traversal (a,a,a,a) (b,b,b,b) a b
--   each :: Traversal (a,a,a,a,a) (b,b,b,b,b) a b
--   
--   each :: (RealFloat a, RealFloat b) => Traversal (Complex a) (Complex b) a b
--   
--   
--   You can also use each with types from array,
--   bytestring, and containers by using
--   microlens-ghc, or additionally with types from vector,
--   text, and unordered-containers by using
--   microlens-platform.
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, Map, etc. (If you want to insert or delete
--   elements as well, look at 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 3
--   Just 3
--   
--   
--   Of course, the element may not be present (which means that you can
--   use ix as a safe variant of (!!)):
--   
--   
--   >>> [0..5] ^? ix 10
--   Nothing
--   
--   
--   Another useful instance is the one for functions – it lets you modify
--   their outputs for specific inputs. For instance, here's maximum
--   that returns 0 when the list is empty (instead of throwing an
--   exception):
--   
--   
--   maximum0 = maximum & ix [] .~ 0
--   
--   
--   The following instances are provided in this package:
--   
--   
--   ix :: Int -> Traversal' [a] a
--   
--   ix :: Int -> Traversal' (NonEmpty a) a
--   
--   ix :: (Eq e) => e -> Traversal' (e -> a) a
--   
--   
--   You can also use ix with types from array,
--   bytestring, and containers by using
--   microlens-ghc, or additionally with types from vector,
--   text, and unordered-containers by using
--   microlens-platform.
ix :: Ixed m => Index m -> Traversal' m (IxValue m)

-- | _head traverses the 1st element of something (usually a list,
--   but can also be a Seq, etc):
--   
--   
--   >>> [1..5] ^? _head
--   Just 1
--   
--   
--   It 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."
--   
--   
--   The reason it's a traversal and not a lens is that there's nothing to
--   traverse when the list is empty:
--   
--   
--   >>> [] ^? _head
--   Nothing
--   
--   
--   This package only lets you use _head on lists, but if you use
--   microlens-ghc you get instances for ByteString and
--   Seq, and if you use microlens-platform you
--   additionally get instances for Text and Vector.
_head :: Cons s s a a => Traversal' s a

-- | _tail gives you access to the tail of a list (or Seq,
--   etc):
--   
--   
--   >>> [1..5] ^? _tail
--   Just [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 _tail with plain
--   (^.) (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
--   _tail with each:
--   
--   
--   >>> "I HATE CAPS." & _tail.each %~ toLower
--   "I hate caps."
--   
--   
--   This package only lets you use _tail on lists, but if you use
--   microlens-ghc you get instances for ByteString and
--   Seq, and if you use microlens-platform you
--   additionally get instances for Text and Vector.
_tail :: Cons s s a a => Traversal' s s

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

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

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

-- | Focus on the words of a string.
--   
--   
--   >>> "avoid success at all costs" & worded . _head %~ toUpper
--   "Avoid Success At All Costs"
--   
--   
--   This violates the traversal laws when whitespace is set or when the
--   source has space at the ends or more than one contiguous space
--   anywhere.
worded :: Traversal' String String

-- | Focus on the lines of a string.
--   
--   
--   countAndMarkEmptyLines :: String -> State Int String
--   countAndMarkEmptyLines s = runState (f s) 0 where
--     f = traverseOf (lined . filtered null) $ \_ -> do
--       modify' (+ 1)
--       return "# Empty line"
--   
--   
--   This violates the traversal laws when newlines are set or when the
--   source has more than one contiguous newline anywhere.
lined :: Traversal' String String

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

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

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

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

-- | _Show targets the Haskell value in a String using
--   Read, or nothing if parsing fails. Likewise, setting a Haskell
--   value through this prism renders a String using Show.
--   
--   
--   >>> ["abc","8","def","9"] & mapped . _Show %~ \x -> x + 1 :: Int
--   ["abc","9","def","10"]
--   
--   
--   Note that this prism is improper for types that don't satisfy read
--   . show = id:
--   
--   
--   >>> "25.9999999" & _Show %~ \x -> x :: Float
--   "26.0"
--   
--   
--   These functions from base can be expressed in terms of
--   _Show:
--   
--   
--   
- Unsafely parsing a value from a String:
--   
--   
--   
--   read = (^?! _Show)
--   
--   
--   
--   
--   
- Safely parsing a value from a String:
--   
--   
--   
--   readMaybe = (^? _Show)
--   
--   
_Show :: (Show a, Read a) => Traversal' String a

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

-- | A type alias for monomorphic LensLikes.
type LensLike' f s a = LensLike f s s a a
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)
instance GHC.Base.Functor (Lens.Micro.Bazaar a b)
instance GHC.Base.Applicative (Lens.Micro.Bazaar a b)
instance GHC.Base.Applicative f => GHC.Base.Monoid (Lens.Micro.Traversed a f)
instance GHC.Base.Applicative f => GHC.Base.Semigroup (Lens.Micro.Traversed a f)

module Lens.Micro.Extras

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

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