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


-- | Monadic conversion between complex data structures and unique integers
--   
--   The library provides functions for encoding and decoding complex data
--   structures with unique integer numbers. The codec structure can be
--   explicitly defined which distinguishes this package from a monad-atom
--   library.
@package monad-codec
@version 0.2.0


-- | The Codec monad provides functions for encoding and decoding complex
--   data structures with unique integer numbers. In the simplest case the
--   entire sturecture can be transformed to unique atom (see
--   <tt>example1</tt> below). When it is not sufficient to encode the
--   input object with one codec, more complex codec structure can be used
--   (see <tt>example2</tt> below). The library relies on a 'data-lens'
--   package which provides types and functions for codec manipulations.
--   
--   Example:
--   
--   <pre>
--   example1 = evalCodec empty $ do
--       let xs = "abcabd"
--       ys &lt;- mapM (encode idLens) xs
--       zs &lt;- mapM (decode idLens) ys
--       return $ zip zs ys
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; example1
--   
--   &gt;&gt;&gt; [('a',0),('b',1),('c',2),('a',0),('b',1),('d',3)]
--   </pre>
--   
--   <pre>
--   example2 = evalCodec (empty, empty) $ do
--       let xs = zip "abcabd" [1, 34342, 5435, 34342, 124, 1]
--       ys &lt;- forM xs $ \(x, y) -&gt;
--           (,) &lt;$&gt; encode fstLens x &lt;*&gt; encode sndLens y
--       zs &lt;- forM ys $ \(i, j) -&gt; 
--           (,) &lt;$&gt; decode fstLens i &lt;*&gt; decode sndLens j
--       return (zs, ys)
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; fst example2
--   
--   &gt;&gt;&gt; [('a',1),('b',34342),('c',5435),('a',34342),('b',124),('d',1)]
--   
--   &gt;&gt;&gt; snd example2
--   
--   &gt;&gt;&gt; [(0,0),(1,1),(2,2),(0,1),(1,3),(3,0)]
--   </pre>
module Control.Monad.Codec

-- | A Codec monad preserves mappings between objects and respective codec
--   components.
data Codec c a

-- | Atomic Codec component, which represents to and fro mapping between
--   <tt>a</tt> objects and unique intergers.
data AtomCodec a
AtomCodec :: !(Map a Int) -> !(IntMap a) -> AtomCodec a
to :: AtomCodec a -> !(Map a Int)
from :: AtomCodec a -> !(IntMap a)

-- | Empty codec component.
empty :: AtomCodec a

-- | Just a type synonym for a lens between codec and codec component.
type AtomLens c a = Lens c (AtomCodec a)

-- | Encode the object with codec component identified by the lens. Return
--   Nothing if the object is not present in the atomic codec component.
maybeEncode :: Ord a => AtomLens c a -> a -> Codec c (Maybe Int)

-- | Encode the object with codec component identified by the lens.
encode :: Ord a => AtomLens c a -> a -> Codec c Int

-- | Version of encode which doesn't update the return componenent of the
--   atom codec. It is useful when we know that particular value (e.g.
--   value of a condition observation) won't be decoded afterwards so there
--   is no need to store it and waste memory.
encode' :: Ord a => AtomLens c a -> a -> Codec c Int

-- | Decode the number with codec component identified by the lens. Return
--   Nothing if the object is not present in the atomic codec component.
maybeDecode :: Ord a => AtomLens c a -> Int -> Codec c (Maybe a)

-- | Decode the number with codec component identified by the lens. Report
--   error when the number is not present in the codec component.
decode :: Ord a => AtomLens c a -> Int -> Codec c a

-- | Run the Codec monad with the initial codec value. Return both the
--   result and the final codec state. The obtained codec can be used next
--   to perform subsequent decoding or encoding.
runCodec :: c -> Codec c a -> (a, c)

-- | Evaluate the Codec monad with the initial codec value. Only the monad
--   result will be returned.
evalCodec :: c -> Codec c a -> a

-- | Execute the Codec monad with the initial codec value. Only the final
--   codec state will be returned.
execCodec :: c -> Codec c a -> c

-- | Identity lenses should be used whenever the structure of the codec is
--   simple, i.e. only one atomic codec is used.
idLens :: Lens a a
instance Functor (Codec c)
instance Applicative (Codec c)
instance Monad (Codec c)
instance (Ord a, Binary a) => Binary (AtomCodec a)