System.FilePath.Glob

A library for globbing: matching patterns against file paths.

Basic usage: match (compile pattern) filepath.

Basic usage in IO: globDir [compile pattern] directory.

Data type

data Pattern

An abstract data type representing a compiled pattern.

The Show instance is essentially the inverse of compile. Though it may not return exactly what was given to compile it will return code which produces the same Pattern.

Note that the Eq instance cannot tell you whether two patterns behave in the same way; only whether they compile to the same Pattern. For instance, compile "x" and compile "[x]" may or may not compare equal, though a match will behave the exact same way no matter which Pattern is used.

Instances

Eq Pattern

Show Pattern

Functions

Compilation

tryCompile :: String -> Either String Pattern

Compiles a glob pattern from its textual representation into a Pattern object, giving an error message in a Left if the pattern is erroneous.

For the most part, a character matches itself. Recognized operators are as follows:

?

Matches any character except path separators.

*

Matches any number of characters except path separators, including the empty string.

[..]

Matches any of the enclosed characters. Ranges of characters can be specified by separating the endpoints with a '-'. '-' or ']' can be matched by including them as the first character(s) in the list.

[^..] or [!..]

Like [..], but matches any character not listed.

<m-n>

Matches any integer in the range m to n, inclusive. The range may be open-ended by leaving out either number: "<->", for instance, matches any integer.

**/

Matches any number of characters, including path separators, excluding the empty string.

Note that path separators (typically '/') have to be matched explicitly or using the **/ pattern. In addition, extension separators (typically '.') have to be matched explicitly at the beginning of the pattern or after any path separator.

If a system supports multiple path separators, any one of them will match any of them. For instance, on Windows, '/' will match itself as well as '\'.

Erroneous patterns include:

• An empty [] or [^] or [!]
• A [ or < without a matching ] or >
• A malformed <>: e.g. nonnumeric characters or no hyphen

compile :: String -> Pattern

Like tryCompile, but calls error if an error results.

Matching

match :: Pattern -> FilePath -> Bool

Matches the given Pattern against the given FilePath, returning True if the pattern matches and False otherwise.

globDir :: [Pattern] -> FilePath -> IO ([[FilePath]], [FilePath])

Matches each given Pattern against the contents of the given FilePath, recursively. The result pair's first component contains the matched paths, grouped for each given Pattern, and the second contains all paths which were not matched by any Pattern.

If multiple Patterns match a single FilePath, that path will be included in multiple groups.

This function is different from a simple filter over all the contents of the directory: the matching is performed relative to the directory, so that for instance the following is true:

 fmap (head.fst) (globDir [compile "*"] dir) == getDirectoryContents dir

If dir is "foo" the pattern should be "foo/*" to get the same results with a plain filter.

Any results deeper than in the given directory are enumerated lazily, using unsafeInterleaveIO.