System.FilePath.Glob (original) (raw)

Description

A library for globbing: matching patterns against file paths akin to the POSIX glob() function.

Pattern syntax is documented by [compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob"). To toggle features at compile time, look into [CompOptions](System-FilePath-Glob.html#t:CompOptions "System.FilePath.Glob"). To modify matching behaviour, look into[MatchOptions](System-FilePath-Glob.html#t:MatchOptions "System.FilePath.Glob").

Basic usage examples:

Matching a [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.String") pattern against a [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO"):

[match](System-FilePath-Glob.html#v:match "System.FilePath.Glob") ([compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob") pattern) filepath

Matching a [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.String") pattern against all paths in the current working directory:

[glob](System-FilePath-Glob.html#v:glob "System.FilePath.Glob") pattern

Matching a [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.String") pattern against all paths in a given directory (a[FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO")):

[globDir1](System-FilePath-Glob.html#v:globDir1 "System.FilePath.Glob") ([compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob") pattern) directorypath

Matching a list of [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.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:

[globDir](System-FilePath-Glob.html#v:globDir "System.FilePath.Glob") (map [compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob") patterns) directorypath

Data type

data Pattern Source #

An abstract data type representing a compiled pattern.

Note that the [Eq](/package/base-4.14.1.0/docs/Data-Eq.html#t:Eq "Data.Eq") instance cannot tell you whether two patterns behave in the same way; only whether they compile to the same [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob"). For instance,`[compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob")` "x" and `[compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob")` "[x]" may or may not compare equal, though a `match` will behave the exact same way no matter which [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") is used.

FunctionsCompilation

compile :: String -> Pattern Source #

Compiles a glob pattern from its textual representation into a [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") 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:

So, e.g. [] will match the string "[]".

decompile :: Pattern -> String Source #

Decompiles a [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") object into its textual representation: essentially the inverse of [compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob").

Note, however, that due to internal optimization, decompile . compile is not the identity function. Instead, compile . decompile is.

Be careful with [CompOptions](System-FilePath-Glob.html#t:CompOptions "System.FilePath.Glob"): [decompile](System-FilePath-Glob.html#v:decompile "System.FilePath.Glob") always produces a [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.String") which can be passed to [compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob") to get back the same [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob"). compileWith options . decompile is not the identity function unless options is[compDefault](System-FilePath-Glob.html#v:compDefault "System.FilePath.Glob").

simplify :: Pattern -> Pattern Source #

Simplifies a [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") object: removes redundant "./", for instance. The resulting [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") matches the exact same input as the original one, with some differences:

For the last of the above reasons, if you're performance-conscious and not using globDir, you should always [simplify](System-FilePath-Glob.html#v:simplify "System.FilePath.Glob") after calling compile.

Options

data CompOptions Source #

Options which can be passed to the [tryCompileWith](System-FilePath-Glob.html#v:tryCompileWith "System.FilePath.Glob") or [compileWith](System-FilePath-Glob.html#v:compileWith "System.FilePath.Glob") functions: with these you can selectively toggle certain features at compile time.

Note that some of these options depend on each other: classes can never occur if ranges aren't allowed, for instance.

Constructors

| CompOptions | | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | FieldscharacterClasses :: BoolAllow character classes, [[:...:]].characterRanges :: BoolAllow character ranges, [...].numberRanges :: BoolAllow open ranges, <...>.wildcards :: BoolAllow wildcards, * and ?.recursiveWildcards :: BoolAllow recursive wildcards, **/.pathSepInRanges :: BoolAllow path separators in character ranges.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 subdirectorya[.errorRecovery :: BoolIf 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. | |

Predefined option setsMatching

globDir :: [Pattern] -> FilePath -> IO [[FilePath]] Source #

Matches each given [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") against the contents of the given [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO"), recursively. The result contains the matched paths, grouped for each given[Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob"). 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 [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob")s match a single [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO"), that path will be included in multiple groups.

Two [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO")s 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](/package/base-4.14.1.0/docs/GHC-List.html#v:filter "GHC.List") 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 [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") is [], [getCurrentDirectory](/package/directory-1.3.6.0/docs/System-Directory.html#v:getCurrentDirectory "System.Directory") will be used.

If the given [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") starts with a drive (as defined by[FilePath](System.html#v:FilePath "System")), it is not relative to the given directory and the[FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") parameter is completely ignored! Similarly, if the given[Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") starts with a path separator, only the drive part of the[FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") is used. On Posix systems these behaviours are equivalent:[Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob")s starting with / work relative to /. On Windows, [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob")s starting with / or \ work relative only to the drive part of the[FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") and [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob")s starting with absolute paths ignore the[FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO").

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, usingunsafeInterleaveIO.

Directories without read permissions are returned as entries but their contents, of course, are not.

glob :: String -> IO [FilePath] Source #

The simplest IO function. Finds matches to the given pattern in the current working directory. Takes a [String](/package/base-4.14.1.0/docs/Data-String.html#t:String "Data.String") instead of a [Pattern](System-FilePath-Glob.html#t:Pattern "System.FilePath.Glob") to avoid the need for a call to [compile](System-FilePath-Glob.html#v:compile "System.FilePath.Glob"), simplifying usage further.

Can also be seen as a convenience wrapper on top of [globDir1](System-FilePath-Glob.html#v:globDir1 "System.FilePath.Glob"), for when you want to work in the current directory or have a pattern referring to an absolute path.

Options

data MatchOptions Source #

Options which can be passed to the matchWith or globDirWith functions: with these you can selectively toggle certain features at matching time.

Predefined option sets

globDefault :: GlobOptions Source #

The default set of globbing options: uses the default matching options, and does not include unmatched files.

Miscellaneous