diff options
Diffstat (limited to 'src/library/scala/util/parsing/combinator/Parsers.scala')
| -rw-r--r-- | src/library/scala/util/parsing/combinator/Parsers.scala | 332 |
1 files changed, 160 insertions, 172 deletions
diff --git a/src/library/scala/util/parsing/combinator/Parsers.scala b/src/library/scala/util/parsing/combinator/Parsers.scala index a02f33ef36..b0760f42ae 100644 --- a/src/library/scala/util/parsing/combinator/Parsers.scala +++ b/src/library/scala/util/parsing/combinator/Parsers.scala @@ -66,19 +66,19 @@ trait Parsers { sealed abstract class ParseResult[+T] { /** Functional composition of ParseResults * - * @param `f' the function to be lifted over this result - * @return `f' applied to the result of this `ParseResult', packaged up as a new `ParseResult' + * @param `f` the function to be lifted over this result + * @return `f` applied to the result of this `ParseResult`, packaged up as a new `ParseResult` */ def map[U](f: T => U): ParseResult[U] /** Partial functional composition of ParseResults * - * @param `f' the partial function to be lifted over this result - * @param error a function that takes the same argument as `f' and produces an error message - * to explain why `f' wasn't applicable (it is called when this is the case) - * @return <i>if `f' f is defined at the result in this `ParseResult',</i> - * `f' applied to the result of this `ParseResult', packaged up as a new `ParseResult'. - * If `f' is not defined, `Failure'. + * @param `f` the partial function to be lifted over this result + * @param error a function that takes the same argument as `f` and produces an error message + * to explain why `f` wasn't applicable (it is called when this is the case) + * @return <i>if `f` f is defined at the result in this `ParseResult`,</i> + * `f` applied to the result of this `ParseResult`, packaged up as a new `ParseResult`. + * If `f` is not defined, `Failure`. */ def mapPartial[U](f: PartialFunction[T, U], error: T => String): ParseResult[U] @@ -167,7 +167,7 @@ trait Parsers { } /** 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' + * No back-tracking is done when a parser returns an `Error` * * @param msg An error message string describing the error. * @param next The parser's unconsumed input at the point where the error occurred. @@ -215,43 +215,41 @@ trait Parsers { // it's short, light (looks like whitespace), has few overloaded meaning (thanks to the recent change from ~ to unary_~) // and we love it! (or do we like `,` better?) - /** A parser combinator for sequential composition + /** A parser combinator for sequential composition. * - * <p> `p ~ q' succeeds if `p' succeeds and `q' succeeds on the input - * left over by `p'.</p> + * `p ~ q` succeeds if `p` succeeds and `q` succeeds on the input left over by `p`. * - * @param q a parser that will be executed after `p' (this parser) succeeds -- evaluated at most once, and only when necessary - * @return a `Parser' that -- on success -- returns a `~' (like a Pair, but easier to pattern match on) - * that contains the result of `p' and that of `q'. - * The resulting parser fails if either `p' or `q' fails. + * @param q a parser that will be executed after `p` (this parser) succeeds -- evaluated at most once, and only when necessary + * @return a `Parser` that -- on success -- returns a `~` (like a Pair, but easier to pattern match on) + * that contains the result of `p` and that of `q`. + * The resulting parser fails if either `p` or `q` fails. */ @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.") def ~ [U](q: => Parser[U]): Parser[~[T, U]] = { lazy val p = q // lazy argument (for(a <- this; b <- p) yield new ~(a,b)).named("~") } - /** A parser combinator for sequential composition which keeps only the right result + /** A parser combinator for sequential composition which keeps only the right result. * - * <p> `p ~> q' succeeds if `p' succeeds and `q' succeeds on the input - * left over by `p'.</p> + * `p ~> q` succeeds if `p` succeeds and `q` succeeds on the input left over by `p`. * - * @param q a parser that will be executed after `p' (this parser) succeeds -- evaluated at most once, and only when necessary - * @return a `Parser' that -- on success -- returns the result of `q'. + * @param q a parser that will be executed after `p` (this parser) succeeds -- evaluated at most once, and only when necessary + * @return a `Parser` that -- on success -- returns the result of `q`. */ @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.") def ~> [U](q: => Parser[U]): Parser[U] = { lazy val p = q // lazy argument (for(a <- this; b <- p) yield b).named("~>") } - /** A parser combinator for sequential composition which keeps only the left result + /** A parser combinator for sequential composition which keeps only the left result. * - * <p> `p <~ q' succeeds if `p' succeeds and `q' succeeds on the input - * left over by `p'.</p> + * <p> `p <~ q` succeeds if `p` succeeds and `q` succeeds on the input + * left over by `p`.</p> * - * <b>Note:</b> <~ has lower operator precedence than ~ or ~>. + * '''Note:''' <~ has lower operator precedence than ~ or ~>. * - * @param q a parser that will be executed after `p' (this parser) succeeds -- evaluated at most once, and only when necessary - * @return a `Parser' that -- on success -- returns the result of `p'. + * @param q a parser that will be executed after `p` (this parser) succeeds -- evaluated at most once, and only when necessary + * @return a `Parser` that -- on success -- returns the result of `p`. */ @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.") def <~ [U](q: => Parser[U]): Parser[T] = { lazy val p = q // lazy argument @@ -263,43 +261,40 @@ trait Parsers { def apply(in: Input) = seq(Parser.this, q)((x, y) => combine(x,y))(in) } */ - /** A parser combinator for non-back-tracking sequential composition + /** A parser combinator for non-back-tracking sequential composition. * - *<p>`p ~! q' succeeds if `p' succeeds and `q' succeeds on the input - * left over by `p'. In case of failure, no back-tracking is performed - * (in an earlier parser produced by the | combinator).</p> + * `p ~! q` succeeds if `p` succeeds and `q` succeeds on the input left over by `p`. + * In case of failure, no back-tracking is performed (in an earlier parser produced by the `|` combinator). * - * @param q a parser that will be executed after `p' (this parser) succeeds - * @return a `Parser' that -- on success -- returns a `~' (like a Pair, but easier to pattern match on) - * that contains the result of `p' and that of `q'. - * The resulting parser fails if either `p' or `q' fails, this failure is fatal. + * @param q a parser that will be executed after `p` (this parser) succeeds + * @return a `Parser` that -- on success -- returns a `~` (like a Pair, but easier to pattern match on) + * that contains the result of `p` and that of `q`. + * The resulting parser fails if either `p` or `q` fails, this failure is fatal. */ def ~! [U](p: => Parser[U]): Parser[~[T, U]] = OnceParser{ (for(a <- this; b <- commit(p)) yield new ~(a,b)).named("~!") } - /** A parser combinator for alternative composition + /** A parser combinator for alternative composition. * - *<p>`p | q' succeeds if `p' succeeds or `q' succeeds - * Note that `q' is only tried if `p's failure is non-fatal (i.e., back-tracking is - * allowed).</p> + * `p | q` succeeds if `p` succeeds or `q` succeeds. + * Note that `q` is only tried if `p`s failure is non-fatal (i.e., back-tracking is allowed). * - * @param q a parser that will be executed if `p' (this parser) fails (and allows back-tracking) - * @return a `Parser' that returns the result of the first parser to succeed (out of `p' and `q') + * @param q a parser that will be executed if `p` (this parser) fails (and allows back-tracking) + * @return a `Parser` that returns the result of the first parser to succeed (out of `p` and `q`) * The resulting parser succeeds if (and only if) <ul> - * <li> `p' succeeds, <i>or</i> </li> - * <li> if `p' fails allowing back-tracking and `q' succeeds. </li> </ul> + * <li> `p` succeeds, <i>or</i> </li> + * <li> if `p` fails allowing back-tracking and `q` succeeds. </li> </ul> */ def | [U >: T](q: => Parser[U]): Parser[U] = append(q).named("|") // TODO - /** A parser combinator for alternative with longest match composition + /** A parser combinator for alternative with longest match composition. * - *<p>`p ||| q' succeeds if `p' succeeds or `q' succeeds - * If `p' and `q' both succeed, the parser that consumed the most - * characters accepts.</p> + * `p ||| q` succeeds if `p` succeeds or `q` succeeds. + * If `p` and `q` both succeed, the parser that consumed the most characters accepts. * * @param q0 a parser that accepts if p consumes less characters. -- evaluated at most once, and only when necessary - * @return a `Parser' that returns the result of the parser consuming the most characters (out of `p' and `q'). + * @return a `Parser` that returns the result of the parser consuming the most characters (out of `p` and `q`). */ @migration(2, 9, "As of 2.9, the call-by-name argument is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.") def ||| [U >: T](q0: => Parser[U]): Parser[U] = new Parser[U] { @@ -319,20 +314,21 @@ trait Parsers { override def toString = "|||" } - /** A parser combinator for function application + /** A parser combinator for function application. * - *<p>`p ^^ f' succeeds if `p' succeeds; it returns `f' applied to the result of `p'.</p> + * `p ^^ f` succeeds if `p` succeeds; it returns `f` applied to the result of `p`. * - * @param f a function that will be applied to this parser's result (see `map' in `ParseResult'). + * @param f a function that will be applied to this parser's result (see `map` in `ParseResult`). * @return a parser that has the same behaviour as the current parser, but whose result is - * transformed by `f'. + * transformed by `f`. */ def ^^ [U](f: T => U): Parser[U] = map(f).named(toString+"^^") /** A parser combinator that changes a successful result into the specified value. * - * <p>`p ^^^ v' succeeds if `p' succeeds; discards its result, and returns `v` instead.</p> + * `p ^^^ v` succeeds if `p` succeeds; discards its result, and returns `v` instead. + * * @param v The new result for the parser, evaluated at most once (if `p` succeeds), not evaluated at all if `p` fails. * @return a parser that has the same behaviour as the current parser, but whose successful result is `v` */ @@ -342,48 +338,47 @@ trait Parsers { def apply(in: Input) = Parser.this(in) map (x => v0) }.named(toString+"^^^") - /** A parser combinator for partial function application + /** A parser combinator for partial function application. * - *<p>`p ^? (f, error)' succeeds if `p' succeeds AND `f' is defined at the result of `p'; - * in that case, it returns `f' applied to the result of `p'. If `f' is not applicable, - * error(the result of `p') should explain why.</p> + * `p ^? (f, error)` succeeds if `p` succeeds AND `f` is defined at the result of `p`; + * in that case, it returns `f` applied to the result of `p`. If `f` is not applicable, + * error(the result of `p`) should explain why. * * @param f a partial function that will be applied to this parser's result - * (see `mapPartial' in `ParseResult'). - * @param error a function that takes the same argument as `f' and produces an error message - * to explain why `f' wasn't applicable - * @return a parser that succeeds if the current parser succeeds <i>and</i> `f' is applicable - * to the result. If so, the result will be transformed by `f'. + * (see `mapPartial` in `ParseResult`). + * @param error a function that takes the same argument as `f` and produces an error message + * to explain why `f` wasn't applicable + * @return a parser that succeeds if the current parser succeeds <i>and</i> `f` is applicable + * to the result. If so, the result will be transformed by `f`. */ def ^? [U](f: PartialFunction[T, U], error: T => String): Parser[U] = Parser{ in => this(in).mapPartial(f, error)}.named(toString+"^?") - /** A parser combinator for partial function application + /** A parser combinator for partial function application. * - *<p>`p ^? f' succeeds if `p' succeeds AND `f' is defined at the result of `p'; - * in that case, it returns `f' applied to the result of `p'.</p> + * `p ^? f` succeeds if `p` succeeds AND `f` is defined at the result of `p`; + * in that case, it returns `f` applied to the result of `p`. * * @param f a partial function that will be applied to this parser's result - * (see `mapPartial' in `ParseResult'). - * @return a parser that succeeds if the current parser succeeds <i>and</i> `f' is applicable - * to the result. If so, the result will be transformed by `f'. + * (see `mapPartial` in `ParseResult`). + * @return a parser that succeeds if the current parser succeeds <i>and</i> `f` is applicable + * to the result. If so, the result will be transformed by `f`. */ def ^? [U](f: PartialFunction[T, U]): Parser[U] = ^?(f, r => "Constructor function not defined at "+r) - /** A parser combinator that parameterizes a subsequent parser with the result of this one + /** A parser combinator that parameterizes a subsequent parser with the result of this one. * - *<p> - * Use this combinator when a parser depends on the result of a previous parser. `p' should be - * a function that takes the result from the first parser and returns the second parser.</p> + * Use this combinator when a parser depends on the result of a previous parser. `p` should be + * a function that takes the result from the first parser and returns the second parser. * - *<p> `p into fq' (with `fq' typically `{x => q}') first applies `p', and then, if `p' successfully - * returned result `r', applies `fq(r)' to the rest of the input. </p> + * `p into fq` (with `fq` typically `{x => q}') first applies `p`, and then, if `p` successfully + * returned result `r`, applies `fq(r)` to the rest of the input. * - *<p> From: G. Hutton. Higher-order functions for parsing. J. Funct. Program., 2(3):323--343, 1992. </p> + * ''From: G. Hutton. Higher-order functions for parsing. J. Funct. Program., 2(3):323--343, 1992.'' * * @param fq a function that, given the result from this parser, returns the second parser to be applied - * @return a parser that succeeds if this parser succeeds (with result `x') and if then `fq(x)' succeeds + * @return a parser that succeeds if this parser succeeds (with result `x`) and if then `fq(x)` succeeds */ def into[U](fq: T => Parser[U]): Parser[U] = flatMap(fq) @@ -399,8 +394,8 @@ trait Parsers { */ def * = rep(this) - /** Returns a parser that repeatedly parses what this parser parses, interleaved with the `sep' parser. - * The `sep' parser specifies how the results parsed by this parser should be combined. + /** Returns a parser that repeatedly parses what this parser parses, interleaved with the `sep` parser. + * The `sep` parser specifies how the results parsed by this parser should be combined. * * @return chainl1(this, sep) */ @@ -421,8 +416,8 @@ trait Parsers { def ? = opt(this) } - /** 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) + /** 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{ in => p(in) match{ @@ -437,9 +432,9 @@ trait Parsers { case class EFNil(res: Boolean) extends ElemFun*/ - /** A parser matching input elements that satisfy a given predicate + /** A parser matching input elements that satisfy a given predicate. * - * <p>elem(kind, p) succeeds if the input starts with an element `e' for which p(e) is true.</p> + * `elem(kind, p)` succeeds if the input starts with an element `e` for which p(e) is true. * * @param kind The element kind, used for error messages * @param p A predicate that determines which elements match. @@ -447,49 +442,48 @@ trait Parsers { */ def elem(kind: String, p: Elem => Boolean) = acceptIf(p)(inEl => kind+" expected") - /** A parser that matches only the given element `e' + /** A parser that matches only the given element `e`. * - * <p>elem(e) succeeds if the input starts with an element `e'</p> + * `elem(e)` succeeds if the input starts with an element `e`. * - * @param e the `Elem' that must be the next piece of input for the returned parser to succeed - * @return a `Parser' that succeeds if `e' is the next available input (and returns it). + * @param e the `Elem` that must be the next piece of input for the returned parser to succeed + * @return a `Parser` that succeeds if `e` is the next available input (and returns it). */ def elem(e: Elem): Parser[Elem] = accept(e) - - /** A parser that matches only the given element `e' - *<p> + /** A parser that matches only the given element `e`. + * * The method is implicit so that elements can automatically be lifted to their parsers. - * For example, when parsing `Token's, Identifier("new") (which is a `Token') can be used directly, - * instead of first creating a `Parser' using accept(Identifier("new")).</p> + * For example, when parsing `Token`s, `Identifier("new")` (which is a `Token`) can be used directly, + * instead of first creating a `Parser` using `accept(Identifier("new"))`. * - * @param e the `Elem' that must be the next piece of input for the returned parser to succeed - * @return a `tParser' that succeeds if `e' is the next available input. + * @param e the `Elem` that must be the next piece of input for the returned parser to succeed + * @return a `tParser` that succeeds if `e` is the next available input. */ implicit def accept(e: Elem): Parser[Elem] = acceptIf(_ == e)("`"+e+"' expected but " + _ + " found") - /** A parser that matches only the given list of element `es' + /** A parser that matches only the given list of element `es`. * - * <p>accept(es) succeeds if the input subsequently provides the elements in the list `es'.</p> + * `accept(es)` succeeds if the input subsequently provides the elements in the list `es`. * * @param es the list of expected elements * @return a Parser that recognizes a specified list of elements */ def accept[ES <% List[Elem]](es: ES): Parser[List[Elem]] = acceptSeq(es) - /** The parser that matches an element in the domain of the partial function `f' - *<p> - * If `f' is defined on the first element in the input, `f' is applied to it to produce - * this parser's result.</p> - *<p> - * Example: The parser <code>accept("name", {case Identifier(n) => Name(n)})</code> - * accepts an <code>Identifier(n)</code> and returns a <code>Name(n)</code>.</p> + /** 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)` * * @param expected a description of the kind of element this parser expects (for error messages) * @param f a partial function that determines when this parser is successful and what its output is - * @return A parser that succeeds if `f' is applicable to the first element of the input, - * applying `f' to it to produce the result. + * @return A parser that succeeds if `f` is applicable to the first element of the input, + * applying `f` to it to produce the result. */ def accept[U](expected: String, f: PartialFunction[Elem, U]): Parser[U] = acceptMatch(expected, f) @@ -506,14 +500,14 @@ trait Parsers { def acceptSeq[ES <% Iterable[Elem]](es: ES): Parser[List[Elem]] = es.foldRight[Parser[List[Elem]]](success(Nil)){(x, pxs) => accept(x) ~ pxs ^^ mkList} - /** A parser that always fails + /** A parser that always fails. * * @param msg The error message describing the failure. * @return A parser that always fails with the specified error message. */ def failure(msg: String) = Parser{ in => Failure(msg, in) } - /** A parser that results in an error + /** A parser that results in an error. * * @param msg The error message describing the failure. * @return A parser that always fails with the specified error message. @@ -521,10 +515,10 @@ trait Parsers { def err(msg: String) = Parser{ in => Error(msg, in) } - /** A parser that always succeeds + /** A parser that always succeeds. * * @param v The result for the parser - * @return A parser that always succeeds, with the given result `v' + * @return A parser that always succeeds, with the given result `v` */ def success[T](v: T) = Parser{ in => Success(v, in) } @@ -537,52 +531,50 @@ trait Parsers { /** A parser generator for repetitions. * - * <p> rep(p) repeatedly uses `p' to parse the input until `p' fails (the result is a List - * of the consecutive results of `p') </p> + * `rep(p)` repeatedly uses `p` to parse the input until `p` fails (the result is a List + * of the consecutive results of `p`). * - * @param p a `Parser' that is to be applied successively to the input - * @return A parser that returns a list of results produced by repeatedly applying `p' to the input. + * @param p a `Parser` that is to be applied successively to the input + * @return A parser that returns a list of results produced by repeatedly applying `p` to the input. */ def rep[T](p: => Parser[T]): Parser[List[T]] = rep1(p) | success(List()) /** A parser generator for interleaved repetitions. * - * <p> 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'.) </p> + * `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`.) * - * <p>Example: <code>repsep(term, ",")</code> parses a comma-separated list of term's, - * yielding a list of these terms</p> + * Example: `repsep(term, ",")` parses a comma-separated list of term's, yielding a list of these terms. * - * @param p a `Parser' that is to be applied successively to the input - * @param q a `Parser' that parses the elements that separate the elements parsed by `p' - * @return A parser that returns a list of results produced by repeatedly applying `p' (interleaved - * with `q') to the input. - * The results of `p' are collected in a list. The results of `q' are discarded. + * @param p a `Parser` that is to be applied successively to the input + * @param q a `Parser` that parses the elements that separate the elements parsed by `p` + * @return A parser that returns a list of results produced by repeatedly applying `p` (interleaved with `q`) to the input. + * The results of `p` are collected in a list. The results of `q` are discarded. */ def repsep[T](p: => Parser[T], q: => Parser[Any]): Parser[List[T]] = rep1sep(p, q) | success(List()) /** A parser generator for non-empty repetitions. * - * <p> 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')</p> + * <p> 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`)</p> * - * @param p a `Parser' that is to be applied successively to the input - * @return 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). + * @param p a `Parser` that is to be applied successively to the input + * @return 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](p: => Parser[T]): Parser[List[T]] = rep1(p, p) /** A parser generator for non-empty repetitions. * - * <p> 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')</p> + * <p> 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`)</p> * - * @param first a `Parser' that parses the first piece of input - * @param p0 a `Parser' that is to be applied successively to the rest of the input (if any) -- evaluated at most once, and only when necessary - * @return 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). + * @param first a `Parser` that parses the first piece of input + * @param p0 a `Parser` that is to be applied successively to the rest of the input (if any) -- evaluated at most once, and only when necessary + * @return 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). */ @migration(2, 9, "As of 2.9, the p0 call-by-name arguments is evaluated at most once per constructed Parser object, instead of on every need that arises during parsing.") def rep1[T](first: => Parser[T], p0: => Parser[T]): Parser[List[T]] = Parser { in => @@ -607,13 +599,13 @@ trait Parsers { /** A parser generator for a specified number of repetitions. * - * <p> repN(n, p) uses `p' exactly `n' time to parse the input - * (the result is a `List' of the `n' consecutive results of `p')</p> + * `repN(n, p)` uses `p` exactly `n` time to parse the input + * (the result is a `List` of the `n` consecutive results of `p`). * - * @param p a `Parser' that is to be applied successively to the input - * @param n the exact number of times `p' must succeed - * @return 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). + * @param p a `Parser` that is to be applied successively to the input + * @param n the exact number of times `p` must succeed + * @return 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 repN[T](num: Int, p: => Parser[T]): Parser[List[T]] = if (num == 0) success(Nil) else Parser { in => @@ -632,24 +624,24 @@ trait Parsers { /** A parser generator for non-empty repetitions. * - * <p>rep1sep(p, q) repeatedly applies `p' interleaved with `q' to parse the input, until `p' fails. - * The parser `p' must succeed at least once.</p> + * `rep1sep(p, q)` repeatedly applies `p` interleaved with `q` to parse the input, until `p` fails. + * The parser `p` must succeed at least once. * - * @param p a `Parser' that is to be applied successively to the input - * @param q a `Parser' that parses the elements that separate the elements parsed by `p' - * (interleaved with `q') - * @return 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). - * The results of `p' are collected in a list. The results of `q' are discarded. + * @param p a `Parser` that is to be applied successively to the input + * @param q a `Parser` that parses the elements that separate the elements parsed by `p` + * (interleaved with `q`) + * @return 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). + * The results of `p` are collected in a list. The results of `q` are discarded. */ def rep1sep[T](p : => Parser[T], q : => Parser[Any]): Parser[List[T]] = p ~ rep(q ~> p) ^^ {case x~y => x::y} - - /** 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. + /** 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. * - * <p> 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.</p> + * ''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.'' * * @param p a parser that parses the elements * @param q a parser that parses the token(s) separating the elements, yielding a left-associative function that @@ -658,7 +650,7 @@ trait Parsers { def chainl1[T](p: => Parser[T], q: => Parser[(T, T) => T]): Parser[T] = chainl1(p, p, q) - /** A parser generator that, roughly, generalises the rep1sep generator so that `q', which parses the separator, + /** 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. * * @param first a parser that parses the first element @@ -671,7 +663,7 @@ trait Parsers { case x ~ xs => xs.foldLeft(x){(_, _) match {case (a, f ~ b) => f(a, b)}} } - /** A parser generator that generalises the rep1sep generator so that `q', which parses the separator, + /** 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 combining function have to be supplied. * @@ -691,16 +683,16 @@ trait Parsers { /** A parser generator for optional sub-phrases. * - * <p>opt(p) is a parser that returns `Some(x)' if `p' returns `x' and `None' if `p' fails</p> + * `opt(p)` is a parser that returns `Some(x)` if `p` returns `x` and `None` if `p` fails. * - * @param p A `Parser' that is tried on the input - * @return a `Parser' that always succeeds: either with the result provided by `p' or + * @param p A `Parser` that is tried on the input + * @return a `Parser` that always succeeds: either with the result provided by `p` or * with the empty result */ def opt[T](p: => Parser[T]): Parser[Option[T]] = p ^^ (x => Some(x)) | success(None) - /** Wrap a parser so that its failures&errors become success and vice versa -- it never consumes any input + /** Wrap a parser so that its failures and errors become success and vice versa -- it never consumes any input. */ def not[T](p: => Parser[T]): Parser[Unit] = Parser { in => p(in) match { @@ -712,8 +704,8 @@ trait Parsers { /** A parser generator for guard expressions. The resulting parser will fail or succeed * just like the one given as parameter but it will not consume any input. * - * @param p a `Parser' that is to be applied to the input - * @return A parser that returns success if and only if 'p' succeeds but never consumes any input + * @param p a `Parser` that is to be applied to the input + * @return A parser that returns success if and only if `p` succeeds but never consumes any input */ def guard[T](p: => Parser[T]): Parser[T] = Parser { in => p(in) match{ @@ -723,10 +715,10 @@ trait Parsers { } - /** `positioned' decorates a parser's result with the start position of the input it consumed. + /** `positioned` decorates a parser's result with the start position of the input it consumed. * - * @param p a `Parser' whose result conforms to `Positional'. - * @return A parser that has the same behaviour as `p', but which marks its result with the + * @param p a `Parser` whose result conforms to `Positional`. + * @return 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[T <: Positional](p: => Parser[T]): Parser[T] = Parser { in => @@ -736,18 +728,14 @@ trait Parsers { } } - /** <p> - * A parser generator delimiting whole phrases (i.e. programs). - * </p> - * <p> - * <code>phrase(p)</code> succeeds if <code>p</code> succeeds and - * no input is left over after <code>p</code>. - * </p> + /** A parser generator delimiting whole phrases (i.e. programs). + * + * `phrase(p)` succeeds if `p` succeeds and no input is left over after `p`. * * @param p the parser that must consume all input for the resulting parser * to succeed. - * @return a parser that has the same result as `p', but that only succeeds - * if <code>p</code> consumed all the input. + * @return a parser that has the same result as `p`, but that only succeeds + * if `p` consumed all the input. */ def phrase[T](p: Parser[T]) = new Parser[T] { lastNoSuccess = null @@ -768,7 +756,7 @@ trait Parsers { override def toString = "("+ _1 +"~"+ _2 +")" } - /** A parser whose ~ combinator disallows back-tracking. + /** A parser whose `~` combinator disallows back-tracking. */ trait OnceParser[+T] extends Parser[T] { override def ~ [U](p: => Parser[U]): Parser[~[T, U]] |