-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A Haskell version of the Construct library for Python. A -- succinct file format specification provides both a parser and the -- serializer for the format. @package construct @version 0.3.2 -- | The only good reason to import this module is if you intend to add -- another instance of the classes it exports. module Construct.Classes -- | Subclass of Alternative that carries an error message in case -- of failure class Alternative m => AlternativeFail m -- | Equivalent to empty except it takes an error message it may -- carry or drop on the floor. The grammatical form of the argument -- should be a noun representing the unexpected value. failure :: AlternativeFail m => String -> m a -- | Sets or modifies the expected value. expectedName :: AlternativeFail m => String -> m a -> m a -- | A subclass of InputParsing for parsers that can switch the -- input stream type class InputMappableParsing m -- | Converts a parser accepting one input stream type to another. The -- functions forth and back must be inverses of each -- other and they must distribute through <>: -- -- 
--   f (s1 <> s2) == f s1 <> f s2
--
mapParserInput :: (InputMappableParsing m, InputParsing (m s), s ~ ParserInput (m s), Monoid s, Monoid s') => (s -> s') -> (s' -> s) -> m s a -> m s' a -- | Converts a parser accepting one input stream type to another just like -- mapParserInput, except the argument functions can return -- Nothing to indicate they need more input. mapMaybeParserInput :: (InputMappableParsing m, InputParsing (m s), s ~ ParserInput (m s), Monoid s, Monoid s') => (s -> Maybe s') -> (s' -> Maybe s) -> m s a -> m s' a -- | A subclass of MonadFix for monads that can fix a function -- that handles higher-kinded data class Monad m => FixTraversable m -- | This specialized form of traverse can be used inside -- mfix. fixSequence :: (FixTraversable m, Traversable g, Applicative n) => g m -> m (g n) data Error Error :: [String] -> Maybe String -> Error errorString :: Error -> String concatExpected :: [String] -> Maybe String oxfordComma :: String -> [String] -> String instance GHC.Show.Show Construct.Classes.Error instance GHC.Classes.Eq Construct.Classes.Error instance GHC.Base.Semigroup Construct.Classes.Error instance GHC.Base.Alternative (Data.Either.Either Construct.Classes.Error) instance Construct.Classes.AlternativeFail (Data.Either.Either Construct.Classes.Error) instance Construct.Classes.FixTraversable Data.Attoparsec.ByteString.Internal.Parser instance GHC.Base.Monoid s => Construct.Classes.FixTraversable (Text.ParserCombinators.Incremental.Parser t s) instance Construct.Classes.InputMappableParsing (Text.ParserCombinators.Incremental.Parser t) instance Construct.Classes.AlternativeFail GHC.Maybe.Maybe instance Construct.Classes.AlternativeFail [] -- | Declarative and symmetrical specification of binary and textual data -- formats. module Construct -- | The central type. The four type parameters are: -- -- -- -- 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. data Format m n s a parse :: Format m n s a -> m a serialize :: Format m n s a -> a -> n s -- | Same as the usual <$ except a Format is no -- Functor. (<$) :: (Eq a, Show a, Functor m, AlternativeFail n) => a -> Format m n s () -> Format m n s a infixl 4 <$ -- | Same as the usual *> except a Format is no -- Functor, let alone Applicative. (*>) :: (Applicative m, Applicative n, Semigroup s) => Format m n s () -> Format m n s a -> Format m n s a infixl 4 *> -- | Same as the usual <* except a Format is no -- Functor, let alone Applicative. (<*) :: (Applicative m, Applicative n, Semigroup s) => Format m n s a -> Format m n s () -> Format m n s a infixl 4 <* -- | Same as the usual <|> except a Format is no -- Functor, let alone Alternative. (<|>) :: (Alternative m, Alternative n) => Format m n s a -> Format m n s a -> Format m n s a infixl 3 <|> -- | A discriminated or tagged choice between two formats. (<+>) :: Alternative m => Format m n s a -> Format m n s b -> Format m n s (Either a b) -- | 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\""
--
() :: (Parsing m, AlternativeFail n) => Format m n s a -> String -> Format m n s a infixr 0 -- | Same as the usual empty except a Format is no -- Functor, let alone Alternative. empty :: (Alternative m, Alternative n) => Format m n s a -- | Same as the usual optional except a Format is no -- Functor, let alone Alternative. optional :: (Alternative m, Alternative n, Monoid s) => Format m n s a -> Format m n s (Maybe a) -- | Like optional except with arbitrary default serialization for -- the Nothing value. -- -- 
--   optional = optionWithDefault (literal mempty)
--
optionWithDefault :: (Alternative m, Alternative n) => Format m n s () -> Format m n s a -> Format m n s (Maybe a) -- | Combines two formats into a format for the pair of their values. -- -- 
--   >>> testParse (pair char char) "abc"
--   Right [(('a','b'),"c")]
--
pair :: (Applicative m, Applicative n, Semigroup s) => Format m n s a -> Format m n s b -> Format m n s (a, b) -- | 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")]
--
deppair :: (Monad m, Applicative n, Semigroup s) => Format m n s a -> (a -> Format m n s b) -> Format m n s (a, b) -- | Same as the usual many except a Format is no -- Functor, let alone Alternative. many :: (Alternative m, Applicative n, Monoid s) => Format m n s a -> Format m n s [a] -- | Same as the usual some except a Format is no -- Functor, let alone Alternative. some :: (Alternative m, AlternativeFail n, Semigroup s) => Format m n s a -> Format m n s [a] -- | 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. manyTill :: (Alternative m, Applicative n, Monoid s) => Format m n s a -> Format m n s () -> Format m n s [a] -- | 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"],"")]
--
sepBy :: (Alternative m, Applicative n, Monoid s) => Format m n s a -> Format m n s () -> Format m n s [a] -- | Sequence a list of formats into a list format. sequence :: forall m n s a. (Monad m, AlternativeFail n, Monoid s, Eq a, Show a) => [Format m n s a] -> Format m n s [a] -- | 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"
--
count :: (Applicative m, AlternativeFail n, Show a, Monoid s) => Int -> Format m n s a -> Format m n s [a] -- | Same as the usual mfix except a Format is no -- Functor, let alone Monad. mfix :: MonadFix m => (a -> Format m n s a) -> Format m n s a -- | Converts a record of field formats into a single format of the whole -- record. record :: (Apply g, Traversable g, FixTraversable m, Applicative n, Monoid s) => g (Format m n s) -> Format m n s (g Identity) -- | Converts a record of field formats into a single format of the whole -- record, a generalized form of record. recordWith :: forall g m n o s. (Apply g, Traversable g, FixTraversable m, Applicative n, Monoid s, Applicative o) => (forall a. o (n a) -> n a) -> g (Format m n s) -> Format m n s (g o) -- | 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])]
--
mapSerialized :: (Monoid s, Monoid t, InputParsing (m s), InputParsing (m t), s ~ ParserInput (m s), t ~ ParserInput (m t), InputMappableParsing m, Functor n) => (s -> t) -> (t -> s) -> Format (m s) n s a -> Format (m t) n t a -- | 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. mapMaybeSerialized :: (Monoid s, Monoid t, InputParsing (m s), InputParsing (m t), s ~ ParserInput (m s), t ~ ParserInput (m t), InputMappableParsing m, Functor n) => (s -> Maybe t) -> (t -> Maybe s) -> Format (m s) n s a -> Format (m t) n t a -- | 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"
--
mapValue :: Functor m => (a -> b) -> (b -> a) -> Format m n s a -> Format m n s b -- | 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. mapMaybeValue :: (Monad m, Parsing m, Show a, Show b, AlternativeFail n) => (a -> Maybe b) -> (b -> Maybe a) -> Format m n s a -> Format m n s b -- | 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")]
--
satisfy :: (Parsing m, Monad m, AlternativeFail n, Show a) => (a -> Bool) -> Format m n s a -> Format m n s a -- | A fixed expected value serialized through the argument format -- -- 
--   >>> testParse (value char 'a') "bcd"
--   Left "encountered 'b'"
--   
--   >>> testParse (value char 'a') "abc"
--   Right [((),"bc")]
--
value :: (Eq a, Show a, Parsing m, Monad m, Alternative n) => Format m n s a -> a -> Format m n s () -- | 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--"
--
padded :: (Monad m, Functor n, InputParsing m, ParserInput m ~ s, FactorialMonoid s) => s -> Format m n s s -> Format m n s s -- | 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. padded1 :: (Monad m, Monad n, InputParsing m, ParserInput m ~ s, FactorialMonoid s, Show s, AlternativeFail n) => s -> Format m n s s -> Format m n s s -- | A literal serialized form, such as a magic constant, corresponding to -- no value -- -- 
--   >>> testParse (literal "Hi") "Hi there"
--   Right [(()," there")]
--
literal :: (Functor m, InputParsing m, Applicative n, ParserInput m ~ s) => s -> Format m n s () -- | A trivial format for a single byte in a ByteString -- -- 
--   >>> testParse byte (ByteString.pack [1,2,3])
--   Right [(1,"\STX\ETX")]
--
byte :: (InputParsing m, ParserInput m ~ ByteString, Applicative n) => Format m n ByteString Word8 -- | A trivial format for a single character -- -- 
--   >>> testParse char "abc"
--   Right [('a',"bc")]
--
char :: (CharParsing m, ParserInput m ~ s, IsString s, Applicative n) => Format m n s Char -- | 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"
--
cereal :: (Serialize a, Monad m, InputParsing m, ParserInput m ~ ByteString, Applicative n) => Format m n ByteString a -- | Specifying a formatter explicitly using the cereal getter and putter -- -- 
--   >>> testParse (cereal' getWord16le putWord16le) (ByteString.pack [1,2,3])
--   Right [(513,"\ETX")]
--
cereal' :: (Monad m, InputParsing m, ParserInput m ~ ByteString, Applicative n) => Get a -> Putter a -> Format m n ByteString a -- | 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\""
--
take :: (InputParsing m, ParserInput m ~ s, FactorialMonoid s, Show s, AlternativeFail n) => Int -> Format m n s s -- | 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 ""
--
takeWhile :: (InputParsing m, ParserInput m ~ s, FactorialMonoid s, Show s, AlternativeFail n) => (s -> Bool) -> Format m n s s -- | 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"
--
takeWhile1 :: (InputParsing m, ParserInput m ~ s, FactorialMonoid s, Show s, AlternativeFail n) => (s -> Bool) -> Format m n s s -- | 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 ""
--
takeCharsWhile :: (InputCharParsing m, ParserInput m ~ s, TextualMonoid s, Show s, AlternativeFail n) => (Char -> Bool) -> Format m n s s -- | 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 \"\""
--
takeCharsWhile1 :: (InputCharParsing m, ParserInput m ~ s, TextualMonoid s, Show s, AlternativeFail n) => (Char -> Bool) -> Format m n s s -- | Attempts to parse the given input with the format with a -- constrained type, returns either a failure message or a list of -- successes. testParse :: Monoid s => Format (Parser Symmetric s) (Either Error) s a -> s -> Either String [(a, s)] -- | A less polymorphic wrapper around serialize useful for testing testSerialize :: Format (Parser Symmetric s) (Either Error) s a -> a -> Either String s -- | This module exports the primitives and combinators for constructing -- formats with sub- or cross-byte components. See test/MBR.hs -- for an example of its use. -- -- 
--   >>> testParse (bigEndianBytesOf $ pair (count 5 bit) (count 3 bit)) (ByteString.pack [9])
--   Right [(([False,False,False,False,True],[False,False,True]),"")]
--
module Construct.Bits -- | The list of bits type Bits = [Bool] -- | The primitive format of a single bit -- -- 
--   >>> testParse bit [True, False, False, True]
--   Right [(True,[False,False,True])]
--
bit :: (Applicative n, InputParsing m, ParserInput m ~ Bits) => Format m n Bits Bool bigEndianBitsOf :: (InputParsing (m Bits), InputParsing (m ByteString), InputMappableParsing m, Functor n, ParserInput (m Bits) ~ Bits, ParserInput (m ByteString) ~ ByteString) => Format (m ByteString) n ByteString a -> Format (m Bits) n Bits a bigEndianBytesOf :: (InputParsing (m Bits), InputParsing (m ByteString), InputMappableParsing m, Functor n, ParserInput (m Bits) ~ Bits, ParserInput (m ByteString) ~ ByteString) => Format (m Bits) n Bits a -> Format (m ByteString) n ByteString a littleEndianBitsOf :: (InputParsing (m Bits), InputParsing (m ByteString), InputMappableParsing m, Functor n, ParserInput (m Bits) ~ Bits, ParserInput (m ByteString) ~ ByteString) => Format (m ByteString) n ByteString a -> Format (m Bits) n Bits a littleEndianBytesOf :: (InputParsing (m Bits), InputParsing (m ByteString), InputMappableParsing m, Functor n, ParserInput (m Bits) ~ Bits, ParserInput (m ByteString) ~ ByteString) => Format (m Bits) n Bits a -> Format (m ByteString) n ByteString a