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


-- | A simple parser-combinator library, a bit like Parsec but without the frills
--   
@package parcom-lib
@version 0.8.0.3

module Text.Parcom.Internal
formatOptionList :: [String] -> String


-- | Typeclasses to describe various aspects of parsable streams and
--   tokens. The standard range of Haskell string-like types
--   (<a>String</a>, and both the lazy and strict flavors of
--   <tt>ByteString</tt> and <tt>Text</tt>) is supported already, as well
--   as any <tt>List</tt>, so under normal circumstances, you should not
--   need to touch this module directly.
module Text.Parcom.Stream

-- | Typeclass for types that are suitable as source streams. Note that
--   implementing just <a>Stream</a> gives you only a small subset of
--   Parcom's features; if you want to implement your own <a>Stream</a>
--   instances, you will most likely also want to implement <a>Token</a>
--   for the corresponding token type, <a>Listish</a> to enable parsers
--   that need to convert to or from lists of tokens, and <a>Textish</a> to
--   enable parsers that work on Unicode text.
class Stream s t | s -> t where consume = snd . pop pop s = (peek s, consume s)
peek :: Stream s t => s -> t
atEnd :: Stream s t => s -> Bool
consume :: Stream s t => s -> s
pop :: Stream s t => s -> (t, s)

-- | All lists are instances of <a>Stream</a>, and the corresponding token
--   type is the list element type. Obviously, this also includes
--   <a>String</a> ('[Char]') and '[Word8]'

-- | This typeclass is pretty much required to do anything useful with
--   Parcom; it is needed for Parcom to detect line endings so that parser
--   errors will report the correct source positions. If you need to parse
--   streams that do not support any meaningful concept of lines, consider
--   implementing a dummy instance, like so: <tt> instance Token Foobar
--   where isLineDelimiter _ = False </tt> This will treat the entire input
--   as a single line.
class Token t
isLineDelimiter :: Token t => t -> Bool

-- | Unicode characters are valid tokens.

-- | List-like types.
class Listish s t | s -> t
toList :: Listish s t => s -> [t]
fromList :: Listish s t => [t] -> s

-- | Any list is trivially list-like

-- | Enables parsing on a per-character basis rather than per-token. For
--   stream types where the token type is <a>Char</a> already, this is
--   trivial, but for other streams (e.g., bytestrings), some extra
--   processing is required to perform a conversion to Unicode.
class Textish s
peekChar :: Textish s => s -> (Maybe Char, Int)
instance Textish [Char]
instance Listish [a] a
instance Token Char
instance Stream [a] a

module Text.Parcom.Word8
instance Token Word8

module Text.Parcom.ByteString.Strict
instance Textish ByteString
instance Listish ByteString Word8
instance Stream ByteString Word8

module Text.Parcom.ByteString

module Text.Parcom.ByteString.Lazy
instance Textish ByteString
instance Listish ByteString Word8
instance Stream ByteString Word8

module Text.Parcom.Text.Strict
instance Textish Text
instance Listish Text Char
instance Stream Text Char

module Text.Parcom.Text

module Text.Parcom.Text.Lazy
instance Textish Text
instance Listish Text Char
instance Stream Text Char


-- | The core functionality of a Parcom parser: defining and running
--   parsers, lifting, getting tokens and characters from a stream, and the
--   most basic primitive parsers and combinators that cannot easily be
--   expressed in terms of other parsers and combinators.
module Text.Parcom.Core

-- | A parser error.
data ParcomError
ParcomError :: String -> SourcePosition -> ParcomError

-- | Human-readable description of the error
peErrorDescription :: ParcomError -> String

-- | Position in the source where the error was found.
peSourcePosition :: ParcomError -> SourcePosition

-- | Represents a position in a source file. Both lines and columns are
--   1-based.
data SourcePosition
SourcePosition :: String -> Int -> Int -> SourcePosition
posFileName :: SourcePosition -> String
posLine :: SourcePosition -> Int
posColumn :: SourcePosition -> Int

-- | Parcom as a monad transformer. You can access the underlying monad
--   stack using the usual lifting techniques.
data ParcomT s t m a

-- | Run a parcom transformer and return the result
parseT :: (Stream s t, Token t, Monad m) => ParcomT s t m a -> String -> s -> m (Either ParcomError a)

-- | Parcom as a pure parser
type Parcom s t a = ParcomT s t Identity a

-- | Run a pure parcom parser and return the result
parse :: (Stream s t, Token t) => Parcom s t a -> String -> s -> Either ParcomError a

-- | Gets the next token from the stream without consuming it. Fails at
--   end-of-input.
peek :: (Monad m, Stream s t) => ParcomT s t m t

-- | Gets the next token from the stream and consumes it. Fails at
--   end-of-input.
next :: (Monad m, Stream s t, Token t) => ParcomT s t m t

-- | Checks whether end-of-input has been reached.
atEnd :: (Monad m, Stream s t) => ParcomT s t m Bool

-- | Backtracking modifier; restores the parser state to the previous
--   situation if the wrapped parser fails.
try :: Monad m => ParcomT s t m a -> ParcomT s t m a

-- | Wrap a raw parser to allow handling success and failure. The error and
--   success handlers take the error or parsed value, respectively, and
--   return a parser that should be applied in the error or success case,
--   respectively. No backtracking is performed.
handle :: Monad m => ParcomT s t m a -> (ParcomError -> ParcomT s t m b) -> (a -> ParcomT s t m b) -> ParcomT s t m b

-- | Same as <a>handle</a>, but backtrack on error (that is, if the raw
--   parser fails, any input it has consumed is restored.
handleB :: Monad m => ParcomT s t m a -> (ParcomError -> ParcomT s t m b) -> (a -> ParcomT s t m b) -> ParcomT s t m b

-- | Succeeds iff the given parser fails
notFollowedBy :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m ()

-- | Tags a parser with a human-readable description of the expected
--   entity, generating an "Expected {entity}" type error message on
--   failure.
(<?>) :: (Monad m, Stream s t) => ParcomT s t m a -> String -> ParcomT s t m a

-- | An associative binary operation
(<|>) :: Alternative f => forall a. f a -> f a -> f a

-- | The identity of <a>&lt;|&gt;</a>
empty :: Alternative f => forall a. f a

-- | Typeclass for types that are suitable as source streams. Note that
--   implementing just <a>Stream</a> gives you only a small subset of
--   Parcom's features; if you want to implement your own <a>Stream</a>
--   instances, you will most likely also want to implement <a>Token</a>
--   for the corresponding token type, <a>Listish</a> to enable parsers
--   that need to convert to or from lists of tokens, and <a>Textish</a> to
--   enable parsers that work on Unicode text.
class Stream s t | s -> t where consume = snd . pop pop s = (peek s, consume s)

-- | This typeclass is pretty much required to do anything useful with
--   Parcom; it is needed for Parcom to detect line endings so that parser
--   errors will report the correct source positions. If you need to parse
--   streams that do not support any meaningful concept of lines, consider
--   implementing a dummy instance, like so: <tt> instance Token Foobar
--   where isLineDelimiter _ = False </tt> This will treat the entire input
--   as a single line.
class Token t

-- | List-like types.
class Listish s t | s -> t

-- | Enables parsing on a per-character basis rather than per-token. For
--   stream types where the token type is <a>Char</a> already, this is
--   trivial, but for other streams (e.g., bytestrings), some extra
--   processing is required to perform a conversion to Unicode.
class Textish s

-- | Get one character from the stream, but do not consume it. Fails when
--   the input stream contains a sequence that does not represent a valid
--   character, or when the end of the input stream has been reached.
peekChar :: (Monad m, Stream s t, Token t, Textish s) => ParcomT s t m Char

-- | Get one character from the stream, and consume it. Fails when the
--   input stream contains a sequence that does not represent a valid
--   character, or when the end of the input stream has been reached.
nextChar :: (Monad m, Stream s t, Token t, Textish s) => ParcomT s t m Char
instance Show SourcePosition
instance Show ParcomError
instance Monad m => Alternative (ParcomT s t m)
instance Monad m => Applicative (ParcomT s t m)
instance Monad m => Functor (ParcomT s t m)
instance MonadTrans (ParcomT s t)
instance Monad m => Monad (ParcomT s t m)


-- | A collection of predefined combinators. Use these to combine other
--   parsers into more complex ones.
module Text.Parcom.Combinators

-- | Walk a list of options, return the first one that succeeds.
choice :: (Monad m, Stream s t) => [ParcomT s t m a] -> ParcomT s t m a

-- | Like <a>choice</a>, but each choice tagged with a human-readable name
--   for better error reporting.
namedChoice :: (Monad m, Stream s t) => [(String, ParcomT s t m a)] -> ParcomT s t m a

-- | Match two consecutive parser, return the first parser's result iff
--   both succeed.
before :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m b -> ParcomT s t m a

-- | Match three consecutive parsers, return the middle parser's result iff
--   all three match. Parsers are given in the order inner, left, right.
between :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m l -> ParcomT s t m r -> ParcomT s t m a

-- | Match zero or more occurrences of a parser
many :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m [a]

-- | Match one or more occurrences of a parser
many1 :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m [a]

-- | Given an item parser and a separator parser, keep parsing until the
--   separator or the item fails.
manySepBy :: (Monad m, Stream s t) => ParcomT s t m a -> ParcomT s t m b -> ParcomT s t m [a]

-- | Run the given parser n times, returning all the results as a list.
times :: (Monad m, Stream s t) => Int -> ParcomT s t m a -> ParcomT s t m [a]

-- | Ignore the result of a parser.
skip :: Monad m => ParcomT s t m a -> ParcomT s t m ()

-- | Optional parsing to Maybe
possibly :: Monad m => ParcomT s t m a -> ParcomT s t m (Maybe a)

-- | Optional parsing with default
optional :: Monad m => a -> ParcomT s t m a -> ParcomT s t m a

-- | Optional parsing, ignoring (but consuming) result
option :: Monad m => ParcomT s t m a -> ParcomT s t m ()


-- | Primitive parsers.
--   
--   Regarding consuming input, unless states otherwise, all of these
--   behave as follows:
--   
--   <ul>
--   <li>If a parser succeeds, it consumes the input it matches</li>
--   <li>If a parser fails, it does not consume any input at all</li>
--   </ul>
module Text.Parcom.Prim

-- | Gets the next token from the stream
anyToken :: (Monad m, Stream s t, Token t) => ParcomT s t m t

-- | Matches one token against a list of possible tokens; returns the
--   matching token or fails.
oneOf :: (Monad m, Stream s t, Token t, Show t, Eq t) => [t] -> ParcomT s t m t

-- | Matches one token against a list of prohibited tokens; returns the
--   non-matching token or fails.
noneOf :: (Monad m, Stream s t, Token t, Show t, Eq t) => [t] -> ParcomT s t m t

-- | Succeeds iff end-of-input has been reached
eof :: (Monad m, Stream s t, Token t) => ParcomT s t m ()

-- | Succeeds if the given predicate is met for the next token.
satisfy :: (Monad m, Stream s t, Token t) => (t -> Bool) -> ParcomT s t m t

-- | Exactly match one particular token
token :: (Monad m, Stream s t, Token t, Show t, Eq t) => t -> ParcomT s t m t

-- | Match a series of tokens exactly
tokens :: (Monad m, Stream s t, Token t, Eq t, Show t) => [t] -> ParcomT s t m [t]

-- | Match a series of tokens exactly. Unlike <a>tokens</a>, this parser
--   accepts the target sequence by the stream's type instead of
--   list-of-tokens. Depending on the stream's <a>Listish</a>
--   implementation, this may be more efficient than matching and consuming
--   the tokens one-by-one, as <a>tokens</a> does.
prefix :: (Monad m, Stream s t, Token t, Eq t, Show t, Listish s t) => s -> ParcomT s t m s

module Text.Parcom.Textual
string :: (Monad m, Stream s t, Listish s t, IsString s, Eq t, Show t, Token t) => String -> ParcomT s t m String
char :: (Monad m, Stream s t, Listish s t, IsString s, Eq t, Show t, Token t) => Char -> ParcomT s t m Char


-- | A parser-combinator library.
--   
--   The primary goal in writing Parcom was to facilitate parsing Unicode
--   string data from various source streams, including raw
--   <a>ByteString</a>s - while Attoparsec can parse <a>ByteString</a>s, it
--   sacrifices some convenience for performance, and using it to parse
--   textual data is not as comfortable as I would like; Parsec can handle
--   textual data much better, but it needs the input to be converetd to
--   Unicode for this to work nicely. Nonetheless, Parcom's interface is
--   quite obviously heavily inspired by both Parsec and Attoparsec.
--   
--   Parcom supports <a>String</a>, <a>ByteString</a> (lazy and strict) and
--   <a>Text</a> (lazy and strict) as its input format out-of-the-box. By
--   implementing one or more of the typeclasses in <a>Stream</a>, you can
--   extend Parcom to work on other input types as well.
module Text.Parcom