A library for globbing: matching patterns against file paths akin to the
POSIX glob() function.
Pattern syntax is documented by compile. To toggle features at compile
time, look into CompOptions. To modify matching behaviour, look into
MatchOptions.
Matching a list of String patterns against all paths in a given directory,
returning the matches for each pattern as well as the paths not matched by
any of the patterns:
An abstract data type representing a compiled 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.
Compiles a glob pattern from its textual representation into a Pattern
object.
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. Never matches path separators:
[/]
matches
nothing at all. Named character classes can also be matched:
[:x:]
within
[]
specifies the class named
x
, which matches
certain predefined characters. See below for a full list.
[^..] or [!..]
Like
[..]
, but matches any character
not
listed.
Note that
[^-x]
is not the inverse of
[-x]
, but
the range
[^-x]
.
<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.
Supported character classes:
[:alnum:]
Equivalent to
"0-9A-Za-z"
.
[:alpha:]
Equivalent to
"A-Za-z"
.
[:blank:]
Equivalent to
"\t "
.
[:cntrl:]
Equivalent to
"\0-\x1f\x7f"
.
[:digit:]
Equivalent to
"0-9"
.
[:graph:]
Equivalent to
"!-~"
.
[:lower:]
Equivalent to
"a-z"
.
[:print:]
Equivalent to
" -~"
.
[:punct:]
Equivalent to
"!-/:-@[-`{-~"
.
[:space:]
Equivalent to
"\t-\r "
.
[:upper:]
Equivalent to
"A-Z"
.
[:xdigit:]
Equivalent to
"0-9A-Fa-f"
.
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
'\'.
Error recovery will be performed: erroneous operators will not be considered
operators, but matched as literal strings. Such operators include:
An empty [] or [^] or [!]
A [ or < without a matching ] or >
A malformed <>: e.g. nonnumeric characters or no hyphen
Decompiles a Pattern object into its textual representation: essentially
the inverse of compile.
Note, however, that due to internal optimization, decompile . compile is
not the identity function. Instead, compile . decompile is.
Be careful with CompOptions: decompile always produces a String which
can be passed to compile to get back the same Pattern. compileWith
options . decompile is not the identity function unless options is
compDefault.
Simplifies a Pattern object: removes redundant "./", for instance.
The resulting Pattern matches the exact same input as the original one,
with some differences:
The output of globDir will differ: for example, globbing for "./*"
gives "./foo", but after simplification this'll be only "foo".
Decompiling the simplified Pattern will obviously not give the original.
The simplified Pattern is a bit faster to match with and uses less
memory, since some redundant data is removed.
For the last of the above reasons, if you're performance-conscious and not
using globDir, you should always simplify after calling compile.
If true, a[/]b never matches anything (since character ranges can't
match path separators); if false and errorRecovery is enabled,
a[/]b matches itself, i.e. a file named ]b in the subdirectory
a[.
If the input is invalid, recover by turning any invalid part into
literals. For instance, with characterRanges enabled, [abc is an
error by default (unclosed character range); with errorRecovery, the
[ is turned into a literal match, as though characterRanges were
disabled.
Instances3Eq, Read, Show
EqCompOptionsDefined in Glob-0.10.2 · System.FilePath.Glob.Base
ReadCompOptionsDefined in Glob-0.10.2 · System.FilePath.Glob.Base
ShowCompOptionsDefined in Glob-0.10.2 · System.FilePath.Glob.Base
Matches each given Pattern against the contents of the given FilePath,
recursively. The result contains the matched paths, grouped for each given
Pattern. The results are not in any defined order.
The given directory is prepended to all the matches: the returned paths are
all valid from the point of view of the current working directory.
If multiple Patterns match a single FilePath, that path will be included
in multiple groups.
Two FilePaths which can be canonicalized to the same file (e.g. "foo"
and "./foo") may appear separately if explicit matching on paths
beginning with "." is done. Looking for ".*/*", for instance, will
cause "./foo" to return as a match but "foo" to not be matched.
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 (globDir [compile "*"] dir) == getDirectoryContents dir
(With the exception that that glob won't match anything beginning with ..)
If the given Pattern starts with a drive (as defined by
FilePath), it is not relative to the given directory and the
FilePath parameter is completely ignored! Similarly, if the given
Pattern starts with a path separator, only the drive part of the
FilePath is used. On Posix systems these behaviours are equivalent:
Patterns starting with / work relative to /. On Windows, Patterns
starting with / or \ work relative only to the drive part of the
FilePath and Patterns starting with absolute paths ignore the
FilePath.
Note that in some cases results outside the given directory may be returned:
for instance the .* pattern matches the .. directory.
Any results deeper than in the given directory are enumerated lazily, using
unsafeInterleaveIO.
Directories without read permissions are returned as entries but their
contents, of course, are not.
The simplest IO function. Finds matches to the given pattern in the current
working directory. Takes a String instead of a Pattern to avoid the need
for a call to compile, simplifying usage further.
Can also be seen as a convenience wrapper on top of globDir1, for when you
want to work in the current directory or have a pattern referring to an
absolute path.
Like globDir, but applies the given GlobOptions instead of the
defaults when matching. The first component of the returned tuple contains
the matched paths, grouped for each given Pattern, and the second contains
Just the unmatched paths if the given GlobOptions specified that unmatched
files should be included, or otherwise Nothing.