tribble.util
Class FilenamePattern

java.lang.Object
  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()