-- 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.1.1


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, tho: 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
instance Lens.Micro.TH.HasName Language.Haskell.TH.Syntax.TyVarBndr
instance Lens.Micro.TH.HasName Language.Haskell.TH.Syntax.Name
instance Lens.Micro.TH.HasName Language.Haskell.TH.Syntax.Con
instance Lens.Micro.TH.HasTypeVars Language.Haskell.TH.Syntax.TyVarBndr
instance Lens.Micro.TH.HasTypeVars Language.Haskell.TH.Syntax.Name
instance Lens.Micro.TH.HasTypeVars Language.Haskell.TH.Syntax.Type
instance Lens.Micro.TH.HasTypeVars Language.Haskell.TH.Syntax.Con
instance Lens.Micro.TH.HasTypeVars t => Lens.Micro.TH.HasTypeVars [t]
instance Lens.Micro.TH.HasTypeVars t => Lens.Micro.TH.HasTypeVars (GHC.Base.Maybe t)
