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


-- | Encoders and decoders for the PostgreSQL's binary format
--   
--   An API for dealing with PostgreSQL's binary data format.
--   
--   It can be used to implement performant bindings to Postgres. E.g.,
--   <a>"hasql"</a> is based on this library.
--   
--   It supports all Postgres versions starting from 8.3 and is tested
--   against 8.3, 9.3 and 9.4 with the <tt>integer_datetimes</tt> setting
--   off and on.
@package postgresql-binary
@version 0.9.1


-- | Models of supported data structures according to the serialisation
--   format.
module PostgreSQL.Binary.Data

-- | A representation of a data serializable to the PostgreSQL array binary
--   format.
--   
--   Consists of a vector of dimensions, a vector of encoded elements, a
--   flag specifying, whether it contains any nulls, and an oid.
type Array = (Vector ArrayDimension, Vector Content, Bool, OID)

-- | A width and a lower bound.
--   
--   Currently the lower bound is only allowed to have a value of
--   <tt>1</tt>.
type ArrayDimension = (Word32, Word32)

-- | An encoded value. <a>Nothing</a> if it represents a <tt>NULL</tt>.
type Content = Maybe ByteString

-- | A Postgres OID of a type.
type OID = Word32

-- | A representation of a composite Postgres data (Record or Row).
type Composite = Vector (OID, Content)

-- | HStore.
type HStore = Vector (ByteString, Content)

-- | The four components of UUID.
type UUID = (Word32, Word32, Word32, Word32)

-- | Representation of the PostgreSQL Numeric encoding.
--   
--   Consists of the following components:
--   
--   <ul>
--   <li>Point index</li>
--   <li>Sign code</li>
--   <li>Components</li>
--   </ul>
type Numeric = (Int16, Word16, Vector Int16)

module PostgreSQL.Binary.Decoder
type Decoder = BinaryParser

-- | Apply a parser to bytes.
run :: BinaryParser a -> ByteString -> Either Text a
int :: (Integral a, Bits a) => Decoder a
float4 :: Decoder Float
float8 :: Decoder Double
bool :: Decoder Bool

-- | BYTEA or any other type in its undecoded form.
bytea_strict :: Decoder ByteString

-- | BYTEA or any other type in its undecoded form.
bytea_lazy :: Decoder LazyByteString

-- | Any of the variable-length character types: BPCHAR, VARCHAR, NAME and
--   TEXT.
text_strict :: Decoder Text

-- | Any of the variable-length character types: BPCHAR, VARCHAR, NAME and
--   TEXT.
text_lazy :: Decoder LazyText

-- | A UTF-8-decoded char.
char :: Decoder Char

-- | Lifts a custom decoder implementation.
fn :: (ByteString -> Either Text a) -> Decoder a
numeric :: Decoder Scientific
uuid :: Decoder UUID
json_ast :: Decoder Value

-- | Given a function, which parses a plain UTF-8 JSON string encoded as a
--   byte-array, produces a decoder.
json_bytes :: (ByteString -> Either Text a) -> Decoder a
jsonb_ast :: Decoder Value

-- | Given a function, which parses a plain UTF-8 JSON string encoded as a
--   byte-array, produces a decoder.
--   
--   For those wondering, yes, JSONB is encoded as plain JSON string in the
--   binary format of Postgres. Sad, but true.
jsonb_bytes :: (ByteString -> Either Text a) -> Decoder a

-- | <tt>DATE</tt> values decoding.
date :: Decoder Day

-- | <tt>TIME</tt> values decoding for servers, which have
--   <tt>integer_datetimes</tt> enabled.
time_int :: Decoder TimeOfDay

-- | <tt>TIME</tt> values decoding for servers, which don't have
--   <tt>integer_datetimes</tt> enabled.
time_float :: Decoder TimeOfDay

-- | <tt>TIMETZ</tt> values decoding for servers, which have
--   <tt>integer_datetimes</tt> enabled.
timetz_int :: Decoder (TimeOfDay, TimeZone)

-- | <tt>TIMETZ</tt> values decoding for servers, which don't have
--   <tt>integer_datetimes</tt> enabled.
timetz_float :: Decoder (TimeOfDay, TimeZone)

-- | <tt>TIMESTAMP</tt> values decoding for servers, which have
--   <tt>integer_datetimes</tt> enabled.
timestamp_int :: Decoder LocalTime

-- | <tt>TIMESTAMP</tt> values decoding for servers, which don't have
--   <tt>integer_datetimes</tt> enabled.
timestamp_float :: Decoder LocalTime

-- | <tt>TIMESTAMP</tt> values decoding for servers, which have
--   <tt>integer_datetimes</tt> enabled.
timestamptz_int :: Decoder UTCTime

-- | <tt>TIMESTAMP</tt> values decoding for servers, which don't have
--   <tt>integer_datetimes</tt> enabled.
timestamptz_float :: Decoder UTCTime

-- | <tt>INTERVAL</tt> values decoding for servers, which don't have
--   <tt>integer_datetimes</tt> enabled.
interval_int :: Decoder DiffTime

-- | <tt>INTERVAL</tt> values decoding for servers, which have
--   <tt>integer_datetimes</tt> enabled.
interval_float :: Decoder DiffTime

-- | An efficient generic array decoder, which constructs the result value
--   in place while parsing.
--   
--   Here's how you can use it to produce a specific array value decoder:
--   
--   <pre>
--   x :: Decoder [ [ Text ] ]
--   x =
--     array (arrayDimension replicateM (fmap catMaybes (arrayDimension replicateM (arrayValue text))))
--   </pre>
data ArrayDecoder a

-- | Unlift an <a>ArrayDecoder</a> to a value <a>Decoder</a>.
array :: ArrayDecoder a -> Decoder a

-- | A function for parsing a dimension of an array. Provides support for
--   multi-dimensional arrays.
--   
--   Accepts:
--   
--   <ul>
--   <li>An implementation of the <tt>replicateM</tt> function
--   (<tt>Control.Monad.<a>replicateM</a></tt>,
--   <tt>Data.Vector.<a>replicateM</a></tt>), which determines the output
--   value.</li>
--   <li>A decoder of its components, which can be either another
--   <a>arrayDimension</a> or <a>arrayValue</a>.</li>
--   </ul>
arrayDimension :: (forall m. Monad m => Int -> m a -> m b) -> ArrayDecoder a -> ArrayDecoder b

-- | Lift a value <a>Decoder</a> into <a>ArrayDecoder</a> for parsing of
--   nullable leaf values.
arrayValue :: Decoder a -> ArrayDecoder (Maybe a)

-- | Lift a value <a>Decoder</a> into <a>ArrayDecoder</a> for parsing of
--   non-nullable leaf values.
arrayNonNullValue :: Decoder a -> ArrayDecoder a
data CompositeDecoder a

-- | Unlift a <a>CompositeDecoder</a> to a value <a>Decoder</a>.
composite :: CompositeDecoder a -> Decoder a

-- | Lift a value <a>Decoder</a> into <a>CompositeDecoder</a>.
compositeValue :: Decoder a -> CompositeDecoder (Maybe a)

-- | Lift a non-nullable value <a>Decoder</a> into <a>CompositeDecoder</a>.
compositeNonNullValue :: Decoder a -> CompositeDecoder a

-- | A function for generic in place parsing of an HStore value.
--   
--   Accepts:
--   
--   <ul>
--   <li>An implementation of the <tt>replicateM</tt> function
--   (<tt>Control.Monad.<a>replicateM</a></tt>,
--   <tt>Data.Vector.<a>replicateM</a></tt>), which determines how to
--   produce the final datastructure from the rows.</li>
--   <li>A decoder for keys.</li>
--   <li>A decoder for values.</li>
--   </ul>
--   
--   Here's how you can use it to produce a parser to list:
--   
--   <pre>
--   hstoreAsList :: Decoder [ ( Text , Maybe Text ) ]
--   hstoreAsList =
--     hstore replicateM text text
--   </pre>
hstore :: (forall m. Monad m => Int -> m (k, Maybe v) -> m r) -> Decoder k -> Decoder v -> Decoder r

-- | Given a partial mapping from text to value, produces a decoder of that
--   value.
enum :: (Text -> Maybe a) -> Decoder a
instance GHC.Base.Functor PostgreSQL.Binary.Decoder.ArrayDecoder
instance GHC.Base.Monad PostgreSQL.Binary.Decoder.CompositeDecoder
instance GHC.Base.Applicative PostgreSQL.Binary.Decoder.CompositeDecoder
instance GHC.Base.Functor PostgreSQL.Binary.Decoder.CompositeDecoder

module PostgreSQL.Binary.Encoder
run :: Encoder a -> a -> ByteString
type Encoder a = a -> Builder
int2_int16 :: Encoder Int16
int2_word16 :: Encoder Word16
int4_int32 :: Encoder Int32
int4_word32 :: Encoder Word32
int8_int64 :: Encoder Int64
int8_word64 :: Encoder Word64
float4 :: Encoder Float
float8 :: Encoder Double
composite :: Encoder Composite
bool :: Encoder Bool
numeric :: Encoder Scientific
uuid :: Encoder UUID
json_ast :: Encoder Value
json_bytes :: Encoder ByteString
jsonb_ast :: Encoder Value
jsonb_bytes :: Encoder ByteString

-- | A UTF-8-encoded char.
--   
--   Note that since it's UTF-8-encoded not the "char" but the "text" OID
--   should be used with it.
char :: Encoder Char
text_strict :: Encoder Text
text_lazy :: Encoder Text
bytea_strict :: Encoder ByteString
bytea_lazy :: Encoder ByteString
date :: Encoder Day
time_int :: Encoder TimeOfDay
time_float :: Encoder TimeOfDay
timetz_int :: Encoder (TimeOfDay, TimeZone)
timetz_float :: Encoder (TimeOfDay, TimeZone)
timestamp_int :: Encoder LocalTime
timestamp_float :: Encoder LocalTime
timestamptz_int :: Encoder UTCTime
timestamptz_float :: Encoder UTCTime
interval_int :: Encoder DiffTime
interval_float :: Encoder DiffTime

-- | A polymorphic in-place <tt>HSTORE</tt> encoder.
--   
--   Accepts:
--   
--   <ul>
--   <li>An implementation of the <tt>foldl</tt> function (e.g.,
--   <tt>Data.Foldable.<a>foldl'</a></tt>), which determines the input
--   value.</li>
--   </ul>
--   
--   Here's how you can use it to produce a specific encoder:
--   
--   <pre>
--   hashMapHStore :: Encoder (Data.HashMap.Strict.HashMap Text (Maybe Text))
--   hashMapHStore =
--     hstore foldl'
--   </pre>
hstore :: (forall a. (a -> (Text, Maybe Text) -> a) -> a -> b -> a) -> Encoder b
hstoreRep :: Encoder HStore
array :: Word32 -> ArrayEncoder a -> Encoder a
data ArrayEncoder a
arrayValue :: Encoder a -> ArrayEncoder a
arrayNullableValue :: Encoder a -> ArrayEncoder (Maybe a)
arrayDimension :: (forall a. (a -> b -> a) -> a -> c -> a) -> ArrayEncoder b -> ArrayEncoder c
arrayRep :: Encoder Array

-- | Given a function, which maps the value into the textual enum label
--   from the DB side, produces an encoder of that value
enum :: (a -> Text) -> Encoder a
