com.github.fge.grappa.misc

Class RangeMatcherBuilder<V>

java.lang.Object

com.github.fge.grappa.misc.RangeMatcherBuilder<V>

Type Parameters:

V - the type parameter of the parser

Direct Known Subclasses:

JoinMatcherBuilder, RepeatMatcherBuilder

public abstract class RangeMatcherBuilder<V>
extends Object

A matcher builder for matchers repeating a given number of times

This class allows to specify a number of times which a given rule should be repeated:

• at least n times;
• at most n times;
• exactly n times;
• between n1 and n2 times.

When appropriate, the returned rule is a simplified version; for instance, a rule repeated "exactly once" is the rule itself. See range(Range) for more details.

See Also:

JoinMatcherBuilder, RepeatMatcherBuilder

Field Summary

Fields

Modifier and Type	Field and Description
protected BaseParser<V>	parser
protected Rule	rule

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RangeMatcherBuilder(BaseParser<V> parser, Rule rule)

Method Summary

Methods

Modifier and Type	Method and Description
protected abstract Rule	boundedBoth(int minCycles, int maxCycles) Build a rule which is expected to match a number of times between two end points
protected abstract Rule	boundedDown(int minCycles) Build a rule which is expected to match a minimum number of times
protected abstract Rule	boundedUp(int maxCycles) Build a rule which is expected to match a maximum number of times
protected abstract Rule	exactly(int nrCycles) Build a rule which is expected to match a fixed number of times
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) Core method for building a repeating matcher
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

Field Detail

parser

protected final BaseParser<V> parser

rule

protected final Rule rule

Constructor Detail

RangeMatcherBuilder

protected RangeMatcherBuilder(BaseParser<V> parser,
                   Rule rule)

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.

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
@DontLabel
public Rule range(Range<Integer> range)

Core method for building a repeating matcher

This is the method which all other methods (min, max, times) delegate to; among other things it is responsible for the logic of simplifying matchers where possible.

The simplifications are as follows:

• [0..0]: returns an EmptyMatcher;
• [0..1]: returns an OptionalMatcher with the rule as a submatcher;
• [1..1]: returns the rule itself.

If none of these apply, this method delegates as follows:

• [n..+∞) for whatever n: delegates to boundedDown(int);
• [0..n] for n >= 2: delegates to boundedUp(int);
• [n..n] for n >= 2: delegates to exactly(int);
• [n..m] with 0 < n < m: delegates to boundedBoth(int, int).

Parameters:

range - the range

Returns:

the final resulting rule

boundedDown

protected abstract Rule boundedDown(int minCycles)

Build a rule which is expected to match a minimum number of times

The returned matcher will attempt to match indefinitely its input until it fails. Success should be declared if and only if the number of times the matcher has succeeded is greater than, or equal to, the number of cycles given as an argument (including 0).

Parameters:

minCycles - the minimum number of cycles (inclusive)

Returns:

a rule

boundedUp

protected abstract Rule boundedUp(int maxCycles)

Build a rule which is expected to match a maximum number of times

The returned matcher will attempt to match repeatedly up to, and including, the number of cycles returned as an argument. Note that the argument will always be greater than or equal to 2.

One consequence is that this matcher always succeeds.

Parameters:

maxCycles - the maximum number of cycles (inclusive)

Returns:

a rule

exactly

protected abstract Rule exactly(int nrCycles)

Build a rule which is expected to match a fixed number of times

The returned matcher will attempt to match repeatedly up to, and including, the number of cycles given as an argument. Success should be declared if and only if the number of cycles matched is exactly this number.

Parameters:

nrCycles - the number of cycles (inclusive)

Returns:

a rule

boundedBoth

protected abstract Rule boundedBoth(int minCycles,
               int maxCycles)

Build a rule which is expected to match a number of times between two end points

The returned matcher will attempt to match repeatedly up to, and including, the maximum number of cycles specified as the second argument. Success should be declared if and only if the number of cycles performed is at least equal to the number of cycles specified as the first argument.

Note that the first argument will always be strictly greater than 0, and that the second argument will always be strictly greater than the first.

Parameters:

minCycles - the minimum number of cycles (inclusive)

maxCycles - the maximum number of cycles (exclusive)

Returns:

a rule