ca.gorman.util.scan
Class Modifier

java.lang.Object
  ca.gorman.util.scan.Modifier

public abstract class Modifier
extends Object

Modifiers for constructing a new ScanRule instance from other ScanRule instances.

This class is immutable with reentrant methods.

The modifiers in this class will create new possessive modifiers if they are applied to ScanRule instances that possessively match character sequences. However, some the modifiers will not create greedy or reluctant ScanRule instances even when applied to ScanRule instances that greedily or reluctantly match character sequences.

Constructor Summary

protected

Modifier() Prevent instantiation, but allow subclasses.

Method Summary

ScanRule	anyOf(ScanRule... scanRule) Alternation, recognize a character sequence that would be recognized by at least one of the ScanRule instances in a list.
ScanRule	atLeast(int count, ScanRule scanRule) Repetition, recognize a character sequence matched by count or more repetitions of a ScanRule.
ScanRule	capture(String key, ScanRule scanRule) Return the character sequence matched by another ScanRule and simultaneously save the character sequence for later retrieval.
ScanRule	concat(ScanRule... scanRule) Concatenation, match a series of character sequences that would be matched consecutively by the ScanRule instances in a list.
ScanRule	lookahead(ScanRule scanRule) Recognize a character sequence at the current point in the ScanBuffer without returning it and without removing it from the ScanBuffer.
ScanRule	lookaheadNot(ScanRule scanRule) Recognize the absence of a matching character sequence at the current point in the ScanBuffer.
static Modifier	newInstance() Return an instance.
ScanRule	oneOrMore(ScanRule scanRule) Optional repetition, recognize a character sequence matched by one or more repetitions of a ScanRule.
ScanRule	repeat(int min, int max, ScanRule scanRule) Repetition, recognize a character sequence that matches at least min repetition of a ScanRule, but accept no more than max repetitions.
ScanRule	repeat(int count, ScanRule scanRule) Repetition, recognize a character sequence that matches exactly count repetitions of a single ScanRule.
ScanRule	zeroOrMore(ScanRule scanRule) Optional match, recognize a character sequence matched by zero or more repetitions of a ScanRule.
ScanRule	zeroOrOne(ScanRule scanRule) Optional match, recognize a character sequence macthed by zero or one repetitions of a ScanRule.

Methods inherited from class java.lang.Object

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

Constructor Detail

Modifier

protected Modifier()

Prevent instantiation, but allow subclasses.

Method Detail

newInstance

public static Modifier newInstance()

Return an instance.

anyOf

public ScanRule anyOf(ScanRule... scanRule)

Alternation, recognize a character sequence that would be recognized by at least one of the ScanRule instances in a list.

The returned ScanRule instance accepts the character sequence that matches the first successful ScanRule in the list, even if a subsequent ScanRule would match a longer character sequence. There is no backtracking to find the longest match.

Parameters:

scanRule - one or more ScanRule instances

Returns:

a ScanRule that will recognize any character sequence that would be recognized by one of the ScanRule instances in the parameter list

Throws:

NullPointerException - if any parameter is null

concat

public ScanRule concat(ScanRule... scanRule)

Concatenation, match a series of character sequences that would be matched consecutively by the ScanRule instances in a list. The returned ScanRule instance is equivalent to testing each of the original ScanRule before proceding to the next one. It may match fewer characters than would be possible by using backtracking and treating the entire group of ScanRule as a single larger test. It may fail to match at all in some cases where backtracking would have allowed a successful match.

Parameters:

scanRule - one or more ScanRule instances, in the order of matching to a character sequence.

Returns:

a ScanRule that will recognize a series of adjacent character sequences that would be recognized by the corresponding ScanRule instances in the parameter list

Throws:

NullPointerException - if any parameter is null

repeat

public ScanRule repeat(int min,
                       int max,
                       ScanRule scanRule)

Repetition, recognize a character sequence that matches at least min repetition of a ScanRule, but accept no more than max repetitions.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches at least min times in succession but not accepting more than max matches, or null when the original ScanRule fails to match at least min times.

Throws:

NullPointerException - if any parameter is null

IndexOutOfBoundsException - if min is negative or greater than max

repeat

public ScanRule repeat(int count,
                       ScanRule scanRule)

Repetition, recognize a character sequence that matches exactly count repetitions of a single ScanRule.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches count times in succession, or null when the original ScanRule fails to match count times.

Throws:

NullPointerException - if any parameter is null

IndexOutOfBoundsException - if count is negative

atLeast

public ScanRule atLeast(int count,
                        ScanRule scanRule)

Repetition, recognize a character sequence matched by count or more repetitions of a ScanRule.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches count or more times in succession, or null when the original ScanRule fails to match at least count times.

Throws:

NullPointerException - if any object is null

IndexOutOfBoundsException - if count is negative.

zeroOrOne

public ScanRule zeroOrOne(ScanRule scanRule)

Optional match, recognize a character sequence macthed by zero or one repetitions of a ScanRule.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches once or a MatchedText of zero length when the original ScanRule fails to match

Throws:

NullPointerException - if any parameter is null

zeroOrMore

public ScanRule zeroOrMore(ScanRule scanRule)

Optional match, recognize a character sequence matched by zero or more repetitions of a ScanRule.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches one or more times in succession, or a MatchedText of zero length when the original ScanRule fails to match.

Throws:

NullPointerException - if any parameter is null

oneOrMore

public ScanRule oneOrMore(ScanRule scanRule)

Optional repetition, recognize a character sequence matched by one or more repetitions of a ScanRule.

Returns:

a new ScanRule that returns a MatchedText containing all the characters matched when the original ScanRule matches one or more times in succession, or null when the original ScanRule fails to match.

Throws:

NullPointerException - if any parameter is null

lookahead

public ScanRule lookahead(ScanRule scanRule)

Recognize a character sequence at the current point in the ScanBuffer without returning it and without removing it from the ScanBuffer.

Returns:

a new ScanRule that returns a MatchedText of zero length when the original ScanRule matches, or null when the original ScanRule fails to match.

Throws:

NullPointerException - if any parameter is null

lookaheadNot

public ScanRule lookaheadNot(ScanRule scanRule)

Recognize the absence of a matching character sequence at the current point in the ScanBuffer.

Returns:

a new ScanRule that returns a MatchedText of zero length when the original ScanRule fails to match, or null when the original ScanRule matches.

Throws:

NullPointerException - if any parameter is null

capture

public ScanRule capture(String key,
                        ScanRule scanRule)

Return the character sequence matched by another ScanRule and simultaneously save the character sequence for later retrieval.

The character sequences are only saved until the Scanner completes the next action.

Returns:

a new ScanRule that matches the same character sequences as the original ScanRule, but also saves the sequences with a key for later retreival.

Throws:

NullPointerException - if any parameter is null