scala.util.parsing.combinator
trait Parsers

[source: `scala/util/parsing/combinator/Parsers.scala`]

`` `trait` Parsers
  `extends` AnyRef

  `Parsers` is a component that provides generic parser combinators.

  It requires the type of the elements these parsers should parse (each parser is polymorphic in the type of result it produces).

  There are two aspects to the result of a parser: (1) success or failure, and (2) the result. A `Parser[T]` provides both kinds of information, but a `UnitParser` only signals success/failure. When composing a `UnitParser' with a normal `Parser`, the `UnitParser` only contributes to whether the combined parser is successful (i.e., its result is discarded).

  The term ``parser combinator'' refers to the fact that these parsers are constructed from primitive parsers and composition operators, such as sequencing, alternation, optionality, repetition, lifting, and so on.

  A ``primitive parser'' is a parser that accepts or rejects a single piece of input, based on a certain criterion, such as whether the input...

  - is equal to some given object,
  - satisfies a certain predicate,
  - is in the domain of a given partial function,....

  Even more primitive parsers always produce the same result, irrespective of the input.

  @requires Elem the type of elements the provided parsers consume (When consuming invidual characters, a parser is typically called a ``scanner'', which produces ``tokens'' that are consumed by what is normally called a ``parser''. Nonetheless, the same principles apply, regardless of the input type.)

  @provides Input = Reader[Elem] The type of input the parsers in this component expect.

  @provides Parser[+T] extends (Input => ParseResult[T]) Essentially, a `Parser[T]' is a function from `Input' to `ParseResult[T]'.

  @provides ParseResult[+T] is like an `Option[T]', in the sense that it is either `Success[T]', which consists of some result (:T) (and the rest of the input) or `Failure[T]', which provides an error message (and the rest of the input).

Author
  Martin Odersky, Iulian Dragos, Adriaan Moors

Direct Known Subclasses:
  Scanners, BindingParsers, TokenParsers

Type Summary
`abstract type` | Elem the type of input elements
`type` | Input The parser input is an abstract reader of input elements

Method Summary
`def` | accept [U](expected : String, f : PartialFunction[Elem, U]) : Parser[U] The parser that matches an element in the domain of the partial function `f' If `f' is defined on the first element in the input, `f' is applied to it to produce this parser's result. Example: The parser `accept("name", {case Identifier(n) => Name(n)})` accepts an `Identifier(n)` and returns a `Name(n)`.
`implicit def` | accept (e : Elem) : UnitParser A parser that matches only the given element `e' The method is implicit so that elements can automatically be lifted to their unit-parsers. For example, when parsing `Token's, Identifier("new") (which is a `Token') can be used directly, instead of first creating a `UnitParser' using accept(Identifier("new")).
`def` | accept [ES](es : ES)(`implicit` view$8 : (ES) => List[Elem]) : UnitParser A parser that matches only the given list of element `es' accept(es) succeeds if the input subsequently provides the elements in the list `es'.
`def` | chainl1 [T](p : => Parser[T], q : => Parser[(T, T) => T]) : Parser[T] A parser generator that, roughly, generalises the rep1sep generator so that `q', which parses the separator, produces a left-associative function that combines the elements it separates. From: J. Fokker. Functional parsers. In J. Jeuring and E. Meijer, editors, Advanced Functional Programming, volume 925 of Lecture Notes in Computer Science, pages 1--23. Springer, 1995.
`def` | chainl1 [T, U](first : => Parser[T], p : => Parser[U], q : => Parser[(T, U) => T]) : Parser[T] A parser generator that, roughly, generalises the rep1sep generator so that `q', which parses the separator, produces a left-associative function that combines the elements it separates.
`def` | chainr1 [T, U](p : Parser[T], q : Parser[(T, U) => U], combine : (T, U) => U, first : U) : Parser[U] A parser generator that generalises the rep1sep generator so that `q', which parses the separator, produces a right-associative function that combines the elements it separates. Additionally, The right-most (last) element and the left-most combinating function have to be supplied. rep1sep(p: Parser[T], q) corresponds to chainr1(p, q ^^ cons, cons, Nil) (where val cons = (x: T, y: List[T]) => x :: y)
`def` | commit [Q](p : => Q)(`implicit` view$6 : (Q) => UnitParser) : UnitParser Wrap a parser so that its failures become errors (the | combinator will give up as soon as it encounters an error, on failure it simply tries the next alternative)
`def` | commit [T](p : => Parser[T]) : Parser[T] Wrap a parser so that its failures become errors (the | combinator will give up as soon as it encounters an error, on failure it simply tries the next alternative)
`implicit def` | discard [T](p : => Parser[T]) : UnitParser A unit-parser that always succeeds, discarding `p's result
`def` | elem (e : Elem) : Parser[Elem] A parser that matches only the given element `e' elem(e) succeeds if the input starts with an element `e'
`def` | elem (kind : String, p : (Elem) => Boolean) : Parser[Elem] A parser matching input elements that satisfy a given predicate elem(kind, p) succeeds if the input starts with an element `e' for which p(e) is true.
`def` | fail (msg : String) : UnitParser A unit-parser that always fails
`def` | failure (msg : String) : Parser[Nothing] A parser that always fails
`def` | log [Q](p : => Q)(name : String)(`implicit` view$9 : (Q) => UnitParser) : UnitParser
`def` | log [T](p : => Parser[T])(name : String) : Parser[T]
`def` | not [Q](p : => Q)(`implicit` view$7 : (Q) => UnitParser) : UnitParser Wrap a parser so that its failures&errors become success and vice versa -- it never consumes any input
`def` | opt [T](p : => Parser[T]) : Parser[Option[T]] A parser generator for optional sub-phrases. opt(p) is a parser that returns `Some(x)' if `p' returns `x' and `None' if `p' fails
`def` | opt [Q](q : => Q)(`implicit` view$16 : (Q) => UnitParser) : Parser[Boolean] Turns a unit-parser into a boolean-parser that denotes whether the unit-parser succeeded.
`def` | positioned [Q](p : => Q)(`implicit` view$17 : (Q) => UnitParser) : Parser[Position] `positioned` decorates a unit-parser so that it returns the start position of the input it consumed.
`def` | positioned [T <: Positional](p : => Parser[T]) : Parser[T] `positioned' decorates a parser's result with the start position of the input it consumed.
`def` | rep [T](p : => Parser[T]) : Parser[List[T]] A parser generator for repetitions. rep(p) repeatedly uses `p' to parse the input until `p' fails (the result is a List of the consecutive results of `p')
`def` | rep [Q](p : => Q)(`implicit` view$10 : (Q) => UnitParser) : UnitParser A parser generator for repetitions. rep(p) repeatedly uses `p' to parse the input until `p' fails
`def` | rep1 [Q](p : => Q)(`implicit` view$12 : (Q) => UnitParser) : UnitParser A parser generator for non-empty repetitions. rep1(p) repeatedly uses `p' to parse the input until `p' fails -- `p' must succeed at least once
`def` | rep1 [T](first : => Parser[T], p : => Parser[T]) : Parser[List[T]] A parser generator for non-empty repetitions. rep1(f, p) first uses `f' (which must succeed) and then repeatedly uses `p' to parse the input until `p' fails (the result is a `List' of the consecutive results of `f' and `p')
`def` | rep1 [T](p : => Parser[T]) : Parser[List[T]] A parser generator for non-empty repetitions. rep1(p) repeatedly uses `p' to parse the input until `p' fails -- `p' must succeed at least once (the result is a `List' of the consecutive results of `p')
`def` | rep1sep [T, Q](p : => Parser[T], q : => Q)(`implicit` view$15 : (Q) => UnitParser) : Parser[List[T]]
`def` | rep1sep [T, Q](first : => Parser[T], p : => Parser[T], q : => Q)(`implicit` view$14 : (Q) => UnitParser) : Parser[List[T]] A parser generator for non-empty repetitions. rep1sep(first, p, q) starts by using `first', followed by repeatedly uses of `p' interleaved with `q' to parse the input, until `p' fails. `first' must succeed (the result is a `List' of the consecutive results of `first' and `p')
`def` | repN [Q](n : Int, p : => Q)(`implicit` view$13 : (Q) => UnitParser) : UnitParser A parser generator for a specified number of repetitions. repN(n, p) uses `p' exactly `n' time to parse the input
`def` | repN [T](n : Int, p : => Parser[T]) : Parser[List[T]] A parser generator for a specified number of repetitions. repN(n, p) uses `p' exactly `n' time to parse the input (the result is a `List' of the `n' consecutive results of `p')
`def` | repsep [T, Q](p : => Parser[T], q : => Q)(`implicit` view$11 : (Q) => UnitParser) : Parser[List[T]] A parser generator for interleaved repetitions. repsep(p, q) repeatedly uses `p' interleaved with `q' to parse the input, until `p' fails. (The result is a `List' of the results of `p'.) Example: `repsep(term, ",")` parses a comma-separated list of term's, yielding a list of these terms
`def` | success [T](v : T) : Parser[T] A parser that always succeeds
`def` | success : UnitParser A unit-parser that always succeeds

Methods inherited from AnyRef
getClass, hashCode, equals, clone, toString, notify, notifyAll, wait, wait, wait, finalize, ==, !=, eq, ne, synchronized

Methods inherited from Any
==, !=, isInstanceOf, asInstanceOf

Class Summary
`case class` | Error (`val override` msg : String, `val override` next : Reader)`extends` NoSuccess `with` Product The fatal failure case of ParseResult: contains an error-message and the remaining input. No back-tracking is done when a parser returns an `Error'
`case class` | Failure (`val override` msg : String, `val override` next : Reader)`extends` NoSuccess `with` Product The failure case of ParseResult: contains an error-message and the remaining input. Parsing will back-track when a failure occurs.
`sealed abstract class` | NoSuccess (`val` msg : String, `val override` next : Reader)`extends` ParseResult[Nothing] A common super-class for unsuccessful parse results
`trait` | OnceParser [+T]`extends` Parser[T] A parser whose ~ combinator disallows back-tracking.
`sealed abstract class` | ParseResult [+T]`extends` AnyRef A base class for parser results. A result is either successful or not (failure may be fatal, i.e., an Error, or not, i.e., a Failure) On success, provides a result of type `T`.
`abstract class` | Parser [+T]`extends` (Reader) => ParseResult[T] The root class of parsers. Parsers are functions from the Input type to ParseResult
`case class` | Success [+T](`val` result : T, `val override` next : Reader)`extends` ParseResult[T]`with` Product The success case of ParseResult: contains the result and the remaining input.
`trait` | UnitOnceParser `extends` UnitParser A parser whose ~ combinator disallows back-tracking.
`abstract class` | UnitParser `extends` (Reader) => ParseResult[Unit] The root class of special parsers returning the trivial result `Unit` These compose differently from normal parsers in that the `Unit` result in a sequential or function composition is dropped.

Type Details

`abstract` `type` Elem

  the type of input elements

`` `type` Input

  The parser input is an abstract reader of input elements

Method Details

`` `def` commit[T](p : => Parser[T]) : Parser[T]

  Wrap a parser so that its failures become errors (the | combinator will give up as soon as it encounters an error, on failure it simply tries the next alternative)

`` `def` commit[Q](p : => Q)(`implicit` view$6 : (Q) => UnitParser) : UnitParser

  Wrap a parser so that its failures become errors (the | combinator will give up as soon as it encounters an error, on failure it simply tries the next alternative)

`` `def` not[Q](p : => Q)(`implicit` view$7 : (Q) => UnitParser) : UnitParser

  Wrap a parser so that its failures&errors become success and vice versa -- it never consumes any input

`` `def` elem(kind : String, p : (Elem) => Boolean) : Parser[Elem]

  A parser matching input elements that satisfy a given predicate

  elem(kind, p) succeeds if the input starts with an element `e' for which p(e) is true.

Parameters
  `kind -` The element kind, used for error messages
  `p -` A predicate that determines which elements match.
Returns

`` `def` elem(e : Elem) : Parser[Elem]

  A parser that matches only the given element `e'

  elem(e) succeeds if the input starts with an element `e'

Parameters
  `e -` the `Elem' that must be the next piece of input for the returned parser to succeed
Returns
  a `Parser' that succeeds if `e' is the next available input (and returns it).

`implicit` `def` accept(e : Elem) : UnitParser

  A parser that matches only the given element `e'

  The method is implicit so that elements can automatically be lifted to their unit-parsers. For example, when parsing `Token's, Identifier("new") (which is a `Token') can be used directly, instead of first creating a `UnitParser' using accept(Identifier("new")).

Parameters
  `e -` the `Elem' that must be the next piece of input for the returned parser to succeed
Returns
  a `UnitParser' that succeeds if `e' is the next available input.

`` `def` accept[ES](es : ES)(`implicit` view$8 : (ES) => List[Elem]) : UnitParser

  A parser that matches only the given list of element `es'

  accept(es) succeeds if the input subsequently provides the elements in the list `es'.

Parameters
  `es -` the list of expected elements
Returns
  a UnitParser that recognizes a specified list of elements

`` `def` accept[U](expected : String, f : PartialFunction[Elem, U]) : Parser[U]

  The parser that matches an element in the domain of the partial function `f'

  If `f' is defined on the first element in the input, `f' is applied to it to produce this parser's result.

  Example: The parser `accept("name", {case Identifier(n) => Name(n)})` accepts an `Identifier(n)` and returns a `Name(n)`.

Parameters
  `expected -` a description of the kind of element this parser expects (for error messages)
  `f -` a partial function that determines when this parser is successful and what its output is
Returns
  A parser that succeeds if `f' is applicable to the first element of the input, applying `f' to it to produce the result.

`` `def` failure(msg : String) : Parser[Nothing]

  A parser that always fails

Parameters
  `msg -` The error message describing the failure.
Returns
  A parser that always fails with the specified error message.

`` `def` fail(msg : String) : UnitParser

  A unit-parser that always fails

Parameters
  `msg -` The error message describing the failure.
Returns
  A parser that always fails with the specified error message.

`` `def` success[T](v : T) : Parser[T]

  A parser that always succeeds

Parameters
  `v -` The result for the parser
Returns
  A parser that always succeeds, with the given result `v'

`` `def` success : UnitParser

  A unit-parser that always succeeds

`implicit` `def` discard[T](p : => Parser[T]) : UnitParser

  A unit-parser that always succeeds, discarding `p's result

Parameters
  `p -` The parser whose result is to be discarded
Returns
  A parser that always succeeds, with the empty result

`` `def` log[T](p : => Parser[T])(name : String) : Parser[T]

`` `def` log[Q](p : => Q)(name : String)(`implicit` view$9 : (Q) => UnitParser) : UnitParser

`` `def` rep[T](p : => Parser[T]) : Parser[List[T]]

  A parser generator for repetitions.

  rep(p) repeatedly uses `p' to parse the input until `p' fails (the result is a List of the consecutive results of `p')

Parameters
  `p -` a `Parser' that is to be applied successively to the input
Returns
  A parser that returns a list of results produced by repeatedly applying `p' to the input.

`` `def` rep[Q](p : => Q)(`implicit` view$10 : (Q) => UnitParser) : UnitParser

  A parser generator for repetitions.

  rep(p) repeatedly uses `p' to parse the input until `p' fails

Parameters
  `p -` a `Parser' that is to be applied successively to the input
Returns
  A parser that repeatedly applies `p' to the input.

`` `def` repsep[T, Q](p : => Parser[T], q : => Q)(`implicit` view$11 : (Q) => UnitParser) : Parser[List[T]]

  A parser generator for interleaved repetitions.

  repsep(p, q) repeatedly uses `p' interleaved with `q' to parse the input, until `p' fails. (The result is a `List' of the results of `p'.)

  Example: `repsep(term, ",")` parses a comma-separated list of term's, yielding a list of these terms

Parameters
  `p -` a `Parser' that is to be applied successively to the input
  `q -` a `UnitParser' that parses the elements that separate the elements parsed by `p'
Returns
  A parser that returns a list of results produced by repeatedly applying `p' (interleaved with `q') to the input.

`` `def` rep1[T](p : => Parser[T]) : Parser[List[T]]

  A parser generator for non-empty repetitions.

  rep1(p) repeatedly uses `p' to parse the input until `p' fails -- `p' must succeed at least once (the result is a `List' of the consecutive results of `p')

Parameters
  `p -` a `Parser' that is to be applied successively to the input
Returns
  A parser that returns a list of results produced by repeatedly applying `p' to the input (and that only succeeds if `p' matches at least once).

`` `def` rep1[T](first : => Parser[T], p : => Parser[T]) : Parser[List[T]]

  A parser generator for non-empty repetitions.

  rep1(f, p) first uses `f' (which must succeed) and then repeatedly uses `p' to parse the input until `p' fails (the result is a `List' of the consecutive results of `f' and `p')

Parameters
  `first -` a `Parser' that parses the first piece of input
  `p -` a `Parser' that is to be applied successively to the rest of the input (if any)
Returns
  A parser that returns a list of results produced by first applying `f' and then repeatedly `p' to the input (it only succeeds if `f' matches).

`` `def` repN[T](n : Int, p : => Parser[T]) : Parser[List[T]]

  A parser generator for a specified number of repetitions.

  repN(n, p) uses `p' exactly `n' time to parse the input (the result is a `List' of the `n' consecutive results of `p')

Parameters
  `p -` a `Parser' that is to be applied successively to the input
  `n -` the exact number of times `p' must succeed
Returns
  A parser that returns a list of results produced by repeatedly applying `p' to the input (and that only succeeds if `p' matches exactly `n' times).

`` `def` rep1[Q](p : => Q)(`implicit` view$12 : (Q) => UnitParser) : UnitParser

  A parser generator for non-empty repetitions.

  rep1(p) repeatedly uses `p' to parse the input until `p' fails -- `p' must succeed at least once

Parameters
  `p -` a `Parser' that is to be applied successively to the input
Returns
  A unitparser that repeatedly applies `p' to the input (and that only succeeds if `p' matches at least once).

`` `def` repN[Q](n : Int, p : => Q)(`implicit` view$13 : (Q) => UnitParser) : UnitParser

  A parser generator for a specified number of repetitions.

  repN(n, p) uses `p' exactly `n' time to parse the input

Parameters
  `p -` a `Parser' that is to be applied successively to the input
  `n -` the exact number of times `p' must succeed
Returns
  A unitparser that repeatedly applies `p' to the input (and that only succeeds if `p' matches at exactly `n' times).

`` `def` rep1sep[T, Q](first : => Parser[T], p : => Parser[T], q : => Q)(`implicit` view$14 : (Q) => UnitParser) : Parser[List[T]]

  A parser generator for non-empty repetitions.

  rep1sep(first, p, q) starts by using `first', followed by repeatedly uses of `p' interleaved with `q' to parse the input, until `p' fails. `first' must succeed (the result is a `List' of the consecutive results of `first' and `p')

Parameters
  `first -` a `Parser' that is to be applied to the first element of input
  `p -` a `Parser' that is to be applied successively to the input
  `q -` a `UnitParser' that parses the elements that separate the elements parsed by `p' (interleaved with `q')
Returns
  A parser that returns a list of results produced by repeatedly applying `p' to the input (and that only succeeds if `p' matches at least once).

`` `def` rep1sep[T, Q](p : => Parser[T], q : => Q)(`implicit` view$15 : (Q) => UnitParser) : Parser[List[T]]

`` `def` chainl1[T](p : => Parser[T], q : => Parser[(T, T) => T]) : Parser[T]

  A parser generator that, roughly, generalises the rep1sep generator so that `q', which parses the separator, produces a left-associative function that combines the elements it separates.

  From: J. Fokker. Functional parsers. In J. Jeuring and E. Meijer, editors, Advanced Functional Programming, volume 925 of Lecture Notes in Computer Science, pages 1--23. Springer, 1995.

Parameters
  `p -` a parser that parses the elements
  `q -` a parser that parses the token(s) separating the elements, yielding a left-associative function that combines two elements into one

`` `def` chainl1[T, U](first : => Parser[T], p : => Parser[U], q : => Parser[(T, U) => T]) : Parser[T]

  A parser generator that, roughly, generalises the rep1sep generator so that `q', which parses the separator, produces a left-associative function that combines the elements it separates.

Parameters
  `first -` a parser that parses the first element
  `p -` a parser that parses the subsequent elements
  `q -` a parser that parses the token(s) separating the elements, yielding a left-associative function that combines two elements into one

`` `def` chainr1[T, U](p : Parser[T], q : Parser[(T, U) => U], combine : (T, U) => U, first : U) : Parser[U]

  A parser generator that generalises the rep1sep generator so that `q', which parses the separator, produces a right-associative function that combines the elements it separates. Additionally, The right-most (last) element and the left-most combinating function have to be supplied. rep1sep(p: Parser[T], q) corresponds to chainr1(p, q ^^ cons, cons, Nil) (where val cons = (x: T, y: List[T]) => x :: y)

Parameters
  `p -` a parser that parses the elements
  `q -` a parser that parses the token(s) separating the elements, yielding a right-associative function that combines two elements into one
  `combine -` the "last" (left-most) combination function to be applied
  `first -` the "first" (right-most) element to be combined

`` `def` opt[T](p : => Parser[T]) : Parser[Option[T]]

  A parser generator for optional sub-phrases.

  opt(p) is a parser that returns `Some(x)' if `p' returns `x' and `None' if `p' fails

Parameters
  `p -` A `Parser' that is tried on the input
Returns
  a `Parser' that always succeeds: either with the result provided by `p' or with the empty result

`` `def` opt[Q](q : => Q)(`implicit` view$16 : (Q) => UnitParser) : Parser[Boolean]

  Turns a unit-parser into a boolean-parser that denotes whether the unit-parser succeeded.

`` `def` positioned[T <: Positional](p : => Parser[T]) : Parser[T]

  `positioned' decorates a parser's result with the start position of the input it consumed.

Parameters
  `p -` a `Parser' whose result conforms to `Positional'.
Returns
  A parser that has the same behaviour as `p', but which marks its result with the start position of the input it consumed, if it didn't already have a position.

`` `def` positioned[Q](p : => Q)(`implicit` view$17 : (Q) => UnitParser) : Parser[Position]

  `positioned` decorates a unit-parser so that it returns the start position of the input it consumed.

Parameters
  `p -` a `UnitParser'.
Returns
  A parser that has the same behaviour as `p', but which returns the start position of the input it consumed.