System.FilePath.Glob

Glob-0.7.5: Globbing library

Safe Haskell | None
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]], [FilePath])
- globDir1 :: Pattern -> FilePath -> IO [FilePath]
- glob :: String -> IO [FilePath]
- data MatchOptions = MatchOptions {
  - matchDotsImplicitly :: Bool
  - ignoreCase :: Bool
  - ignoreDotSlash :: Bool
  }
- matchWith :: MatchOptions -> Pattern -> FilePath -> Bool
- globDirWith :: MatchOptions -> [Pattern] -> FilePath -> IO ([[FilePath]], [FilePath])
- matchDefault :: MatchOptions
- matchPosix :: MatchOptions
- commonDirectory :: Pattern -> (FilePath, Pattern)

# 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 |
Read Pattern |
Show Pattern |
Monoid 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 |
Read CompOptions |
Show CompOptions |

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]], [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`. 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.fst) (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.

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

Like `globDir`, but applies the given `MatchOptions` instead of the defaults when matching.

#### 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.

## 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")`.