Package eu.bandm.tools.paisley

Class Pattern<A>

java.lang.Object
eu.bandm.tools.paisley.Pattern<A>
Type Parameters:
A - the target type (of objects to match against)
All Implemented Interfaces:
Serializable, Cloneable
Direct Known Subclasses:
Adaptive, Atomic, Binary, EnumBranch, IntBranch, Observable, Search, Unary, Variable
public abstract class Pattern<A> extends Object implements Cloneable, Serializable
Abstract base class 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 clone() method.

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

See Also:

  • Field Details

  • Constructor Details

    • Pattern

      protected Pattern()
      Creates a new pattern.

  • Method Details

    • match

      public abstract 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.
      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

      public 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

      public boolean matchVar(Extractor<? extends A> variable)

    • cut

      public final void cut()
      Disposes of all internal state related to nondeterminism. Subsequent matching attempts with matchAgain() should fail. Invokes cut(true).

    • clear

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

    • cut

      public void cut(boolean recursively)
      Disposes of all 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 be deactivated, false otherwise.

    • clear

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

      The default implementation does nothing.

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

    • matchOnce

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

      Closes the pattern immediately by invoking cut().

    • binds

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

    • preserves

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

    • preserves

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

    • isDeterministic

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

      The default implementation returns true.

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

    • narrow

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

    • clone

      public Pattern<A> clone()
      Makes a matching-state copy if this pattern.

      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.clone() 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.
      Overrides:
      clone in class Object

    • variable

      public static <A> Variable<A> variable()
      Creates a new anonymous pattern variable.

    • variable

      public static <A> Variable<A> variable(String name)
      Creates a new named pattern variable.

    • once

      public static <A> Pattern<A> once(Predicate<? super A> test)
      Returns a pattern which matches once by evaluating the given function object.
      Type Parameters:
      A - the target type
      Parameters:
      test - the functional object that implements the match

    • uniquely

      public final 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.

    • limit

      public final Pattern<A> limit(int n)
      Returns a pattern that stops after a given number of matches.
      Parameters:
      n - the maximal number of matches.
      Throws:
      IllegalArgumentException - if n < 0.

    • any

      public static final <A> Pattern<A> any()
      Returns a pattern that matches anything. A pattern returned by this method is deterministic and binds no variables.

    • none

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

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

    • repeat

      public static final <A> Pattern<A> repeat()

    • all

      @SafeVarargs public static <A> Pattern<A> all(Pattern<? super A>... p)
      Combines many patterns conjunctively. Equivalent to folding in the monoid of both(Pattern, Pattern) and any().

    • all

      public static <A> Pattern<A> all(Iterable<? extends Pattern<? super A>> p)

    • all

      public static <A> Pattern<A> all(Pattern<? super A> p1, Pattern<? super A> p2)
      Combines many patterns conjunctively. Equivalent to folding in the monoid of both(Pattern, Pattern) and any().

    • all

      public static <A> Pattern<A> all(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3)
      Combines many patterns conjunctively. Equivalent to folding in the monoid of both(Pattern, Pattern) and any().

    • all

      public static <A> Pattern<A> all(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3, Pattern<? super A> p4)
      Combines many patterns conjunctively. Equivalent to folding in the monoid of both(Pattern, Pattern) and any().

    • some

      public static <A> Pattern<A> some(Pattern<? super A>... p)
      Combines many patterns disjunctively. Equivalent to folding in the monoid of either(Pattern, Pattern) and none().

    • some

      public static <A> Pattern<A> some(Pattern<? super A> p1, Pattern<? super A> p2)
      Combines many patterns disjunctively. Equivalent to folding in the monoid of either(Pattern, Pattern) and none().

    • some

      public static <A> Pattern<A> some(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3)
      Combines many patterns disjunctively. Equivalent to folding in the monoid of either(Pattern, Pattern) and none().

    • some

      public static <A> Pattern<A> some(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3, Pattern<? super A> p4)
      Combines many patterns disjunctively. Equivalent to folding in the monoid of either(Pattern, Pattern) and none().

    • and

      public <B extends A> Pattern<B> and(Pattern<? super B> p)
      Combines this patterns conjunctively with another pattern. Calls both(this, p).

    • or

      public <B extends A> Pattern<B> or(Pattern<? super B> p)
      Combines this patterns disjunctively with another pattern. Calls either(this, p).

    • both

      public static final <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.

      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.

    • either

      public static final <A> Pattern<A> either(Pattern<? super A> p, Pattern<? super A> q)
      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.

      Parameters:
      p - an argument pattern
      q - 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.

    • noMatch

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

    • someMatch

      public Pattern<A> someMatch()

    • enPassant

      public <B extends A> Motif<B,B> enPassant()

    • newAll

      public static final <A> Pattern<A> newAll(Pattern<? super A>... ps)

    • flatten

      public static <A> Pattern<A> flatten(Pattern<A> p)

    • aside

      public static <A> Pattern<A> aside(Runnable r)

    • andThen

      public Pattern<A> andThen(Runnable r)

    • andThen

      public Pattern<A> andThen(Consumer<? super A> c)

    • orElse

      public Pattern<A> orElse(Runnable r)

    • orElse

      public Pattern<A> orElse(Consumer<? super A> c)

    • startCompile

      protected void startCompile(CompilationContext context)

    • compileThis

      protected VariableContext.Variable compileThis(CompilationContext context)

    • compileMatch

      protected void compileMatch(CompilationContext context)

    • compileMatchAgain

      protected void compileMatchAgain(CompilationContext context)

    • compileCut

      protected void compileCut(CompilationContext context)

    • compileCut

      protected void compileCut(CompilationContext context, boolean recursively)

    • compileClear

      protected void compileClear(CompilationContext context)

    • compileClear

      protected void compileClear(CompilationContext context, boolean recursively)

    • compileIsDeterministic

      protected void compileIsDeterministic(CompilationContext context)

    • compile

      public Pattern<A> compile()

    • compileUpTo

      public <B> Motif<B,A> compileUpTo(Variable<B> hole)

    • compileSubPattern

      protected VariableContext.Variable compileSubPattern(CompilationContext context)

    • main

      public static void main(String[] args)

    • DEBUG

      public void DEBUG(String msg)

    • of

      public static <A> Pattern<A> of(Predicate<? super A> pred)