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


-- | Port of parsec's expression parser to attoparsec.
--   
--   Port of parsec's expression parser to attoparsec.
@package attoparsec-expr
@version 0.1.1.2


-- | Author : derek.a.elkins<tt>gmail.com Ported by : Sebastiaan Visser
--   &lt;haskell</tt>fvisser.nl&gt; Stability : provisional Portability :
--   non-portable
--   
--   A helper module to parse "expressions". Builds a parser given a table
--   of operators and associativities.
module Data.Attoparsec.Expr

-- | This data type specifies the associativity of operators: left, right
--   or none.
data Assoc
AssocNone :: Assoc
AssocLeft :: Assoc
AssocRight :: Assoc

-- | This data type specifies operators that work on values of type
--   <tt>a</tt>. An operator is either binary infix or unary prefix or
--   postfix. A binary operator has also an associated associativity.
data Operator t a
Infix :: (Parser t (a -> a -> a)) -> Assoc -> Operator t a
Prefix :: (Parser t (a -> a)) -> Operator t a
Postfix :: (Parser t (a -> a)) -> Operator t a

-- | An <tt>OperatorTable</tt> is a list of <tt>Operator</tt> lists. The
--   list is ordered in descending precedence. All operators in one list
--   have the same precedence (but may have a different associativity).
type OperatorTable t a = [[Operator t a]]

-- | <tt>buildExpressionParser table term</tt> builds an expression parser
--   for terms <tt>term</tt> with operators from <tt>table</tt>, taking the
--   associativity and precedence specified in <tt>table</tt> into account.
--   Prefix and postfix operators of the same precedence can only occur
--   once (i.e. <tt>--2</tt> is not allowed if <tt>-</tt> is prefix
--   negate). Prefix and postfix operators of the same precedence associate
--   to the left (i.e. if <tt>++</tt> is postfix increment, than
--   <tt>-2++</tt> equals <tt>-1</tt>, not <tt>-3</tt>).
--   
--   The <tt>buildExpressionParser</tt> takes care of all the complexity
--   involved in building expression parser. Here is an example of an
--   expression parser that handles prefix signs, postfix increment and
--   basic arithmetic.
--   
--   <pre>
--   expr    = buildExpressionParser table term
--           &lt;?&gt; "expression"
--   
--   term    =  parens expr 
--           &lt;|&gt; natural
--           &lt;?&gt; "simple expression"
--   
--   table   = [ [prefix "-" negate, prefix "+" id ]
--             , [postfix "++" (+1)]
--             , [binary "*" (*) AssocLeft, binary "/" (div) AssocLeft ]
--             , [binary "+" (+) AssocLeft, binary "-" (-)   AssocLeft ]
--             ]
--           
--   binary  name fun assoc = Infix (do{ reservedOp name; return fun }) assoc
--   prefix  name fun       = Prefix (do{ reservedOp name; return fun })
--   postfix name fun       = Postfix (do{ reservedOp name; return fun })
--   </pre>
buildExpressionParser :: Monoid t => [[Operator t b]] -> Parser t b -> Parser t b
