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


-- | Incremental multiple pass parser library.
--   
--   A combinator library for incremental multiple pass parsers. Mostly
--   inspired by the Text.ParserCombinators.ReadP module in the Base
--   package and the conduit package. It has similar capabilities to ReadP
--   as well as more detailed error reporting and the capacity for multiple
--   passes (such as lexing and parsing)
@package phaser
@version 1.0.0.1


-- | Core functions and types.
module Codec.Phaser.Core

-- | Represents a nondeterministic computation in progress. There are 4
--   type parameters: a counter type (may be used for tracking line and
--   column numbers), an input type, an incremental output type, and a
--   final output type.
data Automaton p i o a

-- | A type for building <a>Automaton</a> values. <a>Monad</a> and
--   <a>Applicative</a> instances are defined for this type rather than for
--   <a>Automaton</a> in order to avoid traversing the entire call stack
--   for every input value.
data Phase p i o a

-- | Return one item of the input.
get :: Phase p i o i

-- | Put a list of values back into the input.
put :: (Monoid p) => [i] -> Phase p i o ()

-- | Insert one value back into the input. May be used for implementing
--   lookahead
put1 :: (Monoid p) => i -> Phase p i o ()

-- | Modify the counter
count :: p -> Phase p i o ()

-- | Yield one item for the incremental output
yield :: o -> Phase p i o ()

-- | Fail if any more input is provided.
eof :: (Monoid p) => Phase p i o ()

-- | Fail unless more input is provided.
neof :: (Monoid p) => Phase p i o ()

-- | If parsing fails in the right argument: prepend the left argument to
--   the errors
(<?>) :: [Char] -> Phase p i o a -> Phase p i o a
infixr 1 <?>

-- | Take the incremental output of the first argument and use it as input
--   for the second argument. Discard the final output of the first
--   argument.
(>>#) :: (Monoid p, PhaserType s, PhaserType d) => s p b c x -> d p c t a -> Automaton p b t a
infixr 4 >>#

-- | Change the counter type of a Phaser object.
(>#>) :: (PhaserType s, Monoid p0, Monoid p) => (p0 -> p) -> s p0 i o a -> s p i o a
infixr 1 >#>

-- | Remove an <tt>Automaton'</tt>s ability to consume further input
starve :: (Monoid p) => Automaton p i o a -> Automaton p z o a

-- | Class for types which consume and produce incremental input and
--   output.
class PhaserType s
toAutomaton :: (PhaserType s, Monoid p) => s p i o a -> Automaton p i o a
fromAutomaton :: (PhaserType s, Monoid p) => Automaton p i o a -> s p i o a
toPhase :: (PhaserType s, Monoid p) => s p i o a -> Phase p i o a
fromPhase :: (PhaserType s, Monoid p) => Phase p i o a -> s p i o a
($#$) :: (PhaserType s, Monoid p) => s p b c x -> (c -> t) -> s p b t x

-- | Take a <a>Phase</a> or <a>Automaton</a> which doesn't <a>yield</a>
--   anything and allow it to be used in a chain containing yield
--   statements
fitYield :: PhaserType s => s p i Void a -> s p i o a

-- | Optional pre-processing of an automaton before passing it more input.
--   Produces <a>Right</a> with all "final outputs" and errors stripped if
--   the automaton can accept more input, and <a>Left</a> with everything
--   except errors stripped if it cannot accept more input.
beforeStep :: (Monoid p) => Automaton p i o a -> Either (Automaton p v o a) (Automaton p i o a)

-- | Pass one input to an automaton
step :: (Monoid p) => Automaton p i o a -> i -> Automaton p i o a

-- | Take either counters with errors or a list of possible results from an
--   automaton.
extract :: (Monoid p) => p -> Automaton p i o a -> Either [(p, [String])] [a]

-- | Create a <a>ReadS</a> like value from a Phaser type. If the input type
--   is <a>Char</a>, the result will be <a>ReadS</a>
toReadS :: (PhaserType s, Monoid p) => s p i o a -> [i] -> [(a, [i])]

-- | Pass a list of input values to an <a>Automaton</a>
run :: (Monoid p) => Automaton p i o a -> [i] -> Automaton p i o a

-- | Use a <a>Phase</a> value similarly to a parser.
parse_ :: (Monoid p, PhaserType s) => p -> s p i o a -> [i] -> Either [(p, [String])] [a]

-- | Use a <a>Phase</a> as a parser, but consuming a single input instead
--   of a list
parse1_ :: (Monoid p, PhaserType s) => p -> s p i o a -> i -> Either [(p, [String])] [a]

-- | Decompose an <a>Automaton</a> into its component options.
options :: Automaton p i o a -> [Automaton p i o a]

-- | Separate unconditional counter modifiers from an automaton
readCount :: (Monoid p) => Automaton p i o a -> (p, Automaton p i o a)

-- | Separate the values unconditionally yielded by an automaton
outputs :: (Monoid p) => Automaton p i o a -> ([o], Automaton p i o a)

-- | Run a Phaser object on input values produced by a monadic action and
--   passing the output values to another monadic function. The input
--   action should return <a>Nothing</a> when there is no more input. If
--   there is more than one final result: the left one is chosen, and all
--   the outputs leading to it are also output.
stream :: (Monoid p, PhaserType s, Monad m) => p -> s p i o a -> m (Maybe [i]) -> ([o] -> m ()) -> m (Either [(p, [String])] a)
instance GHC.Base.Functor (Codec.Phaser.Core.Phase p i o)
instance GHC.Base.Applicative (Codec.Phaser.Core.Phase p i o)
instance GHC.Base.Monad (Codec.Phaser.Core.Phase p i o)
instance GHC.Base.Monoid p => GHC.Base.Alternative (Codec.Phaser.Core.Phase p i o)
instance GHC.Base.Monoid p => GHC.Base.MonadPlus (Codec.Phaser.Core.Phase p i o)
instance GHC.Base.Functor (Codec.Phaser.Core.Automaton p i o)
instance Codec.Phaser.Core.PhaserType Codec.Phaser.Core.Phase
instance Codec.Phaser.Core.PhaserType Codec.Phaser.Core.Automaton


-- | <a>Phase</a>s for processing <a>Text</a> objects and their lazy
--   versions.
module Codec.Phaser.Text

-- | A <a>Phase</a> which takes <a>Text</a>s and yields their individual
--   characters
unpackText :: (Monoid p) => Phase p Text Char ()

-- | A <a>Phase</a> which takes <a>Text</a>s and yields their individual
--   characters
unpackLazyText :: (Monoid p) => Phase p Text Char ()


-- | <a>Phase</a>s for decoding bytes to characters using UTF-8
module Codec.Phaser.UTF8

-- | Consume a UTF-8 character from a stream of bytes and return it. Fail
--   on invalid UTF-8.
utf8_char :: (Monoid p) => Phase p Word8 o Char

-- | Consume any number of UTF-8 characters and yield them.
utf8_stream :: (Monoid p) => Phase p Word8 Char ()

-- | Consume any number of Characters and yield them as UTF-8 bytes
utf8_encode :: (Monoid p) => Phase p Char Word8 ()


-- | <a>Phase</a>s for processing bytestrings.
module Codec.Phaser.ByteString

-- | A <a>Phase</a> which takes <a>ByteString</a>s as input and yields
--   their individual bytes.
unpackBS :: (Monoid p) => Phase p ByteString Word8 ()

-- | A <a>Phase</a> which takes lazy <a>ByteString</a>s as input and yields
--   their individual bytes.
unpackLBS :: (Monoid p) => Phase p ByteString Word8 ()

-- | Run a parser on input from a file. Input is provided as bytes, if
--   characters are needed: a decoding phase such as <a>utf8_stream</a> or
--   <tt>latin1</tt> may be used. Counter type agnostic version.
parseFile_ :: (Monoid p, PhaserType s) => p -> s p Word8 o a -> FilePath -> IO (Either [(p, [String])] [a])


-- | Common functions which do not need to be in <a>Core</a>, mostly for
--   using <a>Phase</a>s and <a>Automaton</a>s as parsers.
module Codec.Phaser.Common

-- | A data type for describing a position in a text file. Constructor
--   arguments are row number and column number.
data Position
Position :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Position

-- | Class for types which consume and produce incremental input and
--   output.
class PhaserType s
toAutomaton :: (PhaserType s, Monoid p) => s p i o a -> Automaton p i o a
fromAutomaton :: (PhaserType s, Monoid p) => Automaton p i o a -> s p i o a
toPhase :: (PhaserType s, Monoid p) => s p i o a -> Phase p i o a
fromPhase :: (PhaserType s, Monoid p) => Phase p i o a -> s p i o a
($#$) :: (PhaserType s, Monoid p) => s p b c x -> (c -> t) -> s p b t x

-- | Class for types which have standardized or otherwise unambiguous
--   representations. Implementations of <a>regular</a> may be more
--   permissive than the corresponding <a>Read</a> instance (if any).
class Standardized r a
regular :: (Standardized r a, Monoid p) => Phase p r o a

-- | Tries in this module can be used for creating more efficient parsers
--   when several of the recognized strings begin with the same few
--   characters
data Trie c a

-- | Create a trie which maps a single string to an object. Analogous to
--   <a>singleton</a>.
newTrie :: Ord c => [c] -> a -> Trie c a

-- | Create a <a>Phase</a> or <a>Automaton</a> from a <a>Trie</a>
fromTrie :: (Monoid p, PhaserType s, Ord c) => Trie c a -> s p c o a

-- | Consume one input, return it if it matches the predicate, otherwise
--   fail.
satisfy :: (Monoid p) => (i -> Bool) -> Phase p i o i

-- | Consume one input, if it's equal to the parameter then return it,
--   otherwise fail.
match :: (Eq i, Monoid p) => i -> Phase p i o i

-- | <a>match</a> specialized to <a>Char</a>
char :: (Monoid p) => Char -> Phase p Char o Char

-- | Case insensitive version of <a>char</a>
iChar :: (Monoid p) => Char -> Phase p Char o Char

-- | Match a list of input values
string :: (Eq i, Monoid p) => [i] -> Phase p i o [i]

-- | Match a string (case insensitive)
iString :: (Monoid p) => String -> Phase p Char o String

-- | Parse a standard base 10 integer
integerDecimal :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a standard positive base 10 integer
positiveIntegerDecimal :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a number from decimal digits, "-", and "."
decimal :: (Fractional a, Monoid p) => Phase p Char o a

-- | Parse a number from standard decimal format or from scientific
--   notation.
scientificNotation :: (Fractional a, Monoid p) => Phase p Char o a

-- | Take some hexadecimal digits and parse a number from hexadecimal
directHex :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a hexadecimal number prefixed with <a>Ox</a>
hex :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a positive integer from either decimal or hexadecimal format
positiveInteger :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a number either from decimal digits or from hexadecimal prefixed
--   with "0x"
integer :: (Num a, Monoid p) => Phase p Char o a

-- | Move the position counter one character to the right
countChar :: Phase Position i o ()

-- | Move the position counter to the next line
countLine :: Phase Position i o ()

-- | Count the lines and characters from the input before yielding them
--   again. If the phase pipeline does not include this or similar: parsing
--   errors will not report the correct position. Unix, Windows, Mac-OS
--   Classic, and Acorn newline formats are all recognized.
trackPosition :: Phase Position Char Char ()

-- | Converts all line separators into Unix format.
normalizeNewlines :: Monoid p => Phase p Char Char ()

-- | Use a <a>Phase</a> as a parser. Note that unlike other parsers the
--   reported position in the input when the parser fails is the position
--   reached when all parsing options are exhausted, not the beginning of
--   the failing token. Since the characters may be counted
--   nondeterministically: if multiple errors are returned the reported
--   error position may be different for each error report.
parse :: (PhaserType s) => s Position i o a -> [i] -> Either [(Position, [String])] [a]

-- | sepBy p sep parses zero or more occurrences of p, separated by sep.
--   Returns a list of values returned by p.
sepBy :: Monoid p => Phase p i o a -> Phase p i o s -> Phase p i o [a]

-- | sepBy1 p sep parses one or more occurrences of p, separated by sep.
--   Returns a list of values returned by p.
sepBy1 :: Monoid p => Phase p i o a -> Phase p i o s -> Phase p i o [a]

-- | Parses the first zero or more values satisfying the predicate. Always
--   succeds, exactly once, having consumed all the characters Hence NOT
--   the same as (many (satisfy p))
munch :: Monoid p => (i -> Bool) -> Phase p i o [i]

-- | Parses the first one or more values satisfying the predicate. Succeeds
--   if at least one value matches, having consumed all the characters
--   Hence NOT the same as (some (satisfy p))
munch1 :: Monoid p => (i -> Bool) -> Phase p i o [i]

-- | Run a parser on input from a file. Input is provided as bytes, if
--   characters are needed: a decoding phase such as <a>utf8_stream</a> or
--   <a>latin1</a> may be used
parseFile :: (PhaserType s) => s Position Word8 o a -> FilePath -> IO (Either [(Position, [String])] [a])

-- | Decode bytes to characters using the Latin1 (ISO8859-1) encoding
latin1 :: Monoid p => Phase p Word8 Char ()
instance GHC.Classes.Ord Codec.Phaser.Common.Position
instance GHC.Classes.Eq Codec.Phaser.Common.Position
instance GHC.Show.Show Codec.Phaser.Common.Position
instance GHC.Read.Read Codec.Phaser.Common.Position
instance GHC.Base.Monoid Codec.Phaser.Common.Position
instance GHC.Classes.Ord c => GHC.Base.Monoid (Codec.Phaser.Common.Trie c a)
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Types.Int
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Integer.Type.Integer
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Types.Word
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Word.Word8
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Word.Word16
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Word.Word32
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Word.Word64
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Int.Int8
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Int.Int16
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Int.Int32
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Int.Int64
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Types.Float
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Types.Double
instance (GHC.Real.Integral a, Codec.Phaser.Common.Standardized GHC.Types.Char a) => Codec.Phaser.Common.Standardized GHC.Types.Char (GHC.Real.Ratio a)
instance Codec.Phaser.Common.Standardized GHC.Types.Char GHC.Types.Bool

module Codec.Phaser.UTF16

-- | Consume one or two 16 bit words and decode to a <a>Char</a> using
--   UTF-16
utf16_char :: Monoid p => Phase p Word16 o Char
utf16_word16_stream :: Monoid p => Phase p Word16 Char ()

-- | Decode bytes to characters using UTF-16, using the byte order mark to
--   detect endianness.
utf16_stream_useBOM :: Monoid p => Phase p Word8 Char ()

-- | Decode bytes to characters using UTF-16, little endian mode
utf16_stream_le :: Monoid p => Automaton p Word8 Char ()

-- | Decode bytes to characters using UTF-16, big endian mode
utf16_stream_be :: Monoid p => Automaton p Word8 Char ()

-- | Decode bytes to characters using UTF-16, using byte order mark if
--   available, otherwise trying both byte orders. Downstream parser may be
--   used to disambiguate.
utf16_stream_unknown :: Monoid p => Phase p Word8 Char ()
utf16_word16_stream :: Monoid p => Phase p Word16 Char ()

-- | Encode a stream of characters to bytes using UTF-16, big endian
--   without the byte order mark.
utf16_encode_stream_be_nobom :: Monoid p => Automaton p Char Word8 ()

-- | Encode a stream of characters to bytes using UTF-16, little endian
--   without the byte order mark.
utf16_encode_stream_le_nobom :: Monoid p => Automaton p Char Word8 ()

-- | Encode a stream of characters to bytes using UTF-16, little endian
--   including the byte order mark.
utf16_encode_stream_be :: Monoid p => Automaton p Char Word8 ()

-- | Encode a stream of characters to bytes using UTF-16, big endian
--   including the byte order mark.
utf16_encode_stream_le :: Monoid p => Automaton p Char Word8 ()


module Codec.Phaser

-- | A type for building <a>Automaton</a> values. <a>Monad</a> and
--   <a>Applicative</a> instances are defined for this type rather than for
--   <a>Automaton</a> in order to avoid traversing the entire call stack
--   for every input value.
data Phase p i o a

-- | Represents a nondeterministic computation in progress. There are 4
--   type parameters: a counter type (may be used for tracking line and
--   column numbers), an input type, an incremental output type, and a
--   final output type.
data Automaton p i o a

-- | A data type for describing a position in a text file. Constructor
--   arguments are row number and column number.
data Position
Position :: {-# UNPACK #-} !Int -> {-# UNPACK #-} !Int -> Position

-- | Take the incremental output of the first argument and use it as input
--   for the second argument. Discard the final output of the first
--   argument.
(>>#) :: (Monoid p, PhaserType s, PhaserType d) => s p b c x -> d p c t a -> Automaton p b t a
infixr 4 >>#

-- | Change the counter type of a Phaser object.
(>#>) :: (PhaserType s, Monoid p0, Monoid p) => (p0 -> p) -> s p0 i o a -> s p i o a
infixr 1 >#>

-- | If parsing fails in the right argument: prepend the left argument to
--   the errors
(<?>) :: [Char] -> Phase p i o a -> Phase p i o a
infixr 1 <?>
($#$) :: (PhaserType s, Monoid p) => s p b c x -> (c -> t) -> s p b t x

-- | Use a <a>Phase</a> as a parser. Note that unlike other parsers the
--   reported position in the input when the parser fails is the position
--   reached when all parsing options are exhausted, not the beginning of
--   the failing token. Since the characters may be counted
--   nondeterministically: if multiple errors are returned the reported
--   error position may be different for each error report.
parse :: (PhaserType s) => s Position i o a -> [i] -> Either [(Position, [String])] [a]

-- | Use a <a>Phase</a> value similarly to a parser.
parse_ :: (Monoid p, PhaserType s) => p -> s p i o a -> [i] -> Either [(p, [String])] [a]

-- | Return one item of the input.
get :: Phase p i o i

-- | Modify the counter
count :: p -> Phase p i o ()

-- | Yield one item for the incremental output
yield :: o -> Phase p i o ()

-- | Insert one value back into the input. May be used for implementing
--   lookahead
put1 :: (Monoid p) => i -> Phase p i o ()

-- | Put a list of values back into the input.
put :: (Monoid p) => [i] -> Phase p i o ()

-- | Pass a list of input values to an <a>Automaton</a>
run :: (Monoid p) => Automaton p i o a -> [i] -> Automaton p i o a

-- | Pass one input to an automaton
step :: (Monoid p) => Automaton p i o a -> i -> Automaton p i o a

-- | Take either counters with errors or a list of possible results from an
--   automaton.
extract :: (Monoid p) => p -> Automaton p i o a -> Either [(p, [String])] [a]

-- | Consume one input, return it if it matches the predicate, otherwise
--   fail.
satisfy :: (Monoid p) => (i -> Bool) -> Phase p i o i

-- | Consume one input, if it's equal to the parameter then return it,
--   otherwise fail.
match :: (Eq i, Monoid p) => i -> Phase p i o i

-- | <a>match</a> specialized to <a>Char</a>
char :: (Monoid p) => Char -> Phase p Char o Char

-- | Case insensitive version of <a>char</a>
iChar :: (Monoid p) => Char -> Phase p Char o Char

-- | Match a list of input values
string :: (Eq i, Monoid p) => [i] -> Phase p i o [i]

-- | Match a string (case insensitive)
iString :: (Monoid p) => String -> Phase p Char o String

-- | Parse a number either from decimal digits or from hexadecimal prefixed
--   with "0x"
integer :: (Num a, Monoid p) => Phase p Char o a

-- | Parse a number from decimal digits, "-", and "."
decimal :: (Fractional a, Monoid p) => Phase p Char o a

-- | Parse a number from standard decimal format or from scientific
--   notation.
scientificNotation :: (Fractional a, Monoid p) => Phase p Char o a

-- | sepBy p sep parses zero or more occurrences of p, separated by sep.
--   Returns a list of values returned by p.
sepBy :: Monoid p => Phase p i o a -> Phase p i o s -> Phase p i o [a]

-- | Parses the first zero or more values satisfying the predicate. Always
--   succeds, exactly once, having consumed all the characters Hence NOT
--   the same as (many (satisfy p))
munch :: Monoid p => (i -> Bool) -> Phase p i o [i]

-- | Parses the first one or more values satisfying the predicate. Succeeds
--   if at least one value matches, having consumed all the characters
--   Hence NOT the same as (some (satisfy p))
munch1 :: Monoid p => (i -> Bool) -> Phase p i o [i]

-- | Count the lines and characters from the input before yielding them
--   again. If the phase pipeline does not include this or similar: parsing
--   errors will not report the correct position. Unix, Windows, Mac-OS
--   Classic, and Acorn newline formats are all recognized.
trackPosition :: Phase Position Char Char ()