-- 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
--   <a>Show</a> 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. For now, the package
--   <tt>data-accessor-template</tt> provides Template Haskell functions
--   for automated generation of <a>Data.Acesssor.Accessor</a>s. See also
--   the other <tt>data-accessor</tt> packages that provide an Accessor
--   interface to other data types. The package <tt>enumset</tt> provides
--   accessors to bit-packed records.
--   
--   For similar packages see <tt>lenses</tt> and <tt>fclabel</tt>. A
--   related concept are editors
--   <a>http://conal.net/blog/posts/semantic-editor-combinators/</a>.
--   Editors only consist of a modify method (and <tt>modify</tt> applied
--   to a <a>const</a> function is a <tt>set</tt> 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
--   <tt>f 0 = 1</tt> to <tt>f 0 = 2</tt>. 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 <tt>arr</tt> method of the
--   <tt>Arrow</tt> class, that conflicts with the two-way nature (set and
--   get) of accessors.
@package data-accessor
@version 0.2.2.7


-- | This module defines the <tt>Accessor</tt> 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 <a>undefined</a> in the
--   implementation of the <tt>get</tt> 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 <tt>newtype</tt>, you can generate an
--   <tt>Accessor</tt> 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 <tt>Accessor</tt> that treats
--   a record field containing an unwrapped object like a field containing
--   a wrapped object.
--   
--   <pre>
--   newtype A = A {unA :: Int}
--   
--   access :: Accessor.T A Int
--   access = fromWrapper A unA
--   </pre>
--   
--   We could also have called this function <tt>fromBijection</tt>, since
--   it must hold <tt>wrap . unwrap = id</tt> and <tt>unwrap . wrap =
--   id</tt>.
fromWrapper :: (b -> a) -> (a -> b) -> T a b

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

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

-- | <tt>result a</tt> accesses the value of a function for argument
--   <tt>a</tt>. 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 <tt>if-then-else</tt>.
--   
--   Also see semantic editor combinators, that allow to modify all
--   function values of a function at once. Cf.
--   <a>http://conal.net/blog/posts/semantic-editor-combinators/</a>
result :: Eq a => a -> T (a -> b) b

-- | 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>
--   
--   You may also use the <tt>(.)</tt> operator from Category class.
(<.) :: T b c -> T a b -> T a c

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

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


-- | Access helper functions in a State monad

-- | <i>Deprecated: please use Data.Accessor.Monad.Trans.State from
--   data-accessor-transformers</i>
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, 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 <tt>array</tt> and <tt>containers</tt> 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 <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 Data.Accessor.BinaryRead.ByteCompatible byte => Data.Accessor.BinaryRead.ByteStream [byte]
instance Data.Accessor.BinaryRead.ByteCompatible GHC.Word.Word8
instance (Data.Accessor.BinaryRead.ByteStream s, GHC.Base.Monad m) => Data.Accessor.BinaryRead.ByteSource (Control.Monad.Trans.State.Lazy.StateT s m)
instance Data.Accessor.BinaryRead.C GHC.Word.Word8
instance Data.Accessor.BinaryRead.C GHC.Types.Char
instance Data.Accessor.BinaryRead.C GHC.Types.Int


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

-- | <i>Deprecated: Data.Accessor.Monad.Trans.State.get from
--   data-accessor-transformers package</i>
getA :: Monad m => Accessor r a -> StateT r m a

-- | A structural assignment function for state monads.

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

-- | An "assignment operator" for state monads.
--   
--   <pre>
--   (=:) = putA
--   </pre>

-- | <i>Deprecated: use (Data.Accessor.Monad.Trans.State.%=) from
--   data-accessor-transformers package</i>
(=:) :: 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.

-- | <i>Deprecated: Data.Accessor.Monad.Trans.State.modify from
--   data-accessor-transformers package</i>
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>
--   
--   You may also use the <tt>(.)</tt> operator from Category class.
(<.) :: Accessor b c -> Accessor a b -> Accessor a c