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


-- | First class accessor labels implemented as lenses.
--   
--   This package provides first class labels that can act as bidirectional
--   record fields. The labels can be derived automatically using Template
--   Haskell which means you don't have to write any boilerplate yourself.
--   The labels are implemented as <i>lenses</i> and are fully composable.
--   Lenses can be used to <i>get</i>, <i>set</i> and <i>modify</i> parts
--   of a data type in a consistent way.
--   
--   See <a>Data.Label</a> for an introductory explanation or see the
--   introductory blog post at
--   <a>http://fvisser.nl/post/2013/okt/1/fclabels-2.0.html</a>
--   
--   <ul>
--   <li><i>Total and partial lenses</i></li>
--   </ul>
--   
--   Internally lenses do not used Haskell functions directly, but are
--   implemented as categories. Categories allow the lenses to be run in
--   custom computational contexts. This approach allows us to make partial
--   lenses that point to fields of multi-constructor datatypes in an
--   elegant way.
--   
--   See <a>Data.Label.Partial</a> for the use of partial labels.
--   
--   <ul>
--   <li><i>Monomorphic and polymorphic lenses</i></li>
--   </ul>
--   
--   We have both polymorphic and monomorphic lenses. Polymorphic lenses
--   allow updates that change the type. The types of polymorphic lenses
--   are slightly more verbose than their monomorphic counterparts, but
--   their usage is similar. Because monomorphic lenses are built by
--   restricting the types of polymorphic lenses they are essentially the
--   same and can be freely composed with eachother.
--   
--   See <a>Data.Label.Mono</a> and <a>Data.Label.Poly</a> for the
--   difference between polymorphic and monomorphic lenses.
--   
--   <ul>
--   <li><i>Using fclabels</i></li>
--   </ul>
--   
--   To simplify working with labels we supply both a set of labels for
--   Haskell's base types, like lists, tuples, Maybe and Either, and we
--   supply a set of combinators for working with labels for values in the
--   Reader and State monad.
--   
--   See <a>Data.Label.Base</a> and <a>Data.Label.Monadic</a> for more
--   information.
--   
--   <ul>
--   <li><i>Changelog from 2.0.3.1 to 2.0.3.2</i></li>
--   </ul>
--   
--   <pre>
--   - Allow HUnit 1.5.*.
--   </pre>
@package fclabels
@version 2.0.3.2


-- | The Point data type which generalizes the different lenses and forms
--   the basis for vertical composition using the <a>Applicative</a> type
--   class.
module Data.Label.Point

-- | Abstract Point datatype. The getter and modifier operations work in
--   some category. The type of the value pointed to might change, thereby
--   changing the type of the outer structure.
data Point cat g i f o
Point :: (cat f o) -> (cat (cat o i, f) g) -> Point cat g i f o

-- | Get the getter category from a Point.
get :: Point cat g i f o -> cat f o

-- | Get the modifier category from a Point.
modify :: Point cat g i f o -> cat (cat o i, f) g

-- | Get the setter category from a Point.
set :: Arrow arr => Point arr g i f o -> arr (i, f) g

-- | Identity Point. Cannot change the type.
identity :: ArrowApply arr => Point arr f f o o

-- | Point composition.
compose :: ArrowApply cat => Point cat t i b o -> Point cat g t f b -> Point cat g i f o

-- | An isomorphism is like a <a>Category</a> that works in two directions.
data Iso cat i o
Iso :: cat i o -> cat o i -> Iso cat i o
[fw] :: Iso cat i o -> cat i o
[bw] :: Iso cat i o -> cat o i

-- | Flip an isomorphism.
inv :: Iso cat i o -> Iso cat o i

-- | Context that represents computations that always produce an output.
type Total = (->)

-- | Context that represents computations that might silently fail.
type Partial = Kleisli Maybe

-- | Context that represents computations that might fail with some error.
type Failing e = Kleisli (Either e)

-- | The ArrowFail class is similar to <a>ArrowZero</a>, but additionally
--   embeds some error value in the computation instead of throwing it
--   away.
class Arrow a => ArrowFail e a
failArrow :: ArrowFail e a => a e c
instance Control.Arrow.Arrow arr => GHC.Base.Functor (Data.Label.Point.Point arr f i f)
instance Control.Arrow.Arrow arr => GHC.Base.Applicative (Data.Label.Point.Point arr f i f)
instance GHC.Base.Alternative (Data.Label.Point.Point Data.Label.Point.Partial f view f)
instance Control.Category.Category cat => Control.Category.Category (Data.Label.Point.Iso cat)
instance Data.Label.Point.ArrowFail e Data.Label.Point.Partial
instance Data.Label.Point.ArrowFail e (Data.Label.Point.Failing e)
instance GHC.Base.Functor f => GHC.Base.Functor (Control.Arrow.Kleisli f i)
instance GHC.Base.Applicative f => GHC.Base.Applicative (Control.Arrow.Kleisli f i)
instance GHC.Base.Alternative f => GHC.Base.Alternative (Control.Arrow.Kleisli f i)


-- | Lenses that allow polymorphic updates.
module Data.Label.Poly

-- | Abstract polymorphic lens datatype. The getter and setter functions
--   work in some category. Categories allow for effectful lenses, for
--   example, lenses that might fail or use state.
data Lens cat f o

-- | Create a lens out of a getter and setter.
lens :: cat f o -> cat (cat o i, f) g -> Lens cat (f -> g) (o -> i)

-- | Create lens from a <a>Point</a>.
point :: Point cat g i f o -> Lens cat (f -> g) (o -> i)

-- | Get the getter arrow from a lens.
get :: Lens cat (f -> g) (o -> i) -> cat f o

-- | Get the modifier arrow from a lens.
modify :: Lens cat (f -> g) (o -> i) -> cat (cat o i, f) g

-- | Get the setter arrow from a lens.
set :: Arrow arr => Lens arr (f -> g) (o -> i) -> arr (i, f) g

-- | Lift a polymorphic isomorphism into a <a>Lens</a>.
--   
--   The isomorphism needs to be passed in twice to properly unify.
iso :: ArrowApply cat => Iso cat f o -> Iso cat g i -> Lens cat (f -> g) (o -> i)

-- | Make a Lens output diverge by changing the input of the modifier. The
--   operator can be read as <i>points-to</i>.
(>-) :: Arrow arr => Lens arr (j -> a) (i -> b) -> Lens arr (f -> g) (o -> i) -> Point arr g j f o
infix 7 >-

-- | Non-operator version of <a>&gt;-</a>, since it clashes with an
--   operator when the Arrows language extension is used.
for :: Arrow arr => Lens arr (j -> a) (i -> b) -> Lens arr (f -> g) (o -> i) -> Point arr g j f o
infix 7 `for`
instance Control.Arrow.ArrowApply arr => Control.Category.Category (Data.Label.Poly.Lens arr)


-- | Default lenses for simple total getters and total possibly
--   polymorphic, updates. Useful for creating accessor labels for single
--   constructor datatypes. Also useful field labels that are shared
--   between all the constructors of a multi constructor datatypes.
module Data.Label.Total

-- | Total lens type specialized for total accessor functions.
type (:->) f o = Lens Total f o

-- | Context that represents computations that always produce an output.
type Total = (->)

-- | Create a total lens from a getter and a modifier.
--   
--   We expect the following law to hold:
--   
--   <pre>
--   get l (set l a f) == a
--   </pre>
--   
--   <pre>
--   set l (get l f) f == f
--   </pre>
lens :: (f -> o) -> ((o -> i) -> f -> g) -> (f -> g) :-> (o -> i)

-- | Get the getter function from a lens.
get :: ((f -> g) :-> (o -> i)) -> f -> o

-- | Get the modifier function from a lens.
modify :: (f -> g) :-> (o -> i) -> (o -> i) -> f -> g

-- | Get the setter function from a lens.
set :: ((f -> g) :-> (o -> i)) -> i -> f -> g

-- | Modify in some context.
traverse :: Functor m => (f -> g) :-> (o -> i) -> (o -> m i) -> f -> m g

-- | Lifted lens composition.
--   
--   For example, useful when specialized to lists:
--   
--   <pre>
--   :: (f :-&gt; [o])
--   -&gt; (o :-&gt; [a])
--   -&gt; (f :-&gt; [a])
--   </pre>
lifted :: Monad m => (f -> g) :-> (m o -> m i) -> (o -> i) :-> (m a -> m b) -> (f -> g) :-> (m a -> m b)


-- | Monomorphic lenses where the getters and updates can potentially
--   silently fail. Partial lenses are useful for creating accessor labels
--   for multi constructor data types where projection and modification of
--   fields will not always succeed.
module Data.Label.Partial

-- | Partial lens type for situations in which the accessor functions can
--   fail.
type (:~>) f o = Lens Partial f o

-- | Context that represents computations that might silently fail.
type Partial = Kleisli Maybe

-- | Create a lens that can fail from a getter and a modifier that can
--   themselves potentially fail.
lens :: (f -> Maybe o) -> ((o -> Maybe i) -> f -> Maybe g) -> (f -> g) :~> (o -> i)

-- | Getter for a lens that can fail. When the field to which the lens
--   points is not accessible the getter returns <a>Nothing</a>.
get :: (f -> g) :~> (o -> i) -> f -> Maybe o

-- | Modifier for a lens that can fail. When the field to which the lens
--   points is not accessible this function returns <a>Nothing</a>.
modify :: (f -> g) :~> (o -> i) -> (o -> i) -> f -> Maybe g

-- | Setter for a lens that can fail. When the field to which the lens
--   points is not accessible this function returns <a>Nothing</a>.
set :: (f -> g) :~> (o -> i) -> i -> f -> Maybe g

-- | Embed a total lens that points to a <a>Maybe</a> field into a lens
--   that might fail.
embed :: Lens (->) (f -> g) (Maybe o -> Maybe i) -> (f -> g) :~> (o -> i)

-- | Like <a>set</a> but return behaves like the identity function when the
--   field could not be set.
set' :: (f -> f) :~> (o -> o) -> o -> f -> f

-- | Like <a>modify</a> but return behaves like the identity function when
--   the field could not be set.
modify' :: (f -> f) :~> (o -> o) -> (o -> o) -> f -> f

-- | Like <a>modify</a>, but update allows, depending on the underlying
--   lens, to remove items by modifying to <a>Nothing</a>.
update :: (f -> b) :~> (o -> i) -> (o -> Maybe i) -> f -> Maybe b


-- | Lenses that only allow monomorphic updates. Monomorphic lenses are
--   simply polymorphic lenses with the input and output type variables
--   constraint to the same type.
module Data.Label.Mono

-- | Abstract monomorphic lens datatype. The getter and setter functions
--   work in some category. Categories allow for effectful lenses, for
--   example, lenses that might fail or use state.
type Lens cat f o = Lens cat (f -> f) (o -> o)

-- | Create a lens out of a getter and setter.
lens :: cat f o -> (cat (cat o o, f) f) -> Lens cat f o

-- | Get the getter arrow from a lens.
get :: Lens cat f o -> cat f o

-- | Get the modifier arrow from a lens.
modify :: Lens cat f o -> cat (cat o o, f) f

-- | Create lens from a <a>Point</a>.
point :: Point cat f o f o -> Lens cat f o

-- | Get the setter arrow from a lens.
set :: Arrow arr => Lens arr f o -> arr (o, f) f

-- | Lift an isomorphism into a <a>Lens</a>.
iso :: ArrowApply cat => Iso cat f o -> Lens cat f o

-- | Total monomorphic lens.
type (:->) f o = Lens Total f o

-- | Partial monomorphic lens.
type (:~>) f o = Lens Partial f o


-- | State and Reader operations specialized for working with total lenses.
module Data.Label.Monadic

-- | Get a value out of the state, pointed to by the specified lens.
gets :: MonadState f m => Lens (->) f o -> m o

-- | Set a value somewhere in the state, pointed to by the specified lens.
puts :: MonadState f m => Lens (->) f o -> o -> m ()

-- | Modify a value with a function somewhere in the state, pointed to by
--   the specified lens.
modify :: MonadState f m => Lens (->) f o -> (o -> o) -> m ()

-- | Modify a value with a function somewhere in the state, pointed to by
--   the specified lens. Additionally return a separate value based on the
--   modification.
modifyAndGet :: MonadState f m => (Lens (->) f o) -> (o -> (a, o)) -> m a

-- | Alias for <a>puts</a> that reads like an assignment.
(=:) :: MonadState f m => Lens (->) f o -> o -> m ()
infixr 2 =:

-- | Alias for <a>modify</a> that reads more or less like an assignment.
(=.) :: MonadState f m => Lens (->) f o -> (o -> o) -> m ()
infixr 2 =.

-- | Fetch a value pointed to by a lens out of a reader environment.
asks :: MonadReader f m => (Lens (->) f o) -> m o

-- | Execute a computation in a modified environment. The lens is used to
--   point out the part to modify.
local :: MonadReader f m => (Lens (->) f o) -> (o -> o) -> m a -> m a


-- | Lenses for getters and updates that can potentially fail with some
--   error value. Like partial lenses, failing lenses are useful for
--   creating accessor labels for multi constructor data types where
--   projection and modification of fields will not always succeed. The
--   error value can be used to report what caused the failure.
module Data.Label.Failing

-- | Lens type for situations in which the accessor functions can fail with
--   some error information.
type Lens e f o = Lens (Failing e) f o

-- | Context that represents computations that might fail with some error.
type Failing e = Kleisli (Either e)

-- | Create a lens that can fail from a getter and a modifier that can
--   themselves potentially fail.
lens :: (f -> Either e o) -> ((o -> Either e i) -> f -> Either e g) -> Lens e (f -> g) (o -> i)

-- | Getter for a lens that can fail. When the field to which the lens
--   points is not accessible the getter returns <a>Nothing</a>.
get :: Lens e (f -> g) (o -> i) -> f -> Either e o

-- | Modifier for a lens that can fail. When the field to which the lens
--   points is not accessible this function returns <a>Left</a>.
modify :: Lens e (f -> g) (o -> i) -> (o -> i) -> f -> Either e g

-- | Setter for a lens that can fail. When the field to which the lens
--   points is not accessible this function returns <a>Left</a>.
set :: Lens e (f -> g) (o -> i) -> i -> f -> Either e g

-- | Embed a total lens that points to an <a>Either</a> field into a lens
--   that might fail.
embed :: Lens (->) (f -> g) (Either e o -> Either e i) -> Lens e (f -> g) (o -> i)

-- | Like <a>set</a> but return behaves like the identity function when the
--   field could not be set.
set' :: Lens e (f -> f) (o -> o) -> o -> f -> f

-- | Like <a>modify</a> but return behaves like the identity function when
--   the field could not be set.
modify' :: Lens e (f -> f) (o -> o) -> (o -> o) -> f -> f


-- | Template Haskell functions for automatically generating labels for
--   algebraic datatypes, newtypes and GADTs. There are two basic modes of
--   label generation, the <a>mkLabels</a> family of functions create
--   labels (and optionally type signatures) in scope as top level
--   funtions, the <a>getLabel</a> family of funtions create labels as
--   expressions that can be named and typed manually.
--   
--   In the case of multi-constructor datatypes some fields might not
--   always be available and the derived labels will be partial. Partial
--   labels are provided with an additional type context that forces them
--   to be only usable in the <a>Partial</a> or <a>Failing</a> context.
module Data.Label.Derive

-- | Derive labels including type signatures for all the record selectors
--   in a single datatype. The types will be polymorphic and can be used in
--   an arbitrary context.
mkLabel :: Name -> Q [Dec]

-- | Derive labels including type signatures for all the record selectors
--   for a collection of datatypes. The types will be polymorphic and can
--   be used in an arbitrary context.
mkLabels :: [Name] -> Q [Dec]

-- | Like <a>mkLabels</a>, but uses the specified function to produce
--   custom names for the labels.
--   
--   For instance, <tt>(drop 1 . dropWhile (/='_'))</tt> creates a label
--   <tt>val</tt> from a record <tt>Rec { rec_val :: X }</tt>.
mkLabelsNamed :: (String -> String) -> [Name] -> Q [Dec]

-- | Derive unnamed labels as n-tuples that can be named manually. The
--   types will be polymorphic and can be used in an arbitrary context.
--   
--   Example:
--   
--   <pre>
--   (left, right) = $(getLabel ''Either)
--   </pre>
--   
--   The lenses can now also be typed manually:
--   
--   <pre>
--   left  :: (Either a b -&gt; Either c b) :~&gt; (a -&gt; c)
--   right :: (Either a b -&gt; Either a c) :~&gt; (b -&gt; c)
--   </pre>
--   
--   Note: Because of the abstract nature of the generated lenses and the
--   top level pattern match, it might be required to use
--   <tt>NoMonomorphismRestriction</tt> in some cases.
getLabel :: Name -> Q Exp

-- | Derive labels for all the record types in the supplied declaration.
--   The record fields don't need an underscore prefix. Multiple data types
--   / newtypes are allowed at once.
--   
--   The advantage of this approach is that you don't need to explicitly
--   hide the original record accessors from being exported and they won't
--   show up in the derived <a>Show</a> instance.
--   
--   Example:
--   
--   <pre>
--   fclabels [d|
--     data Record = Record
--       { int  :: Int
--       , bool :: Bool
--       } deriving Show
--     |]
--   </pre>
--   
--   <pre>
--   ghci&gt; modify int (+2) (Record 1 False)
--   Record 3 False
--   </pre>
fclabels :: Q [Dec] -> Q [Dec]

-- | Low level standalone label derivation function.
mkLabelsWith :: (String -> String) -> Bool -> Bool -> Bool -> Bool -> Name -> Q [Dec]

-- | Low level label as expression derivation function.
getLabelWith :: Bool -> Bool -> Bool -> Name -> Q Exp

-- | Default way of generating a label name from the Haskell record
--   selector name. If the original selector starts with an underscore,
--   remove it and make the next character lowercase. Otherwise, add
--   <tt>l</tt>, and make the next character uppercase.
defaultNaming :: String -> String
instance GHC.Show.Show Data.Label.Derive.Context
instance GHC.Classes.Eq Data.Label.Derive.Context
instance Data.Foldable.Foldable Data.Label.Derive.Field
instance GHC.Base.Functor Data.Label.Derive.Field
instance GHC.Classes.Eq c => GHC.Classes.Eq (Data.Label.Derive.Field c)


-- | This package provides first class labels that can act as bidirectional
--   record fields. The labels can be derived automatically using Template
--   Haskell which means you don't have to write any boilerplate yourself.
--   The labels are implemented as lenses and are fully composable. Labels
--   can be used to <i>get</i>, <i>set</i> and <i>modify</i> parts of a
--   datatype in a consistent way.
module Data.Label

-- | Total monomorphic lens.
type (:->) f o = Lens Total f o

-- | Create a total lens from a getter and a modifier.
--   
--   We expect the following law to hold:
--   
--   <pre>
--   get l (modify l m f) == m (get l f)
--   </pre>
lens :: (f -> a) -> ((a -> a) -> f -> f) -> f :-> a

-- | Get the getter function from a lens.
get :: (f :-> a) -> f -> a

-- | Get the setter function from a lens.
set :: (f :-> a) -> a -> f -> f

-- | Get the modifier function from a lens.
modify :: f :-> a -> (a -> a) -> f -> f

-- | Create lens from a <a>Point</a>.
point :: Point cat g i f o -> Lens cat (f -> g) (o -> i)

-- | Make a Lens output diverge by changing the input of the modifier. The
--   operator can be read as <i>points-to</i>.
(>-) :: Arrow arr => Lens arr (j -> a) (i -> b) -> Lens arr (f -> g) (o -> i) -> Point arr g j f o
infix 7 >-

-- | Non-operator version of <a>&gt;-</a>, since it clashes with an
--   operator when the Arrows language extension is used.
for :: Arrow arr => Lens arr (j -> a) (i -> b) -> Lens arr (f -> g) (o -> i) -> Point arr g j f o
infix 7 `for`

-- | An isomorphism is like a <a>Category</a> that works in two directions.
data Iso cat i o
Iso :: cat i o -> cat o i -> Iso cat i o
[fw] :: Iso cat i o -> cat i o
[bw] :: Iso cat i o -> cat o i

-- | Flip an isomorphism.
inv :: Iso cat i o -> Iso cat o i

-- | Lift an isomorphism into a <a>Lens</a>.
iso :: ArrowApply cat => Iso cat f o -> Lens cat f o

-- | Derive labels including type signatures for all the record selectors
--   in a single datatype. The types will be polymorphic and can be used in
--   an arbitrary context.
mkLabel :: Name -> Q [Dec]

-- | Derive labels including type signatures for all the record selectors
--   for a collection of datatypes. The types will be polymorphic and can
--   be used in an arbitrary context.
mkLabels :: [Name] -> Q [Dec]

-- | Derive unnamed labels as n-tuples that can be named manually. The
--   types will be polymorphic and can be used in an arbitrary context.
--   
--   Example:
--   
--   <pre>
--   (left, right) = $(getLabel ''Either)
--   </pre>
--   
--   The lenses can now also be typed manually:
--   
--   <pre>
--   left  :: (Either a b -&gt; Either c b) :~&gt; (a -&gt; c)
--   right :: (Either a b -&gt; Either a c) :~&gt; (b -&gt; c)
--   </pre>
--   
--   Note: Because of the abstract nature of the generated lenses and the
--   top level pattern match, it might be required to use
--   <tt>NoMonomorphismRestriction</tt> in some cases.
getLabel :: Name -> Q Exp

-- | Derive labels for all the record types in the supplied declaration.
--   The record fields don't need an underscore prefix. Multiple data types
--   / newtypes are allowed at once.
--   
--   The advantage of this approach is that you don't need to explicitly
--   hide the original record accessors from being exported and they won't
--   show up in the derived <a>Show</a> instance.
--   
--   Example:
--   
--   <pre>
--   fclabels [d|
--     data Record = Record
--       { int  :: Int
--       , bool :: Bool
--       } deriving Show
--     |]
--   </pre>
--   
--   <pre>
--   ghci&gt; modify int (+2) (Record 1 False)
--   Record 3 False
--   </pre>
fclabels :: Q [Dec] -> Q [Dec]


-- | Labels for data types in the base package. The lens types are kept
--   abstract to be fully reusable in custom contexts. Build to be imported
--   qualified.
module Data.Label.Base

-- | Lens pointing to the head of a list's cons cell. (Partial and
--   monomorphic)
head :: (ArrowZero arr, ArrowApply arr, ArrowChoice arr) => Lens arr [a] a

-- | Lens pointing to the tail of a list's cons cell. (Partial and
--   monomorphic)
tail :: (ArrowZero arr, ArrowApply arr, ArrowChoice arr) => Lens arr [a] [a]

-- | Lens pointing to the left value in an Either. (Partial and
--   polymorphic)
left :: (ArrowZero arr, ArrowApply arr, ArrowChoice arr) => Lens arr (Either a b -> Either o b) (a -> o)

-- | Lens pointing to the right value in an Either. (Partial and
--   polymorphic)
right :: (ArrowZero arr, ArrowApply arr, ArrowChoice arr) => Lens arr (Either a b -> Either a o) (b -> o)

-- | Lens pointing to the value in a Maybe. (Partial and polymorphic)
just :: (ArrowChoice cat, ArrowZero cat, ArrowApply cat) => Lens cat (Maybe a -> Maybe b) (a -> b)

-- | Lens pointing to the first component of a 2-tuple. (Total and
--   polymorphic)
fst :: ArrowApply arr => Lens arr ((a, b) -> (o, b)) (a -> o)

-- | Lens pointing to the second component of a 2-tuple. (Total and
--   polymorphic)
snd :: ArrowApply arr => Lens arr ((a, b) -> (a, o)) (b -> o)

-- | Polymorphic lens that swaps the components of a tuple. (Total and
--   polymorphic)
swap :: ArrowApply arr => Lens arr ((a, b) -> (c, d)) ((b, a) -> (d, c))

-- | Lens pointing to the first component of a 3-tuple. (Total and
--   polymorphic)
fst3 :: ArrowApply arr => Lens arr ((a, b, c) -> (o, b, c)) (a -> o)

-- | Lens pointing to the second component of a 3-tuple. (Total and
--   polymorphic)
snd3 :: ArrowApply arr => Lens arr ((a, b, c) -> (a, o, c)) (b -> o)

-- | Lens pointing to the third component of a 3-tuple. (Total and
--   polymorphic)
trd3 :: ArrowApply arr => Lens arr ((a, b, c) -> (a, b, o)) (c -> o)

-- | Partial isomorphism for readable and showable values. Can easily be
--   lifted into a lens by using <a>iso</a>.
readShow :: (Read a, Show a) => Iso Partial String a
