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...

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
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 [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).

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 [T](p : => Parser[T])(name : String) : Parser[T]
def log [Q](p : => Q)(name : String)(implicit view$9 : (Q) => UnitParser) : UnitParser
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 [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 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 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 rep1sep [T, Q](p : => Parser[T], q : => Q)(implicit view$15 : (Q) => UnitParser) : Parser[List[T]]
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 : UnitParser
A unit-parser that always succeeds
def success [T](v : T) : Parser[T]
A 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.