The central type. The four type parameters are:

• m, type of the parser for the format
• n, container type for the serialized form of the value, typically Identity unless something Alternative is called for.
• s, type of the serialized value, typically ByteString
• a, type of the parsed value in memory

The parse and serialize fields can be used to perform the two sides of the conversion between the in-memory and serialized form of the value.

Same as the usual <$ except a Format is no Functor.

Same as the usual *> except a Format is no Functor, let alone Applicative.

Same as the usual <* except a Format is no Functor, let alone Applicative.

Same as the usual <|> except a Format is no Functor, let alone Alternative.

A discriminated or tagged choice between two formats.

Name a format to improve error messages.

>>> testParse (takeCharsWhile1 isDigit <?> "a number") "abc"
Left "expected a number, encountered 'a'"
>>> testSerialize (takeCharsWhile1 isDigit <?> "a number") "abc"
Left "expected a number, encountered \"abc\""

Same as the usual empty except a Format is no Functor, let alone Alternative.

Same as the usual optional except a Format is no Functor, let alone Alternative.

Like optional except with arbitrary default serialization for the Nothing value.

optional = optionWithDefault (literal mempty)

Combines two formats into a format for the pair of their values.

>>> testParse (pair char char) "abc"
Right [(('a','b'),"c")]

Combines two formats, where the second format depends on the first value, into a format for the pair of their values. Similar to >>= except Format is no Functor let alone Monad.

>>> testParse (deppair char (\c-> satisfy (==c) char)) "abc"
Left "encountered 'b'"
>>> testParse (deppair char (\c-> satisfy (==c) char)) "aac"
Right [(('a','a'),"c")]

Same as the usual many except a Format is no Functor, let alone Alternative.

Same as the usual some except a Format is no Functor, let alone Alternative.

In the parsing direction, the same as the regular manyTill: parses the item zero or more times until the terminator succeeds. When serializing, makes sure to append the terminator. Beware, for performance reasons the function does not verify that no item's serialization can be parsed via the terminator.

Represents any number of values formatted using the first argument, separated by the second format argumewnt in serialized form. Similar to the usual sepBy combinator.

>>> testParse (takeCharsWhile isLetter `sepBy` literal ",") "foo,bar,baz"
Right [([],"foo,bar,baz"),(["foo"],",bar,baz"),(["foo","bar"],",baz"),(["foo","bar","baz"],"")]

Sequence a list of formats into a list format.

Repeats the argument format the given number of times.

The property count n f == Construct.sequence (replicate n f) holds.

>>> testParse (count 4 byte) (ByteString.pack [1,2,3,4,5])
Right [([1,2,3,4],"\ENQ")]
>>> testSerialize (count 4 byte) [1,2,3,4,5]
Left "expected a list of length 4, encountered [1,2,3,4,5]"
>>> testSerialize (count 4 byte) [1,2,3,4]
Right "\SOH\STX\ETX\EOT"

Same as the usual mfix except a Format is no Functor, let alone Monad.

Converts a record of field formats into a single format of the whole record.

Converts a record of field formats into a single format of the whole record, a generalized form of record.

Converts a format for serialized streams of type s so it works for streams of type t instead

>>> testParse (mapSerialized ByteString.unpack ByteString.pack byte) [1,2,3]
Right [(1,[2,3])]

Converts a format for serialized streams of type s so it works for streams of type t instead. The argument functions may return Nothing to indicate they have insuficient input to perform the conversion.

Converts a format for in-memory values of type a so it works for values of type b instead.

>>> testParse (mapValue (read @Int) show $ takeCharsWhile1 isDigit) "012 34"
Right [(12," 34")]
>>> testSerialize (mapValue read show $ takeCharsWhile1 isDigit) 12
Right "12"

Converts a format for in-memory values of type a so it works for values of type b instead. The argument functions may signal conversion failure by returning Nothing.

Filter the argument format so it only succeeds for values that pass the predicate.

>>> testParse (satisfy isDigit char) "abc"
Left "encountered 'a'"
>>> testParse (satisfy isLetter char) "abc"
Right [('a',"bc")]

A fixed expected value serialized through the argument format

>>> testParse (value char 'a') "bcd"
Left "encountered 'b'"
>>> testParse (value char 'a') "abc"
Right [((),"bc")]

Modifies the serialized form of the given format by padding it with the given template if it's any shorter

>>> testParse (padded "----" $ takeCharsWhile isDigit) "12--3---"
Right [("12","3---")]
>>> testSerialize (padded "----" $ takeCharsWhile isDigit) "12"
Right "12--"

Modifies the serialized form of the given format by padding it with the given template. The serialized form has to be shorter than the template before padding.

A literal serialized form, such as a magic constant, corresponding to no value

>>> testParse (literal "Hi") "Hi there"
Right [(()," there")]

A trivial format for a single byte in a ByteString

>>> testParse byte (ByteString.pack [1,2,3])
Right [(1,"\STX\ETX")]

A trivial format for a single character

>>> testParse char "abc"
Right [('a',"bc")]

A quick way to format a value that already has an appropriate Serialize instance

>>> testParse (cereal @Word16) (ByteString.pack [1,2,3])
Right [(258,"\ETX")]
>>> testSerialize cereal (1025 :: Word16)
Right "\EOT\SOH"

Specifying a formatter explicitly using the cereal getter and putter

>>> testParse (cereal' getWord16le putWord16le) (ByteString.pack [1,2,3])
Right [(513,"\ETX")]

Format whose in-memory value is a fixed-size prefix of the serialized value

>>> testParse (take 3) "12345"
Right [("123","45")]
>>> testSerialize (take 3) "123"
Right "123"
>>> testSerialize (take 3) "1234"
Left "expected a value of length 3, encountered \"1234\""

Format whose in-memory value is the longest prefix of the serialized value smallest parts of which all satisfy the given predicate.

>>> testParse (takeWhile (> "b")) "abcd"
Right [("","abcd")]
>>> testParse (takeWhile (> "b")) "dcba"
Right [("dc","ba")]
>>> testSerialize (takeWhile (> "b")) "dcba"
Left "expected takeWhile, encountered \"dcba\""
>>> testSerialize (takeWhile (> "b")) "dc"
Right "dc"
>>> testSerialize (takeWhile (> "b")) ""
Right ""

Format whose in-memory value is the longest non-empty prefix of the serialized value smallest parts of which all satisfy the given predicate.

>>> testParse (takeWhile1 (> "b")) "abcd"
Left "takeWhile1"
>>> testSerialize (takeWhile1 (> "b")) ""
Left "expected takeWhile1, encountered \"\""
>>> testSerialize (takeWhile1 (> "b")) "dc"
Right "dc"

Format whose in-memory value is the longest prefix of the serialized value that consists of characters which all satisfy the given predicate.

>>> testParse (takeCharsWhile isDigit) "a12"
Right [("","a12")]
>>> testParse (takeCharsWhile isDigit) "12a"
Right [("12","a")]
>>> testSerialize (takeCharsWhile isDigit) "12a"
Left "expected takeCharsWhile, encountered \"12a\""
>>> testSerialize (takeCharsWhile isDigit) "12"
Right "12"
>>> testSerialize (takeCharsWhile isDigit) ""
Right ""

Format whose in-memory value is the longest non-empty prefix of the serialized value that consists of characters which all satisfy the given predicate.

>>> testParse (takeCharsWhile1 isDigit) "a12"
Left "takeCharsWhile1 encountered 'a'"
>>> testParse (takeCharsWhile1 isDigit) "12a"
Right [("12","a")]
>>> testSerialize (takeCharsWhile1 isDigit) "12"
Right "12"
>>> testSerialize (takeCharsWhile1 isDigit) ""
Left "expected takeCharsWhile1, encountered \"\""

Attempts to parse the given input with the format with a constrained type, returns either a failure message or a list of successes.

A less polymorphic wrapper around serialize useful for testing