parcr (version 0.6.0)

succeed: The most basic parsers

Description

These are the most basic constructors of a parser, but they are important cogs of the parser machinery. The succeed parser always succeeds, without consuming any input, whereas the fail parser always fails.

Usage

succeed(left)
fail(lnr = LNR(), expected = NULL)

Value

A list. succeed() returns a list with two elements named L and R. fail() returns a marker object which is basically an empty list with a line number n as attribute. It is printed as the icon [], see print.marker(). Note that n will only correctly represent the line number of failure when a parser is wrapped in the reporter() function.

Arguments

left

any R-object constructed from a parsed vector.

lnr

integer. The line number (element number) at which the fail occurs

expected

character vector. Optional descriptions of what was expected.

Pseudocode

succeed(y)(x): [L=[y],R=[x]]
fail()(x):     []

where [L=[y],R=[x]] is a named list with lists [y] and [x] as elements and [] is an empty list.

Details

The succeed parser constructs a list object with a 'left' or L-element that contains the parser result of the consumed part of the input vector and the 'right' or R-element that contains the unconsumed part of the vector. Since the outcome of succeed does not depend on its input, its result value must be pre-determined, so it is included as a parameter.

While succeed never fails, fail always does, regardless of the input vector. It returns the empty list list() to signal this fact.

Examples

succeed("A")("abc")
succeed(data.frame(title = "Keisri hull", author = "Jaan Kross"))(c("Unconsumed", "text"))

fail()("abc")