System.FilePattern (original) (raw)

Contents

• Multiple patterns and paths

Description

A module for matching files using patterns such as "src/**/*.png" for all .png files recursively under the src directory. See [?==](System-FilePattern.html#v:-63--61--61- "System.FilePattern") for the semantics of[FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern") values. Features:

• All matching is O(n). Most functions precompute some information given only one argument.
• Use [match](System-FilePattern.html#v:match "System.FilePattern") and [substitute](System-FilePattern.html#v:substitute "System.FilePattern") to extract suitable strings from the * and ** matches, and substitute them back into other patterns.
• Use [step](System-FilePattern.html#v:step "System.FilePattern") and [matchMany](System-FilePattern.html#v:matchMany "System.FilePattern") to perform bulk matching of many patterns against many paths simultaneously.
• Use System.FilePattern.Directory to perform optimised directory traverals using patterns.

Synopsis

• type FilePattern = String
• (?==) :: FilePattern -> FilePath -> Bool
• match :: FilePattern -> FilePath -> Maybe [String]
• substitute :: Partial => FilePattern -> [String] -> FilePath
• arity :: FilePattern -> Int
• step :: [(a, FilePattern)] -> Step a
• step_ :: [FilePattern] -> Step ()
• data Step a = Step {
  • stepDone :: [(a, [String])]
  • stepNext :: StepNext
  • stepApply :: String -> Step a
    }
• data StepNext
  • = StepOnly [String]
  • | StepEverything
  • | StepUnknown
• matchMany :: [(a, FilePattern)] -> [(b, FilePath)] -> [(a, b, [String])]

Documentation

type FilePattern = String Source #

A type synonym for file patterns, containing ** and *. For the syntax and semantics of [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern") see [?==](System-FilePattern.html#v:-63--61--61- "System.FilePattern").

Most [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") values lacking literal . and .. components are suitable as [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern") values which match only that specific file. On Windows \ is treated as equivalent to /.

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

(?==) :: FilePattern -> FilePath -> Bool Source #

Match a [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern") against a [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO"). There are two special forms:

• * matches part of a path component, excluding any separators.
• ** as a path component matches an arbitrary number of path components.

Some examples:

• test.c matches test.c and nothing else.
• *.c matches all .c files in the current directory, so file.c matches, but file.h and dir/file.c don't.
• **/*.c matches all .c files anywhere on the filesystem, so file.c, dir/file.c, dir1/dir2/file.c and /path/to/file.c all match, but file.h and dir/file.h don't.
• dir/*/* matches all files one level below dir, so dir/one/file.c anddir/two/file.h match, but file.c, one/dir/file.c, dir/file.h and dir/one/two/file.c don't.

Patterns with constructs such as foo/../bar will never match normalised [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO") values, so are unlikely to be correct.

match :: FilePattern -> FilePath -> Maybe [String] Source #

Like [?==](System-FilePattern.html#v:-63--61--61- "System.FilePattern"), but returns [Nothing](/package/base-4.14.1.0/docs/Data-Maybe.html#v:Nothing "Data.Maybe") on if there is no match, otherwise [Just](/package/base-4.14.1.0/docs/Data-Maybe.html#v:Just "Data.Maybe") with the list of fragments matching each wildcard. For example:

isJust ([match](System-FilePattern.html#v:match "System.FilePattern") p x) == (p [?==](System-FilePattern.html#v:-63--61--61- "System.FilePattern") x) [match](System-FilePattern.html#v:match "System.FilePattern") "/*.c" "test.txt" == Nothing [match](System-FilePattern.html#v:match "System.FilePattern") "/.c" "foo.c" == Just ["","foo"] [match](System-FilePattern.html#v:match "System.FilePattern") "**/.c" "bar/baz/foo.c" == Just ["bar/baz/","foo"]

On Windows any \ path separators will be replaced by /.

Multiple patterns and paths

step :: [(a, FilePattern)] -> Step a Source #

Efficient matching of a set of [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern")s against a set of [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO")s. First call [step](System-FilePattern.html#v:step "System.FilePattern") passing in all the [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern")s, with a tag for each one. Next call the methods of [Step](System-FilePattern.html#t:Step "System.FilePattern"), providing the components of the [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO")s in turn.

Useful for efficient bulk searching, particularly directory scanning, where you can avoid descending into directories which cannot match.

matchMany :: [(a, FilePattern)] -> [(b, FilePath)] -> [(a, b, [String])] Source #

Efficiently match many [FilePattern](System-FilePattern.html#t:FilePattern "System.FilePattern")s against many [FilePath](/package/base-4.14.1.0/docs/System-IO.html#t:FilePath "System.IO")s in a single operation. Note that the returned matches are not guaranteed to be in any particular order.

matchMany [(a, pat)] [(b, path)] == maybeToList (map (a,b,) (match pat path))