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


-- | Automatically generate composable accessors for data types.
--   
--   This module provides a simple abstract data type for a piece of a data
--   stucture that can be read from and written to. It provides an
--   automatic Template Haskell routine to scour data type definitions and
--   generate accessor objects for them automatically.
@package data-accessor
@version 0.0.1


-- | This module provides a simple abstract data type for a piece of a data
--   stucture that can be read from and written to. It provides an
--   automatic Template Haskell routine to scour data type definitions and
--   generate accessor objects for them automatically.
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>
data Accessor s a
Accessor :: (s -> a) -> (a -> s -> s) -> Accessor s a
getVal :: Accessor s a -> s -> a
setVal :: Accessor s a -> a -> s -> s

-- | <tt>nameDeriveAccessors n f</tt> where <tt>n</tt> is the name of a
--   data type declared with <tt>data</tt> and <tt>f</tt> is a function
--   from names of fields in that data type to the name of the
--   corresponding accessor. If <tt>f</tt> returns <tt>Nothing</tt>, then
--   no accessor is generated for that field.
nameDeriveAccessors :: Name -> (String -> Maybe String) -> Q [Dec]

-- | <tt>deriveAccessors n</tt> where <tt>n</tt> is the name of a data type
--   declared with <tt>data</tt> looks through all the declared fields of
--   the data type, and for each field ending in an underscore generates an
--   accessor of the same name without the underscore.
--   
--   It is <a>nameDeriveAccessors</a> n f where <tt>f</tt> satisfies
--   
--   <pre>
--   f (s ++ "_") = Just s
--   f x          = x       -- otherwise
--   </pre>
--   
--   For example, given the data type:
--   
--   <pre>
--   data Score = Score { p1Score_ :: Int
--                      , p2Score_ :: Int
--                      , rounds   :: Int
--                      }
--   </pre>
--   
--   <tt>deriveAccessors</tt> will generate the following objects:
--   
--   <pre>
--   p1Score :: Accessor Score Int
--   p1Score = Accessor p1Score_ (\x s -&gt; s { p1Score_ = x })
--   p2Score :: Accessor Score Int
--   p2Score = Accessor p2Score_ (\x s -&gt; s { p2Score_ = x })
--   </pre>
deriveAccessors :: Name -> Q [Dec]

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

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

-- | Accessor composition.
(.>) :: 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

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