Package eu.bandm.tools.paisley
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. Which variables are bound by a successful match is specific to the class and structure of the pattern.
The first successful match is retrieved using the Pattern.match(A) method. All subsequent matches on the
same object are retrieved using the Pattern.matchAgain() method. Any call to these methods
invalidates the variables bound by previous calls. Patterns may be reused
arbitrarily in a sequential manner, but are not reentrant: Behavior is
unspecified if usage times overlap, either concurrently or recursively.
An exhaustive use of a pattern with variables is commonly an instance of the following code template:
Extractor<A> va = Pattern.variable();
Extractor<B> vb = Pattern.variable();
Pattern<C> p = makePattern(va, vb);
C t = obtainTarget();
if (p.match(t)) do {
processMatch(va.getValue(), vb.getValue());
} while (p.matchAgain());
Retaining references to the variables in the pattern is essential for the
type safety of results. A pattern with variables is similar to a
multi-channel iterator: Pattern.match(A) plays the role of Iterator.hasNext(), and Variable.getValue() plays the role of
Iterator.next(), respectively, except that for patterns the
state transition occurs with the former.
The do–while loop can be omitted if only the first
match is of interest.
A pattern together with a single variable that it binds is essentially a
(nondeterministic) function. These are abstracted by the interface Motif.
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, even though the pattern itself remains live.
The implementations of pattern constructions in this package do not
tolerate null arguments; any attempt to construct a pattern where a
null reference is passed for a subpattern or other structurally necessary
part causes a NullPointerException. By contrast, whether
null is a valid target to match against depends on the particular semantics
of each pattern.
- See Also:
-
ClassDescriptionBase class for common patterns.Adaptive<A>Abstract base class for patterns that delegate to some other pattern, chosen dynamically per target.All<A>Base class of variadic pattern conjunction.Atomic<A>Abstract base class for patterns that contain no subpatterns.Binary<A,
B, C> Abstract base class for patterns that contain two subpatterns.Both<A>Base class of binary pattern conjunction.Backtracking variant of binary pattern conjunction.Non-backtracking variant of binary pattern conjunction.CachedTransform<A,B> Abstract base class for patterns that delegate expensively transformed targets to a subpattern.Indicates that a target can not be transformed.The functional interface for the methodCachedTransform.tryApply(A).Static factory methods for creating patterns for collections.Base class of deterministic patterns that do not examine the target object.Either<A>Binary pattern disjunction.EnumBranch<A,E extends Enum<E>> Enum-indexed disjunctive combination of patterns that tracks which branch has been chosen.EnumBranch.Builder<A,E extends Enum<E>> Incremental builder.Extractor<A>Base interface for all extractors.Filter<A>Abstract base class for patterns that match only a subset of the target type.FlatMultiTransform<A,B> Abstract base class for patterns that delegate several transformation results for a target to a subpattern.Static factory methods for creating patterns for functions.IntBranch<A>Indexed disjunctive combination of patterns that tracks which branch has been chosen.Incremental builder.Lazy<A>Wrapper class for a pattern that is to be created lazily on demand.Motif<A,B> Functional interface for pattern templates with a hole.MultiTransform<A,B> Abstract base class for patterns that delegate several transformation results for a target to a subpattern.Pattern<A>Base interface of all patterns.Static factory methods for creating patterns for primitive types and basic objects.Proxy<A>Base class for patterns that contain one subpattern of the same target type.Static factory methods for creating patterns for runtime type information.A function that extracts data from a target object by reflection.RestrictedTransform<A,B> Abstract base class for patterns that either delegate transformed targets to a subpattern or fail immediately.Search<A>Abstract base class for patterns that delegate matching dynamically to a number of alternative subpatterns.Static factory methods for creating patterns for strings and regular expressions.Theme<A,B> Pattern with a distinguished argument variable.TotalTransform<A,B> Abstract base class for patterns that delegate transformed targets to a subpattern.Transform<A,B> Abstract base class for patterns that delegate transformed targets to a subpattern.Unary<A,B> Abstract base class for patterns that contain one subpattern.Variable<A>Class of pattern variables.