tribble.util
Class FilenamePattern

java.lang.Object
  extended by tribble.util.FilenamePattern
All Implemented Interfaces:
java.io.FileFilter, java.io.FilenameFilter, java.lang.Cloneable

public class FilenamePattern
extends java.lang.Object
implements java.lang.Cloneable, java.io.FileFilter, java.io.FilenameFilter

Filename pattern matcher.

A filename pattern is a kind of regular expression that is used for matching filenames.

The matches() method is used to match a pattern against a filename. A static matches() method is also provided for convenience.

Methods accept(File) and accept(File, String) are also provided, which implement the java.io.FileFilter and java.io.FilenameFilter interfaces, respectively.


Filename Pattern Syntax

A filename pattern is composed of regular characters and special pattern matching characters, which are:

?
Matches any single character.

*
Matches zero or more characters.

[abc]
Matches a single character from character set {a,b,c}.

[a-b]
Matches a single character from the character range {a...b}. Note that character a must be lexicographically less than or equal to character b.

[^a]
Matches a single character that is not from character set or range {a}. Note that the ^ character must occur immediately to the right of the opening bracket.

/
Matches one or more directory path separator characters. This is sensitive to the underlying operating system, so that this will match the native directory path separator character for underlying system; for example, it will match '/' on Unix systems and match both '/' and '\' on MS-Windows systems. This makes it possible to use the same filename pattern on any operating system.

!pat
Negates the sense of the rest of pattern pat. For example, pattern "a*" matches filename "abc", but pattern "!a*" does not.

\c
Removes (escapes) any special meaning of character c.

The special pattern matching characters listed above are the default settings for a given filename pattern matcher object, but these can be changed by calling method setSpecialChar().

By default, a filename pattern matcher performs case-sensitive matching depending on the underlying operating system (e.g., matching is case-sensitive for Unix, but case-insensitive for MS/Windows). This behavior can be changed by calling method setIgnoreCase().

An empty string ("") is not a valid filename pattern.

No filename pattern matches an empty filename ("").


Examples

abc
Matches "abc". If case-insensitive matching is enabled, it also matches "Abc", "ABC", "aBc", etc.
a?c
Matches "abc", "a2c", "a.c", etc.
a*
Matches "a", "abc", "a3.p.txt", etc.
a.*
Matches "a.", "a.txt", "a.old.java", etc.
a*x
Matches "ax", "ab37x", "a.txt.x", etc.
*a*
Matches "a", "ax", "claw", "bra", etc.
a.[ch]
Matches "a.c" and "a.h".
a.[ch]??
Matches "a.cpp", "a.hxx", "a.hlp", etc.
a.[d-fm]
Matches "a.d", "a.e", "a.f", and "a.m".
a.[^a-cg-z0-9]
Matches "a.d", "a.e", "a.f", etc.
[mb][ey]*
Matches "me", "mybook", "be.o", "bean.cnt", "byebye", etc.
*.!c
Matches "foo.h", "a.java", etc., but not "foo.c", "a.c", etc.
a*!*x
Matches "aye", "axe7", "a.txt", etc., but not "bake", "ax", "abo.x", etc.
src/*.?
Matches "src/foo.c", "src/x.h", "src//b.o", etc.
*/*.txt
Matches "my/foo.txt", "/x.txt", "a//b.txt", etc.
/*/*.txt
Matches "/my/foo.txt", "//a//b.txt", etc.
!*
Degenerate case that does not match any filename.


References

This pattern matching implementation is based on the filename pattern matching of Unix (POSIX).

This pattern matching implementation is not based on the regular expression matching capabilities provided by the Java standard library (in JRE 1.4+, see java.lang.String.matches() for details).


Future Enhancements

A future revision of this code may support a special pattern of "**", which matches zero or more directory path prefixes.

Source code:
http://david.tribble.com/src/java/tribble/util/FilenamePattern.java
Documentation:
http://david.tribble.com/docs/tribble/util/FilenamePattern.html

Since:
2003-02-09
Version:
$Revision: 1.9 $ $Date: 2008/10/10 22:31:45 $
Author:
David R. Tribble (david@tribble.com).
Copyright 2003-2008 by David R. Tribble, all rights reserved.
Permission is granted to any person or entity except those designated by by the United States Department of State as a terrorist, or terrorist government or agency, to use and distribute this source code provided that the original copyright notice remains present and unaltered.

Field Summary
protected static char DIR_SEP1
          System-dependent directory path separator character (1).
protected static char DIR_SEP2
          System-dependent directory path separator character (2).
protected static boolean IGNORE_CASE
          System-dependent filename case-sensitivity flag.
protected  char m_any
          Special pattern character: Match any single character.
protected  char m_closure
          Special pattern character: Match zero or more characters.
protected  char m_dirSep
          Special pattern character: Directory path separator.
protected  char m_escape
          Special pattern character: Escape any special meaning.
protected  boolean m_hasDirSep
          This pattern contains directory path separator characters.
protected  boolean m_ignoreCase
          Ignore case when matching filenames.
protected  char m_negate
          Special pattern character: Negation.
protected  char[] m_pat
          Filename pattern.
protected  char m_setClose
          Special pattern character: Character set close.
protected  char m_setExcl
          Special pattern character: Character set exclusion.
protected  char m_setOpen
          Special pattern character: Character set open.
protected  char m_setThru
          Special pattern character: Character set range.
static char PAT_ANY
          Default pattern character: Any single character.
static char PAT_CLOSURE
          Default pattern character: Zero or more characters.
static char PAT_DIR_SEP
          Default pattern character: Directory path separator.
static char PAT_ESCAPE
          Default pattern character: Escape any special meaning.
static char PAT_NEGATE
          Default pattern character: Negation.
static char PAT_SET_CLOSE
          Default pattern character: Character set close.
static char PAT_SET_EXCL
          Default pattern character: Character set exclusion.
static char PAT_SET_OPEN
          Default pattern character: Character set open.
static char PAT_SET_THRU
          Default pattern character: Character set range.
 
Constructor Summary
FilenamePattern()
          Default constructor.
FilenamePattern(java.lang.String pat)
          Constructor.
FilenamePattern(java.lang.String pat, boolean ignCase)
          Constructor.
 
Method Summary
 boolean accept(java.io.File fname)
          Determine if a filename matches the filename pattern.
 boolean accept(java.io.File dir, java.lang.String fname)
          Determine if a filename matches the filename pattern.
 java.lang.Object clone()
          Clone this filename pattern matcher.
protected static boolean compareCharIgnoreCase(char ch, char lo, char hi)
          Determine if a character falls within a given character range, ignoring case.
 boolean equals(java.lang.Object obj)
          Compare this object to another.
 java.lang.String getPattern()
          Retrieve the pattern for the filename pattern matcher.
 int hashCode()
          Calculate a hash code for this object.
protected  boolean isValidPattern(java.lang.String pat)
          Determine if a filename pattern is well-formed.
 boolean matches(java.lang.String fname)
          Determine if a filename matches the filename pattern.
static boolean matches(java.lang.String pat, java.lang.String fname)
          Determine if a filename matches a filename pattern.
protected  int matchSubpattern(int patOff, java.lang.String fname, int fnameOff)
          Determine if a filename substring matches a pattern substring.
 boolean setIgnoreCase(boolean flag)
          Establish whether or not the filename pattern matcher ignores case.
 void setPattern(java.lang.String pat)
          Establish the pattern for the filename pattern matcher.
 char setSpecialChar(int type, char ch)
          Modify a special pattern matching character for the filename pattern matcher.
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PAT_ESCAPE

public static final char PAT_ESCAPE
Default pattern character: Escape any special meaning.

See Also:
Constant Field Values

PAT_ANY

public static final char PAT_ANY
Default pattern character: Any single character.

See Also:
Constant Field Values

PAT_CLOSURE

public static final char PAT_CLOSURE
Default pattern character: Zero or more characters.

See Also:
Constant Field Values

PAT_SET_OPEN

public static final char PAT_SET_OPEN
Default pattern character: Character set open.

See Also:
Constant Field Values

PAT_SET_CLOSE

public static final char PAT_SET_CLOSE
Default pattern character: Character set close.

See Also:
Constant Field Values

PAT_SET_THRU

public static final char PAT_SET_THRU
Default pattern character: Character set range.

See Also:
Constant Field Values

PAT_SET_EXCL

public static final char PAT_SET_EXCL
Default pattern character: Character set exclusion.

See Also:
Constant Field Values

PAT_DIR_SEP

public static final char PAT_DIR_SEP
Default pattern character: Directory path separator.

See Also:
Constant Field Values

PAT_NEGATE

public static final char PAT_NEGATE
Default pattern character: Negation.

See Also:
Constant Field Values

DIR_SEP1

protected static final char DIR_SEP1
System-dependent directory path separator character (1).


DIR_SEP2

protected static final char DIR_SEP2
System-dependent directory path separator character (2).


IGNORE_CASE

protected static final boolean IGNORE_CASE
System-dependent filename case-sensitivity flag.


m_pat

protected char[] m_pat
Filename pattern. This is stored as a character array instead of a String object to achieve a slight improvement in speed.


m_ignoreCase

protected boolean m_ignoreCase
Ignore case when matching filenames.


m_hasDirSep

protected boolean m_hasDirSep
This pattern contains directory path separator characters.


m_escape

protected char m_escape
Special pattern character: Escape any special meaning.


m_any

protected char m_any
Special pattern character: Match any single character.


m_closure

protected char m_closure
Special pattern character: Match zero or more characters.


m_setOpen

protected char m_setOpen
Special pattern character: Character set open.


m_setClose

protected char m_setClose
Special pattern character: Character set close.


m_setThru

protected char m_setThru
Special pattern character: Character set range.


m_setExcl

protected char m_setExcl
Special pattern character: Character set exclusion.


m_dirSep

protected char m_dirSep
Special pattern character: Directory path separator.


m_negate

protected char m_negate
Special pattern character: Negation.

Constructor Detail

FilenamePattern

public FilenamePattern()
Default constructor.

Since:
1.1, 2003-02-09
See Also:
setPattern()

FilenamePattern

public FilenamePattern(java.lang.String pat)
Constructor.

Parameters:
pat - A filename pattern.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if pat is malformed.
java.lang.NullPointerException - (unchecked) Thrown if pat is null.
Since:
1.1, 2003-02-09
See Also:
setPattern()

FilenamePattern

public FilenamePattern(java.lang.String pat,
                       boolean ignCase)
Constructor.

Parameters:
pat - A filename pattern.
ignCase - If true, case is ignored when matching alphabetic characters in filenames (e.g, the names "abc", "Abc", and "ABC" all compare equal); if false, filename comparisons are case-sensitive and alphabetic characters must match exactly.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if pat is malformed.
java.lang.NullPointerException - (unchecked) Thrown if pat is null.
Since:
1.6, 2004-10-19
See Also:
setPattern(), setIgnoreCase()
Method Detail

matches

public static boolean matches(java.lang.String pat,
                              java.lang.String fname)
Determine if a filename matches a filename pattern.

Note

The filename is matched against a filename pattern matcher that uses the default settings for its special pattern matching characters.

Parameters:
pat - A filename pattern string.
fname - A filename to compare against pat. Note that empty filenames ("") are not matched by any filename pattern.
Returns:
True if fname matches pat, otherwise false.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if pat is malformed.
java.lang.NullPointerException - (unchecked) Thrown if pat or fname is null.
Since:
1.1, 2003-02-09

compareCharIgnoreCase

protected static boolean compareCharIgnoreCase(char ch,
                                               char lo,
                                               char hi)
Determine if a character falls within a given character range, ignoring case.

Note that this method might exhibit slightly different behavior than the String.compareToIgnoreCase() method for certain regional characters.

Parameters:
ch - A character to compare.
lo - The lower character value in the range to compare.
hi - The upper character value in the range to compare.
Returns:
True if character ch falls within the range [lo,hi], ignoring case, otherwise false.
Since:
1.2, 2003-07-04
See Also:
matchSubpattern()

getPattern

public java.lang.String getPattern()
Retrieve the pattern for the filename pattern matcher.

Returns:
The filename pattern for this pattern matcher. Note that this will be null if the pattern has not been established yet.
Since:
1.7, 2004-10-21
See Also:
setPattern()

setPattern

public void setPattern(java.lang.String pat)
Establish the pattern for the filename pattern matcher.

This method is provided so that this filename pattern matcher can be reused with different patterns.

Parameters:
pat - A filename pattern. This is verified to be a well-formed pattern, using the current special character settings of the filename pattern.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if pat is malformed.
java.lang.NullPointerException - (unchecked) Thrown if pat is null.
Since:
1.1, 2003-02-09
See Also:
getPattern()

setSpecialChar

public char setSpecialChar(int type,
                           char ch)
Modify a special pattern matching character for the filename pattern matcher.

This method should be called prior to calling setPattern().

Parameters:
type - The type of the special pattern matching character to be modified, which is one of the PAT_XXX constants.
ch - The character to use as the special pattern matching character. If this character is '\0' (NUL), the pattern matcher will not recognize any character as the special pattern matching character of type type, effectively disabling that kind of pattern matching.
Returns:
The previous value for the special pattern matching character.
Throws:
java.lang.IllegalArgumentException - (unchecked) Thrown if type is not a valid special pattern character type.
Since:
1.1, 2003-02-09

setIgnoreCase

public boolean setIgnoreCase(boolean flag)
Establish whether or not the filename pattern matcher ignores case. (By default, the case-sensitivity of a pattern matcher is dependent upon the underlying operating system.)

Parameters:
flag - If true, upper and lower case letters are considered to be identical when matching filenames (e.g., filenames "abc", "Abc", and "ABC" will all be considered to be the same filename). If false, the pattern matcher is case-sensitive, and equivalent upper and lower case letters are considered to be different.
Returns:
The previous setting for this pattern matcher.
Since:
1.1, 2003-02-09

matches

public boolean matches(java.lang.String fname)
Determine if a filename matches the filename pattern.

Parameters:
fname - A filename to match against the filename pattern. Note that empty filenames ("") are not matched by any filename pattern.
Returns:
True if the pattern matches fname, otherwise false.
Throws:
java.lang.NullPointerException - (unchecked) Thrown if fname is null, or if this pattern matcher does not have a filename pattern established.
Since:
1.1, 2003-02-09

accept

public boolean accept(java.io.File dir,
                      java.lang.String fname)
Determine if a filename matches the filename pattern.

If the filename pattern contains directory separator characters, this attempts to match the full pathname formed by concatenating the directory name dir with the filename fname. Otherwise it attempts to match only the filename, ignoring the directory name.

Specified by:
accept in interface java.io.FilenameFilter
Parameters:
dir - The pathname of the directory containing fname.
fname - A filename to match against the pattern.
Returns:
True if the filename matches the pattern, otherwise false.
Since:
1.1, 2003-02-09

accept

public boolean accept(java.io.File fname)
Determine if a filename matches the filename pattern.

If the filename pattern contains directory separator characters, this attempts to match the entire pathname of the given filename. Otherwise it attempts to match only the filename portion, ignoring the directory prefix.

Specified by:
accept in interface java.io.FileFilter
Parameters:
fname - A filename to match against the pattern.
Returns:
True if the filename matches the pattern, otherwise false.
Since:
1.1, 2003-02-09

equals

public boolean equals(java.lang.Object obj)
Compare this object to another.

Note

Two filename pattern matchers are considered the same (equal) if they have identical internal patterns and identical control settings.

Overrides:
equals in class java.lang.Object
Parameters:
obj - Another object to compare this one to. If obj is not a FilenamePattern or one of its subtypes, it cannot be equal to this object.
Returns:
True if this object is identical to obj, otherwise false.
Since:
1.7, 2004-10-21

hashCode

public int hashCode()
Calculate a hash code for this object.

Note

Two filename pattern matchers are considered the same (equal) if they have identical internal patterns and identical control settings.

Overrides:
hashCode in class java.lang.Object
Returns:
A hash code for this object.
Since:
1.7, 2004-10-21

clone

public java.lang.Object clone()
Clone this filename pattern matcher.

Note

The internal pattern is shared by both this pattern matcher and the newly created clone object. If the internal pattern is to be modified by a method in a subclass of this class, this method must be overridden so that the clone gets its own copy of the internal pattern which it can then freely modify. (Calling method setPattern() endows a pattern matcher with an entirely new internal pattern, of course).

Overrides:
clone in class java.lang.Object
Returns:
A filename pattern matcher with settings identical to this one.
Since:
1.7, 2004-10-21

isValidPattern

protected boolean isValidPattern(java.lang.String pat)
Determine if a filename pattern is well-formed. The current special character settings of the filename pattern are used.

Parameters:
pat - A filename pattern to verify.
Returns:
True if pat is well-formed, otherwise false.
Since:
1.1, 2003-02-09
See Also:
setSpecialChar()

matchSubpattern

protected int matchSubpattern(int patOff,
                              java.lang.String fname,
                              int fnameOff)
Determine if a filename substring matches a pattern substring.

Note

The pattern string (m_pat) should be well-formed, otherwise the pattern matching algorithm will become confused.

Parameters:
patOff - The index of the first (leftmost) character within the pattern to match.
fname - A filename string to compare against the pattern. Note that empty filenames ("") are not matched by any filename pattern.
fnameOff - The index of the first (leftmost) character within string fname to match.
Returns:
The index of one character past the last (rightmost) character within filename string fname that matches the pattern, or a negative value if the filename substring does not match the pattern substring.
Since:
1.1, 2003-02-09
See Also:
matches(), compareCharIgnoreCase()