eu.bandm.tools.ramus.runtime2

Class Parser<D,T>

java.lang.Object

eu.bandm.tools.ramus.runtime2.Parser<D,T>

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

All Implemented Interfaces:

Action.Continuation<Parser.Input<D,T>,Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>, Function<Parser.Input<D,T>,Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>>

public abstract class Parser<D,T>
extends Object
implements Action.Continuation<Parser.Input<D,T>,Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>

Combinatorial nondeterministic parser building blocks.

Every parser building block is essentially a transition step, a function taking Parser.Input to Parser.Output, with computational behavior specified by Action and diagnostic messages of type SimpleMessage.

Subclasses must implement this behavior by overriding the abstract method Action<Output<D, T>, SimpleMessage<D>, Input<D, T>> apply(Input<D, T>, Success<?, SimpleMessage<D>, Input<D, T>>).

Configurational and OperationalMethods

The methods of this class are divided into a configurational and an operational phase:

• Configurational methods create new parser objects, often by combining existing ones, or query invariant properties. They make invoke other configurational methods on parser objects, but no operational methods. They must not change the observable state of parser objects.
• Operational methods give access to the parsing behavior. They should not to change the observable state of parser objects.

Operational methods are explicitly marked in this documentation; all others are configurational.

Behavioral equivalence

The results of configurational methods are typically specified only in terms of equivalent behavior. Two parsers are behaviorally equivalent iff replacing one by the other in the following procedure does not change the outcome:

• ...

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Parser.Compile
static interface	Parser.Input<D,T> Abstract interface of immutable parser input states.
static class	Parser.Output<D,T> Immutable parser transition outputs.
static class	Parser.Pragma Enumeration of local pragmatic modifiers of parsing behavior.
static interface	Parser.Token<D,T> Abstract interface of parser tokens.

Constructor Summary

Constructors

Constructor and Description
Parser()

Method Summary

Modifier and Type	Method and Description
Parser<D,T>	andThen(Parser<D,T> other) Follows the behavior of this parser sequentially with another.
Parser<D,T>	andThenCombining(Parser<D,T> other, Action.BiContinuation<Data,Data,Data,SimpleMessage<D>,State> combiner) Follows the behavior of this parser sequentially with another, combining the result values.
abstract Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>	apply(Parser.Input<D,T> in, Success<?,SimpleMessage<D>,Parser.Input<D,T>> recyclable) Applies this continuation, possibly using a recyclable leaf node.
Parser<D,T>	assigning(Object key) Adds the assignment of the result value to a semantic variable to the behavior of this parser.
static <D,T> Parser<D,T>	choice(Parser<D,T>... alts) Alternates the behavior of several parsers in nondeterministic choice.
Parser<D,T>	collecting() Adds the collecting of the result value in a sequence to the behavior of this parser.
Parser<D,T>	compile()
protected void	compileApply(eu.bandm.tools.ramus.runtime2.CompilationContext context, ParserCompilationContext.Continuation continuation)
static <D,T> Parser<D,T>	constant(Data value) Returns a parser that succeeds and sets the result to the given value, consuming no tokens.
Parser<D,T>	diagnose(Function<? super Parser.Input<D,T>,? extends SimpleMessage<D>>... msgs)
Parser<D,T>	diagnose(SimpleMessage<D>... msgs) Add diagnostic messages to the behavior of this parser.
static <D,T> Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>	diagnoseUnexpectedToken(Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> body, Location<D> location, @Opt String description)
static <D,T> Parser<D,T>	endInterval() Returns a parser that sets the result value to the token location before the current input state.
static <D,T> Parser<D,T>	fail() Returns a parser that fails immediately.
static <D,T> Parser<D,T>	fix(UnaryOperator<Parser<D,T>> loop) Computes the fixpoint of a recursive parser definition.
Optional<Set<T>>	getFirstSet() Returns the finite set of token types that this parser may consume first, if available.
Parser<D,T>	guard(Predicate<State> condition, Function<State,List<SimpleMessage<D>>> error)
static <D,T> Parser<D,T>	id() Returns a parser that succeeds with no effect, consuming no tokens.
static <D,T> Parser<D,T>	ifThenElse(Predicate<Parser.Token<D,T>> condition, Parser<D,T> thenBranch, Parser<D,T> elseBranch) Alternates the behavior of two parsers in deterministic choice, depending on the next input token.
Parser<D,T>	ignoringResult() Removes the setting of the result value from the semantic effect of this parser.
static <D,T> Predicate<Parser.Token<D,T>>	keyword(String text) Returns a predicate that matches a single token with a given text, regardless of type.
static <D,T> Parser<D,T>	lookbehind(Predicate<Parser.Token<D,T>> match)
static <D,T> Parser<D,T>	lookbehind(Set<T> types)
static <D,T> Parser<D,T>	lookbehind(T... types)
static <D,T> Parser<D,T>	lookup(Map<T,Parser<D,T>> alts) Alternates the behavior of several parsers in deterministic choice, depending on the next input token.
static <D,T> Parser<D,T>	lookup(Map<T,Parser<D,T>> alts, Parser<D,T> otherwise) Alternates the behavior of several parsers in deterministic choice, depending on the next input token.
static void	main(String[] args)
Parser<D,T>	map(Function<Data,Data> transform) Adds a final transformation of the result value to the behavior of this parser.
boolean	mayBeEpsilon() Checks whether this parser may succeed without consuming any token.
Parser<D,T>	negate() Returns a parser that succeeds if this parser fails, and vice versa.
Parser<D,T>	optional(Parser.Pragma... pragmas) Returns a parser that behaves like this parser, or alternatively does nothing.
Parser<D,T>	optionalTagged(Parser.Pragma... pragmas) Returns a parser that behaves like this parser, or alternatively does nothing, setting a corresponding result value.
Parser<D,T>	optionalTagged(Parser<D,T> defaultBranch, Parser.Pragma... pragmas)
Parser<D,T>	orElse(Parser<D,T> other) Alternates the behavior of this parser with another in nondeterministic choice.
Parser<D,T>	plus(Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, one or more times.
Parser<D,T>	plusSequence(Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, one or more times, and collects the result values in a sequence.
Parser<D,T>	plusSequence(Parser<D,T> separator, Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, one or more times, interspersed with a separator parser, and collects the result values in a sequence.
Parser<D,T>	postprocess(Action.Continuation<State,State,SimpleMessage<D>,State> cont) Appends an ad-hoc continuation to the semantic effect of this parser.
Parser<D,T>	postprocess(Action.Continuation<State,State,SimpleMessage<D>,State> cont, int complexity) Appends an ad-hoc continuation to the semantic effect of this parser.
Parser<D,T>	postprocess(Update<SimpleMessage<D>> effect) Appends to the semantic effect of this parser.
Action<State,SimpleMessage<D>,State>	process(Parser.Input<D,T> in, Action.Visitor<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> errorVisitor)
static <D,T> Parser<D,T>	sequence(Parser<D,T>... elems) Combines the behavior of several parsers sequentially.
Parser<D,T>	star(Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, zero or more times.
Parser<D,T>	starSequence(Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, zero or more times, and collects the result values in a sequence.
Parser<D,T>	starSequence(Parser<D,T> separator, Parser.Pragma... pragmas) Returns a parser that behaves as the sequential iteration of this parser, zero or more times, interspersed with a separator parser, and collects the result values in a sequence.
static <D,T> Parser<D,T>	startCollection() Returns a parser that succeeds and sets the result to the empty sequence, consuming no tokens.
static <D,T> Parser<D,T>	startInterval() Returns a parser that sets the result value to the token location at the current input state.
static <D,T> Parser<D,T>	succeed(Function<? super Parser.Input<D,T>,? extends Update<SimpleMessage<D>>> effect) Returns a parser that succeeds with the given state-dependent effect, consuming no tokens.
static <D,T> Parser<D,T>	succeed(Update<SimpleMessage<D>> effect) Returns a parser that succeeds with the given effect, consuming no tokens.
static <D,T> Parser<D,T>	terminal(Predicate<Parser.Token<D,T>> match) Returns a parser that consumes a single token matching a given predicate.
static <D,T> Parser<D,T>	terminal(Predicate<Parser.Token<D,T>> match, Optional<Set<T>> firstSet, @Opt String description) Returns a parser that consumes a single token matching a given predicate.
static <D,T> Parser<D,T>	terminal(T type) Returns a parser that consumes a single token of a given type.
static <D,T> Parser<D,T>	terminal(T type, Predicate<? super String> text) Returns a parser that consumes a single token of a given type and text.
static <D,T> Parser<D,T>	TRACE(String msg)
Parser<D,T>	withScope(Fragment... fragments) Wraps the behavior of this parser in a local scope for a set of semantic variables bound by grammar fragments.
Parser<D,T>	withScope(Map<Object,? extends Data> initializers) Wraps the behavior of this parser in a local scope for a set of semantic variables.
Parser<D,T>	withScope(Object key, Data initializer) Wraps the behavior of this parser in a local scope for a semantic variable.
static <D,T> Parser.Input<D,T>	wrap(Supplier<? extends Parser.Token<D,T>> gen) Returns a parser input state lazily backed by a generator.

Methods inherited from class java.lang.Object

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

Methods inherited from interface eu.bandm.tools.ramus.runtime2.Action.Continuation

apply, forget, map

Methods inherited from interface java.util.function.Function

andThen, compose, identity

Constructor Detail

Parser

public Parser()

Method Detail

apply

public abstract Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> apply(Parser.Input<D,T> in,
                                                                                    Success<?,SimpleMessage<D>,Parser.Input<D,T>> recyclable)

Applies this continuation, possibly using a recyclable leaf node. Operational method.

Specified by:

apply in interface Action.Continuation<Parser.Input<D,T>,Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>

Parameters:

in - the input parsing result

recyclable - a recyclable leaf node, or null if not available

Returns:

a leaf node with a newly computed parsing result; either recyclable if available or new.

See Also:

Action.succeed(Object, Success)

getFirstSet

public Optional<Set<T>> getFirstSet()

Returns the finite set of token types that this parser may consume first, if available.

The default implementation returns Optional.empty(), which is always safe. Subclasses may override this method to return an actual set, if those parsers are known to never succeed with consuming a first token of another type, to enable optimizations.

Returns:

an actual finite set if, whenever this parser succeeds consuming at least one token, the type of the first consumed token must be contained in the set; Optional.empty() if such a set is either unknown or infinite.

See Also:

mayBeEpsilon(), Parser.Token.getType()

mayBeEpsilon

public boolean mayBeEpsilon()

Checks whether this parser may succeed without consuming any token.

The default implementation returns true, which is always safe. Subclasses may override this method to return false, if those parsers are known to never succeed without consuming any token, to enable optimizations.

Returns:

true iff it is possible (certain or unknown) that this parser accepts zero tokens.

See Also:

getFirstSet()

compile

public Parser<D,T> compile()

compileApply

protected void compileApply(eu.bandm.tools.ramus.runtime2.CompilationContext context,
                            ParserCompilationContext.Continuation continuation)

id

public static <D,T> Parser<D,T> id()

Returns a parser that succeeds with no effect, consuming no tokens.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Returns:

a parser that succeeds with no effect, consuming no tokens.

succeed

public static <D,T> Parser<D,T> succeed(Update<SimpleMessage<D>> effect)

Returns a parser that succeeds with the given effect, consuming no tokens.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

effect - the desired semantic effect

Returns:

a parser that succeeds with the given effect, consuming no tokens.

succeed

public static <D,T> Parser<D,T> succeed(Function<? super Parser.Input<D,T>,? extends Update<SimpleMessage<D>>> effect)

Returns a parser that succeeds with the given state-dependent effect, consuming no tokens.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

effect - a function object that computes the desired semantic effect, given the current parser input state

Returns:

a parser that succeeds with the computed effect, consuming no tokens.

constant

public static <D,T> Parser<D,T> constant(Data value)

Returns a parser that succeeds and sets the result to the given value, consuming no tokens.

This method is a shorthand for succeed(Update.setValue(value)).

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

value - the desired semantic effect

Returns:

a parser that succeeds with the effect of setting the result to the given value, consuming no tokens.

See Also:

succeed(Update), Update.setValue(Data)

startCollection

public static <D,T> Parser<D,T> startCollection()

Returns a parser that succeeds and sets the result to the empty sequence, consuming no tokens.

This method is a shorthand for constant(Sequence.empty()).

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Returns:

a parser that succeeds with the effect of setting the result to the empty sequence, consuming no tokens.

See Also:

constant(Data), Sequence

fail

public static <D,T> Parser<D,T> fail()

Returns a parser that fails immediately.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Returns:

a parser that fails with no effect, consuming no tokens.

negate

public final Parser<D,T> negate()

Returns a parser that succeeds if this parser fails, and vice versa.

The resulting parser speculatively executes the behavior of this parser. If this leads to one or more (nondeterministic) successes, the resulting parser fails; speculatively executed semantic effects are undone. Otherwise, if the speculative execution fails, the resulting parser succeeds with no effect, consuming no tokens.

Returns:

a parser that succeeds with no effect if this parser fails and vice versa.

See Also:

id()

startInterval

public static <D,T> Parser<D,T> startInterval()

Returns a parser that sets the result value to the token location at the current input state.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Returns:

a parser that sets the result value to the token location at the current input state.

endInterval

public static <D,T> Parser<D,T> endInterval()

Returns a parser that sets the result value to the token location before the current input state.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Returns:

a parser that sets the result value to the token location before the current input state.

lookbehind

@SafeVarargs
public static <D,T> Parser<D,T> lookbehind(T... types)

lookbehind

public static <D,T> Parser<D,T> lookbehind(Set<T> types)

lookbehind

public static <D,T> Parser<D,T> lookbehind(Predicate<Parser.Token<D,T>> match)

terminal

public static <D,T> Parser<D,T> terminal(Predicate<Parser.Token<D,T>> match)

Returns a parser that consumes a single token matching a given predicate.

This method is a shorthand for terminal(match, Optional.empty(), null); use that method directly if more specific information is available.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

match - a functional object that recognizes matching tokens

Returns:

a parser that succeeds iff a single token matching the predicate can be consumed and stored.

See Also:

State.withValue(eu.bandm.tools.ramus.runtime2.Data), Content, terminal(Predicate, Optional, String)

terminal

public static <D,T> Parser<D,T> terminal(T type)

Returns a parser that consumes a single token of a given type.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

type - the type of tokens to match

Returns:

a parser that succeeds iff a single token of the given type can be consumed and stored.

See Also:

State.withValue(eu.bandm.tools.ramus.runtime2.Data), Content, terminal(Predicate, Optional, String)

terminal

public static <D,T> Parser<D,T> terminal(T type,
                                         Predicate<? super String> text)

Returns a parser that consumes a single token of a given type and text.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

type - the type of tokens to match

Returns:

a parser that succeeds iff a single token of the given type can be consumed and stored.

See Also:

State.withValue(eu.bandm.tools.ramus.runtime2.Data), Content, terminal(Predicate, Optional, String)

terminal

public static <D,T> Parser<D,T> terminal(Predicate<Parser.Token<D,T>> match,
                                         Optional<Set<T>> firstSet,
                                         @Opt
                                         @Opt String description)

Returns a parser that consumes a single token matching a given predicate.

The semantic effect of the returned parser stores the content of the consumed token (as a Content object) as the result value. If the first token does not match, then parsing fails with an error message indicating the expected token description.

This method is a shorthand for terminal(match, Optional.empty(), match.toString()); use that method directly if more specific information is available.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

match - a functional object that recognizes matching tokens

firstSet - an actual finite set of token types, if the type of any matching token must be contained in the set, or Optional.empty() if such a set is unknown or infinite

description - a user-friendly description of the expected tokens, or null if not available

Returns:

a parser that succeeds iff a single token matching the predicate can be consumed and stored.

See Also:

getFirstSet(), State.withValue(eu.bandm.tools.ramus.runtime2.Data), Content, terminal(Predicate, Optional, String)

diagnoseUnexpectedToken

public static <D,T> Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> diagnoseUnexpectedToken(Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> body,
                                                                                                          Location<D> location,
                                                                                                          @Opt
                                                                                                          @Opt String description)

keyword

public static <D,T> Predicate<Parser.Token<D,T>> keyword(String text)

Returns a predicate that matches a single token with a given text, regardless of type.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

text - the text to match

Returns:

a predicate that matches a token iff it has the given text.

See Also:

terminal(Predicate)

diagnose

@SafeVarargs
public final Parser<D,T> diagnose(SimpleMessage<D>... msgs)

Add diagnostic messages to the behavior of this parser.

Parameters:

msgs - the messages to add

Returns:

a parser that behaves equivalently to this parser, but annotates the transition output with the given messages.

See Also:

Diagnosis

diagnose

@SafeVarargs
public final Parser<D,T> diagnose(Function<? super Parser.Input<D,T>,? extends SimpleMessage<D>>... msgs)

map

public final Parser<D,T> map(Function<Data,Data> transform)

Adds a final transformation of the result value to the behavior of this parser.

Parameters:

transform - the transformation to apply to the result value

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect transforms the result value by the specified function.

assigning

public final Parser<D,T> assigning(Object key)

Adds the assignment of the result value to a semantic variable to the behavior of this parser.

Parameters:

key - the key identifying the semantic variable to assign to

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect also assigns the result value to the specified variable.

collecting

public Parser<D,T> collecting()

Adds the collecting of the result value in a sequence to the behavior of this parser.

The resulting parser assumes that the result value of its pre-state is set to a sequence. It then performs the effect of this parser, and appends its result value to the preceding sequence, which becomes the overall result value. If the preceding result value is not a sequence, the result parser fails with a failure message.

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect then appends the result value to the preceding one, if that is a sequence, or otherwise fails.

See Also:

Sequence

withScope

public final Parser<D,T> withScope(Object key,
                                   Data initializer)

Wraps the behavior of this parser in a local scope for a semantic variable.

The semantic effect of the returned parser embeds the effect of this parser in a context that inializes the specified variable before, and restores the previous value afterwards.

Parameters:

key - the key identifying the semantic variable to scope

initializer - the initial value of the variable in its local scope

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect executes in a context where the specified variable is locally scoped.

withScope

public final Parser<D,T> withScope(Map<Object,? extends Data> initializers)

Wraps the behavior of this parser in a local scope for a set of semantic variables.

The semantic effect of the returned parser embeds the effect of this parser in a context that inializes the specified variables before, and restores the previous values afterwards.

Parameters:

initializers - the map of keys to initial value of the variable in its local scope

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect executes in a context where the specified variables are locally scoped.

withScope

public Parser<D,T> withScope(Fragment... fragments)

Wraps the behavior of this parser in a local scope for a set of semantic variables bound by grammar fragments.

The semantic effect of the returned parser embeds the effect of this parser in a context that inializes the specified variables before, and restores the previous values afterwards.

This method creates a local scope for the target variables of all given fragments that are not marked as imported, and initializes them with the specified values.

Parameters:

fragments - the list of grammar fragments

Returns:

a parser that behaves equivalently to this parser, but whose semantic effect executes in a context where the specified variables are locally scoped.

Throws:

IllegalArgumentException - if the list of fragments contains duplicate target variable keys.

See Also:

Fragment.getKey(), Fragment.getInitialValue(), Fragment.isImported()

postprocess

public final Parser<D,T> postprocess(Update<SimpleMessage<D>> effect)

Appends to the semantic effect of this parser.

This method is an equivalent shorthand for andThen(succeed(cons)), but the result of this method may be slightly more efficient.

Parameters:

effect - the semantic effect to append

Returns:

a parser that behaves equivalently to this parser, but where the semantic effect of this parser is sequentially followed by the given effect.

postprocess

public final Parser<D,T> postprocess(Action.Continuation<State,State,SimpleMessage<D>,State> cont)

Appends an ad-hoc continuation to the semantic effect of this parser.

Parameters:

cont - the semantic continuation to append

Returns:

a parser that behaves equivalently to this parser, but where the semantic effect of this parser is sequentially followed by the given continuation.

postprocess

public final Parser<D,T> postprocess(Action.Continuation<State,State,SimpleMessage<D>,State> cont,
                                     int complexity)

Appends an ad-hoc continuation to the semantic effect of this parser.

Giving an estimate of the complexity of the continuation may help self-optimization heuristics. If unknown, use the default value 1.

Parameters:

cont - the semantic continuation to append

complexity - the estimated computational complexity of the continuation, measured in state access operations

Returns:

a parser that behaves equivalently to this parser, but where the semantic effect of this parser is sequentially followed by the given continuation.

ignoringResult

public final Parser<D,T> ignoringResult()

Removes the setting of the result value from the semantic effect of this parser. All other effects, such as diagnostics and assignments to state variables, are unaffected.

Returns:

a parser that behaves equivalently to this parser, but where the previous result value is restored.

andThen

public final Parser<D,T> andThen(Parser<D,T> other)

Follows the behavior of this parser sequentially with another.

Parameters:

other - the subsequent parser

Returns:

a parser that behaves equivalently to this parser, sequentially followed by other.

andThenCombining

public final Parser<D,T> andThenCombining(Parser<D,T> other,
                                          Action.BiContinuation<Data,Data,Data,SimpleMessage<D>,State> combiner)

Follows the behavior of this parser sequentially with another, combining the result values.

Parameters:

other - the subsequent parser

combiner - a binary continuation to combine the result values

Returns:

a parser that behaves equivalently to this parser, sequentially followed by other, followed by the combination of result values.

sequence

@SafeVarargs
public static <D,T> Parser<D,T> sequence(Parser<D,T>... elems)

Combines the behavior of several parsers sequentially.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

elems - the array of parsers to combine sequentially

Returns:

a parser that behaves equivalently to all of the given parsers combined sequentially, or to id() if the array is empty.

See Also:

andThen(Parser), id()

orElse

public final Parser<D,T> orElse(Parser<D,T> other)

Alternates the behavior of this parser with another in nondeterministic choice.

This method may exploit available syntactic information to reduce the choice to a case for the deterministic variant ifThenElse.

Parameters:

other - the alternative parser

Returns:

a parser that behaves equivalently to this parser, nondeterministically branching to other if necessary.

See Also:

Choice, getFirstSet(), mayBeEpsilon()

ifThenElse

public static <D,T> Parser<D,T> ifThenElse(Predicate<Parser.Token<D,T>> condition,
                                           Parser<D,T> thenBranch,
                                           Parser<D,T> elseBranch)

Alternates the behavior of two parsers in deterministic choice, depending on the next input token.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

condition - a predicate to apply to the next input token

thenBranch - the branch to choose if the next input token matches the condition

elseBranch - the branch to choose if the next input token does not match the condition

Returns:

a parser that behaves equivalently to either given branch, depending on whether the next input token matches the condition.

See Also:

Parser.Input.lookahead(int)

optional

public final Parser<D,T> optional(Parser.Pragma... pragmas)

Returns a parser that behaves like this parser, or alternatively does nothing.

This method supports the following pragmas:

• Greedy – always perform the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to this parser, or alternatively to the parser id().

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

id(), getFirstSet(), mayBeEpsilon()

optionalTagged

public final Parser<D,T> optionalTagged(Parser.Pragma... pragmas)

Returns a parser that behaves like this parser, or alternatively does nothing, setting a corresponding result value.

The semantic effect of the returned parser wraps the result value of this parser with Option.just(eu.bandm.tools.ramus.runtime2.Data) if the corresponding branch has been chosen, or sets the result value to Option.none otherwise.

This method supports the following pragmas:

• Greedy – always perform the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to this parser, or alternatively to the parser id(), setting a corresponding result value.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

id(), getFirstSet(), mayBeEpsilon(), Option

optionalTagged

public final Parser<D,T> optionalTagged(Parser<D,T> defaultBranch,
                                        Parser.Pragma... pragmas)

choice

@SafeVarargs
public static <D,T> Parser<D,T> choice(Parser<D,T>... alts)

Alternates the behavior of several parsers in nondeterministic choice.

This method may exploit available syntactic information to reduce the choice to a case for the deterministic variant lookup.

In contrast to the dual operation sequence, which can be conceived as the moral equivalent of an iteration of the binary operation andThen(eu.bandm.tools.ramus.runtime2.Parser<D, T>), this method

• is strongly preferrable to an iteration of the binary operation orElse, where more than two alternatives are concerned;
• but may not preserve the order in which alternative branches are tried.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

alts - the alternative branches

Returns:

a parser that behaves equivalent to the choice of all alternative branches, tried in some arbitrary given order, nondeterministically if necessary.

See Also:

Choice, getFirstSet(), mayBeEpsilon()

lookup

public static <D,T> Parser<D,T> lookup(Map<T,Parser<D,T>> alts)

Alternates the behavior of several parsers in deterministic choice, depending on the next input token.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

alts - a map of token types to parsers, to be chosen if the next token is of the respective type

Returns:

a parser that behaves equivalently to the parser mapped to the type of the next input token, or to a parser that fails with a diagnostic hint if there is none.

lookup

public static <D,T> Parser<D,T> lookup(Map<T,Parser<D,T>> alts,
                                       Parser<D,T> otherwise)

Alternates the behavior of several parsers in deterministic choice, depending on the next input token.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

alts - a map of token types to parsers, to be chosen if the next input token is of the respective type

otherwise - the parser to be chosen if the next input token is of an unmapped type

Returns:

a parser that behaves equivalently to the parser mapped to the type of the next input token, or to otherwise if there is none.

fix

public static <D,T> Parser<D,T> fix(UnaryOperator<Parser<D,T>> loop)

Computes the fixpoint of a recursive parser definition.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

loop - a function object that returns a parser, assuming that it receives a behaviorally equivalent parser as input

Returns:

a parser p that is behaviorally equivalent to loop.apply(p).

star

public final Parser<D,T> star(Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, zero or more times. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method is a shorthand for fix(p -> this.andThen(p).optional(pragmas)).

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of zero or more sequential iterations of this parser.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

plus(Pragma...), getFirstSet(), mayBeEpsilon()

plus

public final Parser<D,T> plus(Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, one or more times. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method is a shorthand for fix(p -> this.andThen(p.optional(pragmas))).

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of one or more sequential iterations of this parser.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

star(Pragma...), getFirstSet(), mayBeEpsilon()

starSequence

public final Parser<D,T> starSequence(Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, zero or more times, and collects the result values in a sequence. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method is a shorthand for startCollection().andThen(this.collecting().star(pragmas)).

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of zero or more sequential iterations of this parser.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

star(Pragma...), plusSequence(Pragma...), collecting(), getFirstSet(), mayBeEpsilon()

plusSequence

public final Parser<D,T> plusSequence(Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, one or more times, and collects the result values in a sequence. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method is a shorthand for startCollection().andThen(this.collecting().plus(pragmas)).

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of one or more sequential iterations of this parser.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and this.mayBeEpsilon() returns true.

See Also:

plus(Pragma...), starSequence(Pragma...), collecting(), getFirstSet(), mayBeEpsilon()

starSequence

public Parser<D,T> starSequence(Parser<D,T> separator,
                                Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, zero or more times, interspersed with a separator parser, and collects the result values in a sequence. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser and the separator may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

separator - the parser to invoke between consecutive iterations

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of zero or more sequential iterations of this parser, interspersed with separator.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and both this.mayBeEpsilon() and {separator.mayBeEpsilon()} return true.

See Also:

star(Pragma...), plusSequence(Parser, Pragma...), collecting(), getFirstSet(), mayBeEpsilon()

plusSequence

public Parser<D,T> plusSequence(Parser<D,T> separator,
                                Parser.Pragma... pragmas)

Returns a parser that behaves as the sequential iteration of this parser, one or more times, interspersed with a separator parser, and collects the result values in a sequence. Increasing numbers of iterations are tried as nondeterministic alternatives in ascending order.

This method supports the following pragmas:

• Greedy – always perform another iteration of the behavior of this parser if the next token is of an acceptable type.
• Productive – throw an exception if this parser and the separator may succeed without consuming a token; thus creating an ambiguity that cannot be resolved by syntax.

Parameters:

separator - the parser to invoke between consecutive iterations

pragmas - the pragmas to apply

Returns:

a parser that behaves equivalently to the choice of any number of one or more sequential iterations of this parser, interspersed with separator.

Throws:

UnsupportedOperationException - optionally if the Productive pragma is specified, and both this.mayBeEpsilon() and {separator.mayBeEpsilon()} return true.

See Also:

plus(Pragma...), starSequence(Parser, Pragma...), collecting(), getFirstSet(), mayBeEpsilon()

guard

public Parser<D,T> guard(Predicate<State> condition,
                         Function<State,List<SimpleMessage<D>>> error)

wrap

public static <D,T> Parser.Input<D,T> wrap(Supplier<? extends Parser.Token<D,T>> gen)

Returns a parser input state lazily backed by a generator.

The returned input state represent the potentially infinite sequence of tokens obtained by successive invocations of the method Supplier.get() of the given generator.

The sequence is created lazily; new tokens are demanded only when required by Parser.Input.lookahead(int) or Parser.Input.consume(). Thus concurrent shared use of the generator may result in nondeterministic behavior.

The implementation is thread-safe: concurrent shared uses of the resulting Parser.Input object observe consistent token sequences.

Type Parameters:

D - the type of source document identifiers

T - the type of token types; typically an enum type

Parameters:

gen - a functional object that generates tokens on demand

Returns:

an input state lazily backed by the given generator.

process

public Action<State,SimpleMessage<D>,State> process(Parser.Input<D,T> in,
                                                    Action.Visitor<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> errorVisitor)

TRACE

public static <D,T> Parser<D,T> TRACE(String msg)

main

public static void main(String[] args)