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

-- | Utilities for accessing and manipulating fields of records
--   
--   In Haskell 98 the name of a record field is automatically also the
--   name of a function which gets the value of the according field. E.g.
--   if we have
--   
--   data Pair a b = Pair {first :: a, second :: b}
--   
--   then
--   
--   
--   first  :: Pair a b -> a
--   second :: Pair a b -> b
--   
--   
--   However for setting or modifying a field value we need to use some
--   syntactic sugar, which is often clumsy.
--   
--   
--   modifyFirst :: (a -> a) -> (Pair a b -> Pair a b)
--   modifyFirst f r@(Pair{first=a}) = r{first = f a}
--   
--   
--   With this package you can define record field accessors which allow
--   setting, getting and modifying values easily. The package clearly
--   demonstrates the power of the functional approach: You can combine
--   accessors of a record and sub-records, to make the access look like
--   the fields of the sub-record belong to the main record.
--   
--   Example:
--   
--   
--   *Data.Accessor.Example> (first^:second^=10) (('b',7),"hallo")
--   (('b',10),"hallo")
--   
--   
--   You can easily manipulate record fields in a
--   Control.Monad.State.State monad, you can easily code
--   Show instances that use the Accessor syntax and you can parse
--   binary streams into records. See Data.Accessor.Example for
--   demonstration of all features.
--   
--   It would be great if in revised Haskell versions the names of record
--   fields are automatically Data.Accessor.Accessors rather than
--   plain get functions. For now, the package
--   data-accessor-template provides Template Haskell functions
--   for automated generation of Data.Acesssor.Accessors. See also
--   the other data-accessor packages that provide an Accessor
--   interface to other data types. The package enumset provides
--   accessors to bit-packed records.
--   
--   For similar packages see lenses and fclabel. A
--   related concept are editors
--   http://conal.net/blog/posts/semantic-editor-combinators/.
--   Editors only consist of a modify method (and modify applied
--   to a const function is a set function). This way, they
--   can modify all function values of a function at once, whereas an
--   accessor can only change a single function value, say, it can change
--   f 0 = 1 to f 0 = 2. This way, editors can even
--   change the type of a record or a function. An Arrow instance can be
--   defined for editors, but for accessors only a Category instance is
--   possible ((.) method). The reason is the arr method of
--   the Arrow class, that conflicts with the two-way nature (set
--   and get) of accessors.
@package data-accessor
@version 0.2.3.1

-- | This module defines the Accessor type. It should be imported
--   with qualification.
module Data.Accessor.Basic

-- | The accessor function we use, has a record value as first argument and
--   returns the content of a specific record field and a function that
--   allows to overwrite that field with a new value.
--   
--   In former version of a package we used a function that resembled the
--   state monad. However this required to use an undefined in the
--   implementation of the get function.
data T r a
fromSetGet :: (a -> r -> r) -> (r -> a) -> T r a
fromLens :: (r -> (a, a -> r)) -> T r a

-- | If an object is wrapped in a newtype, you can generate an
--   Accessor to the unwrapped data by providing a wrapper and an
--   unwrapper function. The set function is simpler in this case, since no
--   existing data must be kept. Since the information content of the
--   wrapped and unwrapped data is equivalent, you can swap wrapper and
--   unwrapper. This way you can construct an Accessor that treats
--   a record field containing an unwrapped object like a field containing
--   a wrapped object.
--   
--   
--   newtype A = A {unA :: Int}
--   
--   access :: Accessor.T A Int
--   access = fromWrapper A unA
--   
--   
--   We could also have called this function fromBijection, since
--   it must hold wrap . unwrap = id and unwrap . wrap =
--   id.
fromWrapper :: (b -> a) -> (a -> b) -> T a b

-- | Access the record itself
self :: T r r

-- | Access a (non-existing) element of type ()
null :: T r ()

-- | result a accesses the value of a function for argument
--   a. It is not very efficient to build a function from setting
--   all of its values using this accessor, since every access to a
--   function adds another if-then-else.
--   
--   Also see semantic editor combinators, that allow to modify all
--   function values of a function at once. Cf.
--   http://conal.net/blog/posts/semantic-editor-combinators/
result :: Eq a => a -> T (a -> b) b

-- | Set the value of a field.
set :: T r a -> a -> r -> r

-- | set as infix operator. This lets us write first ^= 2+3 $
--   second ^= 5+7 $ record.
(^=) :: T r a -> a -> r -> r
infixr 5 ^=

-- | This is a general function, but it is especially useful for setting
--   many values of different type at once.
compose :: [r -> r] -> r -> r

-- | Get the value of a field.
get :: T r a -> r -> a

-- | get as infix operator. This lets us write
--   record^.field^.subfield. This imitates Modula II syntax.
(^.) :: r -> T r a -> a
infixl 8 ^.

-- | Transform the value of a field by a function.
modify :: T r a -> (a -> a) -> r -> r

-- | modify as infix operator. This lets us write
--   field^:subfield^:(2*) $ record,
--   record$%field^:subfield^:(2*) or
--   record$%field^:subfield^:(const 1).
(^:) :: T r a -> (a -> a) -> r -> r
infixr 5 ^:

-- | Accessor composition: Combine an accessor with an accessor to a
--   sub-field. Speak "stack".
(.>) :: T a b -> T b c -> T a c
infixl 9 .>

-- | Accessor composition the other direction.
--   
--   
--   (<.) = flip (.>)
--   
--   
--   You may also use the (.) operator from Category class.
(<.) :: T b c -> T a b -> T a c
infixr 9 <.

-- | Flipped version of ($).
($%) :: a -> (a -> b) -> b
infixl 0 $%

-- | Merge the accessors to two independent fields.
--   
--   Independency means, it must hold:
--   
--   
--   set (merge accA accB) (a,b) = set (merge accB accA) (b,a)
--   
--   
--   You may construct smart accessors by composing a merged accessor with
--   a fromWrapper accessor.
--   
--   This is a special case of the more general Point concept in
--   the package fclabels.
merge :: T a b -> T a c -> T a (b, c)

-- | Access helper functions in a State monad

-- | Deprecated: please use Data.Accessor.Monad.Trans.State from
--   data-accessor-transformers
module Data.Accessor.MonadState
get :: forall (m :: Type -> Type) r a. Monad m => T r a -> StateT r m a
lift :: forall (m :: Type -> Type) r s a. Monad m => T r s -> State s a -> StateT r m a
modify :: forall (m :: Type -> Type) r a. Monad m => T r a -> (a -> a) -> StateT r m ()

-- | Infix variant of set.
(%=) :: forall (m :: Type -> Type) r a. Monad m => T r a -> a -> StateT r m ()
infix 1 %=

-- | Infix variant of modify.
(%:) :: forall (m :: Type -> Type) r a. Monad m => T r a -> (a -> a) -> StateT r m ()
infix 1 %:
set :: forall (m :: Type -> Type) r a. Monad m => T r a -> a -> StateT r m ()

-- | Modify a record element and return its old value.
getAndModify :: forall (m :: Type -> Type) r a. Monad m => T r a -> (a -> a) -> StateT r m a

-- | Modify a record element and return its new value.
modifyAndGet :: forall (m :: Type -> Type) r a. Monad m => T r a -> (a -> a) -> StateT r m a
liftT :: forall (m :: Type -> Type) r s a. Monad m => T r s -> StateT s m a -> StateT r m a

-- | This module allows to access elements of arrays, sets and finite maps
--   like elements of records. This is especially useful for working with
--   nested structures consisting of arrays, sets, maps and records.
--   
--   Maybe we should move it to a separate package, then we would not need
--   to import array and containers package.
module Data.Accessor.Container
array :: Ix i => i -> T (Array i e) e

-- | Treat a Set like a boolean array.
set :: Ord a => a -> T (Set a) Bool

-- | Treats a finite map like an infinite map, where all undefined elements
--   are replaced by a default value.
mapDefault :: Ord key => elem -> key -> T (Map key elem) elem

-- | Treats a finite map like an infinite map, where all undefined elements
--   are Nothing and defined elements are Just.
mapMaybe :: Ord key => key -> T (Map key elem) (Maybe elem)
intMapDefault :: elem -> Int -> T (IntMap elem) elem
intMapMaybe :: Int -> T (IntMap elem) (Maybe elem)

-- | Reading records from streams
--   
--   This is still only for demonstration and might be of not much use and
--   you should not rely on the interface.
module Data.Accessor.BinaryRead
type Stream = [Word8]
class C a
any :: (C a, ByteSource source) => source a
class Monad source => ByteSource (source :: Type -> Type)
readWord8 :: ByteSource source => source Word8
class ByteStream s
getWord8 :: (ByteStream s, MonadFail m) => s -> m (Word8, s)
class ByteCompatible byte
toByte :: ByteCompatible byte => byte -> Word8
newtype Parser s r
Parser :: ((r, s) -> Maybe (r, s)) -> Parser s r
[runParser] :: Parser s r -> (r, s) -> Maybe (r, s)
field :: (ByteStream s, C a) => T r a -> Parser s r
record :: [Parser s r] -> Parser s r
instance Data.Accessor.BinaryRead.C GHC.Types.Char
instance Data.Accessor.BinaryRead.C GHC.Types.Int
instance Data.Accessor.BinaryRead.C GHC.Internal.Word.Word8

-- | This module provides a simple abstract data type for a piece of a data
--   stucture that can be read from and written to. In contrast to
--   Data.Accessor.Basic it is intended for unqualified import.
module Data.Accessor

-- | An Accessor r a is an object that encodes how to get and put
--   a subject of type a out of/into an object of type s.
--   
--   In order for an instance of this data structure a to be an
--   Accessor, it must obey the following laws:
--   
--   
--   getVal a (setVal a x r) = x
--   setVal a (getVal a r) r = r
--   
type Accessor r a = T r a

-- | Construct an Accessor from a get and a set
--   method.
accessor :: (r -> a) -> (a -> r -> r) -> Accessor r a

-- | Set a value of a record field that is specified by an Accessor
setVal :: Accessor r a -> a -> r -> r

-- | set as infix operator. This lets us write first ^= 2+3 $
--   second ^= 5+7 $ record.
(^=) :: T r a -> a -> r -> r
infixr 5 ^=

-- | Get a value from a record field that is specified by an Accessor
getVal :: Accessor r a -> r -> a

-- | get as infix operator. This lets us write
--   record^.field^.subfield. This imitates Modula II syntax.
(^.) :: r -> T r a -> a
infixl 8 ^.

-- | modify as infix operator. This lets us write
--   field^:subfield^:(2*) $ record,
--   record$%field^:subfield^:(2*) or
--   record$%field^:subfield^:(const 1).
(^:) :: T r a -> (a -> a) -> r -> r
infixr 5 ^:

-- | A structural dereference function for state monads.

-- | Deprecated: Data.Accessor.Monad.Trans.State.get from
--   data-accessor-transformers package
getA :: forall (m :: Type -> Type) r a. Monad m => Accessor r a -> StateT r m a

-- | A structural assignment function for state monads.

-- | Deprecated: Data.Accessor.Monad.Trans.State.set from
--   data-accessor-transformers package
putA :: forall (m :: Type -> Type) r a. Monad m => Accessor r a -> a -> StateT r m ()

-- | An "assignment operator" for state monads.
--   
--   
--   (=:) = putA
--   

-- | Deprecated: use (Data.Accessor.Monad.Trans.State.%=) from
--   data-accessor-transformers package
(=:) :: forall (m :: Type -> Type) r a. Monad m => Accessor r a -> a -> StateT r m ()
infix 1 =:

-- | Infix variant of set.
(%=) :: forall (m :: Type -> Type) r a. Monad m => T r a -> a -> StateT r m ()
infix 1 %=

-- | A structural modification function for state monads.

-- | Deprecated: Data.Accessor.Monad.Trans.State.modify from
--   data-accessor-transformers package
modA :: forall (m :: Type -> Type) r a. Monad m => Accessor r a -> (a -> a) -> StateT r m ()

-- | Infix variant of modify.
(%:) :: forall (m :: Type -> Type) r a. Monad m => T r a -> (a -> a) -> StateT r m ()
infix 1 %:

-- | Accessor composition: Combine an accessor with an accessor to a
--   sub-field. Speak "stack".
(.>) :: Accessor a b -> Accessor b c -> Accessor a c
infixl 9 .>

-- | Accessor composition the other direction.
--   
--   
--   (<.) = flip (.>)
--   
--   
--   You may also use the (.) operator from Category class.
(<.) :: Accessor b c -> Accessor a b -> Accessor a c
infixr 9 <.

-- | Support for creating Show instances using the accessors.
module Data.Accessor.Show
field :: (Show a, Eq a) => String -> T r a -> r -> r -> Maybe ShowS
showsPrec :: [r -> r -> Maybe ShowS] -> String -> r -> Int -> r -> ShowS

module Data.Accessor.Tuple

-- | Access to the first value of a pair.
first :: T (a, b) a

-- | Access to the second value of a pair.
second :: T (a, b) b

-- | Access to the first value of a triple.
first3 :: T (a, b, c) a

-- | Access to the second value of a triple.
second3 :: T (a, b, c) b

-- | Access to the third value of a triple.
third3 :: T (a, b, c) c
