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


-- | First class accessor labels.
--   
--   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.
--   
--   See <a>Data.Label</a> for an introductory explanation.
--   
--   Internally lenses are not tied to Haskell functions directly, but are
--   implemented as arrows. Arrows 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 the <a>Data.Label.Maybe</a> module for the use of partial labels.
--   
--   <pre>
--   1.1.4.2 -&gt; 1.1.4.3
--     - Make compilable against template haskell 2.8.
--       Thanks to mgsloan for the pull request.
--   </pre>
@package fclabels
@version 1.1.4.3

module Data.Label.Abstract

-- | Abstract Point datatype. The getter and setter functions work in some
--   arrow.
data Point arr f i o
Point :: f arr o -> (i, f) arr f -> Point arr f i o
_get :: Point arr f i o -> f arr o
_set :: Point arr f i o -> (i, f) arr f

-- | Modification as a compositon of a getter and setter. Unfortunately,
--   <a>ArrowApply</a> is needed for this composition.
_modify :: ArrowApply arr => Point arr f i o -> (o arr i, f) arr f

-- | Abstract Lens datatype. The getter and setter functions work in some
--   arrow. Arrows allow for effectful lenses, for example, lenses that
--   might fail or use state.
newtype Lens arr f a
Lens :: Point arr f a a -> Lens arr f a
unLens :: Lens arr f a -> Point arr f a a

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

-- | Get the getter arrow from a lens.
get :: Arrow arr => Lens arr f a -> f arr a

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

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

-- | Make a <a>Point</a> diverge in two directions.
bimap :: Arrow arr => (o' arr o) -> (i arr i') -> Point arr f i' o' -> Point arr f i o
for :: Arrow arr => (i arr o) -> Lens arr f o -> Point arr f i o

-- | The bijections datatype, an arrow that works in two directions.
data Bijection arr a b
Bij :: a arr b -> b arr a -> Bijection arr a b
fw :: Bijection arr a b -> a arr b
bw :: Bijection arr a b -> b arr a

-- | Lifting <a>Bijection</a>s.
liftBij :: Functor f => Bijection (->) a b -> Bijection (->) (f a) (f b)

-- | The isomorphism type class is like a <a>Functor</a> but works in two
--   directions.
class Iso arr f
iso :: Iso arr f => Bijection arr a b -> f a arr f b

-- | Flipped isomorphism.
osi :: Iso arr f => Bijection arr b a -> f a arr f b
instance Arrow arr => Iso arr (Bijection arr a)
instance Arrow arr => Iso arr (Lens arr f)
instance Category arr => Category (Bijection arr)
instance Arrow arr => Applicative (Point arr f i)
instance Arrow arr => Functor (Point arr f i)
instance ArrowApply arr => Category (Lens arr)

module Data.Label.Pure

-- | Pure lens type specialized for pure accessor functions.
type (:->) f a = PureLens f a

-- | Create a pure lens from a getter and a setter.
--   
--   We expect the following law to hold:
--   
--   <pre>
--   get l (set l a f) == a
--   </pre>
--   
--   Or, equivalently:
--   
--   <pre>
--   set l (get l f) f == f
--   </pre>
lens :: (f -> a) -> (a -> f -> f) -> f :-> a

-- | Getter for a pure lens.
get :: (f :-> a) -> f -> a

-- | Setter for a pure lens.
set :: (f :-> a) -> a -> f -> f

-- | Modifier for a pure lens.
modify :: (f :-> a) -> (a -> a) -> f -> f

module Data.Label.PureM

-- | Get a value out of the state, pointed to by the specified lens.
gets :: MonadState s m => s :-> a -> m a

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

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

-- | Alias for <a>puts</a> that reads like an assignment.
(=:) :: MonadState s m => s :-> a -> a -> m ()

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

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

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

module Data.Label.Maybe

-- | Lens type for situations in which the accessor functions can fail.
--   This is useful, for example, when accessing fields in datatypes with
--   multiple constructors.
type (:~>) f a = MaybeLens f a

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

-- | 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 :~> a) -> f -> Maybe a

-- | 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 :~> a -> a -> f -> Maybe f

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

-- | 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 :~> a) -> (a -> a) -> f -> Maybe f

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

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

module Data.Label.MaybeM

-- | Get a value out of state, pointed to by the specified lens that might
--   fail. When the lens getter fails this computation will fall back to
--   <a>mzero</a>.
gets :: (MonadState f m, MonadPlus m) => (f :~> a) -> m a

-- | Fetch a value, pointed to by a lens that might fail, out of a reader
--   environment. When the lens getter fails this computation will fall
--   back to <a>mzero</a>.
asks :: (MonadReader f m, MonadPlus m) => (f :~> a) -> m a


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

-- | Pure lens type specialized for pure accessor functions.
type (:->) f a = PureLens f a

-- | Create a pure lens from a getter and a setter.
--   
--   We expect the following law to hold:
--   
--   <pre>
--   get l (set l a f) == a
--   </pre>
--   
--   Or, equivalently:
--   
--   <pre>
--   set l (get l f) f == f
--   </pre>
lens :: (f -> a) -> (a -> f -> f) -> f :-> a

-- | Getter for a pure lens.
get :: (f :-> a) -> f -> a

-- | Setter for a pure lens.
set :: (f :-> a) -> a -> f -> f

-- | Modifier for a pure lens.
modify :: (f :-> a) -> (a -> a) -> f -> f

-- | Abstract Lens datatype. The getter and setter functions work in some
--   arrow. Arrows allow for effectful lenses, for example, lenses that
--   might fail or use state.
newtype Lens arr f a
Lens :: Point arr f a a -> Lens arr f a

-- | The bijections datatype, an arrow that works in two directions.
data Bijection arr a b
Bij :: a arr b -> b arr a -> Bijection arr a b
fw :: Bijection arr a b -> a arr b
bw :: Bijection arr a b -> b arr a

-- | The isomorphism type class is like a <a>Functor</a> but works in two
--   directions.
class Iso arr f
iso :: Iso arr f => Bijection arr a b -> f a arr f b
for :: Arrow arr => (i arr o) -> Lens arr f o -> Point arr f i o

-- | Derive lenses 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 lenses 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]

-- | Generate the label name from the record field name. For instance,
--   <tt>drop 1 . dropWhile (/='_')</tt> creates a label <tt>val</tt> from
--   a record <tt>Rec { rec_val :: X }</tt>.
mkLabelsWith :: (String -> String) -> [Name] -> Q [Dec]

-- | Derive lenses including type signatures for all the record selectors
--   in a datatype. The signatures will be concrete and can only be used in
--   the appropriate context.
mkLabelsMono :: [Name] -> Q [Dec]

-- | Derive lenses without type signatures for all the record selectors in
--   a datatype.
mkLabelsNoTypes :: [Name] -> Q [Dec]
