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

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

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

-- | When the right argument fails: apply the left argument to the list of
--   error messages.
(<??>) :: ([String] -> [String]) -> 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]

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


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

-- | Take some digits and parse a number
integerDecimal :: 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 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
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]
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 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 ()


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

-- | When the right argument fails: apply the left argument to the list of
--   error messages.
(<??>) :: ([String] -> [String]) -> 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 ()

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