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


-- | Better records for State monad states
--   
--   This package provides a Template Haskell function which transforms a
--   normal record declaration into one which supports many useful
--   operations when used as the state in a State monad.
@package state-record
@version 0.0.1

module Data.Record.StateFields

-- | A primitive field descriptor.
data Field c a

-- | Modify the given 'data' or 'newtype' declaration so that all field
--   names are prefixed with an underscore followed by the given string,
--   and generate declarations of field descriptors for all fields, each
--   bound to the corresponding field name prefixed with the given string
--   (but no underscore).
--   
--   Example usage (this goes at the top level of a module):
--   
--   <pre>
--   record "foo" [d| data Foo = Foo { bar :: Int, baz :: Int } |]
--   </pre>
--   
--   Note: the second parameter is Q [Dec] because this is what the [d| |]
--   form returns, which is the most convenient way to use this function.
--   However, the list must contain exactly one declaration, and it must be
--   a 'data' or 'newtype' declaration.
--   
--   Note: in addition to adding the given prefix to each name, the first
--   character of the original name is capitalized.
record :: String -> Q [Dec] -> Q [Dec]

-- | The class of field descriptors. A descriptor of type 'f a b' refers to
--   a field of type <tt>b</tt> nested somewhere within a record of type
--   <tt>a</tt>.
class SomeField f
getField :: SomeField f => f a b -> a -> b
putField :: SomeField f => f a b -> b -> a -> a

-- | Modify the value of a field by applying a function.
modField :: SomeField f => f s a -> (a -> a) -> s -> s

-- | A compound field descriptor.
data FieldPath f g b a c

-- | Join two field descriptors into a compound. <a>//</a> is
--   left-associative with precedence level 9.
(//) :: (SomeField f, SomeField g) => f a b -> g b c -> FieldPath f g b a c

-- | Get the value of a field from the state.
getf :: (MonadState s m, SomeField f) => f s a -> m a

-- | Put a value into a field in the state.
putf :: (MonadState s m, SomeField f) => f s a -> a -> m ()

-- | Modify the value of a field in the state by applying a function.
modf :: (MonadState s m, SomeField f) => f s a -> (a -> a) -> m ()

-- | Enter the context of a field and run a stateful computation there.
enter :: (MonadState s m, SomeField f) => f s a -> State a b -> m b

-- | Like <a>enter</a>, but allows the stateful computation on the field to
--   share the same underlying monad as the enclosing record.
enterT :: (Monad m, SomeField f) => f s a -> StateT a m b -> StateT s m b
instance (SomeField f, SomeField g) => SomeField (FieldPath f g b)
instance SomeField Field