com.github.fge.grappa.matchers.join

Class JoinMatcherBuilder

java.lang.Object

com.github.fge.grappa.matchers.join.JoinMatcherBuilder

@ParametersAreNonnullByDefault
@Beta
public final class JoinMatcherBuilder
extends Object

The final step to building a JoinMatcher

At this step of the build, we have both rules (the "joined" rule and the "joining" rule). The final information to feed to the matcher is the number of cycles.

The number of cycles can be bounded on the lower end and on the upper end. The "true" building method is range(Range); all other methods ultimately call this one to generate the result.

The real matcher generated depends on the number of cycles required (for the notation used here, see the javadoc for Range):

• [0..0]: an EmptyMatcher;
• [0..1]: an OptionalMatcher with the joined rule as a submatcher;
• [1..1]: the "joined" rule itself;
• [n..+∞) for whatever n: a BoundedDownJoinMatcher;
• [0..n] for n >= 2: a BoundedUpJoinMatcher;
• [n..n] for n >= 2: an ExactMatchesJoinMatcher;
• [n..m]: a BoundedBothJoinMatcher.

See Also:

JoinMatcher, Range

Method Summary

Methods

Modifier and Type	Method and Description
Rule	max(int nrCycles) Return a rule with a maximum number of cycles to run
Rule	min(int nrCycles) Return a rule with a minimum number of cycles to run
Rule	range(Range<Integer> range) Generic method to build a JoinMatcher
Rule	times(int nrCycles) Return a rule with an exact number of cycles to run
Rule	times(int minCycles, int maxCycles) Return a rule with both lower and upper bounds on the number of cycles

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

min

public Rule min(int nrCycles)

Return a rule with a minimum number of cycles to run

Parameters:

nrCycles - the number of cycles

Returns:

a rule

Throws:

IllegalArgumentException - nrCycles is less than 0

See Also:

Range.atLeast(Comparable)

max

public Rule max(int nrCycles)

Return a rule with a maximum number of cycles to run

Parameters:

nrCycles - the number of cycles

Returns:

a rule

Throws:

IllegalArgumentException - nrCycles is less than 0

See Also:

Range.atMost(Comparable)

times

public Rule times(int nrCycles)

Return a rule with an exact number of cycles to run

Parameters:

nrCycles - the number of cycles

Returns:

a rule

Throws:

IllegalArgumentException - nrCycles is less than 0

See Also:

Range.singleton(Comparable)

times

public Rule times(int minCycles,
         int maxCycles)

Return a rule with both lower and upper bounds on the number of cycles

Note that the range of cycles to run is closed on both ends (that is, the minimum and maximum number of cycles are inclusive).

Note also that the rule will not fail if there are more than the maximum number of cycles; it will simply stop matching if this number of cycles is reached.

Parameters:

minCycles - the minimum number of cycles

maxCycles - the maximum number of cycles

Returns:

a rule

Throws:

IllegalArgumentException - minimum number of cycles is negative; or maximum number of cycles is less than the minimum

See Also:

Range.closed(Comparable, Comparable)

range

@Cached
public Rule range(@Nonnull
                Range<Integer> range)

Generic method to build a JoinMatcher

You can use this method directly; note however that the range you will pass as an argument will be intersected with Range.atLeast(0); if the result of the intersection is an empty range, this is an error condition.

Ranges which are open on any end will be turned to closed range using Range.canonical(DiscreteDomain).

Parameters:

range - the range (must not be null)

Returns:

a rule

Throws:

IllegalArgumentException - see description

See Also:

Range.canonical(DiscreteDomain)