org.apache.regexp
public class RE extends Object implements Serializable
To compile a regular expression (RE), you can simply construct an RE matcher object from the string specification of the pattern, like this:
RE r = new RE("a*b");
Once you have done this, you can call either of the RE.match methods to perform matching on a String. For example:
boolean matched = r.match("aaaab");will cause the boolean matched to be set to true because the pattern "a*b" matches the string "aaaab".
If you were interested in the number of a's which matched the first part of our example expression, you could change the expression to "(a*)b". Then when you compiled the expression and matched it against something like "xaaaab", you would get results like this:
RE r = new RE("(a*)b"); // Compile expression boolean matched = r.match("xaaaab"); // Match against "xaaaab" String wholeExpr = r.getParen(0); // wholeExpr will be 'aaaab' String insideParens = r.getParen(1); // insideParens will be 'aaaa' int startWholeExpr = r.getParenStart(0); // startWholeExpr will be index 1 int endWholeExpr = r.getParenEnd(0); // endWholeExpr will be index 6 int lenWholeExpr = r.getParenLength(0); // lenWholeExpr will be 5 int startInside = r.getParenStart(1); // startInside will be index 1 int endInside = r.getParenEnd(1); // endInside will be index 5 int lenInside = r.getParenLength(1); // lenInside will be 4You can also refer to the contents of a parenthesized expression within a regular expression itself. This is called a 'backreference'. The first backreference in a regular expression is denoted by \1, the second by \2 and so on. So the expression:
([0-9]+)=\1will match any string of the form n=n (like 0=0 or 2=2).
The full regular expression syntax accepted by RE is described here:
Characters unicodeChar Matches any identical unicode character \ Used to quote a meta-character (like '*') \\ Matches a single '\' character \0nnn Matches a given octal character \xhh Matches a given 8-bit hexadecimal character \\uhhhh Matches a given 16-bit hexadecimal character \t Matches an ASCII tab character \n Matches an ASCII newline character \r Matches an ASCII return character \f Matches an ASCII form feed character Character Classes [abc] Simple character class [a-zA-Z] Character class with ranges [^abc] Negated character classNOTE: Incomplete ranges will be interpreted as "starts from zero" or "ends with last character".
Standard POSIX Character Classes [:alnum:] Alphanumeric characters. [:alpha:] Alphabetic characters. [:blank:] Space and tab characters. [:cntrl:] Control characters. [:digit:] Numeric characters. [:graph:] Characters that are printable and are also visible. (A space is printable, but not visible, while an `a' is both.) [:lower:] Lower-case alphabetic characters. [:print:] Printable characters (characters that are not control characters.) [:punct:] Punctuation characters (characters that are not letter, digits, control characters, or space characters). [:space:] Space characters (such as space, tab, and formfeed, to name a few). [:upper:] Upper-case alphabetic characters. [:xdigit:] Characters that are hexadecimal digits. Non-standard POSIX-style Character Classes [:javastart:] Start of a Java identifier [:javapart:] Part of a Java identifier Predefined Classes . Matches any character other than newline \w Matches a "word" character (alphanumeric plus "_") \W Matches a non-word character \s Matches a whitespace character \S Matches a non-whitespace character \d Matches a digit character \D Matches a non-digit character Boundary Matchers ^ Matches only at the beginning of a line $ Matches only at the end of a line \b Matches only at a word boundary \B Matches only at a non-word boundary Greedy Closures A* Matches A 0 or more times (greedy) A+ Matches A 1 or more times (greedy) A? Matches A 1 or 0 times (greedy) A{n} Matches A exactly n times (greedy) A{n,} Matches A at least n times (greedy) A{n,m} Matches A at least n but not more than m times (greedy) Reluctant Closures A*? Matches A 0 or more times (reluctant) A+? Matches A 1 or more times (reluctant) A?? Matches A 0 or 1 times (reluctant) Logical Operators AB Matches A followed by B A|B Matches either A or B (A) Used for subexpression grouping (?:A) Used for subexpression clustering (just like grouping but no backrefs) Backreferences \1 Backreference to 1st parenthesized subexpression \2 Backreference to 2nd parenthesized subexpression \3 Backreference to 3rd parenthesized subexpression \4 Backreference to 4th parenthesized subexpression \5 Backreference to 5th parenthesized subexpression \6 Backreference to 6th parenthesized subexpression \7 Backreference to 7th parenthesized subexpression \8 Backreference to 8th parenthesized subexpression \9 Backreference to 9th parenthesized subexpression
All closure operators (+, *, ?, {m,n}) are greedy by default, meaning that they match as many elements of the string as possible without causing the overall match to fail. If you want a closure to be reluctant (non-greedy), you can simply follow it with a '?'. A reluctant closure will match as few elements of the string as possible when finding matches. {m,n} closures don't currently support reluctancy.
Line terminators
A line terminator is a one- or two-character sequence that marks
the end of a line of the input character sequence. The following
are recognized as line terminators:
RE runs programs compiled by the RECompiler class. But the RE matcher class does not include the actual regular expression compiler for reasons of efficiency. In fact, if you want to pre-compile one or more regular expressions, the 'recompile' class can be invoked from the command line to produce compiled output like this:
// Pre-compiled regular expression "a*b" char[] re1Instructions = { 0x007c, 0x0000, 0x001a, 0x007c, 0x0000, 0x000d, 0x0041, 0x0001, 0x0004, 0x0061, 0x007c, 0x0000, 0x0003, 0x0047, 0x0000, 0xfff6, 0x007c, 0x0000, 0x0003, 0x004e, 0x0000, 0x0003, 0x0041, 0x0001, 0x0004, 0x0062, 0x0045, 0x0000, 0x0000, }; REProgram re1 = new REProgram(re1Instructions);You can then construct a regular expression matcher (RE) object from the pre-compiled expression re1 and thus avoid the overhead of compiling the expression at runtime. If you require more dynamic regular expressions, you can construct a single RECompiler object and re-use it to compile each expression. Similarly, you can change the program run by a given matcher object at any time. However, RE and RECompiler are not threadsafe (for efficiency reasons, and because requiring thread safety in this class is deemed to be a rare requirement), so you will need to construct a separate compiler or matcher object for each thread (unless you do thread synchronization yourself). Once expression compiled into the REProgram object, REProgram can be safely shared across multiple threads and RE objects.
ISSUES:
Version: $Id: RE.java 518156 2007-03-14 14:31:26Z vgritsenko $
See Also: recompile
Field Summary | |
---|---|
int | end0 |
int | end1 |
int | end2 |
int[] | endBackref |
int[] | endn |
static char | E_ALNUM |
static char | E_BOUND |
static char | E_DIGIT |
static char | E_NALNUM |
static char | E_NBOUND |
static char | E_NDIGIT |
static char | E_NSPACE |
static char | E_SPACE |
int | matchFlags |
static int | maxNode |
int | maxParen |
static int | MATCH_CASEINDEPENDENT
Flag to indicate that matching should be case-independent (folded) |
static int | MATCH_MULTILINE
Newlines should match as BOL/EOL (^ and $) |
static int | MATCH_NORMAL
Specifies normal, case-sensitive matching behaviour. |
static int | MATCH_SINGLELINE
Consider all input a single body of text - newlines are matched by . |
static int | MAX_PAREN |
static int | nodeSize |
static int | offsetNext |
static int | offsetOpcode |
static int | offsetOpdata |
static char | OP_ANY |
static char | OP_ANYOF |
static char | OP_ATOM |
static char | OP_BACKREF |
static char | OP_BOL |
static char | OP_BRANCH |
static char | OP_CLOSE |
static char | OP_CLOSE_CLUSTER |
static char | OP_CONTINUE |
static char | OP_END
*
The format of a node in a program is: *
*
[ OPCODE ] [ OPDATA ] [ OPNEXT ] [ OPERAND ] *
*
char OPCODE - instruction *
char OPDATA - modifying data *
char OPNEXT - next node (relative offset) *
*
|
static char | OP_EOL |
static char | OP_ESCAPE |
static char | OP_GOTO |
static char | OP_MAYBE |
static char | OP_NOTHING |
static char | OP_OPEN |
static char | OP_OPEN_CLUSTER |
static char | OP_PLUS |
static char | OP_POSIXCLASS |
static char | OP_RELUCTANTMAYBE |
static char | OP_RELUCTANTPLUS |
static char | OP_RELUCTANTSTAR |
static char | OP_STAR |
int | parenCount |
REProgram | program |
static char | POSIX_CLASS_ALNUM |
static char | POSIX_CLASS_ALPHA |
static char | POSIX_CLASS_BLANK |
static char | POSIX_CLASS_CNTRL |
static char | POSIX_CLASS_DIGIT |
static char | POSIX_CLASS_GRAPH |
static char | POSIX_CLASS_JPART |
static char | POSIX_CLASS_JSTART |
static char | POSIX_CLASS_LOWER |
static char | POSIX_CLASS_PRINT |
static char | POSIX_CLASS_PUNCT |
static char | POSIX_CLASS_SPACE |
static char | POSIX_CLASS_UPPER |
static char | POSIX_CLASS_XDIGIT |
static int | REPLACE_ALL
Flag bit that indicates that subst should replace all occurrences of this
regular expression. |
static int | REPLACE_BACKREFERENCES
Flag bit that indicates that subst should replace backreferences |
static int | REPLACE_FIRSTONLY
Flag bit that indicates that subst should only replace the first occurrence
of this regular expression. |
CharacterIterator | search |
int | start0 |
int | start1 |
int | start2 |
int[] | startBackref |
int[] | startn |
Constructor Summary | |
---|---|
RE(String pattern)
Constructs a regular expression matcher from a String by compiling it
using a new instance of RECompiler. | |
RE(String pattern, int matchFlags)
Constructs a regular expression matcher from a String by compiling it
using a new instance of RECompiler. | |
RE(REProgram program, int matchFlags)
Construct a matcher for a pre-compiled regular expression from program
(bytecode) data. | |
RE(REProgram program)
Construct a matcher for a pre-compiled regular expression from program
(bytecode) data.
| |
RE()
Constructs a regular expression matcher with no initial program.
|
Method Summary | |
---|---|
void | allocParens()
Performs lazy allocation of subexpression arrays |
int | compareChars(char c1, char c2, boolean caseIndependent)
Compares two characters.
|
int | getMatchFlags()
Returns the current match behaviour flags. |
String | getParen(int which)
Gets the contents of a parenthesized subexpression after a successful match.
|
int | getParenCount()
Returns the number of parenthesized subexpressions available after a successful match.
|
int | getParenEnd(int which)
Returns the end index of a given paren level.
|
int | getParenLength(int which)
Returns the length of a given paren level.
|
int | getParenStart(int which)
Returns the start index of a given paren level.
|
REProgram | getProgram()
Returns the current regular expression program in use by this matcher object.
|
String[] | grep(Object[] search)
Returns an array of Strings, whose toString representation matches a regular
expression. |
protected void | internalError(String s)
Throws an Error representing an internal error condition probably resulting
from a bug in the regular expression compiler (or possibly data corruption).
|
boolean | isNewline(int i) |
boolean | match(String search, int i)
Matches the current regular expression program against a character array,
starting at a given index.
|
boolean | match(CharacterIterator search, int i)
Matches the current regular expression program against a character array,
starting at a given index.
|
boolean | match(String search)
Matches the current regular expression program against a String.
|
protected boolean | matchAt(int i)
Match the current regular expression program against the current
input string, starting at index i of the input string. |
protected int | matchNodes(int firstNode, int lastNode, int idxStart)
Try to match a string against a subset of nodes in the program
|
void | setMatchFlags(int matchFlags)
Sets match behaviour flags which alter the way RE does matching. |
protected void | setParenEnd(int which, int i)
Sets the end of a paren level
|
protected void | setParenStart(int which, int i)
Sets the start of a paren level
|
void | setProgram(REProgram program)
Sets the current regular expression program used by this matcher object.
|
static String | simplePatternToFullRegularExpression(String pattern)
Converts a 'simplified' regular expression to a full regular expression
|
String[] | split(String s)
Splits a string into an array of strings on regular expression boundaries.
|
String | subst(String substituteIn, String substitution)
Substitutes a string for this regular expression in another string.
|
String | subst(String substituteIn, String substitution, int flags)
Substitutes a string for this regular expression in another string.
|
Parameters: pattern The regular expression pattern to compile.
Throws: RESyntaxException Thrown if the regular expression has invalid syntax.
See Also: RECompiler recompile
Parameters: pattern The regular expression pattern to compile. matchFlags The matching style
Throws: RESyntaxException Thrown if the regular expression has invalid syntax.
See Also: RECompiler recompile
Parameters: program Compiled regular expression program (see RECompiler and/or recompile) matchFlags One or more of the RE match behaviour flags (RE.MATCH_*):
MATCH_NORMAL // Normal (case-sensitive) matching
MATCH_CASEINDEPENDENT // Case folded comparisons
MATCH_MULTILINE // Newline matches as BOL/EOL
See Also: RECompiler REProgram recompile
Parameters: program Compiled regular expression program
See Also: RECompiler recompile
Parameters: c1 first character to compare. c2 second character to compare. caseIndependent whether comparision is case insensitive or not.
Returns: negative, 0, or positive integer as the first character less than, equal to, or greater then the second.
Returns: Current match behaviour flags (RE.MATCH_*).
MATCH_NORMAL // Normal (case-sensitive) matching
MATCH_CASEINDEPENDENT // Case folded comparisons
MATCH_MULTILINE // Newline matches as BOL/EOL
See Also: RE
Parameters: which Nesting level of subexpression
Returns: String
Returns: Number of available parenthesized subexpressions
Parameters: which Nesting level of subexpression
Returns: String index
Parameters: which Nesting level of subexpression
Returns: Number of characters in the parenthesized subexpression
Parameters: which Nesting level of subexpression
Returns: String index
Returns: Regular expression program
See Also: RE
Parameters: search Array of Objects to search
Returns: Array of Strings whose toString() value matches this regular expression.
Parameters: s Error description
Returns: true if character at i-th position in the search
string is a newline
Parameters: search String to match against i Index to start searching at
Returns: True if string matched
Parameters: search String to match against i Index to start searching at
Returns: True if string matched
Parameters: search String to match against
Returns: True if string matched
Parameters: i The input string index to start matching at
Returns: True if the input matched the expression
Parameters: firstNode Node to start at in program lastNode Last valid node (used for matching a subexpression without matching the rest of the program as well). idxStart Starting position in character array
Returns: Final input array index if match succeeded. -1 if not.
Parameters: matchFlags One or more of the RE match behaviour flags (RE.MATCH_*):
MATCH_NORMAL // Normal (case-sensitive) matching
MATCH_CASEINDEPENDENT // Case folded comparisons
MATCH_MULTILINE // Newline matches as BOL/EOL
Parameters: which Which paren level i Index in input array
Parameters: which Which paren level i Index in input array
Parameters: program Regular expression program compiled by RECompiler.
See Also: RECompiler REProgram recompile
Parameters: pattern The pattern to convert
Returns: The full regular expression
Please note that the first string in the resulting array may be an empty string. This happens when the very first character of input string is matched by the pattern.
Parameters: s String to split on this regular exression
Returns: Array of strings
Parameters: substituteIn String to substitute within substitution String to substitute for all matches of this regular expression.
Returns: The string substituteIn with zero or more occurrences of the current regular expression replaced with the substitution String (if this regular expression object doesn't match at any position, the original String is returned unchanged).
It is also possible to reference the contents of a parenthesized expression with $0, $1, ... $9. A regular expression of "http://[\\.\\w\\-\\?/~_@&=%]+", a String to substituteIn of "visit us: http://www.apache.org!" and the substitution String "<a href=\"$0\">$0</a>", the resulting String returned by subst would be "visit us: <a href=\"http://www.apache.org\">http://www.apache.org</a>!".
Note: $0 represents the whole match.
Parameters: substituteIn String to substitute within substitution String to substitute for matches of this regular expression flags One or more bitwise flags from REPLACE_*. If the REPLACE_FIRSTONLY flag bit is set, only the first occurrence of this regular expression is replaced. If the bit is not set (REPLACE_ALL), all occurrences of this pattern will be replaced. If the flag REPLACE_BACKREFERENCES is set, all backreferences will be processed.
Returns: The string substituteIn with zero or more occurrences of the current regular expression replaced with the substitution String (if this regular expression object doesn't match at any position, the original String is returned unchanged).