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


-- | Library for invertible parsing and printing
--   
--   Specify a single unified grammar which can be used for parsing and
--   pretty-printing
@package boomerang
@version 1.4.9.4


-- | a simple heteregenous stack library
module Text.Boomerang.HStack

-- | A stack datatype. Just a better looking tuple.
data a :- b
(:-) :: a -> b -> (:-) a b
infixr 8 :-
infixr 8 :-
arg :: (ty -> r -> s) -> (a -> ty) -> (a :- r) -> s

-- | Applicative traversal over the top of the stack.
hdTraverse :: Functor f => (a -> f b) -> (a :- t) -> f (b :- t)

-- | Map over the top of the stack.
hdMap :: (a1 -> a2) -> (a1 :- b) -> a2 :- b

-- | Get the top of the stack.
hhead :: (a :- b) -> a

-- | Get the stack with the top popped.
htail :: (a :- b) -> b

-- | Stack destructor.
pop :: (a -> b -> r) -> (a :- b) -> r
instance (GHC.Classes.Eq a, GHC.Classes.Eq b) => GHC.Classes.Eq (a Text.Boomerang.HStack.:- b)
instance (GHC.Internal.Show.Show a, GHC.Internal.Show.Show b) => GHC.Internal.Show.Show (a Text.Boomerang.HStack.:- b)

module Text.Boomerang.Pos

-- | type synonym family that maps an error type to its position type
type family Pos err

-- | the initial position for a position type
class InitialPosition e
initialPos :: InitialPosition e => Maybe e -> Pos e

-- | extract the position information from an error
class ErrorPosition err
getPosition :: ErrorPosition err => err -> Maybe (Pos err)

-- | A basic 2-axis position type (e.g. line, character)
data MajorMinorPos
MajorMinorPos :: Integer -> Integer -> MajorMinorPos
[major] :: MajorMinorPos -> Integer
[minor] :: MajorMinorPos -> Integer

-- | increment major position by <tt>i</tt>, reset minor position to 0.. if
--   you wanted something else.. too bad.
incMajor :: Integral i => i -> MajorMinorPos -> MajorMinorPos

-- | increment minor position by <tt>i</tt>
incMinor :: Integral i => i -> MajorMinorPos -> MajorMinorPos
instance GHC.Internal.Data.Data.Data Text.Boomerang.Pos.MajorMinorPos
instance GHC.Classes.Eq Text.Boomerang.Pos.MajorMinorPos
instance GHC.Classes.Ord Text.Boomerang.Pos.MajorMinorPos
instance GHC.Internal.Show.Show Text.Boomerang.Pos.MajorMinorPos

module Text.Boomerang.Prim

-- | Yet another parser.
--   
--   Returns all possible parses and parse errors
newtype Parser e tok a
Parser :: (tok -> Pos e -> [Either e ((a, tok), Pos e)]) -> Parser e tok a
[runParser] :: Parser e tok a -> tok -> Pos e -> [Either e ((a, tok), Pos e)]

-- | A <tt>Boomerang a b</tt> takes an <tt>a</tt> to parse a URL and
--   results in <tt>b</tt> if parsing succeeds. And it takes a <tt>b</tt>
--   to serialize to a URL and results in <tt>a</tt> if serializing
--   succeeds.
data Boomerang e tok a b
Boomerang :: Parser e tok (a -> b) -> (b -> [(tok -> tok, a)]) -> Boomerang e tok a b
[prs] :: Boomerang e tok a b -> Parser e tok (a -> b)
[ser] :: Boomerang e tok a b -> b -> [(tok -> tok, a)]

-- | <i>Deprecated: Use Boomerang instead</i>
type PrinterParser = Boomerang

-- | Reverse composition, but with the side effects still in left-to-right
--   order.
(.~) :: Boomerang e tok a b -> Boomerang e tok b c -> Boomerang e tok a c
infixr 9 .~

-- | Give all possible parses or errors.
parse :: forall e a p tok. InitialPosition e => Boomerang e tok () a -> tok -> [Either e (a, tok)]

-- | Give the first parse, for Boomerangs with a parser that yields just
--   one value. Otherwise return the error (or errors) with the highest
--   error position.
parse1 :: (ErrorPosition e, InitialPosition e, Show e, Ord (Pos e)) => (tok -> Bool) -> Boomerang e tok () (a :- ()) -> tok -> Either [e] a

-- | Give all possible serializations.
unparse :: tok -> Boomerang e tok () url -> url -> [tok]

-- | Give the first serialization, for Boomerangs with a serializer that
--   needs just one value.
unparse1 :: tok -> Boomerang e tok () (a :- ()) -> a -> Maybe tok

-- | Attempt to extract the most relevant errors from a list of parse
--   errors.
--   
--   The current heuristic is to find error (or errors) where the error
--   position is highest.
bestErrors :: (ErrorPosition e, Ord (Pos e)) => [e] -> [e]

-- | Lift a constructor-destructor pair to a pure router.
xpure :: (a -> b) -> (b -> Maybe a) -> Boomerang e tok a b

-- | lift a <a>Parser</a> and a printer into a <a>Boomerang</a>
val :: Parser e tok a -> (a -> [tok -> tok]) -> Boomerang e tok r (a :- r)

-- | Map over routers.
xmap :: (a -> b) -> (b -> Maybe a) -> Boomerang e tok r a -> Boomerang e tok r b

-- | Like "xmap", but only maps over the top of the stack.
xmaph :: (a -> b) -> (b -> Maybe a) -> Boomerang e tok i (a :- o) -> Boomerang e tok i (b :- o)
instance GHC.Internal.Base.Alternative (Text.Boomerang.Prim.Parser e tok)
instance GHC.Internal.Base.Applicative (Text.Boomerang.Prim.Parser e tok)
instance GHC.Internal.Control.Category.Category (Text.Boomerang.Prim.Boomerang e tok)
instance GHC.Internal.Base.Functor (Text.Boomerang.Prim.Parser e tok)
instance GHC.Internal.Base.Monad (Text.Boomerang.Prim.Parser e tok)
instance GHC.Internal.Base.MonadPlus (Text.Boomerang.Prim.Parser e tok)
instance GHC.Internal.Base.Monoid (Text.Boomerang.Prim.Boomerang e tok a b)
instance GHC.Internal.Base.Semigroup (Text.Boomerang.Prim.Boomerang e tok a b)


-- | An Error handling scheme that can be used with <a>Boomerang</a>
module Text.Boomerang.Error
data ErrorMsg
SysUnExpect :: String -> ErrorMsg
EOI :: String -> ErrorMsg
UnExpect :: String -> ErrorMsg
Expect :: String -> ErrorMsg
Message :: String -> ErrorMsg

-- | extract the <a>String</a> from an <a>ErrorMsg</a>. Note: the resulting
--   <a>String</a> will not include any information about what constructor
--   it came from.
messageString :: ErrorMsg -> String
data ParserError pos
ParserError :: Maybe pos -> [ErrorMsg] -> ParserError pos

-- | lift a <tt>pos</tt> and '[ErrorMsg]' into a parse error
--   
--   This is intended to be used inside a <a>Parser</a> like this:
--   
--   <pre>
--   Parser $ \tok pos -&gt; mkParserError pos [Message "just some error..."]
--   </pre>
mkParserError :: pos -> [ErrorMsg] -> [Either (ParserError pos) a]

-- | annotate a parse error with an additional <a>Expect</a> message
--   
--   <pre>
--   satisfy isUpper &lt;?&gt; 'an uppercase character'
--   </pre>
(<?>) :: Boomerang (ParserError p) tok a b -> String -> Boomerang (ParserError p) tok a b
infix 0 <?>

-- | condense the <a>ParserError</a>s with the highest parse position into
--   a single <a>ParserError</a>
condenseErrors :: Ord pos => [ParserError pos] -> ParserError pos

-- | Helper function for turning '[ErrorMsg]' into a user-friendly
--   <a>String</a>
showErrorMessages :: String -> String -> String -> String -> String -> [ErrorMsg] -> String

-- | turn a parse error into a user-friendly error message
showParserError :: (pos -> String) -> ParserError pos -> String
instance GHC.Internal.Data.Data.Data Text.Boomerang.Error.ErrorMsg
instance GHC.Internal.Data.Data.Data pos => GHC.Internal.Data.Data.Data (Text.Boomerang.Error.ParserError pos)
instance GHC.Classes.Eq Text.Boomerang.Error.ErrorMsg
instance GHC.Classes.Eq pos => GHC.Classes.Eq (Text.Boomerang.Error.ParserError pos)
instance Text.Boomerang.Pos.ErrorPosition (Text.Boomerang.Error.ParserError p)
instance GHC.Classes.Ord Text.Boomerang.Error.ErrorMsg
instance GHC.Classes.Ord pos => GHC.Classes.Ord (Text.Boomerang.Error.ParserError pos)
instance GHC.Internal.Read.Read Text.Boomerang.Error.ErrorMsg
instance GHC.Internal.Show.Show Text.Boomerang.Error.ErrorMsg
instance GHC.Internal.Show.Show pos => GHC.Internal.Show.Show (Text.Boomerang.Error.ParserError pos)

module Text.Boomerang.TH

-- | Make a <a>Boomerang</a> router for each constructor in a datatype. For
--   example:
--   
--   <pre>
--   $(makeBoomerangs ''Sitemap)
--   </pre>
makeBoomerangs :: Name -> Q [Dec]

-- | Old name for <a>makeBoomerangs</a>, since renamed to reflect the fact
--   that it's not actually deriving instances for any type class, but
--   rather generates top-level definitions for routers of type
--   <a>Boomerang</a>.

-- | <i>Deprecated: Use makeBoomerangs instead</i>
derivePrinterParsers :: Name -> Q [Dec]


-- | a collection of generic parsing combinators that can work with any
--   token and error type.
module Text.Boomerang.Combinators
(<>) :: Semigroup a => a -> a -> a

-- | Convert a router to do what it does on the tail of the stack.
duck :: Boomerang e tok r1 r2 -> Boomerang e tok (h :- r1) (h :- r2)

-- | Convert a router to do what it does on the tail of the stack.
duck1 :: Boomerang e tok r1 (a :- r2) -> Boomerang e tok (h :- r1) (a :- (h :- r2))

-- | Make a router optional.
opt :: Boomerang e tok r r -> Boomerang e tok r r

-- | Repeat a router zero or more times, combining the results from left to
--   right.
manyr :: Boomerang e tok r r -> Boomerang e tok r r

-- | Repeat a router one or more times, combining the results from left to
--   right.
somer :: Boomerang e tok r r -> Boomerang e tok r r

-- | <tt>chainr p op</tt> repeats <tt>p</tt> zero or more times, separated
--   by <tt>op</tt>. The result is a right associative fold of the results
--   of <tt>p</tt> with the results of <tt>op</tt>.
chainr :: Boomerang e tok r r -> Boomerang e tok r r -> Boomerang e tok r r

-- | <tt>chainr1 p op</tt> repeats <tt>p</tt> one or more times, separated
--   by <tt>op</tt>. The result is a right associative fold of the results
--   of <tt>p</tt> with the results of <tt>op</tt>.
chainr1 :: Boomerang e tok r (a :- r) -> Boomerang e tok (a :- (a :- r)) (a :- r) -> Boomerang e tok r (a :- r)

-- | Repeat a router zero or more times, combining the results from right
--   to left.
manyl :: Boomerang e tok r r -> Boomerang e tok r r

-- | Repeat a router one or more times, combining the results from right to
--   left.
somel :: Boomerang e tok r r -> Boomerang e tok r r

-- | <tt>chainl1 p op</tt> repeats <tt>p</tt> zero or more times, separated
--   by <tt>op</tt>. The result is a left associative fold of the results
--   of <tt>p</tt> with the results of <tt>op</tt>.
chainl :: Boomerang e tok r r -> Boomerang e tok r r -> Boomerang e tok r r

-- | <tt>chainl1 p op</tt> repeats <tt>p</tt> one or more times, separated
--   by <tt>op</tt>. The result is a left associative fold of the results
--   of <tt>p</tt> with the results of <tt>op</tt>.
chainl1 :: Boomerang e tok r (a :- r) -> Boomerang e tok (a :- (a :- r)) (a :- r) -> Boomerang e tok r (a :- r)

-- | Filtering on routers.
--   
--   TODO: We remove any parse errors, not sure if the should be preserved.
--   Also, if the predicate fails we silently remove the element, but
--   perhaps we should replace the value with an error message?
rFilter :: (a -> Bool) -> Boomerang e tok () (a :- ()) -> Boomerang e tok r (a :- r)

-- | <tt>r `printAs` s</tt> uses ther serializer of <tt>r</tt> to test if
--   serializing succeeds, and if it does, instead serializes as
--   <tt>s</tt>.
--   
--   TODO: can this be more general so that it can work on <tt>tok</tt>
--   instead of <tt>[tok]</tt>
printAs :: Boomerang e [tok] a b -> tok -> Boomerang e [tok] a b

-- | Push a value on the stack (during parsing, pop it from the stack when
--   serializing).
push :: Eq a => a -> Boomerang e tok r (a :- r)
rNil :: Boomerang e tok r ([a] :- r)
rCons :: Boomerang e tok (a :- ([a] :- r)) ([a] :- r)

-- | Converts a router for a value <tt>a</tt> to a router for a list of
--   <tt>a</tt>.
rList :: Boomerang e tok r (a :- r) -> Boomerang e tok r ([a] :- r)

-- | Converts a router for a value <tt>a</tt> to a router for a list of
--   <tt>a</tt>.
rList1 :: Boomerang e tok r (a :- r) -> Boomerang e tok r ([a] :- r)

-- | Converts a router for a value <tt>a</tt> to a router for a list of
--   <tt>a</tt>, with a separator.
rListSep :: Boomerang e tok r (a :- r) -> Boomerang e tok ([a] :- r) ([a] :- r) -> Boomerang e tok r ([a] :- r)
rPair :: Boomerang e tok (f :- (s :- r)) ((f, s) :- r)
rLeft :: forall tok e r a b. Boomerang e tok (a :- r) (Either a b :- r)
rRight :: forall tok e r a b. Boomerang e tok (b :- r) (Either a b :- r)

-- | Combines a router for a value <tt>a</tt> and a router for a value
--   <tt>b</tt> into a router for <tt>Either a b</tt>.
rEither :: Boomerang e tok r (a :- r) -> Boomerang e tok r (b :- r) -> Boomerang e tok r (Either a b :- r)
rNothing :: forall tok e r a. Boomerang e tok r (Maybe a :- r)
rJust :: forall tok e r a. Boomerang e tok (a :- r) (Maybe a :- r)

-- | Converts a router for a value <tt>a</tt> to a router for a <tt>Maybe
--   a</tt>.
rMaybe :: Boomerang e tok r (a :- r) -> Boomerang e tok r (Maybe a :- r)
rTrue :: forall tok e r. Boomerang e tok r (Bool :- r)
rFalse :: forall tok e r. Boomerang e tok r (Bool :- r)
rBool :: Boomerang e tok a r -> Boomerang e tok a r -> Boomerang e tok a (Bool :- r)
rUnit :: Boomerang e tok r (() :- r)


-- | a <a>Boomerang</a> library for working with '[String]'
module Text.Boomerang.Strings
type StringsError = ParserError MajorMinorPos

-- | equivalent to <tt>f . eos . g</tt>
(</>) :: Boomerang StringsError [String] b c -> Boomerang StringsError [String] a b -> Boomerang StringsError [String] a c
infixr 9 </>

-- | matches alphabetic Unicode characters (lower-case, upper-case and
--   title-case letters, plus letters of caseless scripts and modifiers
--   letters). (Uses <a>isAlpha</a>)
alpha :: Boomerang StringsError [String] r (Char :- r)

-- | any character
anyChar :: Boomerang StringsError [String] r (Char :- r)

-- | matches any <a>String</a>
--   
--   the parser returns the remainder of the current String segment, (but
--   does not consume the 'end of segment'.
--   
--   Note that the only combinator that should follow <a>anyString</a> is
--   <a>eos</a> or <a>&lt;/&gt;</a>. Other combinators will lead to
--   inconsistent inversions.
--   
--   For example, if we have:
--   
--   <pre>
--   unparseStrings (rPair . anyString . anyString)  ("foo","bar")
--   </pre>
--   
--   That will unparse to <tt>Just ["foobar"]</tt>. But if we call
--   
--   <pre>
--   parseStrings (rPair . anyString . anyString)  ["foobar"]
--   </pre>
--   
--   We will get <tt>Right ("foobar","")</tt> instead of the original
--   <tt>Right ("foo","bar")</tt>
anyString :: Boomerang StringsError [String] r (String :- r)

-- | matches the specified character
char :: Char -> Boomerang StringsError [String] r (Char :- r)

-- | ascii digits <tt>'0'..'9'</tt>
digit :: Boomerang StringsError [String] r (Char :- r)

-- | end of string
eos :: Boomerang StringsError [String] r r

-- | matches an <a>Int</a>
--   
--   Note that the combinator <tt>(rPair . int . int)</tt> is ill-defined
--   because the parse can not tell where it is supposed to split the
--   sequence of digits to produced two ints.
int :: Boomerang StringsError [String] r (Int :- r)

-- | matches an <a>Integer</a>
--   
--   Note that the combinator <tt>(rPair . integer . integer)</tt> is
--   ill-defined because the parse can not tell where it is supposed to
--   split the sequence of digits to produced two ints.
integer :: Boomerang StringsError [String] r (Integer :- r)

-- | a constant string
lit :: String -> Boomerang StringsError [String] r r

-- | lift <a>Read</a>/<a>Show</a> to a <a>Boomerang</a>
--   
--   There are a few restrictions here:
--   
--   <ol>
--   <li>Error messages are a bit fuzzy. <a>Read</a> does not tell us where
--   or why a parse failed. So all we can do it use the the position that
--   we were at when we called read and say that it failed.</li>
--   <li>it is (currently) not safe to use <a>readshow</a> on integral
--   values because the <a>Read</a> instance for <a>Int</a>,
--   <a>Integer</a>, etc,</li>
--   </ol>
readshow :: (Read a, Show a) => Boomerang StringsError [String] r (a :- r)

-- | statisfy a <a>Char</a> predicate
satisfy :: (Char -> Bool) -> Boomerang StringsError [String] r (Char :- r)

-- | satisfy a <a>String</a> predicate.
--   
--   Note: must match the entire remainder of the <a>String</a> in this
--   segment
satisfyStr :: (String -> Bool) -> Boomerang StringsError [String] r (String :- r)

-- | matches white-space characters in the Latin-1 range. (Uses
--   <a>isSpace</a>)
space :: Boomerang StringsError [String] r (Char :- r)

-- | Predicate to test if we have parsed all the strings. Typically used as
--   argument to <a>parse1</a>
--   
--   see also: <a>parseStrings</a>
isComplete :: [String] -> Bool

-- | run the parser
--   
--   Returns the first complete parse or a parse error.
--   
--   <pre>
--   parseStrings (rUnit . lit "foo") ["foo"]
--   </pre>
parseStrings :: Boomerang StringsError [String] () (r :- ()) -> [String] -> Either StringsError r

-- | run the printer
--   
--   <pre>
--   unparseStrings (rUnit . lit "foo") ()
--   </pre>
unparseStrings :: Boomerang e [String] () (r :- ()) -> r -> Maybe [String]
instance Text.Boomerang.Pos.InitialPosition Text.Boomerang.Strings.StringsError
instance (a GHC.Types.~ b) => GHC.Internal.Data.String.IsString (Text.Boomerang.Prim.Boomerang Text.Boomerang.Strings.StringsError [GHC.Internal.Base.String] a b)


-- | a <a>Boomerang</a> library for working with a <a>String</a>
module Text.Boomerang.String
type StringBoomerang = Boomerang StringError String

-- | <i>Deprecated: Use StringBoomerang instead</i>
type StringPrinterParser = StringBoomerang
type StringError = ParserError MajorMinorPos

-- | matches alphabetic Unicode characters (lower-case, upper-case and
--   title-case letters, plus letters of caseless scripts and modifiers
--   letters). (Uses <a>isAlpha</a>)
alpha :: StringBoomerang r (Char :- r)

-- | any character
anyChar :: StringBoomerang r (Char :- r)

-- | matches the specified character
char :: Char -> StringBoomerang r (Char :- r)

-- | ascii digits <tt>'0'..'9'</tt>
digit :: StringBoomerang r (Char :- r)

-- | matches an <a>Int</a>
int :: StringBoomerang r (Int :- r)

-- | matches an <a>Integer</a>
integer :: StringBoomerang r (Integer :- r)

-- | a constant string
lit :: String -> StringBoomerang r r

-- | statisfy a <a>Char</a> predicate
satisfy :: (Char -> Bool) -> StringBoomerang r (Char :- r)

-- | matches white-space characters in the Latin-1 range. (Uses
--   <a>isSpace</a>)
space :: StringBoomerang r (Char :- r)

-- | Predicate to test if we have parsed all the strings. Typically used as
--   argument to <a>parse1</a>
--   
--   see also: <tt>parseStrings</tt>
isComplete :: String -> Bool

-- | run the parser
--   
--   Returns the first complete parse or a parse error.
--   
--   <pre>
--   parseString (rUnit . lit "foo") ["foo"]
--   </pre>
parseString :: StringBoomerang () (r :- ()) -> String -> Either StringError r

-- | run the printer
--   
--   <pre>
--   unparseString (rUnit . lit "foo") ()
--   </pre>
unparseString :: StringBoomerang () (r :- ()) -> r -> Maybe String
instance Text.Boomerang.Pos.InitialPosition Text.Boomerang.String.StringError
instance (a GHC.Types.~ b) => GHC.Internal.Data.String.IsString (Text.Boomerang.Prim.Boomerang Text.Boomerang.String.StringError GHC.Internal.Base.String a b)


-- | Boomerang is a DSL for creating parsers and pretty-printers using a
--   single specification. Instead of writing a parser, and then writing a
--   separate pretty-printer, both are created at once. This saves time,
--   and ensures that the parser and pretty-printer are inverses and stay
--   in-sync with each other.
--   
--   Boomerang is a generalized derivative of the Zwaluw library created by
--   Sjoerd Visscher and Martijn van Steenbergen:
--   
--   <a>http://hackage.haskell.org/package/Zwaluw</a>
--   
--   Boomerang is similar in purpose, but different in implementation to:
--   
--   <a>http://hackage.haskell.org/package/invertible-syntax</a>
--   
--   Here is a simple example. First we enable three language extensions:
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, TypeOperators, OverloadedStrings #-}
--   </pre>
--   
--   In the imports, note that we hide <tt>((.), id)</tt> from
--   <tt>Prelude</tt> and use <tt>((.), id)</tt> from
--   <a>Control.Category</a> instead.
--   
--   <pre>
--   {-# LANGUAGE TemplateHaskell, TypeOperators, OverloadedStrings #-}
--   module Main where
--   
--   import Prelude hiding ((.), id)
--   import Control.Category ((.), id)
--   import Control.Monad (forever)
--   import Text.Boomerang
--   import Text.Boomerang.String
--   import Text.Boomerang.TH
--   import System.IO (hFlush, stdout)
--   </pre>
--   
--   Next we define a type that we want to be able to pretty-print and
--   define parsers for:
--   
--   <pre>
--   data Foo
--       = Bar
--       | Baz Int Char
--         deriving (Eq, Show)
--   </pre>
--   
--   Then we generate some combinators for the type:
--   
--   <pre>
--   $(makeBoomerangs ''Foo)
--   </pre>
--   
--   The combinators will be named after the constructors, but with an r
--   prefixed to them. In this case, <tt>rBar</tt> and <tt>rBaz</tt>.
--   
--   Now we can define a grammar:
--   
--   <pre>
--   foo :: StringBoomerang () (Foo :- ())
--   foo =
--       (  rBar
--       &lt;&gt; rBaz . "baz-" . int . "-" . alpha
--       )
--   </pre>
--   
--   <tt>.</tt> is used to compose parsers together. <a>&lt;&gt;</a> is
--   used for choice.
--   
--   Now we can use <tt>foo</tt> as a printer or a parser.
--   
--   Here is an example of a successful parse:
--   
--   <pre>
--   test1 = parseString foo "baz-2-c"
--   </pre>
--   
--   <pre>
--   *Main&gt; test1
--   Right (Baz 2 <tt>c</tt>)
--   </pre>
--   
--   And another example:
--   
--   <pre>
--   test2 = parseString foo ""
--   </pre>
--   
--   <pre>
--   *Main&gt; test2
--   Right Bar
--   </pre>
--   
--   Here is an example of a parse error:
--   
--   <pre>
--   test3 = parseString foo "baz-2-3"
--   </pre>
--   
--   <pre>
--   *Main&gt; test3
--   Left parse error at (0, 6): unexpected '3'; expecting an alphabetic Unicode character
--   </pre>
--   
--   we can also use <tt>foo</tt> to pretty-print a value:
--   
--   <pre>
--   test4 = unparseString foo (Baz 1 'z')
--   </pre>
--   
--   <pre>
--   *Main&gt; test4
--   Just "baz-1-z"
--   </pre>
--   
--   Here is a little app that allows you to interactively test
--   <tt>foo</tt>.
--   
--   <pre>
--   testInvert :: String -&gt; IO ()
--   testInvert str =
--       case parseString foo str of
--         (Left e) -&gt; print e
--         (Right f') -&gt;
--             do putStrLn $ "Parsed: " ++ show f'
--                case unparseString foo f' of
--                  Nothing  -&gt; putStrLn "unparseString failed to produce a value."
--                  (Just s) -&gt; putStrLn $ "Pretty: " ++ s
--   </pre>
--   
--   <pre>
--   main = forever $
--       do putStr "Enter a string to parse: "
--          hFlush stdout
--          l &lt;- getLine
--          testInvert l
--   </pre>
module Text.Boomerang


-- | a <a>Boomerang</a> library for working with '[Text]'
module Text.Boomerang.Texts
type TextsError = ParserError MajorMinorPos

-- | equivalent to <tt>f . eos . g</tt>
(</>) :: Boomerang TextsError [Text] b c -> Boomerang TextsError [Text] a b -> Boomerang TextsError [Text] a c
infixr 9 </>

-- | matches alphabetic Unicode characters (lower-case, upper-case and
--   title-case letters, plus letters of caseless scripts and modifiers
--   letters). (Uses <a>isAlpha</a>)
alpha :: Boomerang TextsError [Text] r (Char :- r)

-- | any character
anyChar :: Boomerang TextsError [Text] r (Char :- r)

-- | matches any <a>Text</a>
--   
--   the parser returns the remainder of the current Text segment, (but
--   does not consume the 'end of segment'.
--   
--   Note that the only combinator that should follow <a>anyText</a> is
--   <a>eos</a> or <a>&lt;/&gt;</a>. Other combinators will lead to
--   inconsistent inversions.
--   
--   For example, if we have:
--   
--   <pre>
--   unparseTexts (rPair . anyText . anyText)  ("foo","bar")
--   </pre>
--   
--   That will unparse to <tt>Just ["foobar"]</tt>. But if we call
--   
--   <pre>
--   parseTexts (rPair . anyText . anyText)  ["foobar"]
--   </pre>
--   
--   We will get <tt>Right ("foobar","")</tt> instead of the original
--   <tt>Right ("foo","bar")</tt>
anyText :: Boomerang TextsError [Text] r (Text :- r)

-- | matches the specified character
char :: Char -> Boomerang TextsError [Text] r (Char :- r)

-- | ascii digits <tt>'0'..'9'</tt>
digit :: Boomerang TextsError [Text] r (Char :- r)

-- | a sequence of one or more digits
digits :: Boomerang TextsError [Text] r (Text :- r)

-- | an optional - character
--   
--   Typically used with <a>digits</a> to support signed numbers
--   
--   <pre>
--   signed digits
--   </pre>
signed :: Boomerang TextsError [Text] a (Text :- r) -> Boomerang TextsError [Text] a (Text :- r)

-- | end of string
eos :: Boomerang TextsError [Text] r r

-- | matches an <a>Integral</a> value
--   
--   Note that the combinator <tt>(rPair . integral . integral)</tt> is
--   ill-defined because the parse canwell. not tell where it is supposed
--   to split the sequence of digits to produced two ints.
integral :: (Integral a, Show a) => Boomerang TextsError [Text] r (a :- r)

-- | matches an <a>Int</a> Note that the combinator <tt>(rPair . int .
--   int)</tt> is ill-defined because the parse canwell. not tell where it
--   is supposed to split the sequence of digits to produced two ints.
int :: Boomerang TextsError [Text] r (Int :- r)

-- | matches an <a>Integer</a>
--   
--   Note that the combinator <tt>(rPair . integer . integer)</tt> is
--   ill-defined because the parse can not tell where it is supposed to
--   split the sequence of digits to produced two ints.
integer :: Boomerang TextsError [Text] r (Integer :- r)

-- | a constant string
lit :: Text -> Boomerang TextsError [Text] r r

-- | lift <a>Read</a>/<a>Show</a> to a <a>Boomerang</a>
--   
--   There are a few restrictions here:
--   
--   <ol>
--   <li>Error messages are a bit fuzzy. <a>Read</a> does not tell us where
--   or why a parse failed. So all we can do it use the the position that
--   we were at when we called read and say that it failed.</li>
--   <li>it is (currently) not safe to use <a>readshow</a> on integral
--   values because the <a>Read</a> instance for <a>Int</a>,
--   <a>Integer</a>, etc,</li>
--   </ol>
readshow :: (Read a, Show a) => Boomerang TextsError [Text] r (a :- r)

-- | statisfy a <a>Char</a> predicate
satisfy :: (Char -> Bool) -> Boomerang TextsError [Text] r (Char :- r)

-- | satisfy a <a>Text</a> predicate.
--   
--   Note: must match the entire remainder of the <a>Text</a> in this
--   segment
satisfyStr :: (Text -> Bool) -> Boomerang TextsError [Text] r (Text :- r)

-- | matches white-space characters in the Latin-1 range. (Uses
--   <a>isSpace</a>)
space :: Boomerang TextsError [Text] r (Char :- r)

-- | the first character of a <a>Text</a>
rTextCons :: Boomerang e tok (Char :- (Text :- r)) (Text :- r)

-- | the empty string
rEmpty :: Boomerang e [Text] r (Text :- r)

-- | construct/parse some <a>Text</a> by repeatedly apply a <a>Char</a> 0
--   or more times parser
rText :: Boomerang e [Text] r (Char :- r) -> Boomerang e [Text] r (Text :- r)

-- | construct/parse some <a>Text</a> by repeatedly apply a <a>Char</a> 1
--   or more times parser
rText1 :: Boomerang e [Text] r (Char :- r) -> Boomerang e [Text] r (Text :- r)

-- | Predicate to test if we have parsed all the Texts. Typically used as
--   argument to <a>parse1</a>
--   
--   see also: <a>parseTexts</a>
isComplete :: [Text] -> Bool

-- | run the parser
--   
--   Returns the first complete parse or a parse error.
--   
--   <pre>
--   parseTexts (rUnit . lit "foo") ["foo"]
--   </pre>
parseTexts :: Boomerang TextsError [Text] () (r :- ()) -> [Text] -> Either TextsError r

-- | run the printer
--   
--   <pre>
--   unparseTexts (rUnit . lit "foo") ()
--   </pre>
unparseTexts :: Boomerang e [Text] () (r :- ()) -> r -> Maybe [Text]
instance Text.Boomerang.Pos.InitialPosition Text.Boomerang.Texts.TextsError
instance (a GHC.Types.~ b) => GHC.Internal.Data.String.IsString (Text.Boomerang.Prim.Boomerang Text.Boomerang.Texts.TextsError [Data.Text.Internal.Text] a b)
