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


-- | Automatic generation of record lenses for microlens
--   
--   This package lets you automatically generate lenses for data types;
--   code was extracted from the lens package, and therefore generated
--   lenses are fully compatible with ones generated by lens (and can be
--   used both from lens and microlens).
--   
--   This package is a part of the <a>microlens</a> family; see the readme
--   <a>on Github</a>.
@package microlens-th
@version 0.4.3.15


-- | Functions used by <a>Lens.Micro.TH</a>. This is an internal module and
--   it may go away or change at any time; do not depend on it.
module Lens.Micro.TH.Internal

-- | Has a <a>Name</a>
class HasName t

-- | Extract (or modify) the <a>Name</a> of something
name :: HasName t => Lens' t Name

-- | Generate many new names from a given base name.
newNames :: String -> Int -> Q [Name]

-- | Provides for the extraction of free type variables, and alpha
--   renaming.
class HasTypeVars t
typeVarsEx :: HasTypeVars t => Set Name -> Traversal' t Name
typeVars :: HasTypeVars t => Traversal' t Name
substTypeVars :: HasTypeVars t => Map Name Name -> t -> t
datatypeTypeKinded :: DatatypeInfo -> Type

-- | Generate an INLINE pragma.
inlinePragma :: Name -> [DecQ]

-- | Apply arguments to a type constructor.
conAppsT :: Name -> [Type] -> Type

-- | Template Haskell wants type variables declared in a forall, so we find
--   all free type variables in a given type and declare them.
quantifyType :: Cxt -> Type -> Type

-- | This function works like <a>quantifyType</a> except that it takes a
--   list of variables to exclude from quantification.
quantifyType' :: Set Name -> Cxt -> Type -> Type

-- | Convert a <a>TyVarBndr</a> into its corresponding <a>Type</a>.
tvbToType :: TyVarBndr_ flag -> Type

-- | Peel off a kind signature from a Type (if it has one).
unSigT :: Type -> Type
elemOf :: Eq a => Getting (Endo [a]) s a -> a -> s -> Bool
lengthOf :: Getting (Endo [a]) s a -> s -> Int
setOf :: Ord a => Getting (Endo [a]) s a -> s -> Set a
_ForallT :: Traversal' Type ([TyVarBndrSpec], Cxt, Type)
instance Lens.Micro.TH.Internal.HasTypeVars (Language.Haskell.TH.Datatype.TyVarBndr.TyVarBndr_ flag)
instance Lens.Micro.TH.Internal.HasTypeVars Language.Haskell.TH.Syntax.Name
instance Lens.Micro.TH.Internal.HasTypeVars Language.Haskell.TH.Syntax.Type
instance Lens.Micro.TH.Internal.HasTypeVars Language.Haskell.TH.Syntax.Con
instance Lens.Micro.TH.Internal.HasTypeVars t => Lens.Micro.TH.Internal.HasTypeVars [t]
instance Lens.Micro.TH.Internal.HasTypeVars t => Lens.Micro.TH.Internal.HasTypeVars (GHC.Maybe.Maybe t)
instance Lens.Micro.TH.Internal.HasName (Language.Haskell.TH.Datatype.TyVarBndr.TyVarBndr_ flag)
instance Lens.Micro.TH.Internal.HasName Language.Haskell.TH.Syntax.Name
instance Lens.Micro.TH.Internal.HasName Language.Haskell.TH.Syntax.Con


module Lens.Micro.TH

-- | Generate lenses for a data type or a newtype.
--   
--   To use it, you have to enable Template Haskell first:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell #-}
--   </pre>
--   
--   Then, after declaring the datatype (let's say <tt>Foo</tt>), add
--   <tt>makeLenses ''Foo</tt> on a separate line (if you do it before the
--   type is declared, you'll get a “not in scope” error – see the section
--   at the top of this page):
--   
--   <pre>
--   data Foo = Foo {
--     _x :: Int,
--     _y :: Bool }
--   
--   <a>makeLenses</a> ''Foo
--   </pre>
--   
--   This would generate the following lenses, which can be used to access
--   the fields of <tt>Foo</tt>:
--   
--   <pre>
--   x :: <a>Lens'</a> Foo Int
--   x f foo = (\x' -&gt; foo {_x = x'}) <a>&lt;$&gt;</a> f (_x foo)
--   
--   y :: <a>Lens'</a> Foo Bool
--   y f foo = (\y' -&gt; foo {_y = y'}) <a>&lt;$&gt;</a> f (_y foo)
--   </pre>
--   
--   (If you don't want a lens to be generated for some field, don't prefix
--   it with “_”.)
--   
--   If you want to create lenses for many types, you can do it all in one
--   place like this (of course, instead you just can use <a>makeLenses</a>
--   several times if you feel it would be more readable):
--   
--   <pre>
--   data Foo = ...
--   data Bar = ...
--   data Quux = ...
--   
--   <a>concat</a> <a>&lt;$&gt;</a> <a>mapM</a> <a>makeLenses</a> [''Foo, ''Bar, ''Quux]
--   </pre>
--   
--   When the data type has type parameters, it's possible for a lens to do
--   a polymorphic update – i.e. change the type of the thing along with
--   changing the type of the field. For instance, with this type
--   
--   <pre>
--   data Foo a = Foo {
--     _x :: a,
--     _y :: Bool }
--   </pre>
--   
--   the following lenses would be generated:
--   
--   <pre>
--   x :: <a>Lens</a> (Foo a) (Foo b) a b
--   y :: <a>Lens'</a> (Foo a) Bool
--   </pre>
--   
--   However, when there are several fields using the same type parameter,
--   type-changing updates are no longer possible:
--   
--   <pre>
--   data Foo a = Foo {
--     _x :: a,
--     _y :: a }
--   </pre>
--   
--   generates
--   
--   <pre>
--   x :: <a>Lens'</a> (Foo a) a
--   y :: <a>Lens'</a> (Foo a) a
--   </pre>
--   
--   Finally, when the type has several constructors, some of fields may
--   not be <i>always</i> present – for those, a <a>Traversal</a> is
--   generated instead. For instance, in this example <tt>y</tt> can be
--   present or absent:
--   
--   <pre>
--   data FooBar
--     = Foo { _x :: Int, _y :: Bool }
--     | Bar { _x :: Int }
--   </pre>
--   
--   and the following accessors would be generated:
--   
--   <pre>
--   x :: <a>Lens'</a> FooBar Int
--   y :: <a>Traversal'</a> FooBar Bool
--   </pre>
--   
--   So, to get <tt>_y</tt>, you'd have to either use (<a>^?</a>) if you're
--   not sure it's there, or (<a>^?!</a>) if you're absolutely sure (and if
--   you're wrong, you'll get an exception). Setting and updating
--   <tt>_y</tt> can be done as usual.
makeLenses :: Name -> DecsQ

-- | Like <a>makeLenses</a>, but lets you choose your own names for lenses:
--   
--   <pre>
--   data Foo = Foo {foo :: Int, bar :: Bool}
--   
--   <a>makeLensesFor</a> [("foo", "fooLens"), ("bar", "_bar")] ''Foo
--   </pre>
--   
--   would create lenses called <tt>fooLens</tt> and <tt>_bar</tt>. This is
--   useful, for instance, when you don't want to prefix your fields with
--   underscores and want to prefix <i>lenses</i> with underscores instead.
--   
--   If you give the same name to different fields, it will generate a
--   <a>Traversal</a> instead:
--   
--   <pre>
--   data Foo = Foo {slot1, slot2, slot3 :: Int}
--   
--   <a>makeLensesFor</a> [("slot1", "slots"),
--                  ("slot2", "slots"),
--                  ("slot3", "slots")] ''Foo
--   </pre>
--   
--   would generate
--   
--   <pre>
--   slots :: <a>Traversal'</a> Foo Int
--   slots f foo = Foo <a>&lt;$&gt;</a> f (slot1 foo)
--                     <a>&lt;*&gt;</a> f (slot2 foo)
--                     <a>&lt;*&gt;</a> f (slot3 foo)
--   </pre>
makeLensesFor :: [(String, String)] -> Name -> DecsQ

-- | Generate lenses with custom parameters.
--   
--   To see what exactly you can customise, look at the “Configuring lens
--   rules” section. Usually you would build upon the <a>lensRules</a>
--   configuration, which is used by <a>makeLenses</a>:
--   
--   <pre>
--   <a>makeLenses</a> = <a>makeLensesWith</a> <a>lensRules</a>
--   </pre>
--   
--   Here's an example of generating lenses that would use lazy patterns:
--   
--   <pre>
--   data Foo = Foo {_x, _y :: Int}
--   
--   <a>makeLensesWith</a> (<a>lensRules</a> <a>&amp;</a> <a>generateLazyPatterns</a> <a>.~</a> True) ''Foo
--   </pre>
--   
--   When there are several modifications to the rules, the code looks
--   nicer when you use <a>flip</a>:
--   
--   <pre>
--   <a>flip</a> <a>makeLensesWith</a> ''Foo $
--     <a>lensRules</a>
--       <a>&amp;</a> <a>generateLazyPatterns</a> <a>.~</a> True
--       <a>&amp;</a> <a>generateSignatures</a>   <a>.~</a> False
--   </pre>
makeLensesWith :: LensRules -> Name -> DecsQ

-- | Generate overloaded lenses.
--   
--   This lets you deal with several data types having same fields. For
--   instance, let's say you have <tt>Foo</tt> and <tt>Bar</tt>, and both
--   have a field named <tt>x</tt>. To avoid those fields clashing, you
--   would have to use prefixes:
--   
--   <pre>
--   data Foo a = Foo {
--     fooX :: Int,
--     fooY :: a }
--   
--   data Bar = Bar {
--     barX :: Char }
--   </pre>
--   
--   However, if you use <a>makeFields</a> on both <tt>Foo</tt> and
--   <tt>Bar</tt> now, it would generate lenses called <tt>x</tt> and
--   <tt>y</tt> – and <tt>x</tt> would be able to access both <tt>fooX</tt>
--   and <tt>barX</tt>! This is done by generating a separate class for
--   each field, and making relevant types instances of that class:
--   
--   <pre>
--   class HasX s a | s -&gt; a where
--     x :: <a>Lens'</a> s a
--   
--   instance HasX (Foo a) Int where
--     x :: <a>Lens'</a> (Foo a) Int
--     x = ...
--   
--   instance HasX Bar Char where
--     x :: <a>Lens'</a> Bar Char
--     x = ...
--   
--   
--   class HasY s a | s -&gt; a where
--     y :: <a>Lens'</a> s a
--   
--   instance HasY (Foo a) a where
--     y :: <a>Lens'</a> (Foo a) a
--     y = ...
--   </pre>
--   
--   (There's a minor drawback, though: you can't perform type-changing
--   updates with these lenses.)
--   
--   If you only want to make lenses for some fields, you can prefix them
--   with underscores – the rest would be untouched. If no fields are
--   prefixed with underscores, lenses would be created for all fields.
--   
--   The prefix must be the same as the name of the name of the data type
--   (<i>not</i> the constructor). If you don't like this behavior, use
--   <tt><a>makeLensesWith</a> <a>abbreviatedFields</a></tt> – it allows
--   any prefix (and even different prefixes).
--   
--   If you want to use <a>makeFields</a> on types declared in different
--   modules, you can do it, but then you would have to export the
--   <tt>Has*</tt> classes from one of the modules – <a>makeFields</a>
--   creates a class if it's not in scope yet, so the class must be in
--   scope or else there would be duplicate classes and you would get an
--   “Ambiguous occurrence” error.
--   
--   Finally, <a>makeFields</a> is implemented as <tt><a>makeLensesWith</a>
--   <a>camelCaseFields</a></tt>, so you can build on
--   <a>camelCaseFields</a> if you want to customise behavior of
--   <a>makeFields</a>.
makeFields :: Name -> DecsQ

-- | Generate overloaded lenses without ad-hoc classes; useful when there's
--   a collection of fields that you want to make common for several types.
--   
--   Like <a>makeFields</a>, each lens is a member of a class. However, the
--   classes are per-type and not per-field. Let's take the following type:
--   
--   <pre>
--   data Person = Person {
--     _name :: String,
--     _age :: Double }
--   </pre>
--   
--   <a>makeClassy</a> would generate a single class with 3 methods:
--   
--   <pre>
--   class HasPerson c where
--     person :: Lens' c Person
--   
--     age :: Lens' c Double
--     age = person.age
--   
--     name :: Lens' c String
--     name = person.name
--   </pre>
--   
--   And an instance:
--   
--   <pre>
--   instance HasPerson Person where
--     person = id
--   
--     name = ...
--     age = ...
--   </pre>
--   
--   So, you can use <tt>name</tt> and <tt>age</tt> to refer to the
--   <tt>_name</tt> and <tt>_age</tt> fields, as usual. However, the extra
--   lens – <tt>person</tt> – allows you to do a kind of subtyping. Let's
--   say that there's a type called <tt>Worker</tt> and every worker has
--   the same fields that a person has, but also a <tt>job</tt>. If you
--   were using <a>makeFields</a>, you'd do the following:
--   
--   <pre>
--   data Worker = Worker {
--     _workerName :: String,
--     _workerAge :: Double,
--     _workerJob :: String }
--   </pre>
--   
--   However, with <a>makeClassy</a> you can say “every worker is a person”
--   in a more principled way:
--   
--   <pre>
--   data Worker = Worker {
--     _workerPerson :: Person,
--     _job :: String }
--   
--   makeClassy ''Worker
--   
--   instance HasPerson Worker where person = workerPerson
--   </pre>
--   
--   Now you can use <tt>age</tt> and <tt>name</tt> to access name/age of a
--   <tt>Worker</tt>, but you also can use <tt>person</tt> to “downgrade” a
--   <tt>Worker</tt> to a <tt>Person</tt> (and e.g. apply some
--   <tt>Person</tt>-specific function to it).
--   
--   Unlike <a>makeFields</a>, <a>makeClassy</a> doesn't make use of
--   prefixes. <tt>_workerPerson</tt> could've just as well been named
--   <tt>_foobar</tt>.
--   
--   <a>makeClassy</a> is implemented as <tt><a>makeLensesWith</a>
--   <a>classyRules</a></tt>, so you can build on <a>classyRules</a> if you
--   want to customise behavior of <a>makeClassy</a>.
makeClassy :: Name -> DecsQ

-- | Rules used to generate lenses. The fields are intentionally not
--   exported; to create your own rules, see lenses in the “Configuring
--   lens rules” section. You'd have to customise one of the existing
--   rulesets; for an example of doing that, see <a>makeLensesWith</a>.
data LensRules

-- | Name to give to a generated lens (used in <a>lensField</a>).
data DefName

-- | Simple top-level definiton name
TopName :: Name -> DefName

-- | <a>makeFields</a>-style class name and method name
MethodName :: Name -> Name -> DefName

-- | Lens rules used by default (i.e. in <a>makeLenses</a>):
--   
--   <ul>
--   <li><a>generateSignatures</a> is turned on</li>
--   <li><a>generateUpdateableOptics</a> is turned on</li>
--   <li><a>generateLazyPatterns</a> is turned off</li>
--   <li><a>simpleLenses</a> is turned off</li>
--   <li><a>lensField</a> strips “_” off the field name, lowercases the
--   next character after “_”, and skips the field entirely if it doesn't
--   start with “_” (you can see how it's implemented in the docs for
--   <a>lensField</a>)</li>
--   <li><a>lensClass</a> isn't used (i.e. defined as <tt>const
--   Nothing</tt>)</li>
--   </ul>
lensRules :: LensRules

-- | A modification of <a>lensRules</a> used by <a>makeLensesFor</a> (the
--   only difference is that a simple lookup function is used for
--   <a>lensField</a>).
lensRulesFor :: [(String, String)] -> LensRules

-- | Lens rules used by <a>makeClassy</a>:
--   
--   <ul>
--   <li><a>generateSignatures</a> is turned on</li>
--   <li><a>generateUpdateableOptics</a> is turned on</li>
--   <li><a>generateLazyPatterns</a> is turned off</li>
--   <li><a>simpleLenses</a> is turned on (unlike in <a>lensRules</a>)</li>
--   <li><a>lensField</a> is the same as in <a>lensRules</a></li>
--   <li><a>lensClass</a> just adds “Has” to the name of the type (so for
--   “Person” the generated class would be called “HasPerson” and the
--   type-specific lens in that class would be called “person”)</li>
--   </ul>
classyRules :: LensRules

-- | Lens rules used by <a>makeFields</a>:
--   
--   <ul>
--   <li><a>generateSignatures</a> is turned on</li>
--   <li><a>generateUpdateableOptics</a> is turned on</li>
--   <li><a>generateLazyPatterns</a> is turned off</li>
--   <li><a>simpleLenses</a> is turned on (unlike in <a>lensRules</a>)</li>
--   <li><a>lensField</a> is more complicated – it takes fields which are
--   prefixed with the name of the type they belong to (e.g. “fooFieldName”
--   for “Foo”), strips that prefix, and generates a class called
--   “HasFieldName” with a single method called “fieldName”. If some fields
--   are prefixed with underscores, underscores would be stripped too, but
--   then fields without underscores won't have any lenses generated for
--   them. Also note that e.g. “foolish” won't have a lens called “lish”
--   generated for it – the prefix must be followed by a capital letter (or
--   else it wouldn't be camel case).</li>
--   <li><a>lensClass</a> isn't used (i.e. defined as <tt>const
--   Nothing</tt>)</li>
--   </ul>
camelCaseFields :: LensRules

-- | Like standard rules used by <a>makeFields</a>, but doesn't put any
--   restrictions on the prefix. I.e. if you have fields called
--   
--   <ul>
--   <li><pre>_fooBarBaz</pre></li>
--   <li><pre>_someX</pre></li>
--   <li><pre>someY</pre></li>
--   </ul>
--   
--   then the generated lenses would be called <tt>barBaz</tt> and
--   <tt>x</tt>.
abbreviatedFields :: LensRules

-- | This lets you choose which fields would have lenses generated for them
--   and how would those lenses be called. To do that, you provide a
--   function that would take a field name and output a list (possibly
--   empty) of lenses that should be generated for that field.
--   
--   Here's the full type of the function you have to provide:
--   
--   <pre>
--   <a>Name</a> -&gt;     -- The datatype lenses are being generated for
--   [<a>Name</a>] -&gt;   -- A list of all fields of the datatype
--   <a>Name</a> -&gt;     -- The current field
--   [<a>DefName</a>]   -- A list of lens names
--   </pre>
--   
--   Most of the time you won't need the first 2 parameters, but sometimes
--   they are useful – for instance, the list of all fields would be useful
--   if you wanted to implement a slightly more complicated rule like “if
--   some fields are prefixed with underscores, generate lenses for them,
--   but if no fields are prefixed with underscores, generate lenses for
--   <i>all</i> fields”.
--   
--   As an example, here's a function used by default. It strips “_” off
--   the field name, lowercases the next character after “_”, and skips the
--   field entirely if it doesn't start with “_”:
--   
--   <pre>
--   \_ _ n -&gt;
--     case <a>nameBase</a> n of
--       '_':x:xs -&gt; [<a>TopName</a> (<a>mkName</a> (<a>toLower</a> x : xs))]
--       _        -&gt; []
--   </pre>
--   
--   You can also generate classes (i.e. what <a>makeFields</a> does) by
--   using <tt><a>MethodName</a> className lensName</tt> instead of
--   <tt><a>TopName</a> lensName</tt>.
lensField :: Lens' LensRules (Name -> [Name] -> Name -> [DefName])

-- | This lets you choose whether a class would be generated for the type
--   itself (like <a>makeClassy</a> does). If so, you can choose the name
--   of the class and the name of the type-specific lens.
--   
--   For <a>makeLenses</a> and <a>makeFields</a> this is just <tt>const
--   Nothing</tt>. For <a>makeClassy</a> this function is defined like
--   this:
--   
--   <pre>
--   \n -&gt;
--     case <a>nameBase</a> n of
--       x:xs -&gt; Just (<a>mkName</a> (<a>Has</a> ++ x:xs), <a>mkName</a> (<a>toLower</a> x : xs))
--       []   -&gt; Nothing
--   </pre>
lensClass :: Lens' LensRules (Name -> Maybe (Name, Name))

-- | Decide whether generation of classes is allowed at all.
--   
--   If this is disabled, neither <a>makeFields</a> nor <a>makeClassy</a>
--   would work, regardless of values of <a>lensField</a> or
--   <a>lensClass</a>. On the other hand, if <a>lensField</a> and
--   <a>lensClass</a> don't generate any classes, enabling this won't have
--   any effect.
createClass :: Lens' LensRules Bool

-- | Generate simple (monomorphic) lenses even when type-changing lenses
--   are possible – i.e. <a>Lens'</a> instead of <a>Lens</a> and
--   <a>Traversal'</a> instead of <a>Traversal</a>. Just in case, here's an
--   example of a situation when type-changing lenses would be normally
--   generated:
--   
--   <pre>
--   data Foo a = Foo { _foo :: a }
--   </pre>
--   
--   Generated lens:
--   
--   <pre>
--   foo :: <a>Lens</a> (Foo a) (Foo b) a b
--   </pre>
--   
--   Generated lens with <a>simpleLenses</a> turned on:
--   
--   <pre>
--   foo :: <a>Lens'</a> (Foo a) a
--   </pre>
--   
--   This option is disabled by default.
simpleLenses :: Lens' LensRules Bool

-- | Supply type signatures for the generated lenses.
--   
--   This option is enabled by default. Disable it if you want to write the
--   signature by yourself – for instance, if the signature should be more
--   restricted, or if you want to write haddocks for the lens (as haddocks
--   are attached to the signature and not to the definition).
generateSignatures :: Lens' LensRules Bool

-- | Generate “updateable” optics. When turned off, <a>SimpleFold</a>s will
--   be generated instead of <a>Traversal</a>s and <a>SimpleGetter</a>s
--   will be generated instead of <a>Lens</a>es.
--   
--   This option is enabled by default. Disabling it can be useful for
--   types with invariants (also known as “types with smart constructors”)
--   – if you generate updateable optics, anyone would be able to use them
--   to break your invariants.
generateUpdateableOptics :: Lens' LensRules Bool

-- | Generate lenses using lazy pattern matches. This can allow fields of
--   an undefined value to be initialized with lenses:
--   
--   <pre>
--   data Foo = Foo {_x :: Int, _y :: Bool}
--     deriving Show
--   
--   <a>makeLensesWith</a> (<a>lensRules</a> <a>&amp;</a> <a>generateLazyPatterns</a> <a>.~</a> True) ''Foo
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; <a>undefined</a> <a>&amp;</a> x <a>.~</a> 8 <a>&amp;</a> y <a>.~</a> True
--   Foo {_x = 8, _y = True}
--   </pre>
--   
--   (Without <a>generateLazyPatterns</a>, the result would be just
--   <a>undefined</a>.)
--   
--   This option is disabled by default. The downside of enabling it is
--   that it can lead to space-leaks and code-size/compile-time increases
--   when lenses are generated for large records.
--   
--   When you have a lazy lens, you can get a strict lens from it by
--   composing with (<a>$!</a>):
--   
--   <pre>
--   strictLens = (<a>$!</a>) . lazyLens
--   </pre>
generateLazyPatterns :: Lens' LensRules Bool
instance GHC.Classes.Ord Lens.Micro.TH.DefName
instance GHC.Classes.Eq Lens.Micro.TH.DefName
instance GHC.Show.Show Lens.Micro.TH.DefName
