Package jjparse

Class Parsing<I>

java.lang.Object

jjparse.Parsing<I>

Type Parameters:

I - The input type or, more specifically, the type of a single element in the underlying input stream.

Direct Known Subclasses:

StringParsing

public abstract class Parsing<I>
extends Object

An abstract class that provides all basic parsing capabilities.

In order to implement a parser, one must extend this class and specify the corresponding input type. The subclass then has access to the Parsing.Parser class and the Parsing.Result class, which are specialized for the respective input type.

Author:

Björn Lötters

See Also:

• Parsing.Result
• Parsing.Parser
• StringParsing

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
final class	Parsing.Abort<T>	Represents a fatal Parsing.Failure.
final class	Parsing.Error<T>	Represents a recoverable Parsing.Failure.
class	Parsing.Failure<T>	Represents a Parsing.Result which indicates a parse failure.
class	Parsing.Parser<T>	The abstract base class of a Parsing.Parser.
class	Parsing.Result<T>	Represents the result of a parsing operation.
final class	Parsing.Success<T>	Represents a successful result of a parsing operation.

Constructor Summary

Constructors

Constructor	Description
Parsing()	Creates an instance of this Parsing class and provides access to all Parsing.Parsers and Parsing.Parser combinators in that way.

Method Summary

Modifier and Type	Method	Description
final <T> Parsing<I>.Parser<T>	abort(String message)	Constructs a Parsing.Parser that always fails with an Parsing.Abort.
final <T> Parsing<I>.Parser<T>	choice(Parsing<I>.Parser<? extends T>... parsers)	Constructs a Parsing.Parser that attempts to parse the provided Parsing.Parsers in the order they are given until one of them succeeds or aborts.
final <T> Parsing<I>.Parser<T>	error(String message)	Constructs a Parsing.Parser that always fails with an Parsing.Error.
final <T> Parsing<I>.Parser<T>	lazy(Supplier<Parsing<I>.Parser<? extends T>> supplier)	Constructs a new Parsing.Parser which is initialized lazy.
final <T> Parsing<I>.Parser<T>	lift(Function<? super Input<I>,? extends Parsing<I>.Result<T>> function)	Lifts the provided Function into a Parsing.Parser.
final <T> Parsing<I>.Result<T>	parse(Parsing<I>.Parser<? extends T> parser, Input<? extends I> input)	Attempts to parse the whole Input with the provided Parsing.Parser.
final <T> Parsing<I>.Parser<T>	position(Parsing<I>.Parser<Function<Input<I>.Position,T>> parser)	Constructs a new Parsing.Parser that behaves just like the given one, applying the current Input.Position to the Function returned by the provided Parsing.Parser.
final <T> Parsing<I>.Parser<List<T>>	sequence(Parsing<I>.Parser<? extends T>... parsers)	Constructs a new Parsing.Parser that applies the provided Parsing.Parsers in sequence.
final <T> void	setSkipParser(Parsing<I>.Parser<? extends T> parser)	Sets the Parsing.Parser that is used for skipping Input before another Parsing.Parser is applied.
final Input<I>	skip(Input<? extends I> input)	Skips the prefix of the provided Input using the current skip Parsing.Parser.
final <T> Parsing<I>.Parser<T>	success(Supplier<? extends T> supplier)	Constructs a Parsing.Parser that always succeeds with a Parsing.Success.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Parsing

public Parsing()

Creates an instance of this Parsing class and provides access to all Parsing.Parsers and Parsing.Parser combinators in that way.

Method Details

parse

public final <T> Parsing<I>.Result<T> parse(Parsing<I>.Parser<? extends T> parser,
 Input<? extends I> input)

Attempts to parse the whole Input with the provided Parsing.Parser. This method fails, if Input that cannot be skipped remains after applying the provided Parsing.Parser.

Type Parameters:

T - The type of the Parsing.Result.

Parameters:

parser - The Parsing.Parser that should be applied to the Input.

input - The Input that should be parsed using the provided Parsing.Parser.

Returns:

The Parsing.Result after applying the provided Parsing.Parser to the Input.

See Also:

• skip(Input)
• Parsing.Parser
• Input
• Parsing.Result

skip

public final Input<I> skip(Input<? extends I> input)

Skips the prefix of the provided Input using the current skip Parsing.Parser. This method does not fail, even if the skip Parsing.Parser was not successful.

Parameters:

input - The Input whose prefix should be skipped.

Returns:

The Input that remains after skipping.

See Also:

• setSkipParser(Parser)

setSkipParser

public final <T> void setSkipParser(Parsing<I>.Parser<? extends T> parser)
                             throws NullPointerException

Sets the Parsing.Parser that is used for skipping Input before another Parsing.Parser is applied. By default, no skip Parsing.Parser is set and no Input is skipped.

Type Parameters:

T - The result type of the provided Parsing.Parser, which is voided internally.

Parameters:

parser - The new Parsing.Parser that should be used for skipping. This Parsing.Parser may fail, in which case no Input is skipped.

Throws:

NullPointerException - If the provided Parsing.Parser is null.

See Also:

• skip(Input)

lift

public final <T> Parsing<I>.Parser<T> lift(Function<? super Input<I>,? extends Parsing<I>.Result<T>> function)

Lifts the provided Function into a Parsing.Parser. This allows us to use Java's lambda notation, despite that Parsing.Parser must be an abstract class.

Type Parameters:

T - The type of the Parsing.Result.

Parameters:

function - The Function that parses an Input and returns a Parsing.Result.

Returns:

A Parsing.Parser which behaves just like the provided Function.

See Also:

• Parsing.Parser
• Parsing.Result
• Input
• Function

error

public final <T> Parsing<I>.Parser<T> error(String message)

Constructs a Parsing.Parser that always fails with an Parsing.Error.

Type Parameters:

T - The mandatory type of the Parsing.Result.

Parameters:

message - The message of the Parsing.Error.

Returns:

A Parsing.Parser that always fails with an Parsing.Error.

abort

public final <T> Parsing<I>.Parser<T> abort(String message)

Constructs a Parsing.Parser that always fails with an Parsing.Abort.

Type Parameters:

T - The mandatory type of the Parsing.Result.

Parameters:

message - The message of the Parsing.Abort.

Returns:

A Parsing.Parser that always fails with an Parsing.Abort.

success

public final <T> Parsing<I>.Parser<T> success(Supplier<? extends T> supplier)

Constructs a Parsing.Parser that always succeeds with a Parsing.Success.

Type Parameters:

T - The type of the value that should be returned by Parsing.Parser.

Parameters:

supplier - A Supplier for the value that should be returned by the Parsing.Parser.

Returns:

A Parsing.Parser that always succeeds with a Parsing.Success.

choice

@SafeVarargs
public final <T> Parsing<I>.Parser<T> choice(Parsing<I>.Parser<? extends T>... parsers)

Constructs a Parsing.Parser that attempts to parse the provided Parsing.Parsers in the order they are given until one of them succeeds or aborts. The returned Parsing.Parser fails if all Parsing.Parsers fail.

Type Parameters:

T - The type of the Parsing.Result.

Parameters:

parsers - The Parsing.Parsers that should be used for the new Parsing.Parser.

Returns:

A Parsing.Parser which attempts to parse the provided Parsing.Parsers in the order they are given.

sequence

@SafeVarargs
public final <T> Parsing<I>.Parser<List<T>> sequence(Parsing<I>.Parser<? extends T>... parsers)

Constructs a new Parsing.Parser that applies the provided Parsing.Parsers in sequence. It fails when one of the Parsing.Parsers fails and succeeds only when all Parsing.Parsers succeed. In this case, the Parsing.Results of all Parsing.Parsers are collected in a single, immutable List.

Type Parameters:

T - The type of a single Parsing.Result.

Parameters:

parsers - The Parsing.Parsers that should be used for the new Parsing.Parser.

Returns:

A Parsing.Parser which attempts to parse the provided Parsing.Parsers in sequence.

position

public final <T> Parsing<I>.Parser<T> position(Parsing<I>.Parser<Function<Input<I>.Position,T>> parser)

Constructs a new Parsing.Parser that behaves just like the given one, applying the current Input.Position to the Function returned by the provided Parsing.Parser.

Type Parameters:

T - The type of the Parsing.Result.

Parameters:

parser - A Parsing.Parser returning a Function which accepts the current Input.Position.

Returns:

A new Parsing.Parser that provides the given one with a Input.Position.

lazy

public final <T> Parsing<I>.Parser<T> lazy(Supplier<Parsing<I>.Parser<? extends T>> supplier)

Constructs a new Parsing.Parser which is initialized lazy. That is to say, when this Parsing.Parser is applied for the first time, the provided Supplier is called and the returned Parsing.Parser is used for parsing. Moreover, this Parsing.Parser is memorized for future applications. This method is especially useful since Java does not provide us with lazy declarations, which are required for mutually recursive parsers (as they occur very often in practice).

Type Parameters:

T - The type of the Parsing.Result.

Parameters:

supplier - The Supplier that provides the actual Parsing.Parser.

Returns:

A Parsing.Parser that lazily evaluates the provided Supplier and behaves just like the Parsing.Parser provided by the Supplier.