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


-- | Serialization of data structures with references.
--   
--   Serialization of data structures with references.
@package graph-serialize
@version 0.1


-- | This module provides a way to serialize graph-like structures into
--   lazy <a>ByteString</a>s. Graph-like structures here are structures
--   that may reference other locations in the resulting output. The
--   references are serialized as relative byte offsets.
--   
--   A simple example:
--   
--   <pre>
--   test1 :: [Word8]
--   test1 =
--     L.unpack $ toLazyByteString id $ do
--       r &lt;- <a>newRegion</a>
--       l1 &lt;- <a>label</a> r
--       <tt>emit</tt> r (42 :: Word32)
--       <a>reference</a> S4 LE r l1
--       emit r (43 :: Word32)
--   
--   test1 == [42,0,0,0,252,255,255,255,43,0,0,0]
--   </pre>
module Data.Serialize.References

-- | Monad for constructing the serialised structure.
data BuildM a

-- | Serialise the graph into a lazy <a>ByteString</a>.
toLazyByteString :: ([Region] -> [Region]) -> BuildM () -> ByteString

-- | A logical section of the data stream.
data Region

-- | Create a new region.
newRegion :: BuildM Region

-- | A location in the data stream.
data Label

-- | Emit a label at the current location in the given region.
label :: Region -> BuildM Label

-- | Create a new label (with no location attached to it).
--   
--   It is up to the user to ensure that if this label is ever used in a
--   <a>reference</a>, then the label must have been placed via
--   <a>placeLabel</a>.
--   
--   This is intended for forward references within a region:
--   
--   <pre>
--   example r = do
--    l &lt;- makeLabel
--    reference S4 Host r l
--    ... more stuff ...
--    placeLabel r l
--    ... other stuff ...
--   </pre>
makeLabel :: BuildM Label

-- | Place a label previously created with <a>makeLabel</a>.
--   
--   This function must only be called once per label. If the same label is
--   placed multiple times, it is undefined where references to it point
--   to.
placeLabel :: Region -> Label -> BuildM ()

-- | Emit a reference to the given label in the current region.
--   
--   The reference will be encoded as a signed integer that specifies the
--   relative distance (in bytes) from the current location to the target
--   label.
--   
--   The current location starts before the reference. A serialised
--   reference with value <tt>0</tt> therefore refers to itself.
--   
--   It is up to the user to ensure that references are large enough to
--   encode the required range. If they are not in range
--   <a>toLazyByteString</a> will fail.
reference :: Size -> ByteOrder -> Region -> Label -> BuildM ()

-- | The size of a reference (1, 2, 4, or 8 bytes).
data Size

-- | Translate <a>Size</a> into matching number of bytes.
sizeToBytes :: Size -> Int

-- | The byte ordering to be used when serializing a reference.
data ByteOrder

-- | Emit a single byte.
emitWord8 :: Region -> Word8 -> BuildM ()

-- | Emit a list of bytes.
emitWord8s :: Region -> [Word8] -> BuildM ()

-- | Emit a <a>Word16</a> in little endian format.
emitWord16le :: Region -> Word16 -> BuildM ()

-- | Emit a <a>Word16</a> in big endian format.
emitWord16be :: Region -> Word16 -> BuildM ()

-- | Emit a <a>Word16</a> in native host order and host endianness.
emitWord16host :: Region -> Word16 -> BuildM ()

-- | Emit a <a>Word32</a> in little endian format.
emitWord32le :: Region -> Word32 -> BuildM ()

-- | Emit a <a>Word32</a> in big endian format.
emitWord32be :: Region -> Word32 -> BuildM ()

-- | Emit a <a>Word32</a> in native host order and host endianness.
emitWord32host :: Region -> Word32 -> BuildM ()

-- | Emit a <a>Word64</a> in little endian format.
emitWord64le :: Region -> Word64 -> BuildM ()

-- | Emit a <a>Word64</a> in big endian format.
emitWord64be :: Region -> Word64 -> BuildM ()

-- | Emit a <a>Word64</a> in native host order and host endianness.
emitWord64host :: Region -> Word64 -> BuildM ()

-- | Emit a single byte.
emitInt8 :: Region -> Int8 -> BuildM ()

-- | Emit a list of bytes.
emitInt8s :: Region -> [Int8] -> BuildM ()

-- | Emit a <a>Int16</a> in little endian format.
emitInt16le :: Region -> Int16 -> BuildM ()

-- | Emit a <a>Int16</a> in big endian format.
emitInt16be :: Region -> Int16 -> BuildM ()

-- | Emit a <a>Int16</a> in native host order and host endianness.
emitInt16host :: Region -> Int16 -> BuildM ()

-- | Emit a <a>Int32</a> in little endian format.
emitInt32le :: Region -> Int32 -> BuildM ()

-- | Emit a <a>Int32</a> in big endian format.
emitInt32be :: Region -> Int32 -> BuildM ()

-- | Emit a <a>Int32</a> in native host order and host endianness.
emitInt32host :: Region -> Int32 -> BuildM ()

-- | Emit a <a>Int64</a> in little endian format.
emitInt64le :: Region -> Int64 -> BuildM ()

-- | Emit a <a>Int64</a> in big endian format.
emitInt64be :: Region -> Int64 -> BuildM ()

-- | Emit a <a>Int64</a> in native host order and host endianness.
emitInt64host :: Region -> Int64 -> BuildM ()

-- | Emit an instance of <a>Storable</a>. Does not take into account
--   alignment.
emitStorable :: Storable a => Region -> a -> BuildM ()

-- | Emit a list of <a>Storable</a> instances. Ignores alignment.
emitStorableList :: Storable a => Region -> [a] -> BuildM ()

-- | Insert padding bytes into given region until its size is a multiple of
--   the expected alignment.
padTo :: Region -> Int -> Word8 -> BuildM ()

-- | Emit an aligned label at the current location in the region.
--   
--   The label's address relative to the region start will be at a multiple
--   of the given alignment
alignedLabel :: Region -> Int -> BuildM Label
instance Eq Label
instance Ord Label
instance Eq Region
instance Ord Region
instance Eq Size
instance Show Size
instance Ord Size
instance Enum Size
instance Show Label
instance Show Region
instance Applicative BuildM
instance Functor BuildM
instance Monad BuildM