The Classes

Perl5Pattern
Perl5Compiler
Perl5Matcher
PatternMatcherInput
Perl5StreamInput
Util
Perl5Debug

The Perl5Compiler compile() methods can take the following flags which can be bitwise or'ed together to affect the nature of the compiled pattern:

DEFAULT_MASK

The default mask for the compile methods. It is equal to 0. The default behavior is for a regular expression to be case sensitive and to not specify if it is multiline or singleline. When MULITLINE_MASK and SINGLINE_MASK are not defined, the ^, $, and . metacharacters are interpreted according to the value of isMultiline() in Perl5Matcher. The default behavior of Perl5Matcher is to treat the Perl5Pattern as though MULTILINE_MASK were enabled. If isMultiline() returns false, then the pattern is treated as though SINGLINE_MASK were set. However, compiling a pattern with the MULTILINE_MASK or SINGLELINE_MASK masks will ALWAYS override whatever behavior is specified by the setMultiline() in Perl5Matcher.

CASE_INSENSITIVE_MASK

A mask passed as an option to the compile methods to indicate a compiled regular expression should be case insensitive.

MULTILINE_MASK

A mask passed as an option to the compile methods to indicate a compiled regular expression should treat input as having multiple lines. This option affects the interpretation of the ^ and $ metacharacters. When this mask is used, the ^ metacharacter matches at the beginning of every line, and the $ metacharacter matches at the end of every line. Additionally the . metacharacter will not match newlines when an expression is compiled with MULTILINE_MASK , which is its default behavior. The SINGLELINE_MASK and MULTILINE_MASK should not be used together.

SINGLELINE_MASK

A mask passed as an option to the compile methods to indicate a compiled regular expression should treat input as being a single line. This option only affects the interpretation of the ^ and $ metacharacters. When this mask is used, the ^ metacharacter matches at the beginning of the input, and the $ metacharacter matches at the end of the input. The ^ and $ metacharacters will not match at the beginning and end of lines occurring between the begnning and end of the input. Additionally, the . metacharacter will match newlines when an expression is compiled with SINGLELINE_MASK , unlike its default behavior. The SINGLELINE_MASK and MULTILINE_MASK should not be used together.

EXTENDED_MASK

A mask passed as an option to the compile methods to indicate a compiled regular expression should be treated as a Perl5 extended pattern (i.e., a pattern using the /x modifier). This option tells the compiler to ignore whitespace that is not backslashed or within a character class. It also tells the compiler to treat the # character as a metacharacter introducing a comment as in Perl. In other words, the # character will comment out any text in the regular expression between it and the next newline. The intent of this option is to allow you to divide your patterns into more readable parts. It is provided to maintain compatibility with Perl5 regular expressions, although it will not often make sense to use it in Java.

setMultiline(boolean)

Sets whether or not subsequent calls to matches() or contains() should treat the input as consisting of multiple lines. The default behavior is for input to be treated as consisting of multiple lines. This method should only be called if the Perl5Pattern used for a match was compiled without either of the Perl5Compiler.MULTILINE_MASK or Perl5Compiler.SINGLELINE_MASK flags, and you want to alter the behavior of how the ^ and $ metacharacters are interpreted on the fly. The compilation options used when compiling a pattern ALWAYS override the behavior specified by setMultiline().

isMultiline()

Returns the last value set by setMultiline(). The default value is true.

contains(Perl5StreamInput, Perl5Pattern)

Determines if the contents of a Perl5StreamInput instance, starting from the current offset of the input, contains a pattern. If a pattern match is found, a MatchResult instance representing the first such match is made acessible via getMatch() . The current offset of the input stream is advanced to the end offset corresponding to the end of the match. Consequently a subsequent call to this method will continue searching where the last call left off. See Perl5StreamInput for more details.

You would use a PatternMatcherInput object when you want to search for more than just the first occurrence of a pattern in a string, or when you only want to search a subregion of the string for a match. An example of its most common use is:

      PatternMatcher matcher;
      PatternCompiler compiler;
      Pattern pattern;
      PatternMatcherInput input;
      MatchResult result;

      compiler = new Perl5Compiler();
      matcher  = new Perl5Matcher();

      try {
        pattern = compiler.compile(somePatternString);
      } catch(MalformedPatternException e) {
        System.out.println("Bad pattern.");
        System.out.println(e.getMessage());
        return;
      }

      input   = new PatternMatcherInput(someStringInput);

      while(matcher.contains(input, pattern)) {
        result = matcher.getMatch();  
        // Perform whatever processing on the result you want.
      }

      // Suppose we want to start searching from the beginning again with
      // a different pattern.
      // Just set the current offset to the begin offset.
      input.setCurrentOffset(input.getBeginOffset());

      // Second search omitted
      // Suppose we're done with this input, but want to search another string.
      // There's no need to create another PatternMatcherInput instance.
      // We can just use the setInput() method.
      input.setInput(aNewInputString);

If you want to perform line by line matches on an InputStream, you should use DataInputStream or BufferedReader class (depending on whether you are using JDK 1.0.2 or 1.1) in conjunction with one of the PatternMatcher methods taking a String, char[], or PatternMatcherInput as an argument. The DataInputStream and BufferedReader readLine() methods are implemented as native methods and therefore more efficient than supporting line by line searching within Perl5StreamInput.

In the future the programmer will be able to set this class to save all the input it sees so that it can be accessed later. This will avoid having to read a stream more than once for whatever reason.

For an example of how to use the Perl5StreamInput class, look at streamInputExample.java .

Util

A grep method is not included for two reasons:

1. The details of reading a line at a time from an input stream differ in JDK 1.0.2 and JDK 1.1, making it difficult to retain compatibility across both Java releases.
2. Grep style processing is trivial for the programmer to implement in a while loop. Rarely does anyone want to retrieve all occurences of a pattern and then process them. More often a programmer will retrieve pattern matches and process them as they are retrieved, which is more efficient than storing them all in a Vector and then accessing them.

For an example of how to use the split and substitute methods look at splitExample.java and substituteExample.java .

Perl5Debug