System.FilePath.Glob

Glob-0.10.2: Globbing library

Safe Haskell | Safe-Inferred
Language | Haskell98

System.FilePath.Glob

Contents

- Data type
- Functions
  - Compilation
    - Options
      - Predefined option sets
  - Matching
    - Options
      - Predefined option sets
  - Miscellaneous

Description

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

Synopsis

- data Pattern
- compile :: String -> Pattern
- decompile :: Pattern -> String
- simplify :: Pattern -> Pattern
- data CompOptions = CompOptions {
  - characterClasses :: Bool
  - characterRanges :: Bool
  - numberRanges :: Bool
  - wildcards :: Bool
  - recursiveWildcards :: Bool
  - pathSepInRanges :: Bool
  - errorRecovery :: Bool
  }
- compileWith :: CompOptions -> String -> Pattern
- tryCompileWith :: CompOptions -> String -> Either String Pattern
- compDefault :: CompOptions
- compPosix :: CompOptions
- match :: Pattern -> FilePath -> Bool
- globDir :: [Pattern] -> FilePath -> IO [[FilePath]]
- globDir1 :: Pattern -> FilePath -> IO [FilePath]
- glob :: String -> IO [FilePath]
- data MatchOptions = MatchOptions {
  - matchDotsImplicitly :: Bool
  - ignoreCase :: Bool
  - ignoreDotSlash :: Bool
  }
- matchWith :: MatchOptions -> Pattern -> FilePath -> Bool
- data GlobOptions = GlobOptions {
  - matchOptions :: MatchOptions
  - includeUnmatched :: Bool
  }
- globDirWith :: GlobOptions -> [Pattern] -> FilePath -> IO ([[FilePath]], Maybe [FilePath])
- matchDefault :: MatchOptions
- matchPosix :: MatchOptions
- globDefault :: GlobOptions
- commonDirectory :: Pattern -> (FilePath, Pattern)
- isLiteral :: Pattern -> Bool

# 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

Instances details

IsString Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods fromString :: String -> Pattern
Monoid Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods mempty :: Pattern mappend :: Pattern -> Pattern -> Pattern mconcat :: [Pattern] -> Pattern
Semigroup Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods (<>) :: Pattern -> Pattern -> Pattern sconcat :: NonEmpty Pattern -> Pattern stimes :: Integral b => b -> Pattern -> Pattern
Read Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods readsPrec :: Int -> ReadS Pattern readList :: ReadS [Pattern] readPrec :: ReadPrec Pattern readListPrec :: ReadPrec [Pattern]
Show Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods showsPrec :: Int -> Pattern -> ShowS show :: Pattern -> String showList :: [Pattern] -> ShowS
Eq Pattern # |
Instance details Defined in System.FilePath.Glob.Base Methods (==) :: Pattern -> Pattern -> Bool (/=) :: Pattern -> Pattern -> Bool

# 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

Instances details

Read CompOptions # |
Instance details Defined in System.FilePath.Glob.Base Methods readsPrec :: Int -> ReadS CompOptions readList :: ReadS [CompOptions] readPrec :: ReadPrec CompOptions readListPrec :: ReadPrec [CompOptions]
Show CompOptions # |
Instance details Defined in System.FilePath.Glob.Base Methods showsPrec :: Int -> CompOptions -> ShowS show :: CompOptions -> String showList :: [CompOptions] -> ShowS
Eq CompOptions # |
Instance details Defined in System.FilePath.Glob.Base Methods (==) :: CompOptions -> CompOptions -> Bool (/=) :: CompOptions -> CompOptions -> Bool

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 `Pattern`s match a single `FilePath`, that path will be included in multiple groups.

Two `FilePath`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` 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: `Pattern`s starting with `/` work relative to `/`. On Windows, `Pattern`s starting with `/` or `\` work relative only to the drive part of the `FilePath` and `Pattern`s 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.