/fparsec/main/FParsec/OperatorPrecedenceParser.fsi

  1// Copyright (c) Stephan Tolksdorf 2008-2009
  2// License: Simplified BSD License. See accompanying documentation.
  3
  4module FParsec.OperatorPrecedenceParser
  5
  6open FParsec.Primitives
  7
  8// Represents the associativity of infix operators.
  9type Assoc = None    = 0
 10           | Left    = 1
 11           | Right   = 2
 12
 13/// This union type is used to define operators for an OperatorPrecedenceParser.
 14[<ReferenceEquality>]
 15type PrecedenceParserOp<'a,'u> =
 16     // the operators are parsed as if they were given as "pstring opString >>? whitespaceAfterOpParser"
 17
 18     /// PrefixOp(opString, wsAfterOpParser, precedence, isAssociative, f)
 19     /// represents a prefix operator definition for the `OperatorPrecedenceParser`.
 20     | PrefixOp  of string * Parser<unit,'u> * int * bool * ('a -> 'a)
 21     /// PostfixOp(opString, wsAfterOpParser, precedence, isAssociative, f)
 22     /// represents a postfix operator definition for the `OperatorPrecedenceParser`.
 23     | PostfixOp of string * Parser<unit,'u> * int * bool * ('a -> 'a)
 24     /// InfixOp(opString, wsAfterOpParser, precedence, associativity, f)
 25     /// represents an infix operator definition for the `OperatorPrecedenceParser`.
 26     | InfixOp   of string * Parser<unit,'u> * int * Assoc * ('a -> 'a -> 'a)
 27     /// TernaryOp(op1String, wsAfterOp1Parser, op2String, wsAfterOp2Parser, precedence, associativity, f)
 28     /// represents a ternary operator definition for the `OperatorPrecedenceParser`.
 29     | TernaryOp of string * Parser<unit,'u> *
 30                    string * Parser<unit,'u> * int * Assoc * ('a -> 'a -> 'a -> 'a)
 31
 32     /// PrefixOp'(opString, wsAfterOpParser, precedence, isAssociative, f),
 33     /// The state passed as an argument to the function is captured immediately before
 34     /// the operator string is parsed and contains the position of the operator.
 35     | PrefixOp'  of string * Parser<unit,'u> * int * bool * (State<'u> -> 'a -> 'a)
 36     /// PostfixOp'(opString, wsAfterOpParser, precedence, isAssociative, f),
 37     /// The state passed as an argument to the function is captured immediately before
 38     /// the operator string is parsed and contains the position of the operator.
 39     | PostfixOp' of string * Parser<unit,'u> * int * bool * (State<'u> -> 'a -> 'a)
 40     /// InfixOp'(opString, wsAfterOpParser, precedence, associativity, f),
 41     /// The state passed as an argument to the function is captured immediately before
 42     /// the operator string is parsed and contains the position of the operator.
 43     | InfixOp'   of string * Parser<unit,'u> * int * Assoc * (State<'u> -> 'a -> 'a -> 'a)
 44     /// TernaryOp'(op1String, wsAfterOp1Parser, op2String, wsAfterOp2Parser, precedence, associativity, f)
 45     /// The states passed as arguments to the function are captured immediately before
 46     /// the first and second operator strings are parsed and contain the positions of the operators.
 47     | TernaryOp' of string * Parser<unit,'u> *
 48                     string * Parser<unit,'u> * int * Assoc * (State<'u> -> State<'u> -> 'a -> 'a -> 'a -> 'a)
 49     with
 50         override ToString: unit -> string
 51
 52/// Represents a dynamically configurable parser for parsing expressions involving
 53/// prefix, postfix, infix and ternary operators of different precedence and associativity.
 54[<Sealed>]
 55type OperatorPrecedenceParser<'a,'u> =
 56    /// Constructs an OperatorPrecedenceParser instance and optionally adds the given operators.
 57    new: ?operators:seq<PrecedenceParserOp<'a,'u>> -> OperatorPrecedenceParser<'a,'u>
 58
 59    // Operators with higher precedence bind tighter.
 60
 61    // The middle expression in a ternary expression (e.g. expr2 in "expr1 ? expr2 : expr3")
 62    // is parsed as a "fresh" expression that is not influenced by the precedence of the
 63    // surrounding operators.
 64
 65    // Expressions involving operators with identical precedence are parsed as follows
 66    // (where  o1,   o2   are two infix operators,
 67    //         pre1, pre2 are two prefix operators,
 68    //         po1,  po2  are two postfix operators
 69    //  and all operators have identical precedence):
 70
 71    //  x o1 pre1 y ==> x o1 (pre1 y),
 72    //  x o1 y po1  ==> x o1 (y po1),
 73    //  x o1 y o2 z ==> (x o1 y) o2 z,  if o1   and o2   are left-associative
 74    //  x o1 y o2 z ==> x o1 (y o2 z),  if o1   and o2   are right-associative
 75    //  pre1 x po1  ==> (pre1 x) po1,   if pre1 or po1  is associative
 76    //  pre1 pre2 x ==> pre1 (pre2 x),  if pre1 or pre2 is associative
 77    //  x po1 po2   ==> (x po1) po2,    if po1  or po2  is associative
 78
 79    // In the following situations the OperatorConflictHandler will be called
 80    // and the expression will only be parsed as indicated if the handler returns
 81    // an empty error message. The default handler always generate an error.
 82
 83    //  x o1 y o2 z ==> (x o1 y) o2 z, if o1 and o2 have different associativity,
 84    //                                 or o1 and o2 are non-associative
 85    //  pre1 pre2 x ==> pre1 (pre2 y), if pre1 and pre2 are non-associative
 86    //  pre1 x po1  ==> (pre1 y) po1,  if pre1 and po1  are non-associative
 87    //  x po1 po2   ==> (y po1) po2,   if po1  and po2  are non-associative
 88
 89    /// The expression parser. This is a constant closure that forwards all work to an
 90    /// internal instance method, so that the expression parser always reflects the latest
 91    /// configuration of the `OperatorPrecedenceParser` instance.
 92    /// The parser can be safely called from different threads as long as the
 93    /// `OperatorPrecedenceParser` instance is not mutated at the same time.
 94    member ExpressionParser: Parser<'a,'u>
 95
 96    /// This parser is called to parse the terms in between the operators. There is no default,
 97    /// so you must set this parser before you can call the `ExpressionParser`.
 98    /// Note that the term parser is also expected to parse any whitespace after a term.
 99    member TermParser: Parser<'a, 'u> with get, set
100
101    /// This function is called when the precedence parser encounters two conflicting
102    /// operators in the parser input.
103    /// If the conflict handler returns `null` or an empty string, the operators are
104    /// parsed as if both were (left-)associative, otherwise a parser error with the
105    /// returned message is generated.
106    /// The default handler will always generate an error message.
107    member OperatorConflictHandler: (   State<'u> -> PrecedenceParserOp<'a,'u>
108                                     -> State<'u> -> PrecedenceParserOp<'a,'u>
109                                     -> string) with get, set
110
111    /// Adds an operator to the grammar.
112    /// Raises an `ArgumentException` if the operator definition conflicts with a
113    /// a previous definition or contains empty strings or a non-positive precedence.
114    member AddOperator: PrecedenceParserOp<'a,'u> -> unit
115
116    /// Calls `AddOperator` with each operator in the given sequence.
117    member AddOperators: seq<PrecedenceParserOp<'a,'u>> -> unit
118
119    /// Removes the given operator from the grammar.
120    /// Returns `false` if the operator was not previously registered, otherwise true.
121    member RemoveOperator: PrecedenceParserOp<'a,'u> -> bool
122
123    /// Removes the infix operator with the given string from the grammar.
124    /// Returns `false` if no infix operator with that string was previously registered, otherwise `true`.
125    member RemoveInfixOp: string -> bool
126
127    /// Removes the prefix operator with the given string from the grammar.
128    /// Returns `false` if no prefix operator with that string was previously registered, otherwise `true`.
129    member RemovePrefixOp: string -> bool
130
131    /// Removes the postfix operator with the given string from the grammar.
132    /// Returns `false` if no postfix operator with that string was previously registered, otherwise `true`.
133    member RemovePostfixOp: string -> bool
134
135    /// Removes the ternary operator with the given strings from the grammar.
136    /// Returns `false` if no ternary operator with these strings was previously registered, otherwise `true`.
137    member RemoveTernaryOp: string*string -> bool
138
139    /// Returns a sequence with a snapshot of the operators currently registered with the `OperatorPrecedenceParser`.
140    member Operators: seq<PrecedenceParserOp<'a,'u>>