-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Generalised permutation parser combinator
--
-- General permutation parser combinators that will work with any parser
-- combinator library.
@package permute
@version 1.0
-- | This module implements permutation parsers, and is a generalisation of
-- Text.Parsec.Perm that will work with any parser combinator
-- library. The algorithm is described in:
--
-- Parsing Permutation Phrases, by Arthur Baars, Andres Loh and
-- Doaitse Swierstra.
module Text.ParserCombinators.Perm
-- | The type PermParser p a denotes a permutation parser that,
-- when converted by the permute function, parses s
-- streams with user state st and returns a value of type
-- a on success.
--
-- Normally, a permutation parser is first build with special operators
-- like (<||>) and than transformed into a normal parser
-- using permute.
data PermParser p a
-- | The parser permute perm parses a permutation of parser
-- described by perm. For example, suppose we want to parse a
-- permutation of: an optional string of a's, the character
-- b and an optional c. This can be described by:
--
--
-- test = permute (tuple <$?> ("",many1 (char 'a'))
-- <||> char 'b'
-- <|?> ('_',char 'c'))
-- where
-- tuple a b c = (a,b,c)
--
permute :: (Alternative p, Monad p) => PermParser p a -> p a
-- | The expression perm <||> p adds parser p to
-- the permutation parser perm. The parser p is not
-- allowed to accept empty input - use the optional combinator
-- (<|?>) instead. Returns a new permutation parser that
-- includes p.
(<||>) :: PermParser p (a -> b) -> p a -> PermParser p b
-- | The expression f <$$> p creates a fresh permutation
-- parser consisting of parser p. The the final result of the
-- permutation parser is the function f applied to the return
-- value of p. The parser p is not allowed to accept
-- empty input - use the optional combinator (<$?>) instead.
--
-- If the function f takes more than one parameter, the type
-- variable b is instantiated to a functional type which
-- combines nicely with the adds parser p to the
-- (<||>) combinator. This results in stylized code where a
-- permutation parser starts with a combining function f
-- followed by the parsers. The function f gets its parameters
-- in the order in which the parsers are specified, but actual input can
-- be in any order.
(<$$>) :: (a -> b) -> p a -> PermParser p b
-- | The expression perm <||> (x,p) adds parser p
-- to the permutation parser perm. The parser p is
-- optional - if it can not be applied, the default value x will
-- be used instead. Returns a new permutation parser that includes the
-- optional parser p.
(<|?>) :: PermParser p (a -> b) -> (a, p a) -> PermParser p b
-- | The expression f <$?> (x,p) creates a fresh permutation
-- parser consisting of parser p. The the final result of the
-- permutation parser is the function f applied to the return
-- value of p. The parser p is optional - if it can not
-- be applied, the default value x will be used instead.
(<$?>) :: (a -> b) -> (a, p a) -> PermParser p b