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


-- | First-class record construction and bidirectional serialization
--   
@package codec
@version 0.1.1

module Data.Codec.Field

-- | Describes how to apply a constructor argument and how to extract from
--   a record. <tt>y</tt> should be <tt>x</tt> with one argument knocked
--   out: e. g.
--   
--   <pre>
--   Field MyType Int (Int -&gt; a2 -&gt; MyType) (X -&gt; a2 -&gt; MyType)
--   </pre>
data Field r a x y
Field :: (a -> x -> y) -> (r -> a) -> Field r a x y

-- | An ongoing record construction of an <tt>r</tt> in context <tt>f</tt>.
--   Applicative actions are sequenced in the direction of
--   <a>&gt;&gt;&gt;</a>.
newtype Build r f x y
Build :: (f (x -> y)) -> Build r f x y

-- | A constructor for a given record and a way to check whether it has it.
data Con r x
Con :: x -> (r -> Bool) -> Con r x

-- | Infix version of <a>build</a>.
($>>) :: (Functor f, Buildable r y) => x -> Build r f x y -> f r

-- | Left-to-right composition
(>>>) :: Category k cat => cat a b -> cat b c -> cat a c

-- | No-op <a>Build</a> (same as <a>id</a>).
done :: Applicative f => Build r f x x

-- | <a>Field</a>s partially apply constructors and replace arguments with
--   this type.
data X
X :: X

-- | The class of constructor applications that have been completely filled
--   in by composing <a>Build</a>s. If you see an error message involving
--   this, it means that you forgot to specify a <a>Build</a> for a field.
class Buildable r a
give :: Buildable r a => a -> r

-- | Combine a <a>Field</a> and a way to produce an <tt>a</tt> to get a
--   <a>Build</a>.
having :: Functor f => Field r a x y -> f a -> Build r f x y

-- | Finish a construction given a constructor.
build :: (Functor f, Buildable r y) => x -> Build r f x y -> f r
instance Applicative f => Category (Build r f)
instance Buildable r b => Buildable r (X -> b)
instance Buildable r r

module Data.Codec.Codec

-- | De/serializer for the given types. Usually w ~ r, but they are
--   separate to allow for an <a>Applicative</a> instance.
data Codec' fr fw w r
Codec :: fr r -> (w -> fw ()) -> Codec' fr fw w r
parse :: Codec' fr fw w r -> fr r
produce :: Codec' fr fw w r -> w -> fw ()

-- | De/serializer for <tt>a</tt>.
type Codec fr fw a = Codec' fr fw a a

-- | Associate a <a>Field</a> with a <a>Codec</a> to create a <a>Codec</a>
--   <a>Build</a>.
(>-<) :: Functor fr => Field r a x y -> Codec fr fw a -> Build r (Codec' fr fw r) x y

-- | A codec where <tt>a</tt> can be produced from a concrete value of
--   <tt>b</tt> in context <tt>f</tt>, and a concrete type of value
--   <tt>b</tt> can always be produced.
type ConcreteCodec b f a = Codec (ReaderT b f) (Const b) a

-- | Create a concrete codec from a reader and a writer.
concrete :: (b -> f a) -> (a -> b) -> ConcreteCodec b f a

-- | Parse a concrete value with a given <a>ConcreteCodec</a>.
parseVal :: ConcreteCodec b f a -> b -> f a

-- | Produce a concrete value with a given <a>ConcreteCodec</a>.
produceVal :: ConcreteCodec b f a -> a -> b

-- | A codec that can only serialize a subset of values.
type PartialCodec fr fw a = Codec fr (Compose Maybe fw) a

-- | Finish a codec construction with a <tt><a>Con</a> r</tt> to produce a
--   <a>PartialCodec</a>. This will check that the given record has the
--   appropriate constructor before serializing.
cbuild :: (Functor fr, Buildable r y) => Con r x -> Build r (Codec' fr fw r) x y -> PartialCodec fr fw r

-- | Guard a <a>Codec</a> with a predicate to create a <a>PartialCodec</a>.
assume :: (a -> Bool) -> Codec fr fw a -> PartialCodec fr fw a

-- | Convert a <a>PartialCodec</a> into a <a>Codec</a>, throwing an error
--   on values it cannot serialize.
covered :: PartialCodec fr fw a -> Codec fr fw a

-- | Combine alternative <a>PartialCodec</a>s.
(<->) :: Alternative fr => PartialCodec fr fw a -> PartialCodec fr fw a -> PartialCodec fr fw a

-- | Attempt to get a serialization for a given value.
produceMaybe :: PartialCodec fr fw a -> a -> Maybe (fw ())

-- | Given a <a>Codec</a> for <tt>a</tt>, make one for <a>Maybe</a>
--   <tt>a</tt> that applies its deserializer optionally and does nothing
--   when serializing <a>Nothing</a>.
opt :: (Alternative fr, Applicative fw) => Codec fr fw a -> Codec fr fw (Maybe a)

-- | Turn a <tt><a>Codec</a> a</tt> into a <tt><a>Codec</a> b</tt> by
--   providing an isomorphism.
mapCodec :: Functor fr => (a -> b) -> (b -> a) -> Codec fr fw a -> Codec fr fw b

-- | Map the contexts of a given <a>Codec</a>.
mapCodecF :: (fr a -> gr a) -> (fw () -> gw ()) -> Codec fr fw a -> Codec gr gw a

-- | Map a field codec monadically. Useful for error handling but care must
--   be taken to make sure that the results are still complementary.
mapCodecM :: (Monad fr, Monad fw) => (a -> fr b) -> (b -> fw a) -> Codec fr fw a -> Codec fr fw b
instance Functor fr => Functor (Codec' fr fw w)
instance (Applicative fw, Applicative fr) => Applicative (Codec' fr fw w)

module Data.Codec.Testing
class ParseResult f
toEither :: ParseResult f => f a -> Either String a

-- | Round-trip a value through a <a>ConcreteCodec</a> to an `Either String
--   a`.
roundTrip :: ParseResult f => ConcreteCodec c f a -> a -> Either String a

-- | Round-trip a value through its <a>Storable</a> instance.
roundTripStorable :: Storable a => a -> IO a
instance ParseResult Result
instance ParseResult Maybe
instance ParseResult (Either String)

module Data.Binary.Codec
type BinaryCodec a = Codec Get PutM a

-- | Get/put an n-byte field.
byteString :: Int -> BinaryCodec ByteString

-- | Convert a <a>BinaryCodec</a> into a <a>ConcreteCodec</a> on lazy
--   <a>ByteString</a>s.
toLazyByteString :: BinaryCodec a -> ConcreteCodec ByteString (Either String) a
word8 :: BinaryCodec Word8
word16be :: BinaryCodec Word16
word16le :: BinaryCodec Word16
word16host :: BinaryCodec Word16
word32be :: BinaryCodec Word32
word32le :: BinaryCodec Word32
word32host :: BinaryCodec Word32
word64be :: BinaryCodec Word64
word64le :: BinaryCodec Word64
word64host :: BinaryCodec Word64
wordhost :: BinaryCodec Word

module Foreign.Codec
type ForeignContext a = ReaderT (Ptr a) IO

-- | A foreign codec for <tt>a</tt> given a pointer to itself. Use
--   <tt>def</tt> from <tt>Default</tt> to get a codec that uses a
--   <a>Storable</a> instance,
type ForeignCodec a = ForeignCodec' a a

-- | A foreign codec for <tt>a</tt> given a pointer to <tt>p</tt>.
type ForeignCodec' p a = Codec (ForeignContext p) (ForeignContext p) a

-- | Peek a value using a <a>ForeignCodec'</a>.
peekWith :: ForeignCodec' p a -> Ptr p -> IO a

-- | Poke a value using a <a>ForeignCodec'</a>.
pokeWith :: ForeignCodec' p a -> Ptr p -> a -> IO ()

-- | A <a>ForeignCodec</a> for any <a>Storable</a> type.
storable :: Storable a => ForeignCodec a

-- | A codec for a field of a foreign structure, given its byte offset and
--   a sub-codec. You can get an offset easily using <tt>{#offset
--   struct_type, field}</tt> with <tt>hsc2hs</tt>.
field :: Int -> ForeignCodec' f a -> ForeignCodec' p a

-- | Store any integral type.
cast :: (Integral c, Storable c, Integral a) => ForeignCodec' c a

-- | Store a <a>Bool</a> in any <a>Integral</a> <a>Ptr</a>.
cBool :: Integral c => ForeignCodec' c Bool

-- | Restrict the pointer type of a given codec. Utility function for the
--   <tt>numField</tt> macro.
codecFor :: c -> ForeignCodec' c a -> ForeignCodec' c a

module Data.Codec.TH

-- | Generate <a>Field</a>s for a given data type. Currently only
--   single-constructor records are supported. Each record field <tt>a</tt>
--   will be turned into a <a>Field</a> <tt>f_a</tt>, and all constructors
--   will be turned into <a>Con</a>s.
genFields :: Name -> Q [Dec]

module Data.Codec.Tuple
class Field1 r a x y | r x -> y, r y -> x, r -> a, x y -> r
f_1 :: Field1 r a x y => Field r a x y
class Field2 r a x y | r x -> y, r y -> x, r -> a, x y -> r
f_2 :: Field2 r a x y => Field r a x y
c_Left :: Con (Either a b) (a -> Either a b)
c_Right :: Con (Either a b) (b -> Either a b)
f_left :: Field (Either a b) a (a -> Either a b) (X -> Either a b)
f_right :: Field (Either a b) b (b -> Either a b) (X -> Either a b)
instance Field2 (a, b) b (a1 -> b -> (a, b)) (a1 -> X -> (a, b))
instance Field1 (a, b) a (a -> a2 -> (a, b)) (X -> a2 -> (a, b))

module Data.Codec

module Data.Aeson.Codec

-- | JSON codec. This is just a <a>ToJSON</a>/<a>FromJSON</a>
--   implementation wrapped up in newtypes. Use <a>def</a> to get a
--   <a>JSONCodec</a> for a <a>ToJSON</a>/<a>FromJSON</a> instance.
type JSONCodec a = ConcreteCodec Value Parser a
type ObjectParser = ReaderT Object Parser
type ObjectBuilder = Const (Endo [Pair])

-- | A codec that parses values out of a given <a>Object</a>, and produces
--   key-value pairs into a new one.
type ObjectCodec a = Codec ObjectParser ObjectBuilder a

-- | Read/write a given value from/to a given key in the current object,
--   using a given sub-codec. ObjectCodec's <a>IsString</a> instance is
--   equal to <a>entry</a> <a>def</a>.
entry :: Text -> JSONCodec a -> ObjectCodec a

-- | Produce a key-value pair.
pair :: ToJSON a => Text -> a -> ObjectBuilder ()

-- | Turn an <a>ObjectCodec</a> into a <a>JSONCodec</a> with an expected
--   name (see <a>withObject</a>).
obj :: String -> ObjectCodec a -> JSONCodec a
instance (ToJSON a, FromJSON a) => IsString (ObjectCodec a)
instance (ToJSON a, FromJSON a) => Default (JSONCodec a)

module Data.Binary.Bits.Codec
type BitCodec a = Codec Block BitPut a
bool :: BitCodec Bool
word8 :: Int -> BitCodec Word8
word16be :: Int -> BitCodec Word16
word32be :: Int -> BitCodec Word32
word64be :: Int -> BitCodec Word64

-- | Convert a <a>BitCodec</a> into a <a>BinaryCodec</a>.
toBytes :: BitCodec a -> BinaryCodec a