org.apache.xerces.impl.xpath.regex

Class RegularExpression

Implemented Interfaces:
java.io.Serializable

public class RegularExpression
extends java.lang.Object
implements java.io.Serializable

A regular expression matching engine using Non-deterministic Finite Automaton (NFA). This engine does not conform to the POSIX regular expression.

How to use

A. Standard way
 RegularExpression re = new RegularExpression(regex);
 if (re.matches(text)) { ... }
 
B. Capturing groups
 RegularExpression re = new RegularExpression(regex);
 Match match = new Match();
 if (re.matches(text, match)) {
     ... // You can refer captured texts with methods of the Match class.
 }
 

Case-insensitive matching

 RegularExpression re = new RegularExpression(regex, "i");
 if (re.matches(text) >= 0) { ...}
 

Options

You can specify options to RegularExpression(regex, options) or setPattern(regex, options). This options parameter consists of the following characters.

"i"
This option indicates case-insensitive matching.
"m"
^ and $ consider the EOL characters within the text.
"s"
. matches any one character.
"u"
Redefines \d \D \w \W \s \S \b \B \< \> as becoming to Unicode.
"w"
By this option, \b \B \< \> are processed with the method of 'Unicode Regular Expression Guidelines' Revision 4. When "w" and "u" are specified at the same time, \b \B \< \> are processed for the "w" option.
","
The parser treats a comma in a character class as a range separator. [a,b] matches a or , or b without this option. [a,b] matches a or b with this option.
"X"
By this option, the engine confoms to XML Schema: Regular Expression. The match() method does not do subsring matching but entire string matching.

Syntax

Differences from the Perl 5 regular expression

  • There is 6-digit hexadecimal character representation (\u005cvHHHHHH.)
  • Supports subtraction, union, and intersection operations for character classes.
  • Not supported: \ooo (Octal character representations), \G, \C, \lc, \u005c uc, \L, \U, \E, \Q, \N{name}, (?{code}), (??{code})

Meta characters are `. * + ? { [ ( ) | \ ^ $'.

Enumerated ranges are merged (union operation). [a-ec-z] is equivalent to [a-z]

[^R1R2...Rn] (without a "," option)
[^R1,R2,...,Rn] (with a "," option)
Negative character class. It matches a character not in ranges.
(?[ranges]op[ranges]op[ranges] ... ) (op is - or + or &.)
Subtraction or union or intersection for character classes.
For exmaple, (?[A-Z]-[CF]) is equivalent to [A-BD-EG-Z], and (?[0x00-0x7f]-[K]&[\p{Lu}]) is equivalent to [A-JL-Z].
The result of this operations is a positive character class even if an expression includes any negative character classes. You have to take care on this in case-insensitive matching. For instance, (?[^b]) is equivalent to [\x00-ac-\x{10ffff}], which is equivalent to [^b] in case-sensitive matching. But, in case-insensitive matching, (?[^b]) matches any character because it includes 'B' and 'B' matches 'b' though [^b] is processed as [^Bb].
[R1R2...-[RnRn+1...]] (with an "X" option)
Character class subtraction for the XML Schema. You can use this syntax when you specify an "X" option.
\d
Equivalent to [0-9].
When a "u" option is set, it is equivalent to \p{Nd}.
\D
Equivalent to [^0-9]
When a "u" option is set, it is equivalent to \P{Nd}.
\s
Equivalent to [ \f\n\r\t]
When a "u" option is set, it is equivalent to [ \f\n\r\t\p{Z}].
\S
Equivalent to [^ \f\n\r\t]
When a "u" option is set, it is equivalent to [^ \f\n\r\t\p{Z}].
\w
Equivalent to [a-zA-Z0-9_]
When a "u" option is set, it is equivalent to [\p{Lu}\p{Ll}\p{Lo}\p{Nd}_].
\W
Equivalent to [^a-zA-Z0-9_]
When a "u" option is set, it is equivalent to [^\p{Lu}\p{Ll}\p{Lo}\p{Nd}_].
\p{name}
Matches one character in the specified General Category (the second field in UnicodeData.txt) or the specified Block. The following names are available:
Unicode General Categories:
L, M, N, Z, C, P, S, Lu, Ll, Lt, Lm, Lo, Mn, Me, Mc, Nd, Nl, No, Zs, Zl, Zp, Cc, Cf, Cn, Co, Cs, Pd, Ps, Pe, Pc, Po, Sm, Sc, Sk, So,
(Currently the Cn category includes U+10000-U+10FFFF characters)
Unicode Blocks:
Basic Latin, Latin-1 Supplement, Latin Extended-A, Latin Extended-B, IPA Extensions, Spacing Modifier Letters, Combining Diacritical Marks, Greek, Cyrillic, Armenian, Hebrew, Arabic, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Tamil, Telugu, Kannada, Malayalam, Thai, Lao, Tibetan, Georgian, Hangul Jamo, Latin Extended Additional, Greek Extended, General Punctuation, Superscripts and Subscripts, Currency Symbols, Combining Marks for Symbols, Letterlike Symbols, Number Forms, Arrows, Mathematical Operators, Miscellaneous Technical, Control Pictures, Optical Character Recognition, Enclosed Alphanumerics, Box Drawing, Block Elements, Geometric Shapes, Miscellaneous Symbols, Dingbats, CJK Symbols and Punctuation, Hiragana, Katakana, Bopomofo, Hangul Compatibility Jamo, Kanbun, Enclosed CJK Letters and Months, CJK Compatibility, CJK Unified Ideographs, Hangul Syllables, High Surrogates, High Private Use Surrogates, Low Surrogates, Private Use, CJK Compatibility Ideographs, Alphabetic Presentation Forms, Arabic Presentation Forms-A, Combining Half Marks, CJK Compatibility Forms, Small Form Variants, Arabic Presentation Forms-B, Specials, Halfwidth and Fullwidth Forms
Others:
ALL (Equivalent to [\u005cu0000-\u005cv10FFFF])
ASSGINED (\p{ASSIGNED} is equivalent to \P{Cn})
UNASSGINED (\p{UNASSIGNED} is equivalent to \p{Cn})
\P{name}
Matches one character not in the specified General Category or the specified Block.
  • Selection and Quantifier
    X|Y
    ...
    X*
    Matches 0 or more X.
    X+
    Matches 1 or more X.
    X?
    Matches 0 or 1 X.
    X{number}
    Matches number times.
    X{min,}
    ...
    X{min,max}
    ...
    X*?
    X+?
    X??
    X{min,}?
    X{min,max}?
    Non-greedy matching.
  • Grouping, Capturing, and Back-reference
    (?:X)
    Grouping. "foo+" matches "foo" or "foooo". If you want it matches "foofoo" or "foofoofoo", you have to write "(?:foo)+".
    (X)
    Grouping with capturing. It make a group and applications can know where in target text a group matched with methods of a Match instance after matches(String,Match). The 0th group means whole of this regular expression. The Nth gorup is the inside of the Nth left parenthesis.

    For instance, a regular expression is " *([^<:]*) +<([^>]*)> *" and target text is "From: TAMURA Kent <kent@trl.ibm.co.jp>":

    • Match.getCapturedText(0): " TAMURA Kent <kent@trl.ibm.co.jp>"
    • Match.getCapturedText(1): "TAMURA Kent"
    • Match.getCapturedText(2): "kent@trl.ibm.co.jp"
    \1 \2 \3 \4 \5 \6 \7 \8 \9
    (?>X)
    Independent expression group. ................
    (?options:X)
    (?options-options2:X)
    ............................
    The options or the options2 consists of 'i' 'm' 's' 'w'. Note that it can not contain 'u'.
    (?options)
    (?options-options2)
    ......
    These expressions must be at the beginning of a group.
  • Anchor
    \A
    Matches the beginnig of the text.
    \Z
    Matches the end of the text, or before an EOL character at the end of the text, or CARRIAGE RETURN + LINE FEED at the end of the text.
    \z
    Matches the end of the text.
    ^
    Matches the beginning of the text. It is equivalent to \A.
    When a "m" option is set, it matches the beginning of the text, or after one of EOL characters ( LINE FEED (U+000A), CARRIAGE RETURN (U+000D), LINE SEPARATOR (U+2028), PARAGRAPH SEPARATOR (U+2029).)
    $
    Matches the end of the text, or before an EOL character at the end of the text, or CARRIAGE RETURN + LINE FEED at the end of the text.
    When a "m" option is set, it matches the end of the text, or before an EOL character.
    \b
    Matches word boundary. (See a "w" option)
    \B
    Matches non word boundary. (See a "w" option)
    \<
    Matches the beginning of a word. (See a "w" option)
    \>
    Matches the end of a word. (See a "w" option)
  • Lookahead and lookbehind
    (?=X)
    Lookahead.
    (?!X)
    Negative lookahead.
    (?<=X)
    Lookbehind.
    (Note for text capturing......)
    (?<!X)
    Negative lookbehind.
  • Misc.
    (?(condition)yes-pattern|no-pattern),
    (?(condition)yes-pattern)
    ......
    (?#comment)
    Comment. A comment string consists of characters except ')'. You can not write comments in character classes and before quantifiers.

  • BNF for the regular expression

     regex ::= ('(?' options ')')? term ('|' term)*
     term ::= factor+
     factor ::= anchors | atom (('*' | '+' | '?' | minmax ) '?'? )?
                | '(?#' [^)]* ')'
     minmax ::= '{' ([0-9]+ | [0-9]+ ',' | ',' [0-9]+ | [0-9]+ ',' [0-9]+) '}'
     atom ::= char | '.' | char-class | '(' regex ')' | '(?:' regex ')' | '\' [0-9]
              | '\w' | '\W' | '\d' | '\D' | '\s' | '\S' | category-block | '\X'
              | '(?>' regex ')' | '(?' options ':' regex ')'
              | '(?' ('(' [0-9] ')' | '(' anchors ')' | looks) term ('|' term)? ')'
     options ::= [imsw]* ('-' [imsw]+)?
     anchors ::= '^' | '$' | '\A' | '\Z' | '\z' | '\b' | '\B' | '\<' | '\>'
     looks ::= '(?=' regex ')'  | '(?!' regex ')'
               | '(?<=' regex ')' | '(?<!' regex ')'
     char ::= '\\' | '\' [efnrtv] | '\c' [@-_] | code-point | character-1
     category-block ::= '\' [pP] category-symbol-1
                        | ('\p{' | '\P{') (category-symbol | block-name
                                           | other-properties) '}'
     category-symbol-1 ::= 'L' | 'M' | 'N' | 'Z' | 'C' | 'P' | 'S'
     category-symbol ::= category-symbol-1 | 'Lu' | 'Ll' | 'Lt' | 'Lm' | Lo'
                         | 'Mn' | 'Me' | 'Mc' | 'Nd' | 'Nl' | 'No'
                         | 'Zs' | 'Zl' | 'Zp' | 'Cc' | 'Cf' | 'Cn' | 'Co' | 'Cs'
                         | 'Pd' | 'Ps' | 'Pe' | 'Pc' | 'Po'
                         | 'Sm' | 'Sc' | 'Sk' | 'So'
     block-name ::= (See above)
     other-properties ::= 'ALL' | 'ASSIGNED' | 'UNASSIGNED'
     character-1 ::= (any character except meta-characters)
    
     char-class ::= '[' ranges ']'
                    | '(?[' ranges ']' ([-+&] '[' ranges ']')? ')'
     ranges ::= '^'? (range ','?)+
     range ::= '\d' | '\w' | '\s' | '\D' | '\W' | '\S' | category-block
               | range-char | range-char '-' range-char
     range-char ::= '\[' | '\]' | '\\' | '\' [,-efnrtv] | code-point | character-2
     code-point ::= '\x' hex-char hex-char
                    | '\x{' hex-char+ '}'
     <!--               | '\u005c u' hex-char hex-char hex-char hex-char
     -->               | '\v' hex-char hex-char hex-char hex-char hex-char hex-char
     hex-char ::= [0-9a-fA-F]
     character-2 ::= (any character except \[]-,)
     

    TODO

  • Parsing performance
  • Version:
    $Id: RegularExpression.java,v 1.7 2003/07/15 12:28:25 neeraj Exp $

    Author:
    TAMURA Kent <kent@trl.ibm.co.jp>

    See Also:
    Serialized Form

    Constructor Summary

    RegularExpression(String regex)
    Creates a new RegularExpression instance.
    RegularExpression(String regex, String options)
    Creates a new RegularExpression instance with options.

    Method Summary

    boolean
    equals(Object obj)
    Return true if patterns are the same and the options are equivalent.
    int
    getNumberOfGroups()
    Return the number of regular expression groups.
    String
    getOptions()
    Returns a option string.
    String
    getPattern()
    int
    hashCode()
    boolean
    matches(CharacterIterator target)
    Checks whether the target text contains this pattern or not.
    boolean
    matches(CharacterIterator target, Match match)
    Checks whether the target text contains this pattern or not.
    boolean
    matches(String target)
    Checks whether the target text contains this pattern or not.
    boolean
    matches(String target, int start, int end)
    Checks whether the target text contains this pattern in specified range or not.
    boolean
    matches(String target, int start, int end, Match match)
    Checks whether the target text contains this pattern in specified range or not.
    boolean
    matches(String target, Match match)
    Checks whether the target text contains this pattern or not.
    boolean
    matches(char[] target)
    Checks whether the target text contains this pattern or not.
    boolean
    matches(char[] target, int start, int end)
    Checks whether the target text contains this pattern in specified range or not.
    boolean
    matches(char[] target, int start, int end, Match match)
    Checks whether the target text contains this pattern in specified range or not.
    boolean
    matches(char[] target, Match match)
    Checks whether the target text contains this pattern or not.
    void
    setPattern(String newPattern)
    void
    setPattern(String newPattern, String options)
    String
    toString()
    Represents this instence in String.

    Constructor Details

    RegularExpression

    public RegularExpression(String regex)
                throws ParseException
    Creates a new RegularExpression instance.

    Parameters:
    regex - A regular expression


    RegularExpression

    public RegularExpression(String regex,
                             String options)
                throws ParseException
    Creates a new RegularExpression instance with options.

    Parameters:
    regex - A regular expression
    options - A String consisted of "i" "m" "s" "u" "w" "," "X"

    Method Details

    equals

    public boolean equals(Object obj)
    Return true if patterns are the same and the options are equivalent.


    getNumberOfGroups

    public int getNumberOfGroups()
    Return the number of regular expression groups. This method returns 1 when the regular expression has no capturing-parenthesis.


    getOptions

    public String getOptions()
    Returns a option string. The order of letters in it may be different from a string specified in a constructor or setPattern().

    See Also:
    RegularExpression(java.lang.String,java.lang.String), setPattern(java.lang.String,java.lang.String)


    getPattern

    public String getPattern()


    hashCode

    public int hashCode()


    matches

    public boolean matches(CharacterIterator target)
    Checks whether the target text contains this pattern or not.

    Returns:
    true if the target is matched to this regular expression.


    matches

    public boolean matches(CharacterIterator target,
                           Match match)
    Checks whether the target text contains this pattern or not.

    Parameters:
    match - A Match instance for storing matching result.

    Returns:
    Offset of the start position in target; or -1 if not match.


    matches

    public boolean matches(String target)
    Checks whether the target text contains this pattern or not.

    Returns:
    true if the target is matched to this regular expression.


    matches

    public boolean matches(String target,
                           int start,
                           int end)
    Checks whether the target text contains this pattern in specified range or not.

    Parameters:
    start - Start offset of the range.
    end - End offset +1 of the range.

    Returns:
    true if the target is matched to this regular expression.


    matches

    public boolean matches(String target,
                           int start,
                           int end,
                           Match match)
    Checks whether the target text contains this pattern in specified range or not.

    Parameters:
    start - Start offset of the range.
    end - End offset +1 of the range.
    match - A Match instance for storing matching result.

    Returns:
    Offset of the start position in target; or -1 if not match.


    matches

    public boolean matches(String target,
                           Match match)
    Checks whether the target text contains this pattern or not.

    Parameters:
    match - A Match instance for storing matching result.

    Returns:
    Offset of the start position in target; or -1 if not match.


    matches

    public boolean matches(char[] target)
    Checks whether the target text contains this pattern or not.

    Returns:
    true if the target is matched to this regular expression.


    matches

    public boolean matches(char[] target,
                           int start,
                           int end)
    Checks whether the target text contains this pattern in specified range or not.

    Parameters:
    start - Start offset of the range.
    end - End offset +1 of the range.

    Returns:
    true if the target is matched to this regular expression.


    matches

    public boolean matches(char[] target,
                           int start,
                           int end,
                           Match match)
    Checks whether the target text contains this pattern in specified range or not.

    Parameters:
    start - Start offset of the range.
    end - End offset +1 of the range.
    match - A Match instance for storing matching result.

    Returns:
    Offset of the start position in target; or -1 if not match.


    matches

    public boolean matches(char[] target,
                           Match match)
    Checks whether the target text contains this pattern or not.

    Parameters:
    match - A Match instance for storing matching result.

    Returns:
    Offset of the start position in target; or -1 if not match.


    setPattern

    public void setPattern(String newPattern)
                throws ParseException


    setPattern

    public void setPattern(String newPattern,
                           String options)
                throws ParseException


    toString

    public String toString()
    Represents this instence in String.


    Copyright B) 1999-2004 Apache XML Project. All Rights Reserved.