-- 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
--   
--   <pre>
--   first  :: Pair a b -&gt; a
--   second :: Pair a b -&gt; b
--   </pre>
--   
--   However for setting or modifying a field value we need to use some
--   syntactic sugar, which is often clumsy.
--   
--   modifyFirst :: (a -&gt; a) -&gt; (Pair a b -&gt; 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:
--   
--   <pre>
--   *Data.Accessor.Example&gt; (first^:second^=10) (('b',7),"hallo")
--   (('b',10),"hallo")
--   </pre>
--   
--   You can easily manipulate record fields in a
--   <a>Control.Monad.State.State</a> monad, you can easily code Show
--   instances that use the Accessor syntax and you can parse binary
--   streams into records. See <tt>Data.Accessor.Example</tt> for
--   demonstration of all features.
--   
--   It would be great if in revised Haskell versions the names of record
--   fields are automatically <a>Data.Accessor.Accessor</a>s rather than
--   plain <tt>get</tt> functions. The package
--   <tt>data-accessor-template</tt> provides Template Haskell functions
--   for automated generation of <a>Data.Acesssor.Accessor</a>s.
@package data-accessor
@version 0.2.0.2


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

-- | The access functions we propose, look very similar to those needed for
--   List.mapAccumL (but parameter order is swapped) and State monad. They
--   get the new value of the field and the record and return the old value
--   of the field and the record with the updated field.
data T r a
fromSetGet :: (a -> r -> r) -> (r -> a) -> T r a
fromLens :: (r -> (a, a -> r)) -> T r a

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

-- | Access a (non-existing) element of type <tt>()</tt>
null :: T r ()

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

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

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

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

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

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

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

-- | Accessor composition the other direction.
--   
--   <pre>
--   (&lt;.) = flip (.&gt;)
--   </pre>
(<.) :: T b c -> T a b -> T a c

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


-- | Access helper functions in a State monad
module Data.Accessor.MonadState
set :: (Monad m) => T r a -> a -> StateT r m ()
get :: (Monad m) => T r a -> StateT r m a
modify :: (Monad m) => T r a -> (a -> a) -> StateT r m ()

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

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

-- | Infix variant of <a>set</a>.
(%=) :: (Monad m) => T r a -> a -> StateT r m ()

-- | Infix variant of <a>modify</a>.
(%:) :: (Monad m) => T r a -> (a -> a) -> StateT r m ()
lift :: (Monad m) => T r s -> State s a -> StateT r m a
liftT :: (Monad m) => T r s -> StateT s m a -> StateT r m a


-- | This module allows to access elements of arrays and finite maps like
--   elements of records. This is especially useful for working with nested
--   structures consisting of arrays, maps and records.
module Data.Accessor.Container
array :: (Ix i) => i -> T (Array i e) e

-- | 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 <a>Nothing</a> and defined elements are <a>Just</a>.
mapMaybe :: (Ord key) => key -> T (Map key elem) (Maybe elem)
intMapDefault :: elem -> Int -> T (IntMap elem) elem
intMapMaybe :: Int -> T (IntMap elem) (Maybe elem)


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


-- | 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
readWord8 :: (ByteSource source) => source Word8
class ByteStream s
getWord8 :: (ByteStream s, Monad 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 C Int
instance C Char
instance C Word8
instance (ByteStream s, Monad m) => ByteSource (StateT s m)
instance ByteCompatible Word8
instance (ByteCompatible byte) => ByteStream [byte]


-- | 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
--   <a>Data.Accessor.Basic</a> it is intended for unqualified import.
module Data.Accessor

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

-- | Construct an <a>Accessor</a> from a <tt>get</tt> and a <tt>set</tt>
--   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

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

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

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

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

-- | A structural dereference function for state monads.
getA :: (Monad m) => Accessor r a -> StateT r m a

-- | A structural assignment function for state monads.
putA :: (Monad m) => Accessor r a -> a -> StateT r m ()

-- | An "assignment operator" for state monads.
--   
--   <pre>
--   (=:) = putA
--   </pre>
(=:) :: (Monad m) => Accessor r a -> a -> StateT r m ()

-- | Infix variant of <a>set</a>.
(%=) :: (Monad m) => T r a -> a -> StateT r m ()

-- | A structural modification function for state monads.
modA :: (Monad m) => Accessor r a -> (a -> a) -> StateT r m ()

-- | Infix variant of <a>modify</a>.
(%:) :: (Monad m) => T r a -> (a -> a) -> StateT r m ()

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

-- | Accessor composition the other direction.
--   
--   <pre>
--   (&lt;.) = flip (.&gt;)
--   </pre>
(<.) :: Accessor b c -> Accessor a b -> Accessor a c