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


-- | Serialization library using Data.Generics
--   
--   GenericSerialize is a library for serialization using the existing
--   generic-programming framework.
--   
--   It is often advocated that support for serialization should be added
--   to the compiler (e.g. in the form of a deriving(Binary)). With this I
--   intend to show that the existing infrastructure is sufficient, and has
--   some advantages over a dedicated serialization interface.
--   
--   The main advantage that generic serialization posseses is that it is
--   possible to simultaneously have several serialization modes. While
--   interfaces such as AltBinary allow writing to any type of stream, the
--   data format is fixed. By contrast, GenericSerialize supports multiple
--   serialization modes; while the only currently existing module is for a
--   subset of R5RS s-expressions, that module is less than 100 lines of
--   code and is almost pure grammar.
@package genericserialize
@version 0.1


-- | This module provides a limited form of stream used by the serializers,
--   and utility functions for using serializers on lists.
module Data.Generics.Serialization.Streams

-- | The class of streams that support write operations. e is the type of
--   elements written.
class (Monad m) => MonadWStream m e | m -> e
putv :: (MonadWStream m e) => [e] -> m ()

-- | An implementation of <a>MonadWStream</a> using difference lists.
data ListBuild e a

-- | Run an action in a <a>MonadWStream</a> to produce a list, using
--   <a>ListBuild</a>.
buildList :: ListBuild e () -> [e]

-- | The class of readable streams.
class (Monad m) => MonadRStream m e | m -> e
getv :: (MonadRStream m e) => m e
peekv :: (MonadRStream m e) => m (Maybe e)

-- | An implementation of <a>MonadRStream</a> using lists.
data ListRead e a

-- | Run an action in a <a>MonadRStream</a> to consume a list, using
--   <a>ListRead</a>.
withList :: ListRead e a -> [e] -> Maybe a
instance MonadRStream (ListRead e) e
instance Monad (ListRead e)
instance MonadWStream (ListBuild e) e
instance Monad (ListBuild e)


-- | This module provides a small number of tricky functions used to
--   implement (de)serializers. User code should not need to import this
--   library.
module Data.Generics.Serialization.Standard

-- | Like <a>ext1Q</a>, except for a binary type constructor
ext2Q :: (Data d, Typeable2 t) => (d -> q) -> (forall d1 d2. (Data d1, Data d2) => t d1 d2 -> q) -> (d -> q)

-- | Run a monadic action over each element in an existing data object;
--   also return the <a>Constr</a>.
gSerial :: (Data d, MonadWStream m c) => (forall a. (Data a) => a -> m ()) -> d -> (Constr, m ())

-- | Build an object using monadic actions to read the <a>Constr</a> and
--   all children.
gDeser :: (Data d, Monad m) => (DataType -> m Constr) -> (forall a. (Data a) => m a) -> m d

-- | Execute two monadic actions in sequence, returning the value of the
--   first. This is mainly useful with parser combinators.
(=>>) :: (Monad m) => m a -> m b -> m a

-- | Execute a monadic action, piping the result through a pure function.
--   This is the same as flip liftM, and has the same fixity as
--   <a>&gt;&gt;=</a>.
(>>$) :: (Monad m) => m a -> (a -> b) -> m b

-- | Run a monadic action repeatedly until it returns <a>Nothing</a>; all
--   <a>Just</a> values are returned in a list.
unfoldM :: (Monad m) => m (Maybe a) -> m [a]

-- | Parse a designated character, error on a different character.
match :: (MonadRStream m Char) => Char -> m ()

-- | Parse and return one or more characters parsed using a recognition
--   function.
manySat :: (MonadRStream m a) => (a -> Bool) -> m [a]

-- | Match a string, error on discrepancy.
matchs :: (MonadRStream m Char) => [Char] -> m ()

-- | Get one character, then run a parser (e.g. space).
getv_t :: (MonadRStream m a) => m b -> m a

-- | Get one character and process it using a list of actions.
getcase :: (Eq a, MonadRStream m a) => (a -> m b) -> [(a, m b)] -> m b

-- | Peek at one character and process it using a list of actions.
peekcase :: (Eq a, MonadRStream m a) => m b -> (a -> m b) -> [(a, m b)] -> m b

-- | Parse a designated character, then any amount of whitespace.
matchws :: (MonadRStream m Char) => Char -> m ()

-- | Parse as many spaces as possible.
space :: (MonadRStream m Char) => m ()

-- | Parse a value using a <a>Read</a> instance. This differs from
--   <a>read</a> in that it uses a general monad and type infromation for
--   error reporting.
readM :: (Monad m, Read a, Typeable a) => String -> m a

-- | Convert a <a>Maybe</a> object into any monad, using the imbedding
--   defined by fail and return.
fromMaybeM :: (Monad m) => String -> Maybe a -> m a

-- | Escape a string.
escape :: Char -> [Char] -> [Char] -> String -> String

-- | Unescape a string.
unescape :: Char -> [Char] -> [Char] -> String -> Maybe String

-- | Create an escape and unescape function at the same time. This allows
--   you to only type the translations once.
mkescape :: Char -> [Char] -> [Char] -> (String -> String, String -> Maybe String)

-- | Split a string at the rightmost occurence of a character matching a
--   predicate.
breakr :: (a -> Bool) -> [a] -> ([a], [a])


-- | This module implements serialization to/from a subset of R5RS
--   s-expressions. Several limitations currently exist:
--   
--   <ul>
--   <li>Vectors are not recognized or generated.</li>
--   <li>(Quasi)quote notation is not supported.</li>
--   <li>Constructor names are parsed case-sensitively.</li>
--   </ul>
module Data.Generics.Serialization.SExp

-- | Serialize an arbitrary value to an s-expression.
sexpSerialize :: (Data a, MonadWStream m Char) => a -> m ()

-- | Deserialize an arbitrary value from an s-expression.
sexpDeserialize :: (Data a, MonadRStream m Char) => m a
instance Show SNumber