PathMatcher (Ant-Based Project Support) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

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

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

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

java.lang.Object
  org.netbeans.spi.project.support.ant.PathMatcher

public final class PathMatcher
extends Object
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

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

Method Summary

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 Summary
`PathMatcher(String includes, String excludes, File base)` Create a path matching object.

Method Summary
`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 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 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