Package 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>>>
Direct Known Subclasses:
Parser.Proxy
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:

  • ...

  • Constructor Details

    • Parser

      public Parser()

  • Method Details

    • 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:

    • 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

      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:

    • compile

      public Parser<D,T> compile()

    • compileApply

      protected void compileApply(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:

    • 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:

    • 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:

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

    • locate

      static <D, T> Parser<D,T> locate(Function<Parser.Input<D,T>,Token<D,T>> where)

    • 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<Token<D,T>> match)

    • terminal

      public static <D, T> Parser<D,T> terminal(Predicate<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:

    • 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:

    • 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:

    • terminal

      public static <D, T> Parser<D,T> terminal(Predicate<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:

    • 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<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:

    • 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:

    • 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:

    • 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:

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

    • compose

      static <D, T> Parser<D,T> compose(Parser<D,T> p, Parser<D,T> q)

    • 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:

    • sequence

      public static <D, T> Parser<D,T> sequence(List<? extends Parser<D,T>> elems)

    • 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:

    • ifThenElse

      public static <D, T> Parser<D,T> ifThenElse(Predicate<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:

    • 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:

    • 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:

    • 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

      public static <D, T> Parser<D,T> choice(List<? extends Parser<D,T>> alts)

    • 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

      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:

    • 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:

    • 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:

    • 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:

    • 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:

    • guard

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

    • lift

      static <D, T> Parser<D,T> lift(Function<? super Parser.Input<D,T>,? extends Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>>> fun)

    • dummy

      static <D, T> Parser<D,T> dummy()

    • wrap

      public static <D, T> Parser.Input<D,T> wrap(Supplier<? extends 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.

    • append

      static <D, T> Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> append(Action<Parser.Output<D,T>,SimpleMessage<D>,Parser.Input<D,T>> first, Update<SimpleMessage<D>> last)

    • 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)

    • sideEffect

      public static <D, T> Parser<D,T> sideEffect(Runnable effect)

    • sideEffect

      public static <D, T> Parser<D,T> sideEffect(Consumer<Parser.Input<D,T>> effect)

    • withSideEffects

      public Parser<D,T> withSideEffects(Runnable before, Runnable after)

    • withSideEffects

      public Parser<D,T> withSideEffects(Consumer<Parser.Input<D,T>> before, Consumer<Parser.Input<D,T>> after)

    • withOtherTokenSource

      public <K, L> Parser<D,T> withOtherTokenSource(LookaheadTokenMultiplexer<K,D,T,L> multi, K newKey)

    • TRACE

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

    • main

      public static void main(String[] args)

    • test

      static <D, T> void test(Parser<D,T> test)