public final class Perl5Util extends Object implements MatchResult
The objective of the class is to minimize the amount of code a Java
programmer using Jakarta-ORO
has to write to achieve the same results as Perl by
transparently handling regular expression compilation, caching, and
matching. A second objective is to use the same Perl pattern matching
syntax to ease the task of Perl programmers transitioning to Java
(this also reduces the number of parameters to a method).
All the state affecting methods are synchronized to avoid
the maintenance of explicit locks in multithreaded programs. This
philosophy differs from the
org.apache.oro.text.regex package, where
you are expected to either maintain explicit locks, or more preferably
create separate compiler and matcher instances for each thread.
To use this class, first create an instance using the default constructor or initialize the instance with a PatternCache of your choosing using the alternate constructor. The default cache used by Perl5Util is a PatternCacheLRU of capacity GenericPatternCache.DEFAULT_CAPACITY. You may want to create a cache with a different capacity, a different cache replacement policy, or even devise your own PatternCache implementation. The PatternCacheLRU is probably the best general purpose pattern cache, but your specific application may be better served by a different cache replacement policy. You should remember that you can front-load a cache with all the patterns you will be using before initializing a Perl5Util instance, or you can just let Perl5Util fill the cache as you use it.
You might use the class as follows:
Perl5Util util = new Perl5Util();
String line;
DataInputStream input;
PrintStream output;
// Initialization of input and output omitted
while((line = input.readLine()) != null) {
// First find the line with the string we want to substitute because
// it is cheaper than blindly substituting each line.
if(util.match("/HREF=\"description1.html\"/")) {
line = util.substitute("s/description1\\.html/about1.html/", line);
}
output.println(line);
}
A couple of things to remember when using this class are that the
match() methods have the same meaning as
Perl5Matcher.contains()
and =~ m/pattern/ in Perl. The methods are named match
to more closely associate them with Perl and to differentiate them
from Perl5Matcher.matches().
A further thing to keep in mind is that the
MalformedPerl5PatternException class is derived from
RuntimeException which means you DON'T have to catch it. The reasoning
behind this is that you will detect your regular expression mistakes
as you write and debug your program when a MalformedPerl5PatternException
is thrown during a test run. However, we STRONGLY recommend that you
ALWAYS catch MalformedPerl5PatternException whenever you deal with a
DYNAMICALLY created pattern. Relying on a fatal
MalformedPerl5PatternException being thrown to detect errors while
debugging is only useful for dealing with static patterns, that is, actual
pregenerated strings present in your program. Patterns created from user
input or some other dynamic method CANNOT be relied upon to be correct
and MUST be handled by catching MalformedPerl5PatternException for your
programs to be robust.
Finally, as a convenience Perl5Util implements
the MatchResult interface.
The methods are merely wrappers which call the corresponding method of
the last MatchResult
found (which can be accessed with getMatch()) by a match or
substitution (or even a split, but this isn't particularly useful).
At the moment, the
MatchResult returned
by getMatch() is not stored in a thread-local variable. Therefore
concurrent calls to getMatch() will produce unpredictable
results. So if your concurrent program requires the match results,
you must protect the matching and the result retrieval in a critical
section. If you do not need match results, you don't need to do anything
special. If you feel the J2SE implementation of getMatch()
should use a thread-local variable and obviate the need for a critical
section, please express your views on the oro-dev mailing list.
MalformedPerl5PatternException,
PatternCache,
PatternCacheLRU,
MatchResult| 限定符和类型 | 字段和说明 |
|---|---|
static int |
SPLIT_ALL
A constant passed to the
split() methods indicating
that all occurrences of a pattern should be used to split a string. |
| 构造器和说明 |
|---|
Perl5Util()
Default constructor for Perl5Util.
|
Perl5Util(PatternCache cache)
A secondary constructor for Perl5Util.
|
| 限定符和类型 | 方法和说明 |
|---|---|
int |
begin(int group)
Returns the begin offset of the subgroup of the last match found
relative the beginning of the match.
|
int |
beginOffset(int group)
Returns an offset marking the beginning of the last pattern match
found relative to the beginning of the input from which the match
was extracted.
|
int |
end(int group)
Returns the end offset of the subgroup of the last match found
relative the beginning of the match.
|
int |
endOffset(int group)
Returns an offset marking the end of the last pattern match found
relative to the beginning of the input from which the match was
extracted.
|
MatchResult |
getMatch()
Returns the last match found by a call to a match(), substitute(), or
split() method.
|
String |
group(int group)
Returns the contents of the parenthesized subgroups of the last match
found according to the behavior dictated by the MatchResult interface.
|
int |
groups() |
int |
length()
Returns the length of the last match found.
|
boolean |
match(String pattern,
char[] input)
Searches for the first pattern match somewhere in a character array
taking a pattern specified in Perl5 native format:
[m]/pattern/[i][m][s][x]
The
m prefix is optional and the meaning of the optional
trailing options are:
|
boolean |
match(String pattern,
PatternMatcherInput input)
Searches for the next pattern match somewhere in a
org.apache.oro.text.regex.PatternMatcherInput instance, taking
a pattern specified in Perl5 native format:
[m]/pattern/[i][m][s][x]
The
m prefix is optional and the meaning of the optional
trailing options are:
|
boolean |
match(String pattern,
String input)
Searches for the first pattern match in a String taking
a pattern specified in Perl5 native format:
[m]/pattern/[i][m][s][x]
The
m prefix is optional and the meaning of the optional
trailing options are:
|
String |
postMatch()
Returns the part of the input following the last match found.
|
char[] |
postMatchCharArray()
Returns the part of the input following the last match found as a char
array.
|
String |
preMatch()
Returns the part of the input preceding the last match found.
|
char[] |
preMatchCharArray()
Returns the part of the input preceding the last match found as a
char array.
|
void |
split(Collection results,
String input)
Splits input in the default Perl manner, splitting on all whitespace.
|
void |
split(Collection results,
String pattern,
String input)
This method is identical to calling:
split(results, pattern, input, SPLIT_ALL);
|
void |
split(Collection results,
String pattern,
String input,
int limit)
Splits a String into strings that are appended to a List, but no more
than a specified limit.
|
Vector |
split(String input)
已过时。
Use
split(Collection results, String input) instead. |
Vector |
split(String pattern,
String input)
已过时。
|
Vector |
split(String pattern,
String input,
int limit)
已过时。
|
int |
substitute(StringBuffer result,
String expression,
String input)
Substitutes a pattern in a given input with a replacement string.
|
String |
substitute(String expression,
String input)
Substitutes a pattern in a given input with a replacement string.
|
String |
toString()
Returns the same as group(0).
|
public Perl5Util(PatternCache cache)
// We know we're going to use close to 50 expressions a whole lot, so // we create a cache of the proper size. util = new Perl5Util(new PatternCacheLRU(50));or
// We're only going to use a few expressions and know that second-chance // fifo is best suited to the order in which we are using the patterns. util = new Perl5Util(new PatternCacheFIFO2(10));
public Perl5Util()
public boolean match(String pattern, char[] input) throws MalformedPerl5PatternException
The[m]/pattern/[i][m][s][x]
m prefix is optional and the meaning of the optional
trailing options are:
If the input contains the pattern, the org.apache.oro.text.regex.MatchResult
can be obtained by calling getMatch().
However, Perl5Util implements the MatchResult interface as a wrapper
around the last MatchResult found, so you can call its methods to
access match information.
pattern - The pattern to search for.input - The char[] input to search.MalformedPerl5PatternException - If there is an error in
the pattern. You are not forced to catch this exception
because it is derived from RuntimeException.public boolean match(String pattern, String input) throws MalformedPerl5PatternException
The[m]/pattern/[i][m][s][x]
m prefix is optional and the meaning of the optional
trailing options are:
If the input contains the pattern, the
MatchResult
can be obtained by calling getMatch().
However, Perl5Util implements the MatchResult interface as a wrapper
around the last MatchResult found, so you can call its methods to
access match information.
pattern - The pattern to search for.input - The String input to search.MalformedPerl5PatternException - If there is an error in
the pattern. You are not forced to catch this exception
because it is derived from RuntimeException.public boolean match(String pattern, PatternMatcherInput input) throws MalformedPerl5PatternException
The[m]/pattern/[i][m][s][x]
m prefix is optional and the meaning of the optional
trailing options are:
If the input contains the pattern, the
MatchResult
can be obtained by calling getMatch().
However, Perl5Util implements the MatchResult interface as a wrapper
around the last MatchResult found, so you can call its methods to
access match information.
After the call to this method, the PatternMatcherInput current offset
is advanced to the end of the match, so you can use it to repeatedly
search for expressions in the entire input using a while loop as
explained in the PatternMatcherInput documentation.
pattern - The pattern to search for.input - The PatternMatcherInput to search.MalformedPerl5PatternException - If there is an error in
the pattern. You are not forced to catch this exception
because it is derived from RuntimeException.public MatchResult getMatch()
public int substitute(StringBuffer result, String expression, String input) throws MalformedPerl5PatternException
Thes/pattern/replacement/[g][i][m][o][s][x]
s prefix is mandatory and the meaning of the optional
trailing options are:
Util.substitute().
The default is to compute each interpolation independently.
See
Util.substitute()
and Perl5Substitution
for more details on variable interpolation in
substitutions.
when you could more easily write:numSubs = util.substitute(result, "s/foo\\/bar/goo\\/\\/baz/", input);
where the hashmarks are used instead of slashes.numSubs = util.substitute(result, "s#foo/bar#goo//baz#", input);
There is a special case of backslashing that you need to pay attention to. As demonstrated above, to denote a delimiter in the substituted string it must be backslashed. However, this can be a problem when you want to denote a backslash at the end of the substituted string. As of PerlTools 1.3, a new means of handling this situation has been implemented. In previous versions, the behavior was that
"... a double backslash (quadrupled in the Java String) always represents two backslashes unless the second backslash is followed by the delimiter, in which case it represents a single backslash."
The new behavior is that a backslash is always a backslash in the substitution portion of the expression unless it is used to escape a delimiter. A backslash is considered to escape a delimiter if an even number of contiguous backslashes preceed the backslash and the delimiter following the backslash is not the FINAL delimiter in the expression. Therefore, backslashes preceding final delimiters are never considered to escape the delimiter. The following, which used to be an invalid expression and require a special-case extra backslash, will now replace all instances of / with \:
numSubs = util.substitute(result, "s#/#\\#g", input);
result - The StringBuffer in which to store the result of the
substitutions. The buffer is only appended to.expression - The Perl5 substitution regular expression.input - The input on which to perform substitutions.MalformedPerl5PatternException - If there is an error in
the expression. You are not forced to catch this exception
because it is derived from RuntimeException.public String substitute(String expression, String input) throws MalformedPerl5PatternException
String result;
StringBuffer buffer = new StringBuffer();
perl.substitute(buffer, expression, input);
result = buffer.toString();
expression - The Perl5 substitution regular expression.input - The input on which to perform substitutions.MalformedPerl5PatternException - If there is an error in
the expression. You are not forced to catch this exception
because it is derived from RuntimeException.substitute(java.lang.StringBuffer, java.lang.String, java.lang.String)public void split(Collection results, String pattern, String input, int limit) throws MalformedPerl5PatternException
The[m]/pattern/[i][m][s][x]
m prefix is optional and the meaning of the optional
trailing options are:
The limit parameter causes the string to be split on at most the first limit - 1 number of pattern occurences.
Of special note is that this split method performs EXACTLY the same as the Perl split() function. In other words, if the split pattern contains parentheses, additional Vector elements are created from each of the matching subgroups in the pattern. Using an example similar to the one from the Camel book:
produces the Vector containing:split(list, "/([,-])/","8-12,15,18")
{"8","-","12",",","15",",","18" }
Util.split() method
does NOT implement these behaviors because it is intended to
be a general self-consistent and predictable split function usable
with Pattern instances other than Perl5Pattern.
results - A Collection to which the substrings of the input
that occur between the regular expression delimiter occurences
are appended. The input will not be split into any more substrings
than the specified
limit. A way of thinking of this is that only the first
limit - 1
matches of the delimiting regular expression will be used to split the
input. The Collection must support the
addAll(Collection) operation.pattern - The regular expression to use as a split delimiter.input - The String to split.limit - The limit on the size of the returned Vector.
Values <= 0 produce the same behavior as the SPLIT_ALL constant which
causes the limit to be ignored and splits to be performed on all
occurrences of the pattern. You should use the SPLIT_ALL constant
to achieve this behavior instead of relying on the default behavior
associated with non-positive limit values.MalformedPerl5PatternException - If there is an error in
the expression. You are not forced to catch this exception
because it is derived from RuntimeException.public void split(Collection results, String pattern, String input) throws MalformedPerl5PatternException
split(results, pattern, input, SPLIT_ALL);
public void split(Collection results, String input) throws MalformedPerl5PatternException
split(results, "/\\s+/", input);
public Vector split(String pattern, String input, int limit) throws MalformedPerl5PatternException
split(Collection results, String pattern, String input, int limit)
instead.The[m]/pattern/[i][m][s][x]
m prefix is optional and the meaning of the optional
trailing options are:
The limit parameter causes the string to be split on at most the first limit - 1 number of pattern occurences.
Of special note is that this split method performs EXACTLY the same as the Perl split() function. In other words, if the split pattern contains parentheses, additional Vector elements are created from each of the matching subgroups in the pattern. Using an example similar to the one from the Camel book:
split("/([,-])/","8-12,15,18")
{"8","-","12",",","15",",","18" }
Util.split() method
does NOT implement this particular behavior because it is intended to
be usable with Pattern instances other than Perl5Pattern.
pattern - The regular expression to use as a split delimiter.input - The String to split.limit - The limit on the size of the returned Vector.
Values <= 0 produce the same behavior as the SPLIT_ALL constant which
causes the limit to be ignored and splits to be performed on all
occurrences of the pattern. You should use the SPLIT_ALL constant
to achieve this behavior instead of relying on the default behavior
associated with non-positive limit values. Vector containing the substrings of the input
that occur between the regular expression delimiter occurences. The
input will not be split into any more substrings than the specified
limit. A way of thinking of this is that only the first
limit - 1
matches of the delimiting regular expression will be used to split the
input.MalformedPerl5PatternException - If there is an error in
the expression. You are not forced to catch this exception
because it is derived from RuntimeException.public Vector split(String pattern, String input) throws MalformedPerl5PatternException
split(Collection results, String pattern, String input) instead.split(pattern, input, SPLIT_ALL);
public Vector split(String input) throws MalformedPerl5PatternException
split(Collection results, String input) instead.
split("/\\s+/", input);
public int length()
length 在接口中 MatchResultpublic int groups()
groups 在接口中 MatchResultpublic String group(int group)
group 在接口中 MatchResultgroup - The pattern subgroup to return.public int begin(int group)
begin 在接口中 MatchResultgroup - The pattern subgroup.public int end(int group)
end 在接口中 MatchResultgroup - The pattern subgroup.public int beginOffset(int group)
beginOffset 在接口中 MatchResultgroup - The pattern subgroup.public int endOffset(int group)
endOffset 在接口中 MatchResultgroup - The pattern subgroup.public String toString()
toString 在接口中 MatchResulttoString 在类中 Objectpublic String preMatch()
public String postMatch()
public char[] preMatchCharArray()
public char[] postMatchCharArray()
Copyright © 2024. All rights reserved.