-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/

-- | File path glob-like matching
--   
--   A library for matching files using patterns such as
--   "src/**/*.png" for all .png files recursively under
--   the src directory. Features:
--   
--   
--   
- All matching is O(n). Most functions precompute some
--   information given only one argument.
--   
- See System.FilePattern and ?== simple matching and
--   semantics.
--   
- Use match and substitute to extract suitable
--   strings from the * and ** matches, and substitute
--   them back into other patterns.
--   
- Use step and matchMany to perform bulk matching
--   of many patterns against many paths simultaneously.
--   
- Use System.FilePattern.Directory to perform optimised
--   directory traverals using patterns.
--   
--   
--   Originally taken from the Shake library.
@package filepattern
@version 0.1.3

-- | 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.
module System.FilePattern.Directory

-- | 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").
type FilePattern = String

-- | 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.
getDirectoryFiles :: FilePath -> [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.
getDirectoryFilesIgnore :: 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.
getDirectoryFilesIgnoreSlow :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath]

-- | A module for matching files using patterns such as
--   "src/**/*.png" for all .png files recursively under
--   the src directory. See ?== for the semantics of
--   FilePattern values. Features:
--   
--   
--   
- All matching is O(n). Most functions precompute some
--   information given only one argument.
--   
- Use match and substitute to extract suitable strings
--   from the * and ** matches, and substitute them back
--   into other patterns.
--   
- Use step and matchMany to perform bulk matching of
--   many patterns against many paths simultaneously.
--   
- Use System.FilePattern.Directory to perform optimised
--   directory traverals using patterns.
--   
module System.FilePattern

-- | 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").
type FilePattern = String

-- | Match a FilePattern against a FilePath. 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 and dir/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 values, so are unlikely to be correct.
(?==) :: FilePattern -> FilePath -> Bool

-- | Like ?==, but returns Nothing on if there is no match,
--   otherwise Just with the list of fragments matching each
--   wildcard. For example:
--   
--   
--   isJust (match p x) == (p ?== x)
--   match "**/*.c" "test.txt" == Nothing
--   match "**/*.c" "foo.c" == Just ["","foo"]
--   match "**/*.c" "bar/baz/foo.c" == Just ["bar/baz/","foo"]
--   
--   
--   On Windows any \ path separators will be replaced by
--   /.
match :: FilePattern -> FilePath -> Maybe [String]

-- | Given a successful match, substitute it back in to a pattern
--   with the same arity. Raises an error if the number of parts
--   does not match the arity of the pattern.
--   
--   
--   p ?== x ==> substitute (fromJust $ match p x) p == x
--   substitute "**/*.c" ["dir","file"] == "dir/file.c"
--   
substitute :: Partial => FilePattern -> [String] -> FilePath

-- | How many * and ** elements are there.
--   
--   
--   arity "test.c" == 0
--   arity "**/*.c" == 2
--   
arity :: FilePattern -> Int

-- | Efficient matching of a set of FilePatterns against a set of
--   FilePaths. First call step passing in all the
--   FilePatterns, with a tag for each one. Next call the methods of
--   Step, providing the components of the FilePaths in turn.
--   
--   Useful for efficient bulk searching, particularly directory scanning,
--   where you can avoid descending into directories which cannot match.
step :: [(a, FilePattern)] -> Step a

-- | Like step but using () as the tag for each
--   FilePattern.
step_ :: [FilePattern] -> Step ()

-- | The result of step, used to process successive path components
--   of a set of FilePaths.
data Step a
Step :: [(a, [String])] -> StepNext -> (String -> Step a) -> Step a

-- | The files that match at this step. Includes the list that would have
--   been produced by match, along with the values passed to
--   step. These results are not necessarily in order.
[stepDone] :: Step a -> [(a, [String])]

-- | Information about the results of calling stepApply. See
--   StepNext for details.
[stepNext] :: Step a -> StepNext

-- | Apply one component from a FilePath to get a new Step.
[stepApply] :: Step a -> String -> Step a

-- | What we know about the next step values.
data StepNext

-- | All components not listed will result in dull Step values from
--   stepApply, with stepNext being StepOnly
--   [] and stepDone being []. The field is a set -
--   their order is irrelevant but there will be no duplicates in values
--   arising from step.
StepOnly :: [String] -> StepNext

-- | All calls to stepApply will return stepNext being
--   StepEverything with a non-empty stepDone.
StepEverything :: StepNext

-- | We have no additional information about the output from
--   stepApply.
StepUnknown :: StepNext

-- | Efficiently match many FilePatterns against many
--   FilePaths 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))
--   
matchMany :: [(a, FilePattern)] -> [(b, FilePath)] -> [(a, b, [String])]
