Pattern (BandM metatools API doc)

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:

Serialized Form

Constructor Summary

Constructors
Modifier Constructor and Description

protected Pattern()
Creates a new pattern.

Constructors
Modifier	Constructor and Description
`protected`	`Pattern()` Creates a new pattern.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`static <A> Pattern<A>`	`all(Iterable<? extends Pattern<? super A>> p)`
`static <A> Pattern<A>`	`all(Pattern<? super A>... p)` Combines many patterns conjunctively.
`static <A> Pattern<A>`	`all(Pattern<? super A> p1, Pattern<? super A> p2)` Combines many patterns conjunctively.
`static <A> Pattern<A>`	`all(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3)` Combines many patterns conjunctively.
`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.
`<B extends A> Pattern<B>`	`and(Pattern<? super B> p)` Combines this patterns conjunctively with another pattern.
`Pattern<A>`	`andThen(Consumer<? super A> c)`
`Pattern<A>`	`andThen(Runnable r)`
`static <A> Pattern<A>`	`any()` Returns a pattern that matches anything.
`static <A> Pattern<A>`	`any(Pattern<? super A>... p)` Deprecated. Name conflicts with `any()`, use `some(Pattern...)` instead.
`static <A> Pattern<A>`	`aside(Runnable r)`
`boolean`	`binds(Variable<?> var)` 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.
`void`	`clear()` Disposes of all internal state related to results and nondeterminism.
`void`	`clear(boolean recursively)` Disposes of all internal state related to results and nondeterminism.
`Pattern<A>`	`clone()` Makes a matching-state copy if this pattern.
`static <A extends Comparable<? super A>> Pattern<A>`	`compareTo(A other, Pattern<? super Integer> body)` Deprecated. Use the method `PrimitivePatterns.compareTo(Comparable, Pattern)` instead.
`Pattern<A>`	`compile()`
`protected void`	`compileClear(eu.bandm.tools.paisley.CompilationContext context)`
`protected void`	`compileClear(eu.bandm.tools.paisley.CompilationContext context, boolean recursively)`
`protected void`	`compileCut(eu.bandm.tools.paisley.CompilationContext context)`
`protected void`	`compileCut(eu.bandm.tools.paisley.CompilationContext context, boolean recursively)`
`protected void`	`compileIsDeterministic(eu.bandm.tools.paisley.CompilationContext context)`
`protected void`	`compileMatch(eu.bandm.tools.paisley.CompilationContext context)`
`protected void`	`compileMatchAgain(eu.bandm.tools.paisley.CompilationContext context)`
`protected eu.bandm.tools.lljava.live.VariableContext.Variable`	`compileSubPattern(eu.bandm.tools.paisley.CompilationContext context)`
`protected eu.bandm.tools.lljava.live.VariableContext.Variable`	`compileThis(eu.bandm.tools.paisley.CompilationContext context)`
`<B> Motif<B,A>`	`compileUpTo(Variable<B> hole)`
`void`	`cut()` Disposes of all internal state related to nondeterminism.
`void`	`cut(boolean recursively)` Disposes of all internal state related to nondeterminism.
`void`	`DEBUG(String msg)`
`static <A> Pattern<A>`	`either(Pattern<? super A> p, Pattern<? super A> q)` Combines two patterns disjunctively.
`<B extends A> Motif<B,B>`	`enPassant()`
`static <A> Pattern<A>`	`eq(A a)` Deprecated. Use the method `PrimitivePatterns.eq(A)` instead.
`static <A> Pattern<A>`	`eqNull()` Deprecated. Use the method `PrimitivePatterns.eqNull()` instead.
`static <A> Pattern<A>`	`equal(A a)` Deprecated. Use the method `PrimitivePatterns.equal(A)` instead.
`Pattern<A>`	`filter(Predicate<? super A> pred)` Deprecated. Use the method `FunctionPatterns.filter(java.util.function.Predicate, Pattern)` instead.
`static <A> Pattern<A>`	`flatten(Pattern<A> p)`
`Pattern<Object>`	`forInstancesOf(Class<? extends A> cls)` Deprecated. Use the method `ReflectionPatterns.forInstancesOf(Class, Pattern)` instead.
`boolean`	`isDeterministic()` Checks whether this pattern is deterministic.
`Pattern<A>`	`limit(int n)` Returns a pattern that stops after a given number of matches.
`static void`	`main(String[] args)`
`abstract boolean`	`match(A target)` Attempts to match this pattern against a given object.
`boolean`	`matchAgain()` Attempts to re-match this pattern against a previously matched object.
`boolean`	`matchOnce(A target)` Attempts to match this pattern at most once against a given object.
`boolean`	`matchVar(Extractor<? extends A> var)`
`<B extends A> Pattern<B>`	`narrow()` Returns an equivalent pattern with narrower type parameter.
`static <A> Pattern<A>`	`neq(A a)` Deprecated. Use the method `PrimitivePatterns.neq(A)` instead.
`static <A> Pattern<A>`	`neqNull()` Deprecated. Use the method `PrimitivePatterns.neqNull()` instead.
`static <A> Pattern<A>`	`newAll(Pattern<? super A>... ps)`
`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.
`<B extends A> Pattern<B>`	`or(Pattern<? super B> p)` Combines this patterns disjunctively with another pattern.
`Pattern<A>`	`orElse(Consumer<? super A> c)`
`Pattern<A>`	`orElse(Runnable r)`
`boolean`	`preserves(Variable<?> var)` Checks whether a variable is preserved by this pattern, unconditionally.
`boolean`	`preserves(Variable<?> var, boolean success)` Checks whether a variable is preserved by this pattern, conditionally on success or failure.
`static <A> Pattern<A>`	`repeat()`
`static <A> Pattern<A>`	`some(Pattern<? super A>... p)` Combines many patterns disjunctively.
`static <A> Pattern<A>`	`some(Pattern<? super A> p1, Pattern<? super A> p2)` Combines many patterns disjunctively.
`static <A> Pattern<A>`	`some(Pattern<? super A> p1, Pattern<? super A> p2, Pattern<? super A> p3)` Combines many patterns disjunctively.
`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.
`Pattern<A>`	`someMatch()`
`protected void`	`startCompile(eu.bandm.tools.paisley.CompilationContext context)`
`static <A> Pattern<A>`	`test(Predicate<? super A> pred)` Deprecated. Use the method `FunctionPatterns.test(java.util.function.Predicate)` instead.
`<B> Pattern<B>`	`transform(Function<? super B,? extends A> fun)` Deprecated. Use the method `FunctionPatterns.transform(java.util.function.Function, Pattern)` instead.
`Pattern<A>`	`uniquely()` Returns a pattern that matches if and only if this pattern has a unique match.
`static <A> Variable<A>`	`variable()` Creates a new anonymous pattern variable.
`static <A> Variable<A>`	`variable(String name)` Creates a new named pattern variable.

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
 - Pattern
```
protected Pattern()
```
 Creates a new pattern.
- Method Detail
 - 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:
 
 binds(Variable), preserves(Variable, boolean)
 - 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:
 
 binds(Variable), preserves(Variable, boolean)
 - matchVar
```
public boolean matchVar(Extractor<? extends A> var)
```
 - 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<?> var)
```
 Checks whether a variable is bound by this pattern.
 The default implementation returns false.
 
 Parameters:
 
 var - 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<?> var,
 boolean success)
```
 Checks whether a variable is preserved by this pattern, conditionally on success or failure.
 The default implementation returns false.
 
 Parameters:
 
 var - 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<?> var)
```
 Checks whether a variable is preserved by this pattern, unconditionally.
 The default implementation returns false.
 
 Parameters:
 
 var - 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:
 
 matchAgain()
 - narrow
```
public  Pattern 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, 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.
 - 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()
```
 - equal
```
@Deprecated
public static <A> Pattern<A> equal(A a)
```
 Deprecated. Use the method PrimitivePatterns.equal(A) instead.
 
 Returns a pattern that matches objects equal to a given reference. Equality is determined by Object.equals(java.lang.Object) if an object is given, or by == if null is given instead.
 A pattern returned by this method is deterministic and binds no variables.
 
 Parameters:
 
 a - an object to compare with or null.
 - eq
```
@Deprecated
public static <A> Pattern<A> eq(A a)
```
 Deprecated. Use the method PrimitivePatterns.eq(A) instead.
 
 Returns a pattern that matches objects identically equal to a given reference. Equality is determined by ==.
 A pattern returned by this method is deterministic and binds no variables.
 
 Parameters:
 
 a - an object to compare with or null.
 - neq
```
@Deprecated
public static <A> Pattern<A> neq(A a)
```
 Deprecated. Use the method PrimitivePatterns.neq(A) instead.
 
 Returns a pattern that matches objects not identically equal to a given reference. Equality is determined by !=.
 A pattern returned by this method is deterministic and binds no variables.
 
 Parameters:
 
 a - an object to compare with or null.
 - compareTo
```
@Deprecated
public static <A extends Comparable<? super A>> Pattern<A> compareTo(A other,
 Pattern<? super Integer> body)
```
 Deprecated. Use the method PrimitivePatterns.compareTo(Comparable, Pattern) instead.
 
 Returns a pattern that matches objects based on comparison with a given object. Matching succeeds if and only if the result of comparing the target object via Comparable.compareTo to a given object matches a given int patterns.
 A pattern returned by this method inherits determinism and variable bindings from the given pattern.
 
 Parameters:
 
 other - an object to compare with or null.
 
 body - a pattern to match the comparison result.
 - eqNull
```
@Deprecated
public static <A> Pattern<A> eqNull()
```
 Deprecated. Use the method PrimitivePatterns.eqNull() instead.
 
 Return a pattern that matches only the null reference.
 A pattern returned by this method is deterministic and binds no variables.
 - neqNull
```
@Deprecated
public static <A> Pattern<A> neqNull()
```
 Deprecated. Use the method PrimitivePatterns.neqNull() instead.
 
 Return a pattern that matches anything but the null reference.
 A pattern returned by this method is deterministic and binds no variables.
 - 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().
 - any
```
@Deprecated
public static <A> Pattern<A> any(Pattern<? super A>... p)
```
 Deprecated. Name conflicts with any(), use some(Pattern...) instead.
 
 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>... 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  Pattern and(Pattern<? super B> p)
```
 Combines this patterns conjunctively with another pattern. Calls both(this, p).
 - or
```
public  Pattern 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.
 - transform
```
@Deprecated
public  Pattern transform(Function<? super B,? extends A> fun)
```
 Deprecated. Use the method FunctionPatterns.transform(java.util.function.Function, Pattern) instead.
 - filter
```
@Deprecated
public Pattern<A> filter(Predicate<? super A> pred)
```
 Deprecated. Use the method FunctionPatterns.filter(java.util.function.Predicate, Pattern) instead.
 - test
```
@Deprecated
public static <A> Pattern<A> test(Predicate<? super A> pred)
```
 Deprecated. Use the method FunctionPatterns.test(java.util.function.Predicate) instead.
 - forInstancesOf
```
@Deprecated
public Pattern<Object> forInstancesOf(Class<? extends A> cls)
```
 Deprecated. Use the method ReflectionPatterns.forInstancesOf(Class, Pattern) instead.
 
 Returns a pattern that delegates to this pattern after dynamic type checking.
 
 Parameters:
 
 cls - the class to be checked against.
 
 Returns:
 
 a pattern that matches whatever this pattern matches, but only if the target object is an instance of cls, determined by invoking Class.isInstance(java.lang.Object).
 - 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  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(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileThis
```
protected eu.bandm.tools.lljava.live.VariableContext.Variable compileThis(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileMatch
```
protected void compileMatch(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileMatchAgain
```
protected void compileMatchAgain(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileCut
```
protected void compileCut(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileCut
```
protected void compileCut(eu.bandm.tools.paisley.CompilationContext context,
 boolean recursively)
```
 - compileClear
```
protected void compileClear(eu.bandm.tools.paisley.CompilationContext context)
```
 - compileClear
```
protected void compileClear(eu.bandm.tools.paisley.CompilationContext context,
 boolean recursively)
```
 - compileIsDeterministic
```
protected void compileIsDeterministic(eu.bandm.tools.paisley.CompilationContext context)
```
 - compile
```
public Pattern<A> compile()
```
 - compileUpTo
```
public  Motif<B,A> compileUpTo(Variable hole)
```
 - compileSubPattern
```
protected eu.bandm.tools.lljava.live.VariableContext.Variable compileSubPattern(eu.bandm.tools.paisley.CompilationContext context)
```
 - main
```
public static void main(String[] args)
```
 - DEBUG
```
public void DEBUG(String msg)
```

Class Pattern<A>

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Pattern

Method Detail

match

matchAgain

matchVar

cut

clear

cut

clear

matchOnce

binds

preserves

preserves

isDeterministic

narrow

clone

variable

variable

uniquely

limit

any

none

repeat

equal

eq

neq

compareTo

eqNull

neqNull

all

all

all

all

all

any

some

some

some

some

and

or

both

either

transform

filter

test

forInstancesOf

noMatch

someMatch

enPassant

newAll

flatten

aside

andThen

andThen

orElse

orElse

startCompile

compileThis

compileMatch

compileMatchAgain

compileCut

compileCut

compileClear

compileClear

compileIsDeterministic

compile

compileUpTo

compileSubPattern

main

DEBUG