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

-- | Globbing library
--   
--   A library for globbing: matching patterns against file paths.
@package Glob
@version 0.8.0

-- | A number of primitives from which complete Patterns may be
--   constructed.
--   
--   Using this together with the functions provided by the Monoid
--   instance of Pattern allows for direct manipulation of
--   Patterns beyond what can be done with just the compile
--   family of functions. And of course you don't have to go via
--   Strings if you use these.
module System.FilePath.Glob.Primitive

-- | A Pattern which matches the given String literally.
--   
--   Handles any embedded path and extension separators.
literal :: String -> Pattern

-- | Matches any single character except a path separator: corresponds to
--   the ? operator.
singleWildcard :: Pattern

-- | Matches any number of characters up to a path separator: corresponds
--   to the * operator.
wildcard :: Pattern

-- | Matches any number of characters including path separators:
--   corresponds to the **/ operator.
recursiveWildcard :: Pattern

-- | Matches a single character if it is within the (inclusive) range in
--   any Right or if it is equal to the character in any
--   Left. Corresponds to the [], [^] and
--   [!] operators.
--   
--   If the given Bool is False, the result of the match is
--   inverted: the match succeeds if the character does not match
--   according to the above rules.
charRange :: Bool -> [Either Char (Char, Char)] -> Pattern

-- | Matches a number in the given range, which may be open, half-open, or
--   closed. Corresponds to the <> operator.
numberRange :: Maybe Integer -> Maybe Integer -> Pattern

-- | 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
--   
module System.FilePath.Glob

-- | 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.
data 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 "[]".
compile :: String -> Pattern

-- | 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.
decompile :: Pattern -> String

-- | 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.
simplify :: Pattern -> Pattern

-- | 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.
data CompOptions
CompOptions :: Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> Bool -> CompOptions

-- | Allow character classes, [[:...:]].
[characterClasses] :: CompOptions -> Bool

-- | Allow character ranges, [...].
[characterRanges] :: CompOptions -> Bool

-- | Allow open ranges, <...>.
[numberRanges] :: CompOptions -> Bool

-- | Allow wildcards, * and ?.
[wildcards] :: CompOptions -> Bool

-- | Allow recursive wildcards, **/.
[recursiveWildcards] :: CompOptions -> 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[.
[pathSepInRanges] :: CompOptions -> 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.
[errorRecovery] :: CompOptions -> Bool

-- | 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.
compileWith :: CompOptions -> String -> Pattern

-- | A safe version of compileWith.
--   
--   If an error occurs and errorRecovery is disabled, the error
--   message will be returned in a Left.
tryCompileWith :: CompOptions -> String -> Either String Pattern

-- | The default set of compilation options: closest to the behaviour of
--   the zsh shell, with errorRecovery enabled.
--   
--   All options are enabled.
compDefault :: CompOptions

-- | Options for POSIX-compliance, as described in man 7 glob.
--   
--   numberRanges, recursiveWildcards, and
--   pathSepInRanges are disabled.
compPosix :: CompOptions

-- | Matches the given Pattern against the given FilePath,
--   returning True if the pattern matches and False
--   otherwise.
match :: Pattern -> FilePath -> Bool

-- | 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 Patterns match a single FilePath, that path
--   will be included in multiple groups.
--   
--   Two FilePaths 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: Patterns starting with / work relative to
--   /. On Windows, Patterns starting with / or
--   \ work relative only to the drive part of the FilePath
--   and Patterns 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.
globDir :: [Pattern] -> FilePath -> IO ([[FilePath]], [FilePath])

-- | A convenience wrapper on top of globDir, for when you only have
--   one Pattern you care about. Returns only the matched paths.
globDir1 :: Pattern -> FilePath -> 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.
glob :: String -> IO [FilePath]

-- | Options which can be passed to the matchWith or
--   globDirWith functions: with these you can selectively toggle
--   certain features at matching time.
data MatchOptions
MatchOptions :: Bool -> Bool -> Bool -> MatchOptions

-- | Allow *, ?, and **/ to match . at
--   the beginning of paths.
[matchDotsImplicitly] :: MatchOptions -> Bool

-- | Case-independent matching.
[ignoreCase] :: MatchOptions -> Bool

-- | Treat ./ as a no-op in both paths and patterns.
--   
--   (Of course e.g. ../ means something different and will not be
--   ignored.)
[ignoreDotSlash] :: MatchOptions -> Bool

-- | Like match, but applies the given MatchOptions instead
--   of the defaults.
matchWith :: MatchOptions -> Pattern -> FilePath -> Bool

-- | Like globDir, but applies the given MatchOptions instead
--   of the defaults when matching.
globDirWith :: MatchOptions -> [Pattern] -> FilePath -> IO ([[FilePath]], [FilePath])

-- | The default set of execution options: closest to the behaviour of the
--   zsh shell.
--   
--   Currently identical to matchPosix.
matchDefault :: MatchOptions

-- | Options for POSIX-compliance, as described in man 7 glob.
--   
--   ignoreDotSlash is enabled, the rest are disabled.
matchPosix :: MatchOptions

-- | 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").
commonDirectory :: Pattern -> (FilePath, Pattern)
