Package eu.bandm.tools.paisley

Interface Pattern<A>

Type Parameters:
A - the target type of objects to match against
All Superinterfaces:
Serializable
All Known Implementing Classes:
AbstractPattern, Adaptive, All, Atomic, Binary, Both, Both.Backtrack, Both.NoBacktrack, CachedTransform, Constraint, Either, EnumBranch, Filter, FlatMultiTransform, IntBranch, Lazy, MultiTransform, Proxy, RestrictedTransform, Search, Theme, TotalTransform, Transform, Unary, Variable
Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@Generated(generator="eu.bandm.tools.expander", version="", timestamp="2026-01-12T17:56:30") @FunctionalInterface public interface Pattern<A> extends Serializable
Base interface of all patterns.

Subclasses must implement the match(A) method. Nondeterministic subclasses must override the matchAgain() method. Subclasses with local matching state and/or subpatterns must override the fork() method.

Subclasses should override the isDeterministic(), binds(Variable) and preserves(Variable,boolean) methods, if appropriate, to improve runtime information on pattern behavior.

Serialization

This base interface extends Serializable. Subclasses should not add fields that may hold references to potentially non-serializable objects in their persistent state. However, such references may be held in temporary state during a nondeterministic matching session; the corresponding fields should be declared transient. Deserialized pattern objects are generally in an initial state, as after a call to clear(true).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Pattern<Object>
    none
    A pattern that matches nothing.

  • Method Summary

    Modifier and Type
    Method
    Description
    static <A> Pattern<A>
    all(Pattern<? super A>... patterns)
    Combines several patterns conjunctively.
    static <A> Pattern<A>
    all(Iterable<? extends Pattern<? super A>> patterns)
    Combines several patterns conjunctively.
    default <B extends A>
    Pattern<B>
    and(Pattern<? super B> other)
    Combines this patterns conjunctively with another pattern.
    default Pattern<A>
    andThen(Runnable action)
    Returns a pattern that matches like this pattern, and invokes a given action for each success.
    default Pattern<A>
    andThen(Consumer<? super A> consumer)
    Returns a pattern that matches like this pattern, and invokes a given consumer on the target for each success.
    static <A> Pattern<A>
    any()
    Returns a pattern that matches anything.
    static Pattern<Object>
    aside(Runnable action)
    Returns a deterministic pattern that matches any target and executes an action.
    default boolean
    binds(Variable<?> variable)
    Checks whether a variable is bound by this pattern.
    static <A> Pattern<A>
    both(Pattern<? super A> left, Pattern<? super A> right)
    Combines two patterns conjunctively.
    default void
    clear()
    Disposes of all temporary internal state related to results and nondeterminism.
    default void
    clear(boolean recursively)
    Disposes of all temporary internal state related to results and nondeterminism.
    default void
    cut()
    Disposes of all temporary internal state related to nondeterminism.
    default void
    cut(boolean recursively)
    Disposes of all temporary internal state related to nondeterminism.
    static <A> Pattern<A>
    either(Pattern<? super A> left, Pattern<? super A> right)
    Combines two patterns disjunctively.
    default <B extends A>
    Motif<B,B>
    enPassant()
    Returns a motif that matches this pattern against each target and then binds the whole target.
    default Pattern<A>
    flatten()
    Returns a possibly simplified variant of this pattern.
    default Pattern<A>
    fork()
    Makes a copy of this pattern with independent internal state.
    static <A> Pattern<A>
    ifThenElse(Predicate<? super A> condition, Pattern<? super A> thenBody, Pattern<? super A> elseBody)
    Returns a pattern that delegates to either of two subpatterns, depending on a given condition.
    default boolean
    isDeterministic()
    Checks whether this pattern is deterministic.
    default Pattern<A>
    limit(int n)
    Returns a pattern that stops after a given number of matches.
    boolean
    match(A target)
    Attempts to match this pattern against a given object.
    default boolean
    matchAgain()
    Attempts to re-match this pattern against a previously matched object.
    default BooleanSupplier
    matches(A target)
     
    default boolean
    matchOnce(A target)
    Attempts to match this pattern at most once against a given object.
    default boolean
    matchVar(Extractor<? extends A> variable)
    FIXME.
    default <B extends A>
    Pattern<B>
    narrow()
    Returns an equivalent pattern with narrower type parameter.
    default Pattern<A>
    noMatch()
    Returns a pattern that matches if and only if this pattern has no match.
    static <A> Pattern<A>
    none()
    Returns a pattern that matches nothing.
    default <B extends A>
    Pattern<B>
    or(Pattern<? super B> other)
    Combines this pattern disjunctively with another pattern.
    default Pattern<A>
    orElse(Runnable action)
    Returns a pattern that matches like this pattern, but invokes a given action if there is no match.
    default Pattern<A>
    orElse(Consumer<? super A> consumer)
    Returns a pattern that matches like this pattern, but invokes a given consumer on the target if there is no match.
    default boolean
    preserves(Variable<?> variable)
    Checks whether a variable is preserved by this pattern unconditionally.
    default boolean
    preserves(Variable<?> variable, boolean success)
    Checks whether a variable is preserved by this pattern, conditionally on success or failure.
    static <A> Pattern<A>
    repeat()
    Returns a pattern that matches any target an indefinite number of times.
    static <A> Pattern<A>
    some(Pattern<? super A>... patterns)
    Combines several patterns disjunctively.
    static <A> Pattern<A>
    some(Iterable<? extends Pattern<? super A>> patterns)
    Combines several patterns disjunctively.
    default Pattern<A>
    someMatch()
    Returns a pattern matches this pattern, but at most once per target.
    default Pattern<A>
    uniquely()
    Returns a pattern that matches if and only if this pattern has a unique match.
    default Pattern<A>
    unlessNull()
    Returns a pattern that matches like this pattern against non-null targets.
    static <A> Variable<A>
    variable()
    Creates a new anonymous pattern variable.
    static <A> Variable<A>
    variable(@Opt String name)
    Creates a new named pattern variable.

  • Field Details

    • none

      static final Pattern<Object> none
      A pattern that matches nothing. This pattern may be shared and reused concurrently.

  • Method Details

    • match

      boolean match(A target)
      Attempts to match this pattern against a given object.

      If the class of this pattern imposes a specific order on matches, the first one is chosen.

      The null target is generally allowed.

      Parameters:
      target - the object to match against
      Returns:
      true if the matching is successful, false if it fails. Which Variables are bound by a successful or failed match depends.
      See Also:

    • matchAgain

      default boolean matchAgain()
      Attempts to re-match this pattern against a previously matched object.

      If the class of this pattern imposes a specific order on matches, they are chosen in that order, beginning with the second one. The behaviour of this method is unspecified if the last matching attempt of this pattern has not been successful.

      Patterns classes that do not override this method are deterministic. Pattern classes that overwrite this method to provide additional matches should also override isDeterministic().

      Returns:
      true if the matching is successful, false if it fails. Which Variables are bound by a successful match depends. The default implementation always returns false.
      See Also:

    • matchVar

      default boolean matchVar(Extractor<? extends A> variable)
      FIXME.
      Parameters:
      variable - FIXME
      Returns:
      FIXME

    • cut

      default void cut()
      Disposes of all temporary internal state related to nondeterminism. Subsequent matching attempts with matchAgain() should fail.

      The default implementation invokes cut(true).

    • clear

      default void clear()
      Disposes of all temporary internal state related to results and nondeterminism. Subsequent matching attempts with matchAgain() should fail. Bound variables are reset to initial values.

      The default implementation invokes clear(true).

    • cut

      default void cut(boolean recursively)
      Disposes of all temporary internal state related to nondeterminism.

      The default implementation does nothing. Subclasses that override this method should also override clear(boolean) and ensure that it implies the effect of cut(false).

      Parameters:
      recursively - true if all subpatterns should traversed, false otherwise.

    • clear

      default void clear(boolean recursively)
      Disposes of all temporary internal state related to results and nondeterminism.

      The default implementation just invokes cut(false). Subclasses that override this method should either invoke this overridden implementation, or ensure by other means that the effect of cut(false) is implied.

      Parameters:
      recursively - true if all subpatterns should be traversed, false otherwise.

    • matchOnce

      default boolean matchOnce(A target)
      Attempts to match this pattern at most once against a given object.

      Disposes of internal state of the pattern immediately by invoking cut().

      Parameters:
      target - the object to match against
      Returns:
      true if the matching is successful, false if it fails. Which Variables are bound by a successful or failed match depends.

    • binds

      default boolean binds(Variable<?> variable)
      Checks whether a variable is bound by this pattern.

      The default implementation returns false.

      Parameters:
      variable - a pattern variable
      Returns:
      true if the variable is guaranteed to have a meaningful value when this pattern is open, false otherwise.
      Throws:
      NullPointerException - if variable is null

    • preserves

      default boolean preserves(Variable<?> variable, boolean success)
      Checks whether a variable is preserved by this pattern, conditionally on success or failure.

      The default implementation returns false.

      Parameters:
      variable - a pattern variable
      success - specifies preservation on success or failure
      Returns:
      true if the variable value is guaranteed to be unaffected by a matching attempt with this pattern that returns a value equal to success.
      Throws:
      NullPointerException - if variable is null

    • preserves

      default boolean preserves(Variable<?> variable)
      Checks whether a variable is preserved by this pattern unconditionally.

      The default implementation returns false.

      Parameters:
      variable - a pattern variable
      Returns:
      true if the variable value is guaranteed to be unaffected by any matching attempt with this pattern.
      Throws:
      NullPointerException - if variable is null

    • isDeterministic

      default boolean isDeterministic()
      Checks whether this pattern is deterministic.

      The default implementation returns false.

      Returns:
      true if this pattern is guaranteed to match any object at most once, false otherwise.
      See Also:

    • narrow

      default <B extends A> Pattern<B> narrow()
      Returns an equivalent pattern with narrower type parameter. The default implementation returns this pattern and relies on the class invariants for dynamic type safety.

      Note that, by contrast, casting Variable<A> to Variable<B>, where B is a subtype of A, is not type safe.

      Type Parameters:
      B - the narrower target type of objects to match against
      Returns:
      a pattern that is equivalent to this pattern, but only applicable to targets of type B

    • fork

      default Pattern<A> fork()
      Makes a copy of this pattern with independent internal state.

      Subclasses must override this method if necessary to honour the following rules for all transitively reachable patterns:

      • Subpatterns that are instances of Variable must be shared. This implies that Variable.fork() must return this.
      • Fields that do not refer to subpatterns, but to matching state (changed by invocations of match(A), matchAgain(), cut() or clear()) must be duplicated. If matching state changes are effected by modification of other objects, these must be duplicated. In summary, matching operations on this pattern and its copy must not interfere, with the exception of variable bindings.
      • Fields neither referring to subpatterns nor to matching state may be either shared or duplicated. The usage of such fields in a modifiable way (such that the distinction is relevant) is strongly deprecated.
      • Patterns whose fields need not be duplicated need not be duplicated themselves, but may return this.
      Returns:
      a copy of this pattern that has independent internal state, except for variables

    • variable

      static <A> Variable<A> variable()
      Creates a new anonymous pattern variable.
      Type Parameters:
      A - the target type of objects to match against
      Returns:
      a new anonymous variable

    • variable

      static <A> Variable<A> variable(@Opt @Opt String name)
      Creates a new named pattern variable.
      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      name - the name of the variable, or null if not applicable
      Returns:
      a new variable with the given name

    • uniquely

      default Pattern<A> uniquely()
      Returns a pattern that matches if and only if this pattern has a unique match.

      Note that the resulting pattern invokes this pattern twice, since determining that there is no second match may clobber the state of the first match. Hence nesting such patterns is strongly discouraged.

      A pattern of this class is deterministic by construction.

      Returns:
      a pattern that matches if and only if this pattern has a unique match

    • limit

      default Pattern<A> limit(int n)
      Returns a pattern that stops after a given number of matches.
      Parameters:
      n - the maximal number of matches
      Returns:
      a pattern that matches any target like this patterns, but at most n times
      Throws:
      IllegalArgumentException - if n < 0

    • any

      static <A> Pattern<A> any()
      Returns a pattern that matches anything.

      A pattern returned by this method is deterministic and binds no variables.

      Type Parameters:
      A - the target type of objects to match against
      Returns:
      a pattern that matches any target deterministically and without side effects

    • none

      static <A> Pattern<A> none()
      Returns a pattern that matches nothing.

      A pattern returned by this method is vacuously deterministic and binds all variables.

      Type Parameters:
      A - the target type of objects to match against
      Returns:
      a pattern that matches no target

    • repeat

      static <A> Pattern<A> repeat()
      Returns a pattern that matches any target an indefinite number of times.

      A pattern returned by this method is nondeterministic and binds no variables.

      Type Parameters:
      A - the target type of objects to match against
      Returns:
      a pattern that matches the target indenfinitely often

    • all

      @SafeVarargs static <A> Pattern<A> all(Pattern<? super A>... patterns)
      Combines several patterns conjunctively.

      The given patterns are tried on each target in the given order. If there is no pattern to try, then the resulting pattern succeeds vacuously.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      patterns - the patterns to combine
      Returns:
      a pattern that tries the given patterns in order, and only succeeds if they all succeed
      Throws:
      NullPointerException - if patterns is null or contains a null element
      See Also:

    • all

      static <A> Pattern<A> all(Iterable<? extends Pattern<? super A>> patterns)
      Combines several patterns conjunctively.

      The given patterns are tried on each target in the given order. If there is no pattern to try, then the resulting pattern succeeds vacuously.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      patterns - the patterns to combine
      Returns:
      a pattern that tries the given patterns in order, and only succeeds if they all succeed
      Throws:
      NullPointerException - if patterns is null or contains a null element
      See Also:

    • some

      @SafeVarargs static <A> Pattern<A> some(Pattern<? super A>... patterns)
      Combines several patterns disjunctively.

      The given patterns are tried on each target in the given order. If there is no pattern to try, then the resulting pattern fails vacuously.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      patterns - the patterns to combine
      Returns:
      a pattern that tries the given patterns in order, and succeeds nondeterministically whenever one of them succeeds
      Throws:
      NullPointerException - if patterns is null or contains a null element
      See Also:

    • some

      static <A> Pattern<A> some(Iterable<? extends Pattern<? super A>> patterns)
      Combines several patterns disjunctively.

      The given patterns are tried on each target in the given order. If there is no pattern to try, then the resulting pattern fails vacuously.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      patterns - the patterns to combine
      Returns:
      a pattern that tries the given patterns in order, and succeeds nondeterministically whenever one of them succeeds
      Throws:
      NullPointerException - if patterns is null or contains a null element
      See Also:

    • and

      default <B extends A> Pattern<B> and(Pattern<? super B> other)
      Combines this patterns conjunctively with another pattern.

      A pattern returned by this method is deterministic if and only if both argument patterns are deterministic. A pattern returned by this method is ordered if and only if both argument patterns are ordered. It binds all variables bound by either argument pattern.

      Since the matches of the second argument pattern are repeated for each successful match of the first, it is more efficient to give arguments in decreasing order of matching costs.

      This method calls both(this, other).

      Type Parameters:
      B - the joint target type of objects to match against
      Parameters:
      other - the other pattern
      Returns:
      a pattern that has a successful match for each combination of successful matches of the argument patterns. If both argument patterns are ordered, the resulting order is the lexical order of the pairs.
      Throws:
      NullPointerException - if other is null

    • or

      default <B extends A> Pattern<B> or(Pattern<? super B> other)
      Combines this pattern disjunctively with another pattern.

      A pattern returned by this method is deterministic if and only if both argument patterns are deterministic and mutually exclusive. A pattern returned by this method is ordered if and only if both argument patterns are ordered. It binds all variables bound by both argument patterns.

      Type Parameters:
      B - the joint target type of objects to match against
      Parameters:
      other - the other pattern
      Returns:
      a pattern that has a successful match for each successful match of either argument pattern. If both argument patterns are ordered, the resulting order is the concatenation.
      Throws:
      NullPointerException - if other is null
      See Also:

    • both

      static <A> Pattern<A> both(Pattern<? super A> left, Pattern<? super A> right)
      Combines two patterns conjunctively.

      A pattern returned by this method is deterministic if and only if both argument patterns are deterministic. A pattern returned by this method is ordered if and only if both argument patterns are ordered. It binds all variables bound by either argument pattern.

      Since the matches of the second argument pattern are repeated for each successful match of the first, it is more efficient to give arguments in decreasing order of matching costs.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      left - an argument pattern
      right - another argument pattern
      Returns:
      a pattern that has a successful match for each combination of successful matches of the argument patterns. If both argument patterns are ordered, the resulting order is the lexical order of the pairs.
      Throws:
      NullPointerException - if left or right is null

    • either

      static <A> Pattern<A> either(Pattern<? super A> left, Pattern<? super A> right)
      Combines two patterns disjunctively.

      A pattern returned by this method is deterministic if and only if both argument patterns are deterministic and mutually exclusive. A pattern returned by this method is ordered if and only if both argument patterns are ordered. It binds all variables bound by both argument patterns.

      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      left - an argument pattern
      right - another argument pattern
      Returns:
      a pattern that has a successful match for each successful match of either argument pattern. If both argument patterns are ordered, the resulting order is the concatenation.
      Throws:
      NullPointerException - if left or right is null

    • noMatch

      default Pattern<A> noMatch()
      Returns a pattern that matches if and only if this pattern has no match.

      A pattern returned by this method is deterministic and binds no variables.

      Returns:
      a pattern that matches if and only if this pattern has no match

    • someMatch

      default Pattern<A> someMatch()
      Returns a pattern matches this pattern, but at most once per target.

      Further matches are discarded by invoking this.cut().

      The matchAgain() method of the resulting pattern always returns false.

      The resulting pattern is deterministic by construction.

      Returns:
      a pattern matches this pattern, but at most once per target

    • enPassant

      default <B extends A> Motif<B,B> enPassant()
      Returns a motif that matches this pattern against each target and then binds the whole target.

      Matches are combined conjunctively.

      Type Parameters:
      B - the restricted target type of objects to match against
      Returns:
      a motif that matches this pattern against each target and then binds it
      See Also:

    • flatten

      default Pattern<A> flatten()
      Returns a possibly simplified variant of this pattern.

      The default implementation flattens conjunctions. Use this method if the original pattern uses deep conjunction and is prone to run out of stack.

      Returns:
      a possibly simplified variant of this pattern
      See Also:

    • aside

      static Pattern<Object> aside(Runnable action)
      Returns a deterministic pattern that matches any target and executes an action.

      The resulting patterns are useful to embed in deeply nested patterns for tracing.

      Parameters:
      action - the action to be executed upon match
      Returns:
      a deterministic pattern that matches any target and executes action

    • andThen

      default Pattern<A> andThen(Runnable action)
      Returns a pattern that matches like this pattern, and invokes a given action for each success.
      Parameters:
      action - the action to invoke
      Returns:
      a pattern that matches like this, and invokes action for each success
      Throws:
      NullPointerException - if action is null

    • andThen

      default Pattern<A> andThen(Consumer<? super A> consumer)
      Returns a pattern that matches like this pattern, and invokes a given consumer on the target for each success.
      Parameters:
      consumer - the consumer to invoke
      Returns:
      a pattern that matches like this, and invokes consumer for each success
      Throws:
      NullPointerException - if consumer is null

    • orElse

      default Pattern<A> orElse(Runnable action)
      Returns a pattern that matches like this pattern, but invokes a given action if there is no match.

      The action is only invoked if there no match at all for the given target, i.e., when match(target) fails. It is not invoked when matchAgain fails.

      Parameters:
      action - the action to invoke
      Returns:
      a pattern that matches like this, but invokes action if there is no match
      Throws:
      NullPointerException - if action is null

    • orElse

      default Pattern<A> orElse(Consumer<? super A> consumer)
      Returns a pattern that matches like this pattern, but invokes a given consumer on the target if there is no match.

      The consumer is only invoked if there no match at all for the given target, i.e., when match(target) fails. It is not invoked when matchAgain fails.

      Parameters:
      consumer - the consumer to invoke
      Returns:
      a pattern that matches like this, but invokes consumer if there is no match
      Throws:
      NullPointerException - if consumer is null

    • ifThenElse

      static <A> Pattern<A> ifThenElse(Predicate<? super A> condition, Pattern<? super A> thenBody, Pattern<? super A> elseBody)
      Returns a pattern that delegates to either of two subpatterns, depending on a given condition.
      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      condition - the condition that selects a subpattern for each target
      thenBody - the subpattern to match if condition returns true
      elseBody - the subpattern to match if condition returns false
      Returns:
      a pattern that matches each target like thenBody if condition returns true, or like elseBody if condition returns false
      Throws:
      NullPointerException - if condition, thenBody or elseBody is null

    • unlessNull

      default Pattern<A> unlessNull()
      Returns a pattern that matches like this pattern against non-null targets. The resulting pattern simply fails for null targets.
      Returns:
      a pattern that matches like this pattern if target is non-null, or otherwise fails

    • matches

      default BooleanSupplier matches(A target)