Pattern (BandM metatools API doc)

java.lang.Object
- eu.bandm.tools.ops.Pattern<A>

Direct Known Subclasses:

Pattern.Contravariant, Pattern.Variable
```
public abstract class Pattern<A>
extends Object
```
A modular implementation of pattern matching on arbitrary objects.
A pattern can be matched against a given object, resulting in zero or more successful matches. As a side effect of a successful match, pattern variables may be bound. They retain their bound values until the next matching attempt. The value of variables is unspecified before a match has been attempted, and after a failed attempt. Which variables are bound by a successful match is specific to the class of the pattern.
The first successful match is retrieved using the method. All subsequent matches on the same object are retrieved using the matchAgain() method. Any call to these methods invalidates the variables bound by previous calls. Patterns may be reused arbitrarily. Behaviour is unspecified if usage times overlap, either concurrently or recursively.
A class of patterns that yield multiple successful matches for an object may either guarantee a certain order in which the matches are produced, or leave the order unspecified. A pattern class is ordered if such an order exists for all matched objects, otherwise unordered.
A class of patterns may also guarantee that there is at most one successful match for any object. A pattern class is deterministic if there is at most one match, otherwise nondeterministic. Nondeterministic patterns typically require internal memory to keep track of subsequent matches. That memory can be discarded explicitly, forfeiting remaining matches for the same object, and potentially allowing some heap space to be reclaimed.
A pattern is always in one of three states:
- inactive – initially and after a failed matching attempt,
- open – after a successful matching attempt
- closed – after internal memory has been explicitly discarded
The state is purely conceptual, and need not be stored or checked by a pattern implementation.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`Pattern.Atomic<A>`
`static class`	`Pattern.Binary<A,B,C>`
`static class`	`Pattern.Contravariant<A>`
`class`	`Pattern.Proxy`
`static class`	`Pattern.Transform<A,B>`
`static class`	`Pattern.Unary<A,B>`
`static class`	`Pattern.Variable<A>` Pattern variable.

Field Summary

Fields
Modifier and Type Field and Description

static Pattern.Contravariant<Object> any

static Pattern.Contravariant<Object> none

static Pattern.Contravariant<Object> p_null

Fields
Modifier and Type	Field and Description
`static Pattern.Contravariant<Object>`	`any`
`static Pattern.Contravariant<Object>`	`none`
`static Pattern.Contravariant<Object>`	`p_null`

Constructor Summary

Constructors
Modifier Constructor and Description

protected Pattern()
Base constructor with no toString representation.

Constructors
Modifier	Constructor and Description
`protected`	`Pattern()` Base constructor with no `toString` representation.

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`Pattern.Contravariant<A>`	`and(Pattern<A> p)`
`static <A> Pattern.Contravariant<A>`	`any()` Return a pattern that matches anything.
`abstract boolean`	`bindsVariable(Pattern.Variable x)`
`static <A> Pattern.Contravariant<A>`	`both(Pattern<? super A> p, Pattern<? super A> q)` Combine two patterns conjunctively.
`void`	`clear(boolean recursively)`
`void`	`cut(boolean recursively)`
`abstract boolean`	`disturbsVariable(Pattern.Variable x)`
`static <A> Pattern.Contravariant<A>`	`either(Pattern<? super A> p, Pattern<? super A> q)` Combine two patterns disjunctively.
`static <A> Pattern.Contravariant<A>`	`eq(A a)` Return a pattern that matches objects equal to a given reference.
`static <A> Pattern<Iterable<? extends A>>`	`first(Pattern<? super A> elem)`
`Pattern<Object>`	`forInstancesOf(Class<? extends A> cls)`
`abstract boolean`	`isDeterministic()`
`Pattern<A>`	`limit(int n)`
`abstract boolean`	`match(A x)` Attempt to match this pattern against a given object.
`boolean`	`matchAgain()` Attempt to re-match this pattern against a previously matched object.
`boolean`	`matchOnce(A x)`
`static <A> Pattern.Contravariant<A>`	`none()` Return a pattern that matches nothing.
`Pattern.Contravariant<A>`	`or(Pattern<A> p)`
`static <A> Pattern.Contravariant<A>`	`p_null()` Return a pattern that matches only the `null` reference.
`abstract boolean`	`savesVariable(Pattern.Variable x)`
`Pattern<Iterable<? extends A>>`	`somewhere()` Return a pattern that attempts to match this pattern successively to all elements of an `Iterable`.
`<B> Pattern<B>`	`transform(Function<? super B,? extends A> fun)`
`Pattern<A>`	`uniquely()` Returns a pattern that matches if and only if this pattern has a unique match.
`static <A> Pattern.Variable<A>`	`variable()` Creates a new anonymous pattern variable.
`static <A> Pattern.Variable<A>`	`variable(String name)` Creates a new named pattern variable.

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

- Field Detail
  - any
```
public static final Pattern.Contravariant<Object> any
```
  - none
```
public static final Pattern.Contravariant<Object> none
```
  - p_null
```
public static final Pattern.Contravariant<Object> p_null
```
- Constructor Detail
  - Pattern
```
protected Pattern()
```
    Base constructor with no toString representation. Creates an inactive pattern.
- Method Detail
  - match
```
public abstract boolean match(A x)
```
    Attempt 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 pattern is activated on success, but deactivated on failure.
  - matchAgain
```
public boolean matchAgain()
```
    Attempt 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 pattern is activated on success, but deactivated on failure. The behaviour of this method is unspecified if the pattern is currently deactivated.
    Patterns classes that do not overwrite this method guarantee
  - cut
```
public void cut(boolean recursively)
```
  - clear
```
public void clear(boolean recursively)
```
  - matchOnce
```
public boolean matchOnce(A x)
```
  - bindsVariable
```
public abstract boolean bindsVariable(Pattern.Variable x)
```
  - disturbsVariable
```
public abstract boolean disturbsVariable(Pattern.Variable x)
```
  - savesVariable
```
public abstract boolean savesVariable(Pattern.Variable x)
```
  - isDeterministic
```
public abstract boolean isDeterministic()
```
  - variable
```
public static <A> Pattern.Variable<A> variable()
```
    Creates a new anonymous pattern variable.
  - variable
```
public static <A> Pattern.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.
    A patterns of this class is deterministic.
  - limit
```
public final Pattern<A> limit(int n)
```
  - any
```
public static final <A> Pattern.Contravariant<A> any()
```
    Return a pattern that matches anything. A pattern returned by this method is deterministic and binds no variables.
  - none
```
public static final <A> Pattern.Contravariant<A> none()
```
    Return a pattern that matches nothing.
    A pattern returned by this method is vacuously deterministic and binds all variables.
  - eq
```
public static <A> Pattern.Contravariant<A> eq(A a)
```
    Return 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 bings no variables.
    
    Parameters:
    
    a - an object to compare with or null.
  - p_null
```
public static <A> Pattern.Contravariant<A> p_null()
```
    Return a pattern that matches only the null reference.
    A pattern returned by this method is deterministic and binds no variables.
  - and
```
public Pattern.Contravariant<A> and(Pattern<A> p)
```
  - or
```
public Pattern.Contravariant<A> or(Pattern<A> p)
```
  - both
```
public static final <A> Pattern.Contravariant<A> both(Pattern<? super A> p,
                                                      Pattern<? super A> q)
```
    Combine 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:
    
    p - an argument pattern
    
    q - 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.Contravariant<A> either(Pattern<? super A> p,
                                                        Pattern<? super A> q)
```
    Combine 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.
  - first
```
public static <A> Pattern<Iterable<? extends A>> first(Pattern<? super A> elem)
```
  - somewhere
```
public Pattern<Iterable<? extends A>> somewhere()
```
    Return a pattern that attempts to match this pattern successively to all elements of an Iterable.
    A pattern returned by this method is generally nondeterministic. It is ordered if the underlying pattern is ordered. It binds all variables bound by the underlying pattern.
    
    Returns:
    
    a pattern that
  - transform
```
public <B> Pattern<B> transform(Function<? super B,? extends A> fun)
```
  - forInstancesOf
```
public Pattern<Object> forInstancesOf(Class<? extends A> cls)
```

Class Pattern<A>

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

any

none

p_null

Constructor Detail

Pattern

Method Detail

match

matchAgain

cut

clear

matchOnce

bindsVariable

disturbsVariable

savesVariable

isDeterministic

variable

variable

uniquely

limit

any

none

eq

p_null

and

or

both

either

first

somewhere

transform

forInstancesOf