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


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

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

-- | Set many fields at once.
--   
--   This function could also be used for initialisation of record, if
--   record value with undefined fields is provided.
--   
--   Drawback: Since all types in a list must have the same type, you can
--   set only values of the same type.
setMany :: [r -> (a, r)] -> 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

-- | <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 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>
(^.) :: 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>record$%field^:subfield^:(1+)</tt> or
--   <tt>record$%field^:subfield^:(const 1)</tt>.
(^:) :: T r a -> (a -> a) -> (r -> r)

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

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

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


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


-- | Support for creating Show instances using the accessors.
module Data.Accessor.Show
toMaybe :: Bool -> a -> Maybe a
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 s 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 s) = x
--   setVal a (getVal a s) s = s
--   </pre>
type Accessor s a = T s a

-- | Construct an <a>Accessor</a> from a <tt>get</tt> and a <tt>set</tt>
--   method.
accessor :: (s -> a) -> (a -> s -> s) -> Accessor s a

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

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

-- | A structural dereference function for state monads.
getA :: (MonadState s m) => Accessor s a -> m a

-- | A structural assignment function for state monads.
putA :: (MonadState s m) => Accessor s a -> a -> m ()

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

-- | A structural modification function for state monads.
modA :: (MonadState s m) => Accessor s a -> (a -> a) -> 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