FilenamePattern (Maverick Next Generation API - Packaging 2.0.0-SNAPSHOT API)

java.lang.Object
- com.sshtools.server.scp.FilenamePattern

All Implemented Interfaces:

FileFilter, FilenameFilter, Cloneable
```
public class FilenamePattern
extends Object
implements Cloneable, FileFilter, 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.

Since:

2003-02-09

Version:

$Revision: 1.5 $ $Date: 2008-07-08 09:11:55 $

Author:

David R. Tribble (david@tribble.com).
Copyright 2003 by David R. Tribble, all rights reserved.
Permission is granted to freely use and distribute this source code provided that the original copyright and authorship notices remain intact.

Field Summary

Fields
Modifier and Type	Field and Description
`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

Constructors
Constructor and Description
`FilenamePattern()` Default constructor.
`FilenamePattern(String pat)` Constructor.
`FilenamePattern(String pat, boolean ignCase)` Constructor.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`boolean`	`accept(File fname)` Determine if a filename matches the filename pattern.
`boolean`	`accept(File dir, String fname)` Determine if a filename matches the filename pattern.
`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(Object obj)` Compare this object to another.
`String`	`getPattern()` Retrieve the pattern for the filename pattern matcher.
`int`	`hashCode()` Calculate a hash code for this object.
`protected boolean`	`isValidPattern(String pat)` Determine if a filename pattern is well-formed.
`static void`	`main(String[] args)` Test driver for this class.
`boolean`	`matches(String fname)` Determine if a filename matches the filename pattern.
`static boolean`	`matches(String pat, String fname)` Determine if a filename matches a filename pattern.
`protected int`	`matchSubpattern(int patOff, 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(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(String pat)
```
    Constructor.
    
    Parameters:
    
    pat - A filename pattern.
    
    Throws:
    
    IllegalArgumentException - (unchecked) Thrown if pat is malformed.
    
    NullPointerException - (unchecked) Thrown if pat is null.
    
    Since:
    
    1.1, 2003-02-09
    
    See Also:
    
    setPattern()
  - FilenamePattern
```
public FilenamePattern(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:
    
    IllegalArgumentException - (unchecked) Thrown if pat is malformed.
    
    NullPointerException - (unchecked) Thrown if pat is null.
    
    Since:
    
    1.6, 2004-10-19
    
    See Also:
    
    setPattern(), setIgnoreCase()
- Method Detail
  - matches
```
public static boolean matches(String pat,
                              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:
    
    boolean True if fname matches pat, otherwise false.
    
    Throws:
    
    IllegalArgumentException - (unchecked) Thrown if pat is malformed.
    
    NullPointerException - (unchecked) Thrown if pat or fname is null.
    
    Since:
    
    1.1, 2003-02-09
  - main
```
public static void main(String[] args)
```
    Test driver for this class.
    Usage
    java tribble.util.FilenamePattern pattern filename result Where pattern is a filename pattern, filename is a filename, and result is the expected result, which is one of:
    
    t - True
    f - False
    m - Malformed pattern (java.lang.IllegalArgumentException)
    
    Parameters:
    
    args - Command line arguments.
    
    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:
    
    boolean 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 String getPattern()
```
    Retrieve the pattern for the filename pattern matcher.
    
    Returns:
    
    String 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(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:
    
    IllegalArgumentException - (unchecked) Thrown if pat is malformed.
    
    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:
    
    char The previous value for the special pattern matching character.
    
    Throws:
    
    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:
    
    boolean The previous setting for this pattern matcher.
    
    Since:
    
    1.1, 2003-02-09
  - matches
```
public boolean matches(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:
    
    boolean True if the pattern matches fname, otherwise false.
    
    Throws:
    
    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(File dir,
                      String fname)
```
    Determine if a filename matches the filename pattern.
    If this filename pattern matcher contains directory separator characters, it 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 FilenameFilter
    
    Parameters:
    
    dir - The pathname of the directory containing fname. (This pattern matcher implementation ignores this argument.)
    
    fname - A filename to match against the pattern.
    
    Returns:
    
    boolean True if the filename matches the pattern, otherwise false.
    
    Since:
    
    1.1, 2003-02-09
  - accept
```
public boolean accept(File fname)
```
    Determine if a filename matches the filename pattern.
    If this filename pattern matcher contains directory separator characters, it 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 FileFilter
    
    Parameters:
    
    fname - A filename to match against the pattern.
    
    Returns:
    
    boolean True if the filename matches the pattern, otherwise false.
    
    Since:
    
    1.1, 2003-02-09
  - equals
```
public boolean equals(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 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:
    
    boolean 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 Object
    
    Returns:
    
    int A hash code for this object.
    
    Since:
    
    1.7, 2004-10-21
  - clone
```
public 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 Object
    
    Returns:
    
    Object A filename pattern matcher with settings identical to this one.
    
    Since:
    
    1.7, 2004-10-21
  - isValidPattern
```
protected boolean isValidPattern(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:
    
    boolean True if pat is well-formed, otherwise false.
    
    Since:
    
    1.1, 2003-02-09
    
    See Also:
    
    setSpecialChar()
  - matchSubpattern
```
protected int matchSubpattern(int patOff,
                              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:
    
    int 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()

Class FilenamePattern

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

PAT_ESCAPE

PAT_ANY

PAT_CLOSURE

PAT_SET_OPEN

PAT_SET_CLOSE

PAT_SET_THRU

PAT_SET_EXCL

PAT_DIR_SEP

PAT_NEGATE

DIR_SEP1

DIR_SEP2

IGNORE_CASE

m_pat

m_ignoreCase

m_hasDirSep

m_escape

m_any

m_closure

m_setOpen

m_setClose

m_setThru

m_setExcl

m_dirSep

m_negate

Constructor Detail

FilenamePattern

FilenamePattern

FilenamePattern

Method Detail

matches

main

compareCharIgnoreCase

getPattern

setPattern

setSpecialChar

setIgnoreCase

matches

accept

accept

equals

hashCode

clone

isValidPattern

matchSubpattern