The central type. The four type parameters are:

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

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.

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"],"")]

Repeats the argument format the given number of times.

>>> 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 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