org.netbeans.spi.project.support.ant

Class PathMatcher

java.lang.Object

org.netbeans.spi.project.support.ant.PathMatcher

public final class PathMatcher
extends Object

Utility to match Ant-style file patterns with extended glob syntax.

A path matcher can be given an optional list of include patterns, and an optional list of exclude patterns. A given file path matches the pattern if it is matched by at least one include pattern (or there is a null includes list), and is not matched by any of the exclude patterns (if this list is not null).

The format is based on Ant patterns. Some details:

• A file path to be matched must be a /-separated relative path from an unspecified base directory. A path representing a folder must end in /, except for the path representing the root folder, which is the empty string. Thus, the full path to a file is always the simple concatenation of the path to its containing folder, and the file's basename.
• An include or exclude list, if not null, is a list of nonempty patterns separated by spaces and/or commas. It may be an empty list; this is equivalent to null in the case of excludes, but in the case of includes means that nothing matches.
• A pattern may use either / or \ as a path separator interchangeably.
• Most characters in a pattern match literally, and match a complete file path. A folder path ends in /, so the pattern foo will not match a folder named foo.
• * in a pattern matches zero or more characters within a path component (i.e. not including /).
• ** matches zero or more complete path components. It must be preceded by a slash (or be at the beginning of the pattern) and be followed by a slash (or be at the end of the pattern).
• foo/ is treated the same as foo/** and matches the whole tree rooted at the folder foo.
• /**/ can match just a single /. **/ and /** can match the empty string at path boundaries.

Some example patterns:

foo/bar/

The folder foo/bar and anything inside it.

foo/bar/baz

The file foo/bar/baz.

**/foo/

Any folder named foo and anything inside it.

**/*.java

Any Java source file (even in the default package).

Since:

org.netbeans.modules.project.ant/1 1.15

Constructor Summary

Constructors

Constructor and Description
PathMatcher(String includes, String excludes, File base) Create a path matching object.

Method Summary

Modifier and Type	Method and Description
Set<File>	findIncludedRoots() Find folders which match although their parent folders do not; or folders which do not match but which contain files which do.
boolean	matches(String path, boolean useKnownIncludes) Check whether a given path matches some includes (if not null) and no excludes.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PathMatcher

public PathMatcher(String includes,
                   String excludes,
                   File base)

Create a path matching object. It is faster to create one matcher and call PathMatcher.matches(java.lang.String, boolean) multiple times than to recreate a matcher for each query.

Parameters:

includes - a list of paths to match, or null to match everything by default

excludes - a list of paths to not match, or null

base - a base directory to scan for known include roots (see PathMatcher.findIncludedRoots()), or null if unknown

Method Detail

matches

public boolean matches(String path,
                       boolean useKnownIncludes)

Check whether a given path matches some includes (if not null) and no excludes.

Parameters:

path - a relative file path as described in class Javadoc

useKnownIncludes - true to also match in case this path is a parent of some known included root

Returns:

true for a match

findIncludedRoots

public Set<File> findIncludedRoots()
                            throws IllegalArgumentException

Find folders which match although their parent folders do not; or folders which do not match but which contain files which do.

• Wildcard-free folder include paths, such as foo/bar/ (or the equivalent foo/bar/**), are returned directly if they are not excluded.
• Wildcard-using paths trigger a scan of the provided root directory. Any actual files or folders found beneath that root which match are noted, and their minimal paths are returned.
• If a file matches but its containing folder does not, and the file exists, the folder is listed as an include root.
• If this matcher has a null includes list, just the root folder is returned.

Returns:

a set of minimal included folders

Throws:

IllegalArgumentException

toString

public String toString()

Overrides:

toString in class Object