Package eu.bandm.tools.paisley

Interface Motif<A,B>

Type Parameters:
A - the subtarget type of objects to match the hole against
B - the target type of objects to match the entire pattern against
All Superinterfaces:
Function<Pattern<? super A>,Pattern<B>>, Serializable
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="2025-12-18T16:24:36") @FunctionalInterface public interface Motif<A,B> extends Function<Pattern<? super A>,Pattern<B>>, Serializable
Functional interface for pattern templates with a hole.

A motif is a function object that can be applied to a subpattern p, resulting in a pattern where the hole is filled with p. In contrast to an arbitrary function on patterns, a motif should implement a pattern template: Any pattern structure it creates when applied to a subpattern p should not depend on observable properties of p; the subpattern should be passed around, and possibly incorporated one or more times, as a completely opaque reference.

Note that holes are characterized semantically, in that they can be filled by applying the motif. Syntactically, a hole is not necessarily a single reference in an object graph: The hole of a motif can be referred to by zero, one or several fields of other pattern objects.

Patterns are contravariant: A function on patterns on target type A to patterns on target type B corresponds to a nondeterministic function from B to A.

  • Method Summary

    Modifier and Type
    Method
    Description
    default <C> Motif<A,C>
    andThen(Motif<? extends B,C> after)
    Returns a composed motif that first applies this motif to its input pattern, and then applies a given motif to the result.
    Pattern<B>
    apply(Pattern<? super A> subpattern)
    Wrap the given subpattern in a template.
    default boolean
    attempt(B target, Consumer<? super A> consumer)
    Match this pattern once against a target, with the hole occupied by a given consumer.
    static <A, B> Motif<A,B>
    both(Motif<? extends A,? super B> left, Motif<? extends A,? super B> right)
    Combine two motifs conjunctively with a shared hole.
    default <C> Motif<C,B>
    compose(Motif<C,? super A> before)
    Returns a composed motif that first applies a given motif to its input pattern, and then applies this motif to the result.
    static <A, B> Motif<A,B>
    constant(Pattern<? super B> pattern)
    Returns a constant motif where the hole is never used.
    default List<A>
    eagerBindings(B target)
    Finds all values corresponding to the hole of this motif by the matches for a given target.
    static <A, B> Motif<A,B>
    either(Motif<? extends A,? super B> left, Motif<? extends A,? super B> right)
    Combine two motifs disjunctively with a shared hole.
    default Motif<A,B>
    etaExpand()
    Creates an eta-expanded variant of this motif.
    default void
    exhaust(B target, Consumer<? super A> consumer)
    Match this pattern exhaustively against a target, with the hole occupied by a given consumer.
    static <A> Motif<A,A>
    identity()
    Returns an identity motif.
    default Iterable<A>
    lazyBindings(B target)
    Finds all values corresponding to the hole of this motif by the matches for a given target.
    static <A, B> Motif<A,B>
    multiTransform(Function<? super B,? extends Iterable<A>> fun)
    Returns a motif that transforms the target with the given multi-valued function and then passes the results to the hole.
    default <C> Motif<C,B>
    on(Motif<C,? super A> before)
    Deprecated.
    Use compose(eu.bandm.tools.paisley.Motif<C, ? super A>) instead.
    static <A> Motif<A,A>
    plus(Motif<A,A> step)
    Returns a motif that is equivalent to one or more iterations of the given step motif.
    static <A> Motif<A,A>
    star(Motif<A,A> step)
    Returns a motif that is equivalent to zero or more iterations of the given step motif.
    default Stream<A>
    stream(B target)
     
    default <C> Motif<A,C>
    then(Motif<? extends B,C> after)
    Deprecated.
    Use andThen(eu.bandm.tools.paisley.Motif<? extends B, C>) instead.
    static <A, B> Motif<A,B>
    transform(Function<? super B,? extends A> fun)
    Returns a motif that transforms the target with the given function and then passes the result to the hole.
    default Theme<A,B>
    unlambda()
    Returns a pattern where the hole has been filled with a fresh variable.

    Methods inherited from interface java.util.function.Function

    andThen, compose

  • Method Details

    • apply

      Pattern<B> apply(Pattern<? super A> subpattern)
      Wrap the given subpattern in a template.

      The shape of the returned pattern should not depend on observable properties of the given subpattern: The result should be a fixed pattern-with-a-hole template, where the hole is filled with the given subpattern.

      Unless specified explicitly otherwise, implementations of this interface are not expected to tolerate null references, but rather throw an exception for early detection of caller errors.

      Specified by:
      apply in interface Function<A,B>
      Parameters:
      subpattern - the pattern to fill the hole with
      Returns:
      a pattern where the hole has been filled with subpattern
      Throws:
      NullPointerException - if subpattern is null

    • star

      static <A> Motif<A,A> star(Motif<A,A> step)
      Returns a motif that is equivalent to zero or more iterations of the given step motif.
      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      step - a step motif to be iterated
      Returns:
      a motif that is equivalent to the infinite disjunction of identity(), step, root.compose(root), root.compose(root).compose(root), etc.
      Throws:
      NullPointerException - if step is null
      See Also:

    • plus

      static <A> Motif<A,A> plus(Motif<A,A> step)
      Returns a motif that is equivalent to one or more iterations of the given step motif.
      Type Parameters:
      A - the target type of objects to match against
      Parameters:
      step - a step motif to be iterated
      Returns:
      a motif that is equivalent to the infinite disjunction of step, root.compose(root), root.compose(root).compose(root), etc.
      Throws:
      NullPointerException - if step is null
      See Also:

    • identity

      static <A> Motif<A,A> identity()
      Returns an identity motif. Such a motif consists only of a hole: When applied to a subpattern p, it returns p.

      The returned motif is hardly useful by itself, but rather as a building block in motif algebra.

      Type Parameters:
      A - the target type of objects to match against
      Returns:
      a motif that consists only of a hole

    • constant

      static <A, B> Motif<A,B> constant(Pattern<? super B> pattern)
      Returns a constant motif where the hole is never used.
      Type Parameters:
      A - the subtarget type of objects to match the hole against
      B - the target type of objects to match the entire pattern against
      Parameters:
      pattern - the constant pattern
      Returns:
      a constant motif that always returns pattern when applied
      Throws:
      NullPointerException - if pattern is null

    • transform

      static <A, B> Motif<A,B> transform(Function<? super B,? extends A> fun)
      Returns a motif that transforms the target with the given function and then passes the result to the hole.
      Type Parameters:
      A - the subtarget type of objects to match the hole against
      B - the target type of objects to match the entire pattern against
      Parameters:
      fun - the function to transform targets with
      Returns:
      a motif that transforms the target with fun and then passes the result to the hole
      Throws:
      NullPointerException - if fun is null
      See Also:

    • multiTransform

      static <A, B> Motif<A,B> multiTransform(Function<? super B,? extends Iterable<A>> fun)
      Returns a motif that transforms the target with the given multi-valued function and then passes the results to the hole.
      Type Parameters:
      A - the subtarget type of objects to match the hole against
      B - the target type of objects to match the entire pattern against
      Parameters:
      fun - the function to transform targets with
      Returns:
      a motif that transforms the target with fun and then passes the results to the hole, combining matches disjunctively
      Throws:
      NullPointerException - if fun is null
      See Also:

    • either

      static <A, B> Motif<A,B> either(Motif<? extends A,? super B> left, Motif<? extends A,? super B> right)
      Combine two motifs disjunctively with a shared hole.
      Type Parameters:
      A - the subtarget type of objects to match the hole against
      B - the target type of objects to match the entire pattern against
      Parameters:
      left - an argument motif
      right - another argument motif
      Returns:
      a motif that fills the holes of left and right with the same subpattern, and combines the resulting patterns disjunctively
      Throws:
      NullPointerException - if left or right is null
      See Also:

    • both

      static <A, B> Motif<A,B> both(Motif<? extends A,? super B> left, Motif<? extends A,? super B> right)
      Combine two motifs conjunctively with a shared hole.
      Type Parameters:
      A - the subtarget type of objects to match the hole against
      B - the target type of objects to match the entire pattern against
      Parameters:
      left - an argument motif
      right - another argument motif
      Returns:
      a motif that fills the holes of left and right with the same subpattern, and combines the resulting patterns conjunctively
      Throws:
      NullPointerException - if left or right is null
      See Also:

    • on

      @Deprecated(forRemoval=false, since="1.0") default <C> Motif<C,B> on(Motif<C,? super A> before)
      Deprecated.
      Use compose(eu.bandm.tools.paisley.Motif<C, ? super A>) instead.
      Returns a composed motif that first applies a given motif to its input pattern, and then applies this motif to the result.
      Type Parameters:
      C - the subtarget type of objects to match the hole of the combined motif against
      Parameters:
      before - the motif to wrap a given subpattern with before filling the hole of this motif with the result
      Returns:
      a composed motif that first applies before to its input pattern, and then applies this to the result
      See Also:

    • compose

      default <C> Motif<C,B> compose(Motif<C,? super A> before)
      Returns a composed motif that first applies a given motif to its input pattern, and then applies this motif to the result.
      Type Parameters:
      C - the subtarget type of objects to match the hole of the combined motif against
      Parameters:
      before - the motif to wrap a given subpattern with before filling the hole of this motif with the result
      Returns:
      a composed motif that first applies before to its input pattern, and then applies this to the result
      See Also:

    • then

      @Deprecated(forRemoval=false, since="1.0") default <C> Motif<A,C> then(Motif<? extends B,C> after)
      Deprecated.
      Use andThen(eu.bandm.tools.paisley.Motif<? extends B, C>) instead.
      Returns a composed motif that first applies this motif to its input pattern, and then applies a given motif to the result.
      Type Parameters:
      C - the target type of objects to match the combined motif against
      Parameters:
      after - the motif to wrap the result of filling the hole of this motif with a given subpattern
      Returns:
      a composed motif that first applies this to its input pattern, and then applies after to the result
      See Also:

    • andThen

      default <C> Motif<A,C> andThen(Motif<? extends B,C> after)
      Returns a composed motif that first applies this motif to its input pattern, and then applies a given motif to the result.
      Type Parameters:
      C - the target type of objects to match the combined motif against
      Parameters:
      after - the motif to wrap the result of filling the hole of this motif with a given subpattern
      Returns:
      a composed motif that first applies this to its input pattern, and then applies after to the result
      See Also:

    • lazyBindings

      default Iterable<A> lazyBindings(B target)
      Finds all values corresponding to the hole of this motif by the matches for a given target.

      In contrast to eagerBindings(B), the alternative successful matches are effected lazily on demand.

      Parameters:
      target - the object to match against
      Returns:
      the values bound by this extractor on all successive matching attempts of root against target, in order.
      See Also:

    • eagerBindings

      default List<A> eagerBindings(B target)
      Finds all values corresponding to the hole of this motif by the matches for a given target.

      In contrast to lazyBindings(B), the alternative successful matches are are exhausted before this method returns.

      Parameters:
      target - the object to match against
      Returns:
      the values bound by this extractor on all successive matching attempts of root against target, in order.
      See Also:

    • stream

      default Stream<A> stream(B target)

    • unlambda

      default Theme<A,B> unlambda()
      Returns a pattern where the hole has been filled with a fresh variable.

      The variable can be retrieved from the result with Theme.getArgument().

      Returns:
      a pattern where the hole has been filled with a fresh variable

    • attempt

      default boolean attempt(B target, Consumer<? super A> consumer)
      Match this pattern once against a target, with the hole occupied by a given consumer.

      At most one match is performed; nondeterministic extra matches are ignored. For multiple matches, use exhaust(B, java.util.function.Consumer<? super A>) instead.

      If a match is successful up to the hole, then the subobject to match the hole against is passed to consumer.

      Parameters:
      target - the target object to match against
      consumer - a consumer for the extracted subobject to match the hole against
      Returns:
      true if a match has been successful; false otherwise
      Throws:
      NullPointerException - if consumer is null
      See Also:

    • exhaust

      default void exhaust(B target, Consumer<? super A> consumer)
      Match this pattern exhaustively against a target, with the hole occupied by a given consumer.

      Matching is iterated until failure. For a single match, use attempt(B, java.util.function.Consumer<? super A>) instead.

      If a match is successful up to the hole, then the subobject to match the hole against is passed to consumer.

      Parameters:
      target - the target object to match against
      consumer - a consumer for each extracted subobject to match the hole against
      Throws:
      NullPointerException - if consumer is null
      See Also:

    • etaExpand

      default Motif<A,B> etaExpand()
      Creates an eta-expanded variant of this motif.

      The returned motif has the same observable behavior as this motif, but creates patterns with a particular structure: The original hole is filled with a fresh variable, and a new hole is made that consumes the lazy bindings of that variable.

      The resulting form can improve efficiency if a motif is reused many times and/or compiled: The hole in an eta-expanded motif occurs exactly once right at the top; the rest of the template is unchanged and can be shared.

      Returns:
      an eta-expanded variant of this motif
      See Also: