System.FilePath.Glob

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.

Basic usage examples:

Matching a String pattern against a FilePath:

match (compile pattern) filepath

Matching a String pattern against all paths in the current working directory:

glob pattern

Matching a String pattern against all paths in a given directory (a FilePath):

globDir1 (compile pattern) directorypath

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:

globDir (map compile patterns) directorypath

Data type

data Pattern

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.

Instances

Eq Pattern

Methods

(==) :: Pattern -> Pattern -> Bool

(/=) :: Pattern -> Pattern -> Bool

Read Pattern

Methods

readsPrec :: Int -> ReadS Pattern

readList :: ReadS [Pattern]

readPrec :: ReadPrec Pattern

readListPrec :: ReadPrec [Pattern]

Show Pattern

Methods

showsPrec :: Int -> Pattern -> ShowS

show :: Pattern -> String

showList :: [Pattern] -> ShowS

IsString Pattern

Methods

fromString :: String -> Pattern

Semigroup Pattern

Methods

(<>) :: Pattern -> Pattern -> Pattern

sconcat :: NonEmpty Pattern -> Pattern

stimes :: Integral b => b -> Pattern -> Pattern

Monoid Pattern

Methods

mempty :: Pattern

mappend :: Pattern -> Pattern -> Pattern

mconcat :: [Pattern] -> Pattern

Functions

Compilation

compile :: String -> Pattern

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

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

decompile :: Pattern -> String

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.

simplify :: Pattern -> Pattern

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.

Options

data CompOptions

Options which can be passed to the tryCompileWith or compileWith 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

Fields

• characterClasses :: Bool

  Allow character classes, [[:...:]].

• characterRanges :: Bool

  Allow character ranges, [...].

• numberRanges :: Bool

  Allow open ranges, <...>.

• wildcards :: Bool

  Allow wildcards, * and ?.

• recursiveWildcards :: Bool

  Allow recursive wildcards, **/.

• pathSepInRanges :: Bool

  Allow 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 subdirectory a[.

• errorRecovery :: Bool

  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.

Instances

Eq CompOptions

Methods

(==) :: CompOptions -> CompOptions -> Bool

(/=) :: CompOptions -> CompOptions -> Bool

Read CompOptions

Methods

readsPrec :: Int -> ReadS CompOptions

readList :: ReadS [CompOptions]

readPrec :: ReadPrec CompOptions

readListPrec :: ReadPrec [CompOptions]

Show CompOptions

Methods

showsPrec :: Int -> CompOptions -> ShowS

show :: CompOptions -> String

showList :: [CompOptions] -> ShowS

compileWith :: CompOptions -> String -> Pattern

Like compile, but recognizes operators according to the given CompOptions instead of the defaults.

If an error occurs and errorRecovery is disabled, error will be called.

tryCompileWith :: CompOptions -> String -> Either String Pattern

A safe version of compileWith.

If an error occurs and errorRecovery is disabled, the error message will be returned in a Left.

Predefined option sets

compDefault :: CompOptions

The default set of compilation options: closest to the behaviour of the zsh shell, with errorRecovery enabled.

All options are enabled.

compPosix :: CompOptions

Options for POSIX-compliance, as described in man 7 glob.

numberRanges, recursiveWildcards, and pathSepInRanges are disabled.

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]]

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 FilePath is [], getCurrentDirectory will be used.

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.

globDir1 :: Pattern -> FilePath -> IO [FilePath]

A convenience wrapper on top of globDir, for when you only have one Pattern you care about. Returns only the matched paths.

glob :: String -> IO [FilePath]

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.

Options

data MatchOptions

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

Constructors

MatchOptions

Fields

• matchDotsImplicitly :: Bool

  Allow *, ?, and **/ to match . at the beginning of paths.

• ignoreCase :: Bool

  Case-independent matching.

• ignoreDotSlash :: Bool

  Treat ./ as a no-op in both paths and patterns.

  (Of course e.g. ../ means something different and will not be ignored.)

matchWith :: MatchOptions -> Pattern -> FilePath -> Bool

Like match, but applies the given MatchOptions instead of the defaults.

data GlobOptions

Options which can be passed to the globDirWith function.

Constructors

GlobOptions

Fields

• matchOptions :: MatchOptions

  Options controlling how matching is performed; see MatchOptions.

• includeUnmatched :: Bool

  Whether to include unmatched files in the result.

globDirWith :: GlobOptions -> [Pattern] -> FilePath -> IO ([[FilePath]], Maybe [FilePath])

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.

Predefined option sets

matchDefault :: MatchOptions

The default set of execution options: closest to the behaviour of the zsh shell.

Currently identical to matchPosix.

matchPosix :: MatchOptions

Options for POSIX-compliance, as described in man 7 glob.

ignoreDotSlash is enabled, the rest are disabled.

globDefault :: GlobOptions

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

Miscellaneous

commonDirectory :: Pattern -> (FilePath, Pattern)

Factors out the directory component of a Pattern. Useful in conjunction with globDir.

Preserves the number of path separators: commonDirectory (compile "foo///bar") becomes ("foo///", compile "bar").

isLiteral :: Pattern -> Bool

Returns True iff the given Pattern is a literal file path, i.e. it has no wildcards, character ranges, etc.