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


-- | Fast, online, error-correcting, monadic, applicative, merging, permuting, interleaving, idiomatic parser combinators.
--   
--   New version of the Utrecht University parser combinator library, which
--   provides online, error correction, annotation free, applicative style
--   parser combinators. In addition to this we provide a monadic and an
--   idomatic interface. Parsers do analyse themselves to avoid commonly
--   made errors.
--   
--   This version is based on the module <a>Data.Listlike</a>, and as a
--   result a great variety of input structures (<tt>Strings</tt>,
--   <tt>ByteStrings</tt>, etc.) can be handled.
--   
--   The modules <a>Text.ParserCombinators.UU.Demo.Examples</a>,
--   <a>Text.ParserCombinators.UU.Idioms</a> and
--   <a>Text.ParserCombinators.UU.Demo.MergeAndpermute</a> contain a
--   ready-made <tt>show_examples</tt> function, which can be called (e.g.
--   from <tt>ghci</tt>) to see e.g. the error correction at work. It
--   contains extensive haddock documentation, so why not just take a look
--   to see the correction process at work, and to get a feeling for how
--   the various combinators can be used?
--   
--   The file <a>Text.ParserCombinators.UU.CHANGELOG</a> contains a log of
--   the most recent changes and additions.
--   
--   The file <a>Text.ParserCombinators.UU.README</a> contains some
--   references to background information.
--   
--   We maintain a low frequency mailing for discussing the package. You
--   can subscribe at:
--   <a>http://lists.science.uu.nl/mailman/listinfo/parsing</a>
@package uu-parsinglib
@version 2.9.1.1


-- | This module just contains the CHANGELOG Version 2.8.2
--   
--   Change in the internal Steps data type in order to get correct
--   behaviour when-- inserting at end of file
--   
--   Version 2.7.4.1
--   
--   export of constructors of LineCol and LineColPos export of pState from
--   Core.hs
--   
--   Version 2.7.4
--   
--   Made some abstract interpretation a bit simpler, and made comparing
--   lengths less trict. Some times the abstrcat interpretation would
--   
--   Version 2.7.3.3
--   
--   cured a problem with loosing priority information when applying
--   semantic actions, final cure is probably to intrduce a real priority
--   mechanism replace pSpaces with more efficient version using pMunch
--   
--   Version 2.7.3.2
--   
--   made TypeOperators explicit as required by GHC 7.4
--   
--   Version 2.7.3.1
--   
--   fixed corner case when combining to failing parsers during grammar
--   analysis; probably useful error message is now gone
--   
--   Version 2.7.3
--   
--   better behaviour when inserting at end of input
--   
--   Version 2.7.2.2
--   
--   fixed the case where the left hand operand of <a>&lt;||</a> starts
--   with a monadic bind
--   
--   Version 2.7.2.1
--   
--   removed a left-over from debugging
--   
--   Version 2.7.2
--   
--   fixed a subtle bug in the merging parsers caused by name shielding
--   ;-{{
--   
--   Version 2.7.1.1
--   
--   added <tt>pDoubleStr</tt> to the export list of the Utils module
--   
--   Version 2.7.1
--   
--   fixed a subtle black hole which prevented computation of lengths!! You
--   should upgrade.
--   
--   Version 2.7.0.2
--   
--   <ul>
--   <li>Some types were reformulated to compile correctly with ghc
--   6.12.3</li>
--   </ul>
--   
--   Version 2.7.0.1
--   
--   <ul>
--   <li>Typos fixed in Haddock documentation</li>
--   </ul>
--   
--   Version 2.7.0
--   
--   Improvement: change of error correction at end of <tt>amb</tt>
--   combinator, so lookahead is better taken into account
--   
--   Relatively large change:
--   
--   <ul>
--   <li>Change to <a>Data.ListLike</a> inputs, so a general stream input
--   structure is possible; hence we can now parse all instances of
--   <tt>ListLike</tt></li>
--   <li>Simplified and generalised implementation of merging<i>permuting
--   parsers; any kind of parsers can now be merged</i>permuted</li>
--   <li>New class <tt>IsParser</tt> was introduced which captures the
--   basic properties of our parsers</li>
--   <li>Inclusion of a module <a>Text.ParserCombinators.UU.Utils</a>
--   containing common <tt>Char</tt> based parsers</li>
--   <li>Removal of the class <tt>Provides</tt>, and replaced by separate
--   <tt>pSym</tt>, <tt>pSatisfy</tt> and <tt>pRange</tt>; this may require
--   some rwriting of existing parsers. Readbaility is supposed to improve
--   from that. Types become simpler. For an example see the module
--   <a>Text.ParserCombinators.UU.Utils</a>.</li>
--   <li>Included a Demo directory, with a modules for demonstrating normal
--   parsers and one aimed at merging parsers</li>
--   <li>Added the module <a>Text.ParserCombinaors.UU.Idioms</a>, which
--   contains specialised version for the idiomatic notation; it infers the
--   sequental composition operators from the types of the operands;
--   <tt>String</tt>-s and <tt>Char</tt>-s are not supposed to contribute
--   to the result, function parameters are lifted using <a>pure</a>, and
--   normal parsers are composed with <a>&lt;*&gt;</a>.</li>
--   <li>Many other small changes, mostly upwards compatible or invisible
--   (code cleanup)</li>
--   </ul>
--   
--   Version 2.6.1
--   
--   <ul>
--   <li>Changed the input to a <tt>Stream</tt> interface to handle
--   different kind of inputs like <tt>String</tt>, <tt>Data.Text</tt> and
--   <tt>Data.ByteString</tt>.</li>
--   <li>To update old code to the new interface you should add</li>
--   </ul>
--   
--   <pre>
--   import Text.ParserCombinators.UU.BasicInstances.String
--   </pre>
--   
--   in the file header and change
--   
--   <pre>
--   listToStr inp (0,0)
--   </pre>
--   
--   to
--   
--   <pre>
--   createStr inp
--   </pre>
--   
--   <ul>
--   <li>To work with other inputs, import
--   <a>Text.ParserCombinators.UU.BasicInstances.List</a>,
--   <a>Text.ParserCombinators.UU.BasicInstances.Text</a>,
--   <a>Text.ParserCombinators.UU.BasicInstances.ByteString</a> or
--   <a>Text.ParserCombinators.UU.BasicInstances.ByteString.Lazy</a>.</li>
--   </ul>
--   
--   Version 2.5.6.1
--   
--   <ul>
--   <li>replaced references to modules with references in the new library
--   scheme</li>
--   </ul>
--   
--   Version 2.5.6
--   
--   <ul>
--   <li>added a special version of &lt;|&gt; (called <tt>&lt;-|-&gt;</tt>)
--   in <tt>ExtAlternative</tt> which does not compare the length of the
--   parsers; to be used in permutations</li>
--   </ul>
--   
--   Version 2.5.5.2
--   
--   <ul>
--   <li>type signatures were added to make Haddock happy</li>
--   </ul>
--   
--   Version 2.5.5.1
--   
--   <ul>
--   <li>type signatures were added to make the library GHC 7 ready.</li>
--   </ul>
--   
--   Version 2.5.5
--   
--   <ul>
--   <li>preference is given to earlier accept steps in order to avoid
--   infinite insertions in case of otherwise equivalent repair
--   strategies</li>
--   </ul>
--   
--   Version 2.5.4.2
--   
--   <ul>
--   <li>fixed small problem in <a>?</a> so it gets its chance to do its
--   work</li>
--   </ul>
--   
--   Version 2.5.4.1
--   
--   <ul>
--   <li>added a <tt>pSem</tt> which makes it possible to tell how certain
--   components of merged structures are to be combined before exposing all
--   elements to the outer sem:</li>
--   </ul>
--   
--   <pre>
--   run ( (,)  `pMerge` ( ((++) `pSem` (pMany pa &lt;||&gt; pMany pb)) &lt;||&gt; pOne pc))  "abcaaab"
--   
--   Result: (["a","a","a","a","b","b"],"c")
--   </pre>
--   
--   <ul>
--   <li>added a <tt>pMergedSep</tt>, which allows you to specify a
--   separator between two merged elements</li>
--   </ul>
--   
--   <pre>
--    run ((((,), pc) `pMergeSep` (pMany pa &lt;||&gt; pMany pb))) "acbcacbc"
--   
--   Result: (["a","a","a"],["b","b"])
--   Correcting steps: 
--      Inserted 'a' at position (0,8) expecting one of ['b', 'a']
--   </pre>
--   
--   Version 2.5.4
--   
--   <ul>
--   <li>made the merging combinators more general introducing
--   <tt>pAtMost</tt>, <tt>pBetween</tt> and <tt>pAtLeast</tt>; examples
--   are extended; see <tt><tt>demo_merge</tt></tt></li>
--   <li>used CPP in order to generate demo's easily</li>
--   <li>fixed a bug which made <tt>pPos</tt> ambiguous</li>
--   <li>modified haddock stuff</li>
--   </ul>
--   
--   Version 2.5.3
--   
--   <ul>
--   <li>fixed a bug in the implementation; some functions were too strict,
--   due to introduction of nice abstractions!!</li>
--   <li>added a generalisation of <tt><tt>pMerged</tt></tt> and
--   <tt><tt>pPerms</tt></tt> to the module
--   <a>Text.ParserCombinators.UU.Derived</a>; the old modules have been
--   marked as deprecated</li>
--   <li>removed the old module Text.ParserCombinators.UU.Parsing, which
--   was already marged as deprecated</li>
--   </ul>
--   
--   Version 2.5.2
--   
--   <ul>
--   <li>fixed a bug in sequential composition with a pure as left hand
--   side</li>
--   <li>added an experimental <tt>pMerge</tt>, which combines the featurs
--   of <tt>pPerms</tt> and <tt>pMerged</tt></li>
--   </ul>
--   
--   Version 2.5.1.1
--   
--   <ul>
--   <li>Now with the correct Changelog</li>
--   </ul>
--   
--   Version 2.5.1
--   
--   <ul>
--   <li>added the permutation parsers from the old uulib</li>
--   <li>extended the abstract interpretation so more soundness checks can
--   be done statically</li>
--   <li>everything seems to work; in case of problems please report and go
--   back to 2.5.0</li>
--   </ul>
--   
--   Version 2.5.0
--   
--   <ul>
--   <li>generalised over the position in the input; now it is easy to
--   maintain e.g. (line,column) info as shown in the "Examples.hs"
--   file</li>
--   <li>added needed instances for <tt>String</tt> s as input in
--   "BasicInstances.hs"</li>
--   <li>fixed a bug in pMunch where a Step was inserted with 0 progress,
--   leading to infinite insertions</li>
--   <li>added Haddock beautifications</li>
--   </ul>
--   
--   Version 2.4.5
--   
--   <ul>
--   <li>added the function <tt><tt>pPos</tt></tt> for retreiving the
--   current input position</li>
--   </ul>
--   
--   Version 2.4.4
--   
--   <ul>
--   <li>solved a mistake which had crept in in the greedy choice</li>
--   <li>added priority for <tt><tt>&lt;&lt;|&gt;</tt></tt> which had
--   disappeared</li>
--   <li>added an example how to achieve the effect of manytill from
--   parsec</li>
--   </ul>
--   
--   Version 2.4.3
--   
--   <ul>
--   <li>removed the classes IsParser and Symbol, which made the code
--   shorter and more H98-alike last version with dynamic error message
--   computation</li>
--   </ul>
--   
--   Version 2.4.2
--   
--   <ul>
--   <li>fixed dependency in cabal file to base &gt;=4.2</li>
--   <li>moved definition of &lt;$ to the class Functor and removed the
--   class ExtApplicative</li>
--   </ul>
--   
--   Version 2.4.1
--   
--   <ul>
--   <li>added the module Text.ParserCombinators.Merge for recognizing
--   alternating sequences</li>
--   <li>made <tt>P st</tt> an instance of <tt><tt>MonadPlus</tt></tt></li>
--   <li>beautified Haddock documentation</li>
--   </ul>
--   
--   Version 2.4.0
--   
--   <ul>
--   <li>contains abstract interpretation for minimal lenth, in order to
--   avoid recursive correction process</li>
--   <li>idem for checking that no repeating combinators like pList are
--   parameterised with possibly empty parsers</li>
--   <li>lots of Haddcock doumentation in
--   <a>Text.ParserCombinators.UU.Examples</a></li>
--   </ul>
--   
--   Version 2.3.4
--   
--   <ul>
--   <li>removed dependecies on impredictaive types, preparing for next GHC
--   version</li>
--   </ul>
--   
--   Version 2.3.3
--   
--   <ul>
--   <li>added <tt>pMunch</tt> which takes a Boolean function, and
--   recognises the longest prefix for which the symbols match the
--   predicate</li>
--   <li>added the infix operator with piority 2 <tt>&lt;?&gt; :: P state a
--   -&gt; String -&gt; P state a</tt> which replaces the list of expected
--   symbols in error message by its right argument String</li>
--   </ul>
--   
--   Version 2.3.2
--   
--   <ul>
--   <li>added microsteps, which can be used to disambiguate</li>
--   </ul>
--   
--   Version 2.3.1
--   
--   <ul>
--   <li>fix for GHC 6.12, because of change in GADT definition
--   handling</li>
--   </ul>
--   
--   Versions above 2.2:
--   
--   <ul>
--   <li>make use of type families</li>
--   <li>contain a module with many list-based derived combinators</li>
--   </ul>
--   
--   Versions above 2.1: * based on Control.Applicative
--   
--   Note that the basic parser interface will probably not change much
--   when we add more features, but the calling conventions of the outer
--   parser and the class structure upon which the parametrisation is based
--   may change slightly
module Text.ParserCombinators.UU.CHANGELOG


-- | The module <tt>Core</tt> contains the basic functionality of the
--   parser library. It defines the types and implementations of the
--   elementary parsers and recognisers involved.
module Text.ParserCombinators.UU.Core

-- | In the class <a>IsParser</a> we assemble the basic properties we
--   expect parsers to have. The class itself does not have any methods.
--   Most properties come directly from the standard
--   <a>Control.Applicative</a> module. The class <a>ExtAlternative</a>
--   contains some extra methods we expect our parsers to have.
class (Alternative p, Applicative p, ExtAlternative p) => IsParser p
class (Alternative p) => ExtAlternative p

-- | <a>&lt;&lt;|&gt;</a> is the greedy version of <a>&lt;|&gt;</a>. If its
--   left hand side parser can make any progress then it commits to that
--   alternative. Can be used to make parsers faster, and even get a
--   complete Parsec equivalent behaviour, with all its (dis)advantages.
--   Intended use <tt>p &lt;&lt;|&gt; q &lt;&lt;|&gt; r &lt;|&gt; x
--   &lt;|&gt; y &lt;?&gt; "string"</tt>. Use with care!
(<<|>) :: ExtAlternative p => p a -> p a -> p a

-- | The parsers build a list of symbols which are expected at a specific
--   point. This list is used to report errors. Quite often it is more
--   informative to get e.g. the name of the non-terminal . The
--   <a>&lt;?&gt;</a> combinator replaces this list of symbols by the
--   string argument.
(<?>) :: ExtAlternative p => p a -> String -> p a

-- | <a>must_be_non_empty</a> checks whether its second argument is a
--   parser which can recognise the empty input. If so, an error message is
--   given using the String parameter. If not, then the third argument is
--   returned. This is useful in testing for illogical combinations. For
--   its use see the module <a>Text.ParserCombinators.UU.Derived</a>.
must_be_non_empty :: ExtAlternative p => String -> p a -> c -> c

-- | <a>must_be_non_empties</a> is similar to <a>must_be_non_empty</a>, but
--   can be used in situations where we recognise a sequence of elements
--   separated by other elements. This does not make sense if both parsers
--   can recognise the empty string. Your grammar is then highly ambiguous.
must_be_non_empties :: ExtAlternative p => String -> p a -> p b -> c -> c

-- | If <tt>p</tt> can be recognized, the return value of <tt>p</tt> is
--   used. Otherwise, the value <tt>v</tt> is used. Note that <a>opt</a> by
--   default is greedy. If you do not want this use <tt>...&lt;|&gt; pure
--   v</tt> instead. Furthermore, <tt>p</tt> should not recognise the empty
--   string, since this would make the parser ambiguous!!
opt :: ExtAlternative p => p a -> a -> p a

-- | The class <a>Eof</a> contains a function <a>eof</a> which is used to
--   check whether we have reached the end of the input and
--   <tt>deletAtEnd</tt> should discard any unconsumed input at the end of
--   a successful parse.
class Eof state
eof :: Eof state => state -> Bool
deleteAtEnd :: Eof state => state -> Maybe (Cost, state)

-- | The input state may maintain a location which can be used in
--   generating error messages. Since we do not want to fix our input to be
--   just a <tt>String</tt> we provide an interface which can be used to
--   advance this location by passing information about the part
--   recognised. This function is typically called in the
--   <tt>splitState</tt> functions.
class Show loc => loc `IsLocationUpdatedBy` str
advance :: IsLocationUpdatedBy loc str => loc -> str -> loc

-- | The class <a>StoresErrors</a> is used by the function <a>pErrors</a>
--   which retrieves the generated correction steps since the last time it
--   was called.
class state `StoresErrors` error | state -> error

-- | <a>getErrors</a> retrieves the correcting steps made since the last
--   time the function was called. The result can, by using it in a monad,
--   be used to control how to proceed with the parsing process.
getErrors :: StoresErrors state error => state -> ([error], state)
class state `HasPosition` pos | state -> pos

-- | <a>getPos</a> retrieves the correcting steps made since the last time
--   the function was called. The result can, by using it as the left hand
--   side of a monadic bind, be used to control how to proceed with the
--   parsing process.
getPos :: HasPosition state pos => state -> pos
data P st a
P :: (T st a) -> (Maybe (T st a)) -> (Maybe a) -> Nat -> P st a

-- | The data type <a>Steps</a> is the core data type around which the
--   parsers are constructed. It describes a tree structure of streams
--   containing (in an interleaved way) both the online result of the
--   parsing process, and progress information. Recognising an input token
--   should correspond to a certain amount of <tt><a>Progress</a></tt>,
--   which tells how much of the input state was consumed. The
--   <tt><a>Progress</a></tt> is used to implement the breadth-first search
--   process, in which alternatives are examined in a more-or-less
--   synchronised way. The meaning of the various <tt><a>Step</a></tt>
--   constructors is as follows:
--   
--   <ul>
--   <li><i><a>Step</a></i> A token was succesfully recognised, and as a
--   result the input was <tt>advanced</tt> by the distance
--   <tt><a>Progress</a></tt></li>
--   <li><i><a>Apply</a></i> The type of value represented by the
--   <a>Steps</a> changes by applying the function parameter.</li>
--   <li><i><a>Fail</a></i> A correcting step has to be made to the input;
--   the first parameter contains information about what was expected in
--   the input, and the second parameter describes the various corrected
--   alternatives, each with an associated <a>Cost</a></li>
--   <li><i><a>Micro</a></i> A small cost is inserted in the sequence,
--   which is used to disambiguate. Use with care!</li>
--   </ul>
--   
--   The last two alternatives play a role in recognising ambigous
--   non-terminals. For a full description see the technical report
--   referred to from <a>Text.ParserCombinators.UU.README</a>.
data Steps :: * -> *
[Step] :: Progress -> Steps a -> Steps a
[Apply] :: forall a b. (b -> a) -> Steps b -> Steps a
[Fail] :: Strings -> [Strings -> (Cost, Steps a)] -> Steps a
[Micro] :: Int -> Steps a -> Steps a
[Done] :: a -> Steps a
[End_h] :: ([a], [a] -> Steps r) -> Steps (a, r) -> Steps (a, r)
[End_f] :: [Steps a] -> Steps a -> Steps a
type Cost = Int
type Progress = Int

-- | The data type <tt><a>Nat</a></tt> is used to represent the minimal
--   length of a parser. Care should be taken in order to not evaluate the
--   right hand side of the binary function <tt>`nat-add`</tt> more than
--   necesssary.
data Nat
Zero :: Nat
Succ :: Nat -> Nat
Infinite :: Nat
Unspecified :: Nat
Hole :: Nat
type Strings = [String]

-- | <a>micro</a> inserts a <a>Cost</a> step into the sequence representing
--   the progress the parser is making; for its use see
--   `<a>Text.ParserCombinators.UU.Demos.Examples</a>`
micro :: P state a -> Int -> P state a

-- | For the precise functioning of the <a>amb</a> combinators see the
--   paper cited in the <a>Text.ParserCombinators.UU.README</a>; it
--   converts an ambiguous parser into a parser which returns a list of all
--   possible recognitions,
amb :: P st a -> P st [a]

-- | <a>pErrors</a> returns the error messages that were generated since
--   its last call.
pErrors :: StoresErrors st error => P st [error]

-- | <a>pPos</a> returns the current input position.
pPos :: HasPosition st pos => P st pos

-- | <a>pState</a> returns the current input state
pState :: P st st

-- | The function <a>pEnd</a> should be called at the end of the parsing
--   process. It deletes any unconsumed input, turning it into error
--   messages.
pEnd :: (StoresErrors st error, Eof st) => P st [error]

-- | <tt><a>pSwitch</a></tt> takes the current state and modifies it to a
--   different type of state to which its argument parser is applied. The
--   second component of the result is a function which converts the
--   remaining state of this parser back into a value of the original type.
--   For the second argument to <tt><a>pSwitch</a></tt> (say split) we
--   expect the following to hold:
--   
--   <pre>
--   let (n,f) = split st in f n == st
--   </pre>
pSwitch :: (st1 -> (st2, st2 -> st1)) -> P st2 a -> P st1 a

-- | The basic recognisers are written elsewhere (e.g. in our module
--   <a>Text.ParserCombinataors.UU.BasicInstances</a>; they (i.e. the
--   parameter <tt>splitState</tt>) are lifted to our<a>P</a> descriptors
--   by the function <a>pSymExt</a> which also takes the minimal number of
--   tokens recognised by the parameter <tt>splitState</tt> and an
--   <tt>Maybe</tt> value describing the possibly empty value.
pSymExt :: (forall a. (token -> state -> Steps a) -> state -> Steps a) -> Nat -> Maybe token -> P state token

-- | The function <tt><a>parse</a></tt> shows the prototypical way of
--   running a parser on some specific input. By default we use the future
--   parser, since this gives us access to partial result; future parsers
--   are expected to run in less space.
parse :: (Eof t) => P t a -> t -> a

-- | The function <tt><a>parse_h</a></tt> behaves like
--   <tt><a>parse</a></tt> but using the history parser. This parser does
--   not give online results, but might run faster.
parse_h :: (Eof t) => P t a -> t -> a

-- | <a>getZeroP</a> retrieves the possibly empty part from a descriptor.
getZeroP :: P t a -> Maybe a

-- | <a>getOneP</a> retrieves the non-zero part from a descriptor.
getOneP :: P a b -> Maybe (P a b)
addLength :: () => Int -> P st a -> P st a

-- | <tt><a>eval</a></tt> removes the progress information from a sequence
--   of steps, and constructs the value embedded in it. If you are really
--   desparate to see how your parsers are making progress (e.g. when you
--   have written an ambiguous parser, and you cannot find the cause of the
--   exponential blow-up of your parsing process), you may switch on the
--   trace in the function <tt><a>eval</a></tt> (you will need to edit the
--   library source code).
eval :: Steps a -> a
instance GHC.Show.Show Text.ParserCombinators.UU.Core.Nat
instance GHC.Base.MonadPlus (Text.ParserCombinators.UU.Core.P st)
instance GHC.Show.Show (Text.ParserCombinators.UU.Core.P st a)
instance GHC.Base.Functor (Text.ParserCombinators.UU.Core.P state)
instance GHC.Base.Applicative (Text.ParserCombinators.UU.Core.P state)
instance GHC.Base.Alternative (Text.ParserCombinators.UU.Core.P state)
instance Text.ParserCombinators.UU.Core.ExtAlternative (Text.ParserCombinators.UU.Core.P st)
instance Text.ParserCombinators.UU.Core.IsParser (Text.ParserCombinators.UU.Core.P st)
instance GHC.Base.Monad (Text.ParserCombinators.UU.Core.P st)
instance GHC.Base.Functor (Text.ParserCombinators.UU.Core.T st)
instance GHC.Base.Applicative (Text.ParserCombinators.UU.Core.T state)
instance GHC.Base.Alternative (Text.ParserCombinators.UU.Core.T state)
instance GHC.Show.Show (Text.ParserCombinators.UU.Core.Steps a)


-- | This module contains basic instances for the class interface described
--   in the <a>Text.ParserCombinators.UU.Core</a> module. It demonstates
--   how to construct and maintain a state during parsing. In the state we
--   store error messages, positional information and the actual input that
--   is being parsed. Unless you have very specific wishes the module can
--   be used as such. Since we make use of the <a>Data.ListLike</a>
--   interface a wide variety of input structures can be handled.
module Text.ParserCombinators.UU.BasicInstances

-- | The data type <a>Error</a> describes the various kinds of errors which
--   can be generated by the instances in this module
data Error pos

-- | <tt>String</tt> was inserted at <tt>pos</tt>-ition, where we expected
--   <tt>Strings</tt>
Inserted :: String -> pos -> Strings -> Error pos

-- | <tt>String</tt> was deleted at <tt>pos</tt>-ition, where we expected
--   <tt>Strings</tt>
Deleted :: String -> pos -> Strings -> Error pos

-- | for future use
Replaced :: String -> String -> pos -> Strings -> Error pos

-- | the unconsumed part of the input was deleted
DeletedAtEnd :: String -> Error pos

-- | The data type <a>Str</a> holds the input data to be parsed, the
--   current location, the error messages generated and whether it is ok to
--   delete elements from the input. Since an insert/delete action is the
--   same as a delete/insert action we try to avoid the first one. So: no
--   deletes after an insert.
data Str a s loc
Str :: s -> [Error loc] -> loc -> !Bool -> Str a s loc

-- | the unconsumed part of the input
[input] :: Str a s loc -> s

-- | the accumulated error messages
[msgs] :: Str a s loc -> [Error loc]

-- | the current input position
[pos] :: Str a s loc -> loc

-- | we want to avoid deletions after insertions
[deleteOk] :: Str a s loc -> !Bool

-- | the <tt>String</tt> describes what is being inserted, the <tt>a</tt>
--   parameter the value which is to be inserted and the <tt>cost</tt> the
--   prices to be paid.
data Insertion a
Insertion :: String -> a -> Cost -> Insertion a
data LineCol
LineCol :: !Int -> !Int -> LineCol
data LineColPos
LineColPos :: !Int -> !Int -> !Int -> LineColPos

-- | A <a>Parser</a> is a parser that is prepared to accept
--   <a>Data.Listlike</a> input; hence we can deal with <tt>String</tt>'s,
--   <tt>ByteString</tt>'s, etc.
type Parser a = forall loc state. (IsLocationUpdatedBy loc Char, ListLike state Char) => P (Str Char state loc) a

-- | A <tt><a>ParserTrafo</a> a b</tt> maps a <tt><a>Parser</a> a</tt> onto
--   a <tt><a>Parser</a> b</tt>.
type ParserTrafo a b = forall loc state. (IsLocationUpdatedBy loc Char, ListLike state Char) => P (Str Char state loc) a -> P (Str Char state loc) b

-- | The input state may maintain a location which can be used in
--   generating error messages. Since we do not want to fix our input to be
--   just a <tt>String</tt> we provide an interface which can be used to
--   advance this location by passing information about the part
--   recognised. This function is typically called in the
--   <tt>splitState</tt> functions.
class Show loc => loc `IsLocationUpdatedBy` str

-- | <a>createStr</a> initialises the input stream with the input data and
--   the initial position. There are no error messages yet.
createStr :: ListLike s a => loc -> s -> Str a s loc
show_expecting :: Show pos => pos -> [String] -> String

-- | <a>pSatisfy</a> describes and elementary parsing step. Its first
--   parameter check whether the head element of the input can be
--   recognised, and the second parameter how to proceed in case an element
--   recognised by this parser is absent, and parsing may proceed by
--   pretending such an element was present in the input anayway.
pSatisfy :: forall loc state a. ((Show a, loc `IsLocationUpdatedBy` a, ListLike state a) => (a -> Bool) -> (Insertion a) -> P (Str a state loc) a)

-- | <a>pRangeInsert</a> recognises an element between a lower and an upper
--   bound. Furthermore it can be specified what element is to be inserted
--   in case such an element is not at the head of the input.
pRangeInsert :: (Ord a, Show a, IsLocationUpdatedBy loc a, ListLike state a) => (a, a) -> Insertion a -> P (Str a state loc) a

-- | <a>pRange</a> uses the information from the bounds to compute the
--   <a>Insertion</a> information.
pRange :: (Ord a, Show a, IsLocationUpdatedBy loc a, ListLike state a) => (a, a) -> P (Str a state loc) a

-- | <a>pSymInsert</a> recognises a specific element. Furthermore it can be
--   specified what element is to be inserted in case such an element is
--   not at the head of the input.
pSymInsert :: (Eq a, Show a, IsLocationUpdatedBy loc a, ListLike state a) => a -> Insertion a -> P (Str a state loc) a

-- | <a>pSym</a> recognises a specific element. Furthermore it can be
--   specified what element. Information about <a>Insertion</a> is derived
--   from the parameter. is to be inserted in case such an element is not
--   at the head of the input.
pSym :: (Eq a, Show a, IsLocationUpdatedBy loc a, ListLike state a) => a -> P (Str a state loc) a
pToken :: forall loc state a. ((Show a, Eq a, loc `IsLocationUpdatedBy` a, ListLike state a) => [a] -> P (Str a state loc) [a])

-- | <a>pTokenCost</a> succeeds if its parameter is a prefix of the input.
pTokenCost :: forall loc state a. ((Show a, Eq a, loc `IsLocationUpdatedBy` a, ListLike state a) => [a] -> Int -> P (Str a state loc) [a])

-- | <a>pMunch</a> recognises the longest prefix of the input for which the
--   passed predicate holds.
pMunch :: forall loc state a. ((Show a, loc `IsLocationUpdatedBy` a, ListLike state a) => (a -> Bool) -> P (Str a state loc) [a])

-- | <a>pMunchL</a> recognises the longest prefix of the input for which
--   the passed predicate holds. The message parameter is used when tracing
--   has been switched on.
pMunchL :: forall loc state a. ((Show a, loc `IsLocationUpdatedBy` a, ListLike state a) => (a -> Bool) -> String -> P (Str a state loc) [a])
instance GHC.Show.Show Text.ParserCombinators.UU.BasicInstances.LineColPos
instance GHC.Show.Show Text.ParserCombinators.UU.BasicInstances.LineCol
instance Text.ParserCombinators.UU.Core.IsLocationUpdatedBy Text.ParserCombinators.UU.BasicInstances.LineColPos GHC.Types.Char
instance Text.ParserCombinators.UU.Core.IsLocationUpdatedBy Text.ParserCombinators.UU.BasicInstances.LineCol GHC.Types.Char
instance (GHC.Show.Show a, Data.ListLike.Base.ListLike s a) => Text.ParserCombinators.UU.Core.Eof (Text.ParserCombinators.UU.BasicInstances.Str a s loc)
instance Text.ParserCombinators.UU.Core.StoresErrors (Text.ParserCombinators.UU.BasicInstances.Str a s loc) (Text.ParserCombinators.UU.BasicInstances.Error loc)
instance Text.ParserCombinators.UU.Core.HasPosition (Text.ParserCombinators.UU.BasicInstances.Str a s loc) loc
instance GHC.Show.Show pos => GHC.Show.Show (Text.ParserCombinators.UU.BasicInstances.Error pos)
instance Text.ParserCombinators.UU.Core.IsLocationUpdatedBy GHC.Types.Int GHC.Types.Char
instance Text.ParserCombinators.UU.Core.IsLocationUpdatedBy GHC.Types.Int GHC.Word.Word8
instance Text.ParserCombinators.UU.Core.IsLocationUpdatedBy loc a => Text.ParserCombinators.UU.Core.IsLocationUpdatedBy loc [a]


-- | This module contains a large variety of combinators for list-like
--   structures. the extension <tt>_ng</tt> indicates that that variant is
--   the non-greedy variant. See the
--   <a>Text.ParserCombinators.UU.Demo.Examples</a> module for some
--   examples of their use.
module Text.ParserCombinators.UU.Derived

-- | <tt><a>pReturn</a></tt> is defined for upwards compatibility
pReturn :: Applicative p => a -> p a

-- | <tt><a>pFail</a></tt> is defined for upwards compatibility, and is the
--   unit for <tt><a>|</a></tt>
pFail :: Alternative p => p a

-- | <a>pMaybe</a> greedily recognises its argument. If not
--   <tt>Nothing</tt> is returned.
pMaybe :: IsParser p => p a -> p (Maybe a)

-- | <a>pEither</a> recognises either one of its arguments.
pEither :: IsParser p => p a -> p b -> p (Either a b)

-- | <a>&lt;$$&gt;</a> is the version of <a>&lt;$&gt;</a> which flips the
--   function argument
(<$$>) :: IsParser p => (a -> b -> c) -> p b -> p (a -> c)

-- | <a>&lt;??&gt;</a> parses an optional postfix element and applies its
--   result to its left hand result
(<??>) :: IsParser p => p a -> p (a -> a) -> p a
infixl 4 <??>

-- | <a>&lt;.&gt;</a> functional composition of two parsers
(<.>) :: IsParser p => p (b -> c) -> p (a -> b) -> p (a -> c)

-- | <a>&lt;..&gt;</a> functional composition of two parsers with the
--   arguments reversed
(<..>) :: IsParser p => p (a -> b) -> p (b -> c) -> p (a -> c)

-- | <a>pMany</a> is equivalent to the <a>many</a> from
--   <a>Control.Applicative</a>. We want however all our parsers to start
--   with a lower case <tt>p</tt>.
pMany :: IsParser p => p a -> p [a]

-- | <a>pSome</a> is equivalent to the <a>some</a> from
--   <a>Control.Applicative</a>. We want however all our parsers to start
--   with a lower case <tt>p</tt>.
pSome :: (IsParser f) => f a -> f [a]

-- | <tt><a>pPacked</a></tt> surrounds its third parser with the first and
--   the second one, returning only the middle result
pPacked :: IsParser p => p b1 -> p b2 -> p a -> p a
pFoldr :: IsParser p => (a -> a1 -> a1, a1) -> p a -> p a1
pFoldr_ng :: IsParser p => (a -> a1 -> a1, a1) -> p a -> p a1
pFoldr1 :: IsParser p => (v -> b -> b, b) -> p v -> p b
pFoldr1_ng :: IsParser p => (v -> b -> b, b) -> p v -> p b
list_alg :: (a -> [a] -> [a], [a1])
pList :: IsParser p => p a -> p [a]
pList_ng :: IsParser p => p a -> p [a]
pList1 :: IsParser p => p a -> p [a]
pList1_ng :: IsParser p => p a -> p [a]
pFoldrSep :: IsParser p => (v -> b -> b, b) -> p a -> p v -> p b
pFoldrSep_ng :: IsParser p => (v -> b -> b, b) -> p a -> p v -> p b
pFoldr1Sep :: IsParser p => (a -> b -> b, b) -> p a1 -> p a -> p b
pFoldr1Sep_ng :: IsParser p => (a -> b -> b, b) -> p a1 -> p a -> p b
pListSep :: IsParser p => p a1 -> p a -> p [a]
pListSep_ng :: IsParser p => p a1 -> p a -> p [a]
pList1Sep :: IsParser p => p a1 -> p a -> p [a]
pList1Sep_ng :: IsParser p => p a1 -> p a -> p [a]
pChainr :: IsParser p => p (c -> c -> c) -> p c -> p c
pChainr_ng :: IsParser p => p (c -> c -> c) -> p c -> p c
pChainl :: IsParser p => p (c -> c -> c) -> p c -> p c
pChainl_ng :: IsParser p => p (c -> c -> c) -> p c -> p c

-- | <a>pExact</a> recognises a specified number of elements
pExact :: (IsParser f) => Int -> f a -> f [a]
pBetween :: (IsParser f) => Int -> Int -> f a -> f [a]
pAtLeast :: (IsParser f) => Int -> f a -> f [a]
pAtMost :: (IsParser f) => Int -> f a -> f [a]

-- | Count the number of times <tt>p</tt> has succeeded
pCount :: (IsParser p, Num b) => p a -> p b

-- | Build a parser for each element in the argument list and try them all.
pAny :: IsParser p => (a -> p a1) -> [a] -> p a1


-- | The non-exported modules in <a>Text.ParserCombinators.UU.Demo</a>
--   contain a list of examples of how to use the main functionality of
--   this library which demonstrates:
--   
--   <ul>
--   <li>how to write basic parsers</li>
--   <li>how to to write ambiguous parsers</li>
--   <li>how error correction works</li>
--   <li>how to fine-tune your parsers to get rid of ambiguities</li>
--   <li>how to use the monadic interface</li>
--   <li>what kind of error messages you can expect if you write erroneous
--   parsers</li>
--   <li>how to use the permutating/merging parsers</li>
--   <li>to see the parsers in action load the module
--   <a>Text.ParserCombinators.UU.Demo.Examples</a> or
--   <a>Text.ParserCombinators.UU.Demo.MergeAndPermute</a> in <tt>ghci</tt>
--   and type <tt>show_demos</tt>, while looking at the corresponding
--   code</li>
--   </ul>
module Text.ParserCombinators.UU


-- | This module contains the additional data types, instance definitions
--   and functions to run parsers in an interleaved way. If all the
--   interleaved parsers recognise a single connected piece of the input
--   text this incorporates the permutation parsers. For some examples see
--   the module <a>Text.ParserCombinators.UU.Demo.MergeAndPermute</a>.
module Text.ParserCombinators.UU.Interleaved
mkP :: Gram (P st) a -> P st a

-- | <a>doNotInterpret</a> forgets the computed minimal number of tokens
--   recognised by this parser which makes a parser opaque for abstract
--   interpretation; used when interleaving parsers where we do not want to
--   compare lengths.
doNotInterpret :: P st a -> P st a
instance Control.Applicative.Interleaved.Splittable (Text.ParserCombinators.UU.Core.P st)
instance GHC.Base.Functor f => Text.ParserCombinators.UU.Core.ExtAlternative (Control.Applicative.Interleaved.Gram f)
instance Text.ParserCombinators.UU.Core.IsParser (Control.Applicative.Interleaved.Gram (Text.ParserCombinators.UU.Core.P st))


-- | This module contains some background information about a completely
--   new version of the Utrecht parser combinator library.
--   
--   Background material
--   
--   The library is based on ideas described in the paper:
--   
--   @inproceedings{uuparsing:piriapolis, Author = {Swierstra, S.~Doaitse},
--   Booktitle = {Language Engineering and Rigorous Software Development},
--   Editor = {Bove, A. and Barbosa, L. and Pardo, A. and and Sousa Pinto,
--   J.}, Pages = {252-300}, Place = {Piriapolis}, Publisher = {Spinger},
--   Series = {LNCS}, Title = {Combinator Parsers: a short tutorial},
--   Volume = {5520}, Year = {2009}}
--   
--   which is also available as a technical report from
--   <a>http://www.cs.uu.nl/research/techreps/repo/CS-2008/2008-044.pdf</a>
--   
--   The first part of this report is a general introduction to parser
--   combinators, whereas the second part contains the motivation for and
--   documentation of the current package.
--   
--   We appreciate if you include a reference to the above documentation in
--   any publication describing software in which you have used the library
--   succesfully.
--   
--   Any feedback on particular use of the library, and suggestions for
--   extensions, are welcome at <a>mailto:doaitse@swierstra.net</a>
module Text.ParserCombinators.UU.README


-- | This module provides some higher-level types and infrastructure to
--   make it easier to use.
module Text.ParserCombinators.UU.Utils
pCR :: Parser Char
pLF :: Parser Char
pLower :: Parser Char
pUpper :: Parser Char
pLetter :: Parser Char
pAscii :: Parser Char
pDigit :: Parser Char
pDigitAsNum :: Num a => Parser a
pAnySym :: (IsLocationUpdatedBy loc Char, ListLike state Char) => String -> P (Str Char state loc) Char
pSpaces :: Parser String

-- | Lexeme Parsers skip trailing whitespace (this terminology comes from
--   Parsec)
lexeme :: ParserTrafo a a
pDot :: Parser Char
pComma :: Parser Char
pDQuote :: Parser Char
pLParen :: Parser Char
pRParen :: Parser Char
pLBracket :: Parser Char
pRBracket :: Parser Char
pLBrace :: Parser Char
pRBrace :: Parser Char
pSymbol :: (IsLocationUpdatedBy loc Char, ListLike state Char) => String -> P (Str Char state loc) String
pNaturalRaw :: (Num a) => Parser a
pIntegerRaw :: (Num a) => Parser a
pDoubleRaw :: (Read a) => Parser a
pDoubleStr :: Parser [Char]
pNatural :: Num a => Parser a
pInteger :: Num a => Parser a
pDouble :: Parser Double
pPercent :: Parser Double
pEnumRaw :: forall a. ((Enum a, Show a) => Parser a)
pEnum :: (Enum a, Show a) => Parser a
pEnumStrs :: [String] -> Parser String
pParens :: ParserTrafo a a
pBraces :: ParserTrafo a a
pBrackets :: ParserTrafo a a

-- | eg [1,2,3]
listParser :: ParserTrafo a [a]

-- | eg (1,2,3)
tupleParser :: ParserTrafo a [a]
pTuple :: (IsLocationUpdatedBy loc Char, ListLike state Char) => [P (Str Char state loc) a] -> P (Str Char state loc) [a]
pDay :: Parser Day
pDayMonthYear :: (Num d, Num y) => Parser (d, Int, y)
pParentheticalString :: Char -> Parser String
pQuotedString :: Parser String

-- | Converts a UU Parser into a read-style one.
--   
--   This is intended to facilitate migration from read-style parsers to
--   UU-based ones.
parserReadsPrec :: Parser a -> Int -> ReadS a

-- | The lower-level interface. Returns all errors.
execParser :: Parser a -> String -> (a, [Error LineColPos])

-- | The higher-level interface. (Calls <a>error</a> with a simplified
--   error). Runs the parser; if the complete input is accepted without
--   problems return the result else fail with reporting unconsumed tokens
runParser :: String -> Parser a -> String -> a
instance GHC.Classes.Ord Text.ParserCombinators.UU.Utils.Month
instance GHC.Show.Show Text.ParserCombinators.UU.Utils.Month
instance GHC.Classes.Eq Text.ParserCombinators.UU.Utils.Month
instance GHC.Enum.Bounded Text.ParserCombinators.UU.Utils.Month
instance GHC.Enum.Enum Text.ParserCombinators.UU.Utils.Month


-- | This module contains a lot of examples of the typical use of our
--   parser combinator library. We strongly encourage you to take a look at
--   the source code. At the end you find a <tt><tt>main</tt></tt> function
--   which demonstrates the main characteristics. Only the
--   <tt><a>run</a></tt> function is exported since it may come in handy
--   elsewhere.
module Text.ParserCombinators.UU.Demo.Examples
type Parser a = P (Str Char String LineColPos) a
justamessage :: [Char]

-- | Running the function <a>show_demos</a> should give the following
--   output:
--   
--   <pre>
--   &gt;&gt;&gt; run pa  "a"
--    Result: "a"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run pa  ""
--    Result: "a"
--    Correcting steps: 
--      Inserted  'a' at position LineColPos 0 0 0 expecting 'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run pa  "b"
--    Result: "a"
--    Correcting steps: 
--      Deleted   'b' at position LineColPos 0 0 0 expecting 'a'
--      Inserted  'a' at position LineColPos 0 1 1 expecting 'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run ((++) &lt;$&gt; pa &lt;*&gt; pa)  "bbab"
--    Result: "aa"
--    Correcting steps: 
--      Deleted   'b' at position LineColPos 0 0 0 expecting 'a'
--      Deleted   'b' at position LineColPos 0 1 1 expecting 'a'
--      Deleted   'b' at position LineColPos 0 3 3 expecting 'a'
--      Inserted  'a' at position LineColPos 0 4 4 expecting 'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run pa  "ba"
--    Result: "a"
--    Correcting steps: 
--      Deleted   'b' at position LineColPos 0 0 0 expecting 'a'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run pa  "aa"
--    Result: "a"
--    Correcting steps: 
--      The token 'a' was not consumed by the parsing process.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (pCount pa :: Parser Int)  "aaa"
--    Result: 3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (do  {l &lt;- pCount pa; pExact l pb})  "aaacabbbbb"
--    Result: ["b","b","b","b"]
--    Correcting steps: 
--      Deleted   'c' at position LineColPos 0 3 3 expecting one of ['b', 'a']
--      The token 'b' was not consumed by the parsing process.
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (amb ( (++) &lt;$&gt; pa2 &lt;*&gt; pa3 &lt;|&gt; (++) &lt;$&gt; pa3 &lt;*&gt; pa2))  "aaaaa"
--    Result: ["aaaaa","aaaaa"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (pList pLower)  "doaitse"
--    Result: "doaitse"
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run paz  "abc2ez"
--    Result: "abcez"
--    Correcting steps: 
--      Deleted   '2' at position LineColPos 0 3 3 expecting 'a'..'z'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (max &lt;$&gt; pParens ((+1) &lt;$&gt; wfp) &lt;*&gt; wfp `opt` 0)  "((()))()(())"
--    Result: 3
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (pa &lt;|&gt; pb &lt;?&gt; justamessage)  "c"
--    Result: "b"
--    Correcting steps: 
--      Deleted   'c' at position LineColPos 0 0 0 expecting justamessage
--      Inserted  'b' at position LineColPos 0 1 1 expecting 'b'
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; run (amb (pEither  parseIntString  pIntList))  "(123;456;789)"
--    Result: [Left ["123","456","789"],Right [123,456,789]]
--   </pre>
show_demos :: IO ()

-- | The fuction <tt><a>run</a></tt> runs the parser and shows both the
--   result, and the correcting steps which were taken during the parsing
--   process.
run :: Show t => Parser t -> String -> IO ()
run' :: (Show a2, ListLike p a2, Show a1) => P Str a2 p LineColPos a1 -> p -> IO ()

-- | Our first two parsers are simple; one recognises a single <tt>a</tt>
--   character and the other one a single <tt>b</tt>. Since we will use
--   them later we convert the recognised character into <a>String</a> so
--   they can be easily combined.
pa :: Parser String
pb :: Parser String
pc :: Parser String
lift :: () => a -> [a]
(<++>) :: Parser String -> Parser String -> Parser String
pa2 :: Parser String
pa3 :: Parser String
paz :: Parser String

-- | The applicative style makes it very easy to merge recogition and
--   computing a result. As an example we parse a sequence of nested well
--   formed parentheses pairs and compute the maximum nesting depth with
--   <tt><a>wfp</a></tt>:
wfp :: Parser Int

-- | It is very easy to recognise infix expressions with any number of
--   priorities and operators:
--   
--   <pre>
--   operators       = [[('+', (+)), ('-', (-))],  [('*' , (*))], [('^', (^))]]
--   same_prio  ops  = msum [ op &lt;$ pSym c | (c, op) &lt;- ops]
--   expr            = foldr pChainl ( pNatural &lt;|&gt; pParens expr) (map same_prio operators) -- 
--   </pre>
--   
--   which we can call:
--   
--   <pre>
--   run expr "15-3*5+2^5"
--   </pre>
--   
--   <pre>
--   Result: 32
--   </pre>
--   
--   Note that also here correction takes place:
--   
--   <pre>
--   run expr "2 + + 3 5"
--   </pre>
--   
--   <pre>
--   Result: 37
--   Correcting steps: 
--      Deleted  ' ' at position 1 expecting one of ['0'..'9', '^', '*', '-', '+']
--      Deleted  ' ' at position 3 expecting one of ['(', '0'..'9']
--      Inserted '0' at position 4 expecting '0'..'9'
--      Deleted  ' ' at position 5 expecting one of ['(', '0'..'9']
--      Deleted  ' ' at position 7 expecting one of ['0'..'9', '^', '*', '-', '+']
--   </pre>
test11 :: IO ()
expr :: Parser Int
operators :: Integral a => [[(Char, a -> a -> a)]]
same_prio :: (Show b, ListLike state b, IsLocationUpdatedBy loc b, Eq b) => [(b, a)] -> P Str b state loc a

-- | A common case where ambiguity arises is when we e.g. want to recognise
--   identifiers, but only those which are not keywords. The combinator
--   <a>micro</a> inserts steps with a specfied cost in the result of the
--   parser which can be used to disambiguate:
--   
--   <pre>
--   ident ::  Parser String
--   ident = ((:) &lt;$&gt; pSym ('a','z') &lt;*&gt; pMunch (\x -&gt; 'a' &lt;= x &amp;&amp; x &lt;= 'z') `micro` 2) &lt;* spaces
--   idents = pList1 ident
--   pKey keyw = pToken keyw `micro` 1 &lt;* spaces
--   spaces :: Parser String
--   spaces = pMunch (==' ')
--   takes_second_alt =   pList ident 
--                  \&lt;|&gt; (\ c t e -&gt; ["IfThenElse"] ++  c   ++  t  ++  e) 
--                      \&lt;$ pKey "if"   &lt;*&gt; pList_ng ident 
--                      \&lt;* pKey "then" &lt;*&gt; pList_ng ident
--                      \&lt;* pKey "else" &lt;*&gt; pList_ng ident  
--   </pre>
--   
--   A keyword is followed by a small cost <tt>1</tt>, which makes sure
--   that identifiers which have a keyword as a prefix win over the
--   keyword. Identifiers are however followed by a cost <tt>2</tt>, with
--   as result that in this case the keyword wins. Note that a limitation
--   of this approach is that keywords are only recognised as such when
--   expected!
--   
--   <pre>
--   test13 = run takes_second_alt "if a then if else c"
--   test14 = run takes_second_alt "ifx a then if else c"
--   </pre>
--   
--   with results for <tt>test13</tt> and <tt>test14</tt>:
--   
--   <pre>
--   Result: ["IfThenElse","a","if","c"]
--   Result: ["ifx","a","then","if", "else","c"]
--   </pre>
--   
--   A mistake which is made quite often is to construct a parser which can
--   recognise a sequence of elements using one of the derived combinators
--   (say <tt><a>pList</a></tt>), but where the argument parser can
--   recognise the empty string. The derived combinators check whether this
--   is the case and terminate the parsing process with an error message:
--   
--   <pre>
--   run (pList spaces) ""
--   Result: *** Exception: The combinator pList
--    requires that it's argument cannot recognise the empty string
--   </pre>
--   
--   <pre>
--   run (pMaybe spaces) " "
--   Result: *** Exception: The combinator pMaybe
--   requires that it's argument cannot recognise the empty string
--   </pre>
test16 :: IO ()
ident :: P Str Char String LineColPos [Char]
idents :: P Str Char String LineColPos [[Char]]
pKey :: [Char] -> P Str Char String LineColPos [Char]
spaces :: Parser String
takes_second_alt :: P Str Char String LineColPos [[Char]]
test13 :: IO ()
test14 :: IO ()
pManyTill :: P st a -> P st b -> P st [a]
simpleComment :: (ListLike state Char, IsLocationUpdatedBy loc Char) => P Str Char state loc [Char]
string :: (IsLocationUpdatedBy loc Char, ListLike state Char) => String -> P (Str Char state loc) String
pVarId :: (ListLike state Char, IsLocationUpdatedBy loc Char) => P Str Char state loc [Char]
pConId :: (ListLike state Char, IsLocationUpdatedBy loc Char) => P Str Char state loc [Char]
pIdChar :: (ListLike state Char, IsLocationUpdatedBy loc Char) => P Str Char state loc Char
pAnyToken :: (IsLocationUpdatedBy loc Char, ListLike state Char) => [String] -> P (Str Char state loc) String
pIntList :: Parser [Int]
parseIntString :: Parser [String]
demo :: Show r => String -> String -> P (Str Char String LineColPos) r -> IO ()

module Text.ParserCombinators.UU.Idioms
data IF
IF :: IF
data THEN
THEN :: THEN
data ELSE
ELSE :: ELSE
data FI
FI :: FI
data OR
OR :: OR
data String'
String' :: String -> String'
[fromStr] :: String' -> String

-- | The <a>Ii</a> is to be pronounced as <tt>stop</tt>
data Ii
Ii :: Ii

-- | The function <a>iI</a> is to be pronounced as <tt>start</tt>
iI :: Idiomatic i (a -> a) g => g
class Idiomatic st f g | g -> f st
idiomatic :: Idiomatic st f g => P st f -> g

-- | The idea of the Idiom concept is that sequential composition operators
--   can be inferred from the type of the various operands
--   
--   <pre>
--   &gt;&gt;&gt; run (iI (+) '(' pNatural "plus"  pNatural ')' Ii) "(2 plus 3"
--     Result: 5
--      Correcting steps: 
--        Inserted  ')' at position LineColPos 0 4 4 expecting one of [')', Whitespace, '0'..'9']
--   </pre>
pNat :: Parser Int
show_demos :: IO ()
instance Text.ParserCombinators.UU.Idioms.Idiomatic st x (Text.ParserCombinators.UU.Idioms.Ii -> Text.ParserCombinators.UU.Core.P st x)
instance Text.ParserCombinators.UU.Idioms.Idiomatic st f g => Text.ParserCombinators.UU.Idioms.Idiomatic st (a -> f) (Text.ParserCombinators.UU.Core.P st a -> g)
instance Text.ParserCombinators.UU.Idioms.Idiomatic st f g => Text.ParserCombinators.UU.Idioms.Idiomatic st ((a -> b) -> f) ((a -> b) -> g)
instance (Text.ParserCombinators.UU.Idioms.Idiomatic (Text.ParserCombinators.UU.BasicInstances.Str GHC.Types.Char state loc) f g, Text.ParserCombinators.UU.Core.IsLocationUpdatedBy loc GHC.Types.Char, Data.ListLike.Base.ListLike state GHC.Types.Char) => Text.ParserCombinators.UU.Idioms.Idiomatic (Text.ParserCombinators.UU.BasicInstances.Str GHC.Types.Char state loc) f (GHC.Base.String -> g)
instance (Text.ParserCombinators.UU.Idioms.Idiomatic (Text.ParserCombinators.UU.BasicInstances.Str GHC.Types.Char state loc) f g, Text.ParserCombinators.UU.Core.IsLocationUpdatedBy loc GHC.Types.Char, Data.ListLike.Base.ListLike state GHC.Types.Char) => Text.ParserCombinators.UU.Idioms.Idiomatic (Text.ParserCombinators.UU.BasicInstances.Str GHC.Types.Char state loc) f (GHC.Types.Char -> g)
instance Text.ParserCombinators.UU.Idioms.Idiomatic st f g => Text.ParserCombinators.UU.Idioms.Idiomatic st (a -> f) (Text.ParserCombinators.UU.Idioms.IF -> GHC.Types.Bool -> Text.ParserCombinators.UU.Idioms.THEN -> Text.ParserCombinators.UU.Core.P st a -> Text.ParserCombinators.UU.Idioms.ELSE -> Text.ParserCombinators.UU.Core.P st a -> Text.ParserCombinators.UU.Idioms.FI -> g)
