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


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

-- | Class for types which consume and produce incremental input and
--   output.
class Link s d l | s d -> l

-- | 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.
(>>#) :: Link s d l => s p b c x -> d p c t a -> l p b t a

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

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

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

-- | Modify the counter
count :: (p -> 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 :: Phase p i o ()

-- | When the right argument fails: apply the left argument to the list of
--   error messages. Depreciated because it doesn't work correctly for all
--   arguments and fixing it would break the <a>Alternative</a> and
--   <a>MonadPlus</a> instances.

-- | <i>Warning: <a>??</a> is faulty and will be removed in future
--   versions. Please use <a>?</a> instead</i>
(<??>) :: ([String] -> [String]) -> Phase p i o a -> Phase 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 <?>

-- | Change the counter type of a Phase object.
(>#>) :: ((p0 -> p0) -> p -> p) -> Phase p0 i o a -> Phase p i o a
infixr 1 >#>

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

-- | Convert a <a>Phase</a> to an <a>Automaton</a>. Subject to fusion.
toAutomaton :: Phase p i o a -> Automaton p i o a

-- | Convert an <a>Automaton</a> back to a <a>Phase</a> (somewhat
--   inefficient). Subject to fusion.
fromAutomaton :: Automaton p i o a -> Phase 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 :: Automaton p i o a -> Either (Automaton p v o a) (Automaton p i o a)

-- | Pass one input to an automaton
step :: 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 :: p -> Automaton p i o a -> Either [(p, [String])] [a]

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

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

-- | Use a <a>Phase</a> value similarly to a parser.
parse_ :: p -> Phase 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_ :: p -> Phase 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 :: Automaton p i o a -> (p -> p, Automaton p i o a)

-- | Separate the values unconditionally yielded by an automaton
outputs :: Automaton p i o a -> ([o], Automaton p i o 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.Alternative (Codec.Phaser.Core.Phase p i o)
instance 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.Link Codec.Phaser.Core.Phase Codec.Phaser.Core.Automaton Codec.Phaser.Core.Phase
instance Codec.Phaser.Core.Link Codec.Phaser.Core.Phase Codec.Phaser.Core.Phase Codec.Phaser.Core.Phase
instance Codec.Phaser.Core.Link Codec.Phaser.Core.Automaton Codec.Phaser.Core.Automaton 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 :: Phase p Text Char ()

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


-- | <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 :: Phase p ByteString Word8 ()

-- | A <a>Phase</a> which takes lazy <a>ByteString</a>s as input and yields
--   their individual bytes.
unpackLBS :: 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_ :: p -> Phase 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

-- | Consume one input, return it if it matches the predicate, otherwise
--   fail.
satisfy :: (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) => i -> Phase p i o i

-- | <a>match</a> specialized to <a>Char</a>
char :: Char -> Phase p Char o Char

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

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

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

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

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

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

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

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

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

-- | Parse a number either from decimal digits or from hexadecimal prefixed
--   with "0x"
integer :: Num a => 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.
trackPosition :: Phase Position 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 :: Phase 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 :: 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 :: 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 :: (i -> Bool) -> Phase p i o [i]

-- | Parses the first one or more values satisfying the predicate. Always
--   succeds, exactly once, having consumed all the characters Hence NOT
--   the same as (some (satisfy p))
munch1 :: (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 :: Phase Position Word8 o a -> FilePath -> IO (Either [(Position, [String])] [a])

-- | Decode bytes to characters using the Latin1 (ISO8859-1) encoding
latin1 :: 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


-- | <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 :: Phase p Word8 o Char

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


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.
(>>#) :: Link s d l => s p b c x -> d p c t a -> l p b t a

-- | Change the counter type of a Phase object.
(>#>) :: ((p0 -> p0) -> p -> p) -> Phase p0 i o a -> Phase 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 <?>

-- | 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 :: Phase Position i o a -> [i] -> Either [(Position, [String])] [a]

-- | Use a <a>Phase</a> value similarly to a parser.
parse_ :: p -> Phase 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 -> 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 :: i -> Phase p i o ()

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

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

-- | Pass one input to an automaton
step :: 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 :: p -> Automaton p i o a -> Either [(p, [String])] [a]

-- | Consume one input, return it if it matches the predicate, otherwise
--   fail.
satisfy :: (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) => i -> Phase p i o i

-- | <a>match</a> specialized to <a>Char</a>
char :: Char -> Phase p Char o Char

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

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

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

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

-- | Parse a number from decimal digits and "."
decimal :: Fractional a => 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 :: 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 :: (i -> Bool) -> Phase p i o [i]

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