System.FilePattern.Directory

filepattern-0.1.3: File path glob-like matching

Safe Haskell | None
Language | Haskell2010

System.FilePattern.Directory

Description

Optimised directory traversal using `FilePattern` values. All results are guaranteed to be sorted.

Case Sensitivity: these traversals are optimised to reduce the number of IO operations performed. In particular, if the relevant subdirectories can be determined in advance it will use `doesDirectoryExist` rather than `getDirectoryContents`. However, on case-insensitive file systems, if there is a directory `foo`, then `doesDirectoryExist "FOO"` will report `True`, but `FOO` won't be a result returned by `getDirectoryContents`, which may result in different search results depending on whether a certain optimisations kick in.

If these optimisation differences are absolutely unacceptable use `getDirectoryFilesIgnoreSlow`. However, normally these differences are not a problem.

Synopsis

- type FilePattern = String
- getDirectoryFiles :: FilePath -> [FilePattern] -> IO [FilePath]
- getDirectoryFilesIgnore :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath]
- getDirectoryFilesIgnoreSlow :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath]

# Documentation

type FilePattern = String #

A type synonym for file patterns, containing `**` and `*`. For the syntax and semantics of `FilePattern` see `?==`.

Most `FilePath` values lacking literal `.` and `..` components are suitable as `FilePattern` values which match only that specific file. On Windows `\` is treated as equivalent to `/`.

You can write `FilePattern` values as a literal string, or build them up using the operators `<.>` and `</>` (but be aware that `"" `</>` "foo"` produces `"./foo"`).

getDirectoryFiles :: FilePath -> [FilePattern] -> IO [FilePath] #

Get the files below a certain root that match any of the `FilePattern` values. Only matches files, not directories. Avoids traversing into directories that it can detect won't have any matches in.

    getDirectoryFiles "myproject/src" ["**/*.h","**/*.c"]

If there are certain directories/files that should not be explored, use `getDirectoryFilesIgnore`.

Warning: on case-insensitive file systems certain optimisations can cause surprising results. See the top of the module for details.

getDirectoryFilesIgnore :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath] #

Get the files below a certain root matching any of the first set of `FilePattern` values, but don't return any files which match any ignore pattern (the final argument). Typically the ignore pattens will end with `/**`, e.g. `.git/**`.

    getDirectoryFilesIgnore "myproject/src" ["**/*.h","**/*.c"] [".git/**"]

Warning: on case-insensitive file systems certain optimisations can cause surprising results. See the top of the module for details.

getDirectoryFilesIgnoreSlow :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath] #

Like `getDirectoryFilesIgnore` but that the optimisations that may change behaviour on a case-insensitive file system. Note that this function will never return more results then `getDirectoryFilesIgnore`, and may return less. However, it will obey invariants such as:

    getDirectoryFilesIgnoreSlow root [x] [] ++ getDirectoryFilesIgnoreSlow root [y] []
        == getDirectoryFilesIgnoreSlow root [x,y] []

In contrast `getDirectoryFilesIgnore` only guarantees that invariant on case-sensitive file systems.