Java Doc for Regexp.java in  » Scripting » jacl » sunlabs » brazil » util » regexp » Java Source Code / Java DocumentationJava Source Code and Java Documentation

Regular expressions were implemented by translating Henry Spencer's regular expression package for tcl8.0. Much of the description below is copied verbatim from the tcl8.0 regsub manual entry.

A regular expression is zero or more branches, separated by "|". It matches anything that matches one of the branches.

A branch is zero or more pieces, concatenated. It matches a match for the first piece, followed by a match for the second piece, etc.

A piece is an atom, possibly followed by "*", "+", or "?".

• An atom followed by "*" matches a sequence of 0 or more matches of the atom.
• An atom followed by "+" matches a sequence of 1 or more matches of the atom.
• An atom followed by "?" matches either 0 or 1 matches of the atom.

An atom is

• a regular expression in parentheses (matching a match for the regular expression)
• a range (see below)
• "." (matching any single character)
• "^" (matching the null string at the beginning of the input string)
• "$" (matching the null string at the end of the input string)
• a "\" followed by a single character (matching that character)
• a single character with no other significance (matching that character).

A range is a sequence of characters enclosed in "[]". The range normally matches any single character from the sequence. If the sequence begins with "^", the range matches any single character not from the rest of the sequence. If two characters in the sequence are separated by "-", this is shorthand for the full list of characters between them (e.g. "[0-9]" matches any decimal digit). To include a literal "]" in the sequence, make it the first character (following a possible "^"). To include a literal "-", make it the first or last character.

In general there may be more than one way to match a regular expression to an input string. For example, consider the command

 String[] match = new String[2];
 Regexp.match("(a*)b*", "aabaaabb", match);
 

• "aabb" and "aa"
• "aaab" and "aaa"
• "ab" and "a"

1. If a regular expression could match two different parts of an input string then it will match the one that begins earliest.
2. If a regular expression contains "|" operators then the leftmost matching sub-expression is chosen.
3. In "*", "+", and "?" constructs, longer matches are chosen in preference to shorter ones.
4. In sequences of expression components the components are considered from left to right.

In the example from above, "(a*)b*" therefore matches exactly "aab"; the "(a*)" portion of the pattern is matched first and it consumes the leading "aa", then the "b*" portion of the pattern consumes the next "b". Or, consider the following example:

 String match = new String[3];
 Regexp.match("(ab|a)(b*)c", "abc", match);
 

Regular expression substitution matches a string against a regular expression, transforming the string by replacing the matched region(s) with new substring(s).

What gets substituted into the result is controlled by a subspec. The subspec is a formatting string that specifies what portions of the matched region should be substituted into the result.

• "&" or "\0" is replaced with a copy of the entire matched region.
• "\n", where n is a digit from 1 to 9, is replaced with a copy of the nth subexpression.
• "\&" or "\\" are replaced with just "&" or "\" to escape their special meaning.
• any other character is passed through.

 public static void
 main(String[] args)
 throws Exception
 {
 Regexp re;
 String[] matches;
 String s;
 /*
 A regular expression to match the first line of a HTTP request.
 1. ^               - starting at the beginning of the line
 2. ([A-Z]+)        - match and remember some upper case characters
 3. [ \t]+          - skip blank space
 4. ([^ \t]*)       - match and remember up to the next blank space
 5. [ \t]+          - skip more blank space
 6. (HTTP/1\\.[01]) - match and remember HTTP/1.0 or HTTP/1.1
 7. $		      - end of string - no chars left.
 /
 s = "GET http://a.b.com:1234/index.html HTTP/1.1";
 re = new Regexp("^([A-Z]+)[ \t]+([^ \t]+)[ \t]+(HTTP/1\\.[01])$");
 matches = new String[4];
 if (re.match(s, matches)) {
 System.out.println("METHOD  " + matches[1]);
 System.out.println("URL     " + matches[2]);
 System.out.println("VERSION " + matches[3]);
 }
 /*
 A regular expression to extract some simple comma-separated data,
 reorder some of the columns, and discard column 2.
 /
 s = "abc,def,ghi,klm,nop,pqr";
 re = new Regexp("^([^,]+),([^,]+),([^,]+),(.*)");
 System.out.println(re.sub(s, "\\3,\\1,\\4"));
 }
 

It takes a certain amount of time to parse and validate a regular expression pattern before it can be used to perform matches or substitutions.

substrs[0] is set to the range of str that matched the entire regular expression.

substrs[1] is set to the range of str that matched the first (leftmost) parenthesized subexpression. substrs[n] is set to the range that matched the nth subexpression, and so on.

If subexpression n did not match, then substrs[n] is set to null.

For the indices specified below, the range extends from the character at the starting index up to, but not including, the character at the ending index.

indices[0] and indices[1] are set to starting and ending indices of the range of str that matched the entire regular expression.

indices[2] and indices[3] are set to the starting and ending indices of the range of str that matched the first (leftmost) parenthesized subexpression. indices[n * 2] and indices[n * 2 + 1] are set to the range that matched the nth subexpression, and so on.

If subexpression n did not match, then indices[n * 2] and indices[n * 2 + 1] are both set to -1.

The length that the caller should use when allocating the indices array is twice the return value of Regexp.subspecs.

It takes a certain amount of time to parse and validate a regular expression pattern before it can be used to perform matches or substitutions. If the caller caches the new Regexp object, that parsing time will be saved because the same Regexp can be used with respect to many different strings.
Parameters:
  pat - The string holding the regular expression pattern.
throws:
  IllegalArgumentException - if the pattern is malformed.The detail message for the exception will be set to astring indicating how the pattern was malformed.

substrs[0] is set to the range of str that matched the entire regular expression.

substrs[1] is set to the range of str that matched the first (leftmost) parenthesized subexpression. substrs[n] is set to the range that matched the nth subexpression, and so on.

If subexpression n did not match, then substrs[n] is set to null. Not to be confused with "", which is a valid value for a subexpression that matched 0 characters.

The length that the caller should use when allocating the substr array is the return value of Regexp.subspecs. The array can be shorter (in which case not all the information will be returned), or longer (in which case the remainder of the elements are initialized to null), or null (to ignore the subexpressions).
Parameters:
  str - The string to match.
Parameters:
  substrs - An array of strings allocated by the caller, and filled inwith information about the portions of str thatmatched the regular expression. May be null. true if str that matched thisregular expression, false otherwise.If false is returned, then the contents ofsubstrs are unchanged.
See Also:   Regexp.subspecs

For the indices specified below, the range extends from the character at the starting index up to, but not including, the character at the ending index.

indices[0] and indices[1] are set to starting and ending indices of the range of str that matched the entire regular expression.

indices[2] and indices[3] are set to the starting and ending indices of the range of str that matched the first (leftmost) parenthesized subexpression. indices[n * 2] and indices[n * 2 + 1] are set to the range that matched the nth subexpression, and so on.

If subexpression n did not match, then indices[n * 2] and indices[n * 2 + 1] are both set to -1.

The length that the caller should use when allocating the indices array is twice the return value of Regexp.subspecs. The array can be shorter (in which case not all the information will be returned), or longer (in which case the remainder of the elements are initialized to -1), or null (to ignore the subexpressions).
Parameters:
  str - The string to match.
Parameters:
  indices - An array of integers allocated by the caller, and filled inwith information about the portions of str thatmatched all the parts of the regular expression.May be null. true if the string matched the regular expression,false otherwise. If false isreturned, then the contents of indices areunchanged.
See Also:   Regexp.subspecs