net.sf.saxon.regex

Class REMatcher

java.lang.Object

net.sf.saxon.regex.REMatcher

public class REMatcher
extends Object

RE is an efficient, lightweight regular expression evaluator/matcher class. Regular expressions are pattern descriptions which enable sophisticated matching of strings. In addition to being able to match a string against a pattern, you can also extract parts of the match. This is especially useful in text parsing! Details on the syntax of regular expression patterns are given below.

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 4
 

You 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]+)=\1
 

will match any string of the form n=n (like 0=0 or 2=2).

The full regular expression syntax accepted by RE is as defined in the XSD 1.1 specification, modified by the XPath 2.0 or 3.0 specifications.

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:

• A newline (line feed) character ('\n'),
• A carriage-return character followed immediately by a newline character ("\r\n"),
• A standalone carriage-return character ('\r'),
• A next-line character ('…'),
• A line-separator character ('
'), or
• A paragraph-separator character ('
).

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:

Not *all* possibilities are considered for greediness when backreferences are involved (as POSIX suggests should be the case). The POSIX RE "(ac*)c*d[ac]*\1", when matched against "acdacaa" should yield a match of acdacaa where \1 is "a". This is not the case in this RE package, and actually Perl doesn't go to this extent either! Until someone actually complains about this, I'm not sure it's worth "fixing". If it ever is fixed, test #137 in RETest.txt should be updated.

This library is based on the Apache Jakarta regex library as downloaded on 3 January 2012. Changes have been made to make the grammar and semantics conform to XSD and XPath rules; these changes are listed in source code comments in the RECompiler source code module.

Author:

Jonathan Locke, Tobias Schäfer, Michael Kay

See Also:

RECompiler