Pattern (RegExodus 0.1.3)

java.lang.Object
- regexodus.Pattern

All Implemented Interfaces:

Serializable, REFlags
```
public class Pattern
extends Object
implements Serializable, REFlags
```
A handle for a precompiled regular expression; core operations should be identical to java.util.regex.Pattern . Pattern should be no different.
To match a regular expression myExpr against a text myString one should first create a Pattern object:
```
 Pattern p = new Pattern(myExpr);
 
```
or
```
 Pattern p = Pattern.compile(myExpr);
 
```
then obtain a Matcher object:
```
 Matcher matcher=p.matcher(myText);
 
```
The latter is an automaton that actually performs a search. It provides the following methods:
- search for matching substrings : matcher.find() or matcher.findAll();
- test whether the text matches the whole pattern : matcher.matches();
- test whether the text matches the beginning of the pattern : matcher.matchesPrefix();
- search with custom options : matcher.find(int options)
Flags
Flags (see REFlags interface) change the meaning of some regular expression elements at compiletime. These flags may be passed both as string(see Pattern(String,String)) and as bitwise OR of:
- REFlags.IGNORE_CASE - enables case insensitivity
- REFlags.MULTILINE - forces "^" and "$" to match both at the start and the end of line;
- REFlags.DOTALL - forces "." to match eols('\r' and '\n' in ASCII);
- REFlags.IGNORE_SPACES - literal spaces in expression are ignored for better readability;
- REFlags.UNICODE - the predefined classes('\w','\d',etc) are referenced to Unicode;
- REFlags.XML_SCHEMA - permits XML Schema regular expressions syntax extensions.
Multithreading
Pattern instances are not thread-safe, and neither are Matcher objects.
See Also:

REFlags, Matcher, Matcher.setTarget(java.lang.CharSequence), Matcher.setTarget(java.lang.CharSequence, int, int), Matcher.setTarget(char[], int, int), Matcher.setTarget(java.io.Reader, int), MatchResult, MatchResult.group(int), MatchResult.start(int), MatchResult.end(int), MatchResult.length(int), MatchResult.charAt(int, int), MatchResult.prefix(), MatchResult.suffix(), Serialized Form

Field Summary
- Fields inherited from interface regexodus.REFlags
  DEFAULT, DOTALL, IGNORE_CASE, IGNORE_SPACES, MULTILINE, UNICODE, XML_SCHEMA

Constructor Summary

Constructors
Modifier	Constructor and Description
`protected`	`Pattern()`
	`Pattern(String regex)` Compiles an expression with default flags.
	`Pattern(String regex, String flags)` Compiles a regular expression using Perl5-style flags.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`static Pattern`	`compile(String regex)` Compiles the given String into a Pattern that can be used to match text.
`static Pattern`	`compile(String regex, int flags)` Compiles the given String into a Pattern that can be used to match text.
`static Pattern`	`compile(String regex, String flags)` Compiles the given String into a Pattern that can be used to match text.
`boolean`	`equals(Object o)`
`int`	`groupCount()` How many capturing groups does this expression include?
`Integer`	`groupId(String name)` Get numeric id for a group name.
`int`	`hashCode()`
`Matcher`	`matcher()` Returns a target-less matcher.
`Matcher`	`matcher(char[] data, int start, int end)` Returns a matcher for a specified region.
`Matcher`	`matcher(CharSequence s)` Returns a matcher for a specified string.
`Matcher`	`matcher(MatchResult res, int groupId)` Returns a matcher for a match result (in a performance-friendly way).
`Matcher`	`matcher(MatchResult res, String groupName)` Just as above, yet with symbolic group name.
`Matcher`	`matcher(Reader text, int length)` Returns a matcher taking a text stream as target.
`boolean`	`matches(String s)` A shorthand for Pattern.matcher(String).matches().
`Replacer`	`replacer(String expr)` Returns a replacer of a pattern by specified perl-like expression.
`Replacer`	`replacer(Substitution model)` Returns a replacer will substitute all occurrences of a pattern through applying a user-defined substitution model.
`boolean`	`startsWith(String s)` A shorthand for Pattern.matcher(String).matchesPrefix().
`RETokenizer`	`tokenizer(char[] data, int off, int len)` Tokenizes a specified region by an occurrences of the pattern.
`RETokenizer`	`tokenizer(Reader in, int length)` Tokenizes a specified region by an occurrences of the pattern.
`RETokenizer`	`tokenizer(String text)` Tokenizes a text by an occurrences of the pattern.
`String`	`toString_d()` Returns a less or more readable representation of a bytecode for the pattern.
`String`	`toString()`

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Constructor Detail
  - Pattern
```
protected Pattern()
           throws PatternSyntaxException
```
    Throws:
    
    PatternSyntaxException
  - Pattern
```
public Pattern(String regex)
        throws PatternSyntaxException
```
    Compiles an expression with default flags.
    
    Parameters:
    
    regex - the Perl5-compatible regular expression string.
    
    Throws:
    
    PatternSyntaxException - if the argument doesn't correspond to perl5 regex syntax.
    
    See Also:
    
    Pattern(java.lang.String, java.lang.String), Pattern(java.lang.String, int)
  - Pattern
```
public Pattern(String regex,
               String flags)
        throws PatternSyntaxException
```
    Compiles a regular expression using Perl5-style flags. The flag string should consist of letters 'i','m','s','x','u','X'(the case is significant) and a hyphen or plus. The meaning of letters:
    - i - case insensitivity, corresponds to REFlags.IGNORE_CASE;
    - m - multiline treatment(BOLs and EOLs affect the '^' and '$'), corresponds to REFlags.MULTILINE flag;
    - s - single line treatment('.' matches \r's and \n's),corresponds to REFlags.DOTALL;
    - x - extended whitespace comments (spaces and eols in the expression are ignored), corresponds to REFlags.IGNORE_SPACES.
    - u - predefined classes are regarded as belonging to Unicode, corresponds to REFlags.UNICODE; this may yield some performance penalty.
    - X - compatibility with XML Schema, corresponds to REFlags.XML_SCHEMA.
    - - - turn off the specified flags; normally has no effect unless something adds the flags.
    - + - turn on the specified flags; normally is no different from just using the letters.
    Parameters:
    
    regex - the Perl5-compatible regular expression string.
    
    flags - the Perl5-compatible flags.
    
    Throws:
    
    PatternSyntaxException - if the argument doesn't correspond to perl5 regex syntax. see REFlags
- Method Detail
  - compile
```
public static Pattern compile(String regex)
                       throws PatternSyntaxException
```
    Compiles the given String into a Pattern that can be used to match text. The syntax is normal for Java, including backslashes as part of regex syntax, like the digit shorthand "\d", escaped twice to "\\d" (so the double-quoted String itself doesn't try to interpret the backslash).
    
    Parameters:
    
    regex - a String in normal Java regular expression format
    
    Returns:
    
    a newly constructed Pattern object that can be used to match text that fits the given regular expression
    
    Throws:
    
    PatternSyntaxException
  - compile
```
public static Pattern compile(String regex,
                              int flags)
                       throws PatternSyntaxException
```
    Compiles the given String into a Pattern that can be used to match text. The syntax is normal for Java, including backslashes as part of regex syntax, like the digit shorthand "\d", escaped twice to "\\d" (so the double-quoted String itself doesn't try to interpret the backslash).
    This variant allows flags to be passed as an int constructed via bitwise OR from REFlags constants. You may prefer the variant that takes a String for clarity.
    
    Parameters:
    
    regex - a String in normal Java regular expression format
    
    flags - integer flags that are constructed via bitwise OR from the flag constants in REFlags.
    
    Returns:
    
    a newly constructed Pattern object that can be used to match text that fits the given regular expression
    
    Throws:
    
    PatternSyntaxException
  - compile
```
public static Pattern compile(String regex,
                              String flags)
                       throws PatternSyntaxException
```
    Compiles the given String into a Pattern that can be used to match text. The syntax is normal for Java, including backslashes as part of regex syntax, like the digit shorthand "\d", escaped twice to "\\d" (so the double-quoted String itself doesn't try to interpret the backslash).
    This variant allows flags to be passed as an String. The flag string should consist of letters 'i','m','s','x','u','X'(the case is significant) and a hyphen or plus. The meaning of letters:
    - i - case insensitivity, corresponds to REFlags.IGNORE_CASE;
    - m - multiline treatment(BOLs and EOLs affect the '^' and '$'), corresponds to REFlags.MULTILINE flag;
    - s - single line treatment('.' matches \r's and \n's),corresponds to REFlags.DOTALL;
    - x - extended whitespace comments (spaces and eols in the expression are ignored), corresponds to REFlags.IGNORE_SPACES.
    - u - predefined classes are regarded as belonging to Unicode, corresponds to REFlags.UNICODE; this may yield some performance penalty.
    - X - compatibility with XML Schema, corresponds to REFlags.XML_SCHEMA.
    - - - turn off the specified flags; normally has no effect unless something adds the flags.
    - + - turn on the specified flags; normally is no different from just using the letters.
    Parameters:
    
    regex - a String in normal Java regular expression format
    
    flags - integer flags that are constructed via bitwise OR from the flag constants in REFlags.
    
    Returns:
    
    a newly constructed Pattern object that can be used to match text that fits the given regular expression
    
    Throws:
    
    PatternSyntaxException
  - groupCount
```
public int groupCount()
```
    How many capturing groups does this expression include?
  - groupId
```
public Integer groupId(String name)
```
    Get numeric id for a group name.
    
    Returns:
    
    null if no such name found.
    
    See Also:
    
    MatchResult.group(java.lang.String), MatchResult.isCaptured(java.lang.String)
  - matches
```
public boolean matches(String s)
```
    A shorthand for Pattern.matcher(String).matches().
    
    Parameters:
    
    s - the target
    
    Returns:
    
    true if the entire target matches the pattern
    
    See Also:
    
    Matcher.matches(), Matcher.matches(String)
  - startsWith
```
public boolean startsWith(String s)
```
    A shorthand for Pattern.matcher(String).matchesPrefix().
    
    Parameters:
    
    s - the target
    
    Returns:
    
    true if the entire target matches the beginning of the pattern
    
    See Also:
    
    Matcher.matchesPrefix()
  - matcher
```
public Matcher matcher()
```
    Returns a target-less matcher. Don't forget to supply a target.
  - matcher
```
public Matcher matcher(CharSequence s)
```
    Returns a matcher for a specified string.
  - matcher
```
public Matcher matcher(char[] data,
                       int start,
                       int end)
```
    Returns a matcher for a specified region.
  - matcher
```
public Matcher matcher(MatchResult res,
                       int groupId)
```
    Returns a matcher for a match result (in a performance-friendly way). groupId parameter specifies which group is a target.
    
    Parameters:
    
    groupId - which group is a target; either positive integer(group id), or one of MatchResult.MATCH,MatchResult.PREFIX,MatchResult.SUFFIX,MatchResult.TARGET.
  - matcher
```
public Matcher matcher(MatchResult res,
                       String groupName)
```
    Just as above, yet with symbolic group name.
    
    Throws:
    
    NullPointerException - if there is no group with such name
  - matcher
```
public Matcher matcher(Reader text,
                       int length)
                throws IOException
```
    Returns a matcher taking a text stream as target. Note that this is not a true POSIX-style stream matching, i.e. the whole length of the text is preliminary read and stored in a char array.
    
    Parameters:
    
    text - a text stream
    
    length - the length to read from a stream; if len is -1, the whole stream is read in.
    
    Throws:
    
    IOException - indicates an IO problem
  - replacer
```
public Replacer replacer(String expr)
```
    Returns a replacer of a pattern by specified perl-like expression. Such replacer will substitute all occurrences of a pattern by an evaluated expression ("$&" and "$0" will substitute by the whole match, "$1" will substitute by group#1, etc). Example:
```
 String text="The quick brown fox jumped over the lazy dog";
 Pattern word=new Pattern("\\w+");
 System.out.println(word.replacer("[$&]").replace(text));
 //prints "[The] [quick] [brown] [fox] [jumped] [over] [the] [lazy] [dog]"
 Pattern swap=new Pattern("(fox|dog)(.*?)(fox|dog)");
 System.out.println(swap.replacer("$3$2$1").replace(text));
 //prints "The quick brown dog jumped over the lazy fox"
 Pattern scramble=new Pattern("(\\w+)(.*?)(\\w+)");
 System.out.println(scramble.replacer("$3$2$1").replace(text));
 //prints "quick The fox brown over jumped lazy the dog"
 
```
    Parameters:
    
    expr - a perl-like expression, the "$&" and "${&}" standing for whole match, the "$N" and "${N}" standing for group#N, and "${Foo}" standing for named group Foo.
    
    See Also:
    
    Replacer
  - replacer
```
public Replacer replacer(Substitution model)
```
    Returns a replacer will substitute all occurrences of a pattern through applying a user-defined substitution model.
    
    Parameters:
    
    model - a Substitution object which is in charge for match substitution
    
    See Also:
    
    Replacer
  - tokenizer
```
public RETokenizer tokenizer(String text)
```
    Tokenizes a text by an occurrences of the pattern. Note that a series of adjacent matches are regarded as a single separator. The same as new RETokenizer(Pattern,String);
    
    See Also:
    
    RETokenizer, RETokenizer.RETokenizer(regexodus.Pattern, java.lang.String)
  - tokenizer
```
public RETokenizer tokenizer(char[] data,
                             int off,
                             int len)
```
    Tokenizes a specified region by an occurrences of the pattern. Note that a series of adjacent matches are regarded as a single separator. The same as new RETokenizer(Pattern,char[],int,int);
    
    See Also:
    
    RETokenizer, RETokenizer.RETokenizer(regexodus.Pattern, char[], int, int)
  - tokenizer
```
public RETokenizer tokenizer(Reader in,
                             int length)
                      throws IOException
```
    Tokenizes a specified region by an occurrences of the pattern. Note that a series of adjacent matches are regarded as a single separator. The same as new RETokenizer(Pattern,Reader,int);
    
    Throws:
    
    IOException
    
    See Also:
    
    RETokenizer, RETokenizer.RETokenizer(regexodus.Pattern, java.io.Reader, int)
  - toString
```
public String toString()
```
    Overrides:
    
    toString in class Object
  - toString_d
```
public String toString_d()
```
    Returns a less or more readable representation of a bytecode for the pattern.
  - equals
```
public boolean equals(Object o)
```
    Overrides:
    
    equals in class Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class Object

Class Pattern

Field Summary

Fields inherited from interface regexodus.REFlags

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Pattern

Pattern

Pattern

Method Detail

compile

compile

compile

groupCount

groupId

matches

startsWith

matcher

matcher

matcher

matcher

matcher

matcher

replacer

replacer

tokenizer

tokenizer

tokenizer

toString

toString_d

equals

hashCode