org.apache.oro.text

Class GlobCompiler

public final class GlobCompiler extends Object implements PatternCompiler

The GlobCompiler class will compile a glob expression into a Perl5Pattern that may be used to match patterns in conjunction with Perl5Matcher. Rather than create extra GlobMatcher and GlobPattern classes tailored to the task of matching glob expressions, we have simply reused the Perl5 regular expression classes from org.apache.oro.text.regex by making GlobCompiler translate a glob expression into a Perl5 expression that is compiled by a Perl5Compiler instance internal to the GlobCompiler.

Because there are various similar glob expression syntaxes, GlobCompiler tries to provide a small amount of customization by providing the STAR_CANNOT_MATCH_NULL_MASK and QUESTION_MATCHES_ZERO_OR_ONE_MASK compilation options.

The GlobCompiler expression syntax is based on Unix shell glob expressions but should be usable to simulate Win32 wildcards. The following syntax is supported:

Please remember that the when you construct a Java string in Java code, the backslash character is itself a special Java character, and it must be double backslashed to represent single backslash in a regular expression.

Since: 1.0

Version: 2.0.8

See Also: PatternCompiler Perl5Matcher

Field Summary
static intCASE_INSENSITIVE_MASK
A mask passed as an option to the compile methods to indicate a compiled glob expression should be case insensitive.
static intDEFAULT_MASK
The default mask for the compile methods.
static intQUESTION_MATCHES_ZERO_OR_ONE_MASK
A mask passed as an option to the compile methods to indicate that a ?
static intREAD_ONLY_MASK
A mask passed as an option to the compile methods to indicate that the resulting Perl5Pattern should be treated as a read only data structure by Perl5Matcher, making it safe to share a single Perl5Pattern instance among multiple threads without needing synchronization.
static intSTAR_CANNOT_MATCH_NULL_MASK
A mask passed as an option to the compile methods to indicate that a * should not be allowed to match the null string.
Constructor Summary
GlobCompiler()
The default GlobCompiler constructor.
Method Summary
Patterncompile(char[] pattern, int options)
Compiles a Glob expression into a Perl5Pattern instance that can be used by a Perl5Matcher object to perform pattern matching.
Patterncompile(char[] pattern)
Same as calling compile(pattern, GlobCompiler.DEFAULT_MASK);

Patterncompile(String pattern)
Same as calling compile(pattern, GlobCompiler.DEFAULT_MASK);

Patterncompile(String pattern, int options)
Compiles a Glob expression into a Perl5Pattern instance that can be used by a Perl5Matcher object to perform pattern matching.
static StringglobToPerl5(char[] pattern, int options)
This static method is the basic engine of the Glob PatternCompiler implementation.

Field Detail

CASE_INSENSITIVE_MASK

public static final int CASE_INSENSITIVE_MASK
A mask passed as an option to the compile methods to indicate a compiled glob expression should be case insensitive.

DEFAULT_MASK

public static final int DEFAULT_MASK
The default mask for the compile methods. It is equal to 0. The default behavior is for a glob expression to be case sensitive unless it is compiled with the CASE_INSENSITIVE_MASK option.

QUESTION_MATCHES_ZERO_OR_ONE_MASK

public static final int QUESTION_MATCHES_ZERO_OR_ONE_MASK
A mask passed as an option to the compile methods to indicate that a ? should not be allowed to match the null string. The normal behavior of the ? metacharacter is that it may match any 1 character. This mask causes it to match 0 or 1 characters.

READ_ONLY_MASK

public static final int READ_ONLY_MASK
A mask passed as an option to the compile methods to indicate that the resulting Perl5Pattern should be treated as a read only data structure by Perl5Matcher, making it safe to share a single Perl5Pattern instance among multiple threads without needing synchronization. Without this option, Perl5Matcher reserves the right to store heuristic or other information in Perl5Pattern that might accelerate future matches. When you use this option, Perl5Matcher will not store or modify any information in a Perl5Pattern. Use this option when you want to share a Perl5Pattern instance among multiple threads using different Perl5Matcher instances.

STAR_CANNOT_MATCH_NULL_MASK

public static final int STAR_CANNOT_MATCH_NULL_MASK
A mask passed as an option to the compile methods to indicate that a * should not be allowed to match the null string. The normal behavior of the * metacharacter is that it may match any 0 or more characters. This mask causes it to match 1 or more characters of anything.

Constructor Detail

GlobCompiler

public GlobCompiler()
The default GlobCompiler constructor. It initializes an internal Perl5Compiler instance to compile translated glob expressions.

Method Detail

compile

public Pattern compile(char[] pattern, int options)
Compiles a Glob expression into a Perl5Pattern instance that can be used by a Perl5Matcher object to perform pattern matching.

Parameters: pattern A Glob expression to compile. options A set of flags giving the compiler instructions on how to treat the glob expression. The flags are a logical OR of any number of the 3 MASK constants. For example:

 regex =
   compiler.compile(pattern, GlobCompiler.
                    CASE_INSENSITIVE_MASK |
                    GlobCompiler.STAR_CANNOT_MATCH_NULL_MASK);
                 
This says to compile the pattern so that * cannot match the null string and to perform matches in a case insensitive manner.

Returns: A Pattern instance constituting the compiled expression. This instance will always be a Perl5Pattern and can be reliably casted to a Perl5Pattern.

Throws: MalformedPatternException If the compiled expression is not a valid Glob expression.

compile

public Pattern compile(char[] pattern)
Same as calling compile(pattern, GlobCompiler.DEFAULT_MASK);

Parameters: pattern A regular expression to compile.

Returns: A Pattern instance constituting the compiled regular expression. This instance will always be a Perl5Pattern and can be reliably casted to a Perl5Pattern.

Throws: MalformedPatternException If the compiled expression is not a valid Glob expression.

compile

public Pattern compile(String pattern)
Same as calling compile(pattern, GlobCompiler.DEFAULT_MASK);

Parameters: pattern A regular expression to compile.

Returns: A Pattern instance constituting the compiled regular expression. This instance will always be a Perl5Pattern and can be reliably casted to a Perl5Pattern.

Throws: MalformedPatternException If the compiled expression is not a valid Glob expression.

compile

public Pattern compile(String pattern, int options)
Compiles a Glob expression into a Perl5Pattern instance that can be used by a Perl5Matcher object to perform pattern matching.

Parameters: pattern A Glob expression to compile. options A set of flags giving the compiler instructions on how to treat the glob expression. The flags are a logical OR of any number of the 3 MASK constants. For example:

 regex =
   compiler.compile("*.*", GlobCompiler.
                    CASE_INSENSITIVE_MASK |
                    GlobCompiler.STAR_CANNOT_MATCH_NULL_MASK);
                 
This says to compile the pattern so that * cannot match the null string and to perform matches in a case insensitive manner.

Returns: A Pattern instance constituting the compiled expression. This instance will always be a Perl5Pattern and can be reliably casted to a Perl5Pattern.

Throws: MalformedPatternException If the compiled expression is not a valid Glob expression.

globToPerl5

public static String globToPerl5(char[] pattern, int options)
This static method is the basic engine of the Glob PatternCompiler implementation. It takes a glob expression in the form of a character array and converts it into a String representation of a Perl5 pattern. The method is made public so that programmers may use it for their own purposes. However, the GlobCompiler compile methods work by converting the glob pattern to a Perl5 pattern using this method, and then invoking the compile() method of an internally stored Perl5Compiler instance.

Parameters: pattern A character array representation of a Glob pattern.

Returns: A String representation of a Perl5 pattern equivalent to the Glob pattern.

Copyright B) 2000-2003 Apache Software Foundation. All Rights Reserved.