regexp
Class RE

java.lang.Object
  |
  +--regexp.REToken
        |
        +--regexp.RE

public class RE

extends REToken

RE provides the user interface for compiling and matching regular expressions.

A regular expression object (class RE) is compiled by constructing it from a String, StringBuffer or character array, with optional compilation flags (below) and an optional syntax specification (see RESyntax; if not specified, RESyntax.RE_SYNTAX_PERL5 is used).

Various methods attempt to match input text against a compiled regular expression. These methods are:

isMatch: returns true if the input text in its entirety matches the regular expression pattern.

getMatch: returns the first match found in the input text, or null if no match is found.

getAllMatches: returns an array of all non-overlapping matches found in the input text. If no matches are found, the array is zero-length.

substitute: substitute the first occurence of the pattern in the input text with a replacement string (which may include metacharacters $0-$9, see REMatch.substituteInto).

substituteAll: same as above, but repeat for each match before returning.

getMatchEnumeration: returns an REMatchEnumeration object that allows iteration over the matches (see REMatchEnumeration for some reasons why you may want to do this instead of using getAllMatches.

These methods all have similar argument lists. The input can be a String, a character array, a StringBuffer or an InputStream of some sort. Note that when using an InputStream, the stream read position cannot be guaranteed after attempting a match (this is not a bug, but a consequence of the way regular expressions work). Using an REMatchEnumeration can eliminate most positioning problems.

The optional index argument specifies the offset from the beginning of the text at which the search should start (see the descriptions of some of the execution flags for how this can affect positional pattern operators). For an InputStream, this means an offset from the current read position, so subsequent calls with the same index argument on an InputStream will not necessarily be accessing the same position on the stream, whereas repeated searches at a given index in a fixed string will return consistent results.

You can optionally affect the execution environment by using a combination of execution flags (constants listed below).

Version:

1.0.8, 21 March 1999

Author:

Wes Biggs

Field Summary

private REToken	firstToken
private REToken	lastToken
private int	m_numSubs
static int	REG_ANCHORINDEX Execution flag.
static int	REG_DOT_NEWLINE Compilation flag.
static int	REG_ICASE Compilation flag.
static int	REG_MULTILINE Compilation flag.
static int	REG_NOTBOL Execution flag.
static int	REG_NOTEOL Execution flag.
private static String	s_version

Fields inherited from class regexp.REToken

m_next, m_subIndex, m_uncle, newline

Constructor Summary

	RE(Object pattern) Constructs a regular expression pattern buffer without any compilation flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).
	RE(Object pattern, int cflags) Constructs a regular expression pattern buffer using the specified compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).
	RE(Object pattern, int cflags, RESyntax syntax) Constructs a regular expression pattern buffer using the specified compilation flags and regular expression syntax.
private	RE(Object patternObj, int cflags, RESyntax syntax, int myIndex, int nextSub)
private	RE(REToken f_first, REToken f_last, int f_subs, int f_subIndex)

Method Summary

private void	addToken(REToken next)
(package private) boolean	chain(REToken f_next)
(package private) void	dump(StringBuffer os)
REMatch[]	getAllMatches(Object input) Returns an array of all matches found in the input.
REMatch[]	getAllMatches(Object input, int index) Returns an array of all matches found in the input, beginning at the specified index position.
REMatch[]	getAllMatches(Object input, int index, int eflags) Returns an array of all matches found in the input string, beginning at the specified index position and using the specified execution flags.
private REMatch[]	getAllMatchesImpl(CharIndexed input, int index, int eflags)
private static int	getCharUnit(char[] input, int index, CharUnit unit)
REMatch	getMatch(Object input) Returns the first match found in the input.
REMatch	getMatch(Object input, int index) Returns the first match found in the input, beginning the search at the specified index.
REMatch	getMatch(Object input, int index, int eflags) Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.
REMatch	getMatch(Object input, int index, int eflags, StringBuffer buffer) Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags.
REMatchEnumeration	getMatchEnumeration(Object input) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
REMatchEnumeration	getMatchEnumeration(Object input, int index) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
REMatchEnumeration	getMatchEnumeration(Object input, int index, int eflags) Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.
(package private) REMatch	getMatchImpl(CharIndexed input, int index, int eflags, StringBuffer buffer)
int	getMinimumLength() Returns the minimum number of characters that could possibly constitute a match of this regular expression.
private int	getMinMax(char[] input, int index, IntPair minMax, RESyntax syntax)
int	getNumSubs() Returns the maximum number of subexpressions in this regular expression.
private static int	getPosixSet(char[] pattern, int index, StringBuffer buf)
boolean	isMatch(Object input) Checks if the input in its entirety is an exact match of this regular expression.
boolean	isMatch(Object input, int index) Checks if the input string, starting from index, is an exact match of this regular expression.
boolean	isMatch(Object input, int index, int eflags) Checks if the input, starting from index and using the specified execution flags, is an exact match of this regular expression.
private boolean	isMatchImpl(CharIndexed input, int index, int eflags)
private static CharIndexed	makeCharIndexed(Object input, int index)
(package private) int[]	match(CharIndexed input, int index, int eflags, REMatch mymatch)
private static REToken	setRepeated(REToken current, int min, int max, int index)
(package private) void	setUncle(REToken f_uncle)
String	substitute(Object input, String replace) Substitutes the replacement text for the first match found in the input.
String	substitute(Object input, String replace, int index) Substitutes the replacement text for the first match found in the input beginning at the specified index position.
String	substitute(Object input, String replace, int index, int eflags) Substitutes the replacement text for the first match found in the input string, beginning at the specified index position and using the specified execution flags.
String	substituteAll(Object input, String replace) Substitutes the replacement text for each non-overlapping match found in the input text.
String	substituteAll(Object input, String replace, int index) Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index.
String	substituteAll(Object input, String replace, int index, int eflags) Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index and using the specified execution flags.
private String	substituteAllImpl(CharIndexed input, String replace, int index, int eflags)
private String	substituteImpl(CharIndexed input, String replace, int index, int eflags)
String	toString() Return a human readable form of the compiled regular expression, useful for debugging.
static String	version() Returns a string representing the version of the gnu.regexp package.

Methods inherited from class regexp.REToken

dumpAll, next

Methods inherited from class java.lang.Object

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

Field Detail

s_version

private static final String s_version

firstToken

private REToken firstToken

lastToken

private REToken lastToken

m_numSubs

private int m_numSubs

REG_ICASE

public static final int REG_ICASE

Compilation flag. Do not differentiate case. Subsequent searches using this RE will be case insensitive.

REG_DOT_NEWLINE

public static final int REG_DOT_NEWLINE

Compilation flag. The match-any-character operator (dot) will match a newline character. When set this overrides the syntax bit RE_DOT_NEWLINE (see RESyntax for details). This is equivalent to the "/s" operator in Perl.

REG_MULTILINE

public static final int REG_MULTILINE

Compilation flag. Use multiline mode. In this mode, the ^ and $ anchors will match based on newlines within the input. This is equivalent to the "/m" operator in Perl.

REG_NOTBOL

public static final int REG_NOTBOL

Execution flag. The match-beginning operator (^) will not match at the beginning of the input string. Useful for matching on a substring when you know the context of the input is such that position zero of the input to the match test is not actually position zero of the text.

This example demonstrates the results of various ways of matching on a substring.

String s = "food bar fool";
RE exp = new RE("^foo.");
REMatch m0 = exp.getMatch(s);
REMatch m1 = exp.getMatch(s.substring(8));
REMatch m2 = exp.getMatch(s.substring(8),0,RE.REG_NOTBOL);
REMatch m3 = exp.getMatch(s,8);
REMatch m4 = exp.getMatch(s,8,RE.REG_ANCHORINDEX);


// Results:
// m0 = "food"
// m1 = "fool"
// m2 = null
// m3 = null
// m4 = "fool"


REG_NOTEOL

public static final int REG_NOTEOL

Execution flag. The match-end operator ($) does not match at the end of the input string. Useful for matching on substrings.

REG_ANCHORINDEX

public static final int REG_ANCHORINDEX

Execution flag. The match-beginning operator (^) matches not at position 0 in the input string, but at the position the search started at (based on the index input given to the getMatch function). See the example under REG_NOTBOL.

Constructor Detail

RE

public RE(Object pattern)
   throws REException

Constructs a regular expression pattern buffer without any compilation flags set, and using the default syntax (RESyntax.RE_SYNTAX_PERL5).

Parameters:

pattern - A regular expression pattern, in the form of a String, StringBuffer or char[].

Throws:

REException - The input pattern could not be parsed.

IllegalArgumentException - The pattern was not a String, StringBuffer or char[].

NullPointerException - The pattern was null.

RE

public RE(Object pattern,
          int cflags)
   throws REException

Constructs a regular expression pattern buffer using the specified compilation flags and the default syntax (RESyntax.RE_SYNTAX_PERL5).

Parameters:

pattern - A regular expression pattern, in the form of a String, StringBuffer, or char[].

cflags - The logical OR of any combination of the compilation flags listed above.

Throws:

REException - The input pattern could not be parsed.

IllegalArgumentException - The pattern was not a String, StringBuffer or char[].

NullPointerException - The pattern was null.

RE

public RE(Object pattern,
          int cflags,
          RESyntax syntax)
   throws REException

Constructs a regular expression pattern buffer using the specified compilation flags and regular expression syntax.

Parameters:

pattern - A regular expression pattern, in the form of a String, StringBuffer, or char[].

cflags - The logical OR of any combination of the compilation flags listed above.

syntax - The type of regular expression syntax to use.

Throws:

REException - The input pattern could not be parsed.

IllegalArgumentException - The pattern was not a String, StringBuffer or char[].

NullPointerException - The pattern was null.

RE

private RE(REToken f_first,
           REToken f_last,
           int f_subs,
           int f_subIndex)

RE

private RE(Object patternObj,
           int cflags,
           RESyntax syntax,
           int myIndex,
           int nextSub)
    throws REException

Method Detail

version

public static final String version()

Returns a string representing the version of the gnu.regexp package.

getCharUnit

private static int getCharUnit(char[] input,
                               int index,
                               CharUnit unit)
                        throws REException

isMatch

public boolean isMatch(Object input)

Checks if the input in its entirety is an exact match of this regular expression.

Parameters:

input - The input text.

Throws:

IllegalArgumentException - The input text was not a String, char[], or InputStream.

isMatch

public boolean isMatch(Object input,
                       int index)

Checks if the input string, starting from index, is an exact match of this regular expression.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

isMatch

public boolean isMatch(Object input,
                       int index,
                       int eflags)

Checks if the input, starting from index and using the specified execution flags, is an exact match of this regular expression.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

isMatchImpl

private boolean isMatchImpl(CharIndexed input,
                            int index,
                            int eflags)

getNumSubs

public int getNumSubs()

Returns the maximum number of subexpressions in this regular expression. If the expression contains branches, the value returned will be the maximum subexpressions in any of the branches.

setUncle

void setUncle(REToken f_uncle)

Overrides:

setUncle in class REToken

chain

boolean chain(REToken f_next)

Overrides:

chain in class REToken

getMinimumLength

public int getMinimumLength()

Returns the minimum number of characters that could possibly constitute a match of this regular expression.

Overrides:

getMinimumLength in class REToken

getAllMatches

public REMatch[] getAllMatches(Object input)

Returns an array of all matches found in the input.

Parameters:

input - The input text.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getAllMatches

public REMatch[] getAllMatches(Object input,
                               int index)

Returns an array of all matches found in the input, beginning at the specified index position.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getAllMatches

public REMatch[] getAllMatches(Object input,
                               int index,
                               int eflags)

Returns an array of all matches found in the input string, beginning at the specified index position and using the specified execution flags.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getAllMatchesImpl

private REMatch[] getAllMatchesImpl(CharIndexed input,
                                    int index,
                                    int eflags)

match

int[] match(CharIndexed input,
            int index,
            int eflags,
            REMatch mymatch)

Overrides:

match in class REToken

getMatch

public REMatch getMatch(Object input)

Returns the first match found in the input.

Parameters:

input - The input text.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatch

public REMatch getMatch(Object input,
                        int index)

Returns the first match found in the input, beginning the search at the specified index.

Parameters:

input - The input text.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatch

public REMatch getMatch(Object input,
                        int index,
                        int eflags)

Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags. If no match is found, returns null.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatch

public REMatch getMatch(Object input,
                        int index,
                        int eflags,
                        StringBuffer buffer)

Returns the first match found in the input, beginning the search at the specified index, and using the specified execution flags. If no match is found, returns null. If a StringBuffer is provided and is non-null, the contents of the input text from the index to the beginning of the match (or to the end of the input, if there is no match) are appended to the StringBuffer.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

buffer - The StringBuffer to save pre-match text in.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatchImpl

REMatch getMatchImpl(CharIndexed input,
                     int index,
                     int eflags,
                     StringBuffer buffer)

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.

Parameters:

input - The input text.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input,
                                              int index)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

getMatchEnumeration

public REMatchEnumeration getMatchEnumeration(Object input,
                                              int index,
                                              int eflags)

Returns an REMatchEnumeration that can be used to iterate over the matches found in the input text.

Parameters:

input - The input text.

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substitute

public String substitute(Object input,
                         String replace)

Substitutes the replacement text for the first match found in the input.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substitute

public String substitute(Object input,
                         String replace,
                         int index)

Substitutes the replacement text for the first match found in the input beginning at the specified index position.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

index - The offset index at which the search should be begin.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substitute

public String substitute(Object input,
                         String replace,
                         int index,
                         int eflags)

Substitutes the replacement text for the first match found in the input string, beginning at the specified index position and using the specified execution flags.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substituteImpl

private String substituteImpl(CharIndexed input,
                              String replace,
                              int index,
                              int eflags)

substituteAll

public String substituteAll(Object input,
                            String replace)

Substitutes the replacement text for each non-overlapping match found in the input text.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substituteAll

public String substituteAll(Object input,
                            String replace,
                            int index)

Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

index - The offset index at which the search should be begin.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substituteAll

public String substituteAll(Object input,
                            String replace,
                            int index,
                            int eflags)

Substitutes the replacement text for each non-overlapping match found in the input text, starting at the specified index and using the specified execution flags.

Parameters:

input - The input text.

replace - The replacement text, which may contain $x metacharacters (see REMatch.substituteInto).

index - The offset index at which the search should be begin.

eflags - The logical OR of any execution flags above.

Throws:

IllegalArgumentException - The input text was not a String, char[], StringBuffer or InputStream.

substituteAllImpl

private String substituteAllImpl(CharIndexed input,
                                 String replace,
                                 int index,
                                 int eflags)

addToken

private void addToken(REToken next)

setRepeated

private static REToken setRepeated(REToken current,
                                   int min,
                                   int max,
                                   int index)
                            throws REException

getPosixSet

private static int getPosixSet(char[] pattern,
                               int index,
                               StringBuffer buf)

getMinMax

private int getMinMax(char[] input,
                      int index,
                      IntPair minMax,
                      RESyntax syntax)
               throws REException

toString

public String toString()

Return a human readable form of the compiled regular expression, useful for debugging.

Overrides:

toString in class Object

dump

void dump(StringBuffer os)

Overrides:

dump in class REToken

makeCharIndexed

private static CharIndexed makeCharIndexed(Object input,
                                           int index)