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


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

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

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

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

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

-- | Matches a single character if it is within the (inclusive) range in
--   any <a>Right</a> or if it is equal to the character in any
--   <a>Left</a>. Corresponds to the <tt>[]</tt>, <tt>[^]</tt> and
--   <tt>[!]</tt> operators.
--   
--   If the given <a>Bool</a> is <a>False</a>, the result of the match is
--   inverted: the match succeeds if the character does <i>not</i> 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 <tt>&lt;&gt;</tt> operator.
numberRange :: Maybe Integer -> Maybe Integer -> Pattern


-- | A library for globbing: matching patterns against file paths akin to
--   the POSIX <tt>glob()</tt> function.
--   
--   Pattern syntax is documented by <a>compile</a>. To toggle features at
--   compile time, look into <a>CompOptions</a>. To modify matching
--   behaviour, look into <a>MatchOptions</a>.
--   
--   Basic usage examples:
--   
--   Matching a <a>String</a> pattern against a <a>FilePath</a>:
--   
--   <pre>
--   <a>match</a> (<a>compile</a> pattern) filepath
--   </pre>
--   
--   Matching a <a>String</a> pattern against all paths in the current
--   working directory:
--   
--   <pre>
--   <a>glob</a> pattern
--   </pre>
--   
--   Matching a <a>String</a> pattern against all paths in a given
--   directory (a <a>FilePath</a>):
--   
--   <pre>
--   <a>globDir1</a> (<a>compile</a> pattern) directorypath
--   </pre>
--   
--   Matching a list of <a>String</a> 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:
--   
--   <pre>
--   <a>globDir</a> (map <a>compile</a> patterns) directorypath
--   </pre>
module System.FilePath.Glob

-- | An abstract data type representing a compiled pattern.
--   
--   Note that the <a>Eq</a> instance cannot tell you whether two patterns
--   behave in the same way; only whether they compile to the same
--   <a>Pattern</a>. For instance, <tt><a>compile</a> "x"</tt> and
--   <tt><a>compile</a> "[x]"</tt> may or may not compare equal, though a
--   <tt><tt>match</tt></tt> will behave the exact same way no matter which
--   <a>Pattern</a> is used.
data Pattern

-- | Compiles a glob pattern from its textual representation into a
--   <a>Pattern</a> object.
--   
--   For the most part, a character matches itself. Recognized operators
--   are as follows:
--   
--   <ul>
--   <li><i><tt>?</tt></i> Matches any character except path
--   separators.</li>
--   <li><i><tt>*</tt></i> Matches any number of characters except path
--   separators, including the empty string.</li>
--   <li><i>@[..\</i> <tt>] Matches any of the enclosed characters. Ranges
--   of characters can be specified by separating the endpoints with a
--   </tt>'-'<tt>. </tt>'-'<tt> or </tt>']'<tt> can be matched by including
--   them as the first character(s) in the list. Never matches path
--   separators: </tt>[/]<tt> matches nothing at all. Named character
--   classes can also be matched: </tt>[:x:]<tt> within </tt>[]<tt>
--   specifies the class named </tt>x@, which matches certain predefined
--   characters. See below for a full list.</li>
--   <li><i>@[^..\</i> <tt> or </tt>[!..]<tt>] Like </tt>[..]<tt>, but
--   matches any character <i>not</i> listed. Note that </tt>[^-x]<tt> is
--   not the inverse of </tt>[-x]<tt>, but the range </tt>[^-x]@.</li>
--   <li><i><tt>&lt;m-n&gt;</tt></i> Matches any integer in the range m to
--   n, inclusive. The range may be open-ended by leaving out either
--   number: <tt>"&lt;-&gt;"</tt>, for instance, matches any integer.</li>
--   <li><i><tt>**/</tt></i> Matches any number of characters, including
--   path separators, excluding the empty string.</li>
--   </ul>
--   
--   Supported character classes:
--   
--   <ul>
--   <li><i>@[:alnum:\</i> <tt>] Equivalent to </tt>"0-9A-Za-z"@.</li>
--   <li><i>@[:alpha:\</i> <tt>] Equivalent to </tt>"A-Za-z"@.</li>
--   <li><i>@[:blank:\</i> <tt>] Equivalent to </tt>"\t "@.</li>
--   <li><i>@[:cntrl:\</i> <tt>] Equivalent to </tt>"\0-\x1f\x7f"@.</li>
--   <li><i>@[:digit:\</i> <tt>] Equivalent to </tt>"0-9"@.</li>
--   <li><i>@[:graph:\</i> <tt>] Equivalent to </tt>"!-~"@.</li>
--   <li><i>@[:lower:\</i> <tt>] Equivalent to </tt>"a-z"@.</li>
--   <li><i>@[:print:\</i> <tt>] Equivalent to </tt>" -~"@.</li>
--   <li><i>@[:punct:\</i> <tt>] Equivalent to </tt>"!-/:-@[-`{-~"@.</li>
--   <li><i>@[:space:\</i> <tt>] Equivalent to </tt>"\t-\r "@.</li>
--   <li><i>@[:upper:\</i> <tt>] Equivalent to </tt>"A-Z"@.</li>
--   <li><i>@[:xdigit:\</i> <tt>] Equivalent to </tt>"0-9A-Fa-f"@.</li>
--   </ul>
--   
--   Note that path separators (typically <tt>'/'</tt>) have to be matched
--   explicitly or using the <tt>**/</tt> pattern. In addition, extension
--   separators (typically <tt>'.'</tt>) 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, <tt>'/'</tt> will match
--   itself as well as <tt>'\'</tt>.
--   
--   Error recovery will be performed: erroneous operators will not be
--   considered operators, but matched as literal strings. Such operators
--   include:
--   
--   <ul>
--   <li>An empty <tt>[]</tt> or <tt>[^]</tt> or <tt>[!]</tt></li>
--   <li>A <tt>[</tt> or <tt>&lt;</tt> without a matching <tt>]</tt> or
--   <tt>&gt;</tt></li>
--   <li>A malformed <tt>&lt;&gt;</tt>: e.g. nonnumeric characters or no
--   hyphen</li>
--   </ul>
--   
--   So, e.g. <tt>[]</tt> will match the string <tt>"[]"</tt>.
compile :: String -> Pattern

-- | Decompiles a <a>Pattern</a> object into its textual representation:
--   essentially the inverse of <a>compile</a>.
--   
--   Note, however, that due to internal optimization, <tt>decompile .
--   compile</tt> is not the identity function. Instead, <tt>compile .
--   decompile</tt> is.
--   
--   Be careful with <a>CompOptions</a>: <a>decompile</a> always produces a
--   <a>String</a> which can be passed to <a>compile</a> to get back the
--   same <a>Pattern</a>. <tt>compileWith options . decompile</tt> is
--   <i>not</i> the identity function unless <tt>options</tt> is
--   <a>compDefault</a>.
decompile :: Pattern -> String

-- | Simplifies a <a>Pattern</a> object: removes redundant <tt>"./"</tt>,
--   for instance. The resulting <a>Pattern</a> matches the exact same
--   input as the original one, with some differences:
--   
--   <ul>
--   <li>The output of <tt>globDir</tt> will differ: for example, globbing
--   for <tt>"./*"</tt> gives <tt>"./foo"</tt>, but after simplification
--   this'll be only <tt>"foo"</tt>.</li>
--   <li>Decompiling the simplified <a>Pattern</a> will obviously not give
--   the original.</li>
--   <li>The simplified <a>Pattern</a> is a bit faster to match with and
--   uses less memory, since some redundant data is removed.</li>
--   </ul>
--   
--   For the last of the above reasons, if you're performance-conscious and
--   not using <tt>globDir</tt>, you should always <a>simplify</a> after
--   calling <tt>compile</tt>.
simplify :: Pattern -> Pattern

-- | Options which can be passed to the <a>tryCompileWith</a> or
--   <a>compileWith</a> 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, <tt>[[:...:]]</tt>.
[characterClasses] :: CompOptions -> Bool

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

-- | Allow open ranges, <tt>&lt;...&gt;</tt>.
[numberRanges] :: CompOptions -> Bool

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

-- | Allow recursive wildcards, <tt>**/</tt>.
[recursiveWildcards] :: CompOptions -> Bool

-- | Allow path separators in character ranges.
--   
--   If true, <tt>a[/]b</tt> never matches anything (since character ranges
--   can't match path separators); if false and <a>errorRecovery</a> is
--   enabled, <tt>a[/]b</tt> matches itself, i.e. a file named <tt>]b</tt>
--   in the subdirectory <tt>a[</tt>.
[pathSepInRanges] :: CompOptions -> Bool

-- | If the input is invalid, recover by turning any invalid part into
--   literals. For instance, with <a>characterRanges</a> enabled,
--   <tt>[abc</tt> is an error by default (unclosed character range); with
--   <a>errorRecovery</a>, the <tt>[</tt> is turned into a literal match,
--   as though <a>characterRanges</a> were disabled.
[errorRecovery] :: CompOptions -> Bool

-- | Like <a>compile</a>, but recognizes operators according to the given
--   <a>CompOptions</a> instead of the defaults.
--   
--   If an error occurs and <a>errorRecovery</a> is disabled, <a>error</a>
--   will be called.
compileWith :: CompOptions -> String -> Pattern

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

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

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

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

-- | Matches each given <a>Pattern</a> against the contents of the given
--   <a>FilePath</a>, recursively. The result pair's first component
--   contains the matched paths, grouped for each given <a>Pattern</a>, and
--   the second contains all paths which were not matched by any
--   <a>Pattern</a>. 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 <a>Pattern</a>s match a single <a>FilePath</a>, that path
--   will be included in multiple groups.
--   
--   Two <a>FilePath</a>s which can be canonicalized to the same file (e.g.
--   <tt>"foo"</tt> and <tt>"./foo"</tt>) may appear separately if explicit
--   matching on paths beginning with <tt>"."</tt> is done. Looking for
--   <tt>".*/*"</tt>, for instance, will cause <tt>"./foo"</tt> to return
--   as a match but <tt>"foo"</tt> to not be matched.
--   
--   This function is different from a simple <a>filter</a> over all the
--   contents of the directory: the matching is performed relative to the
--   directory, so that for instance the following is true:
--   
--   <pre>
--   fmap (head.fst) (globDir [compile "*"] dir) == getDirectoryContents dir
--   </pre>
--   
--   (With the exception that that glob won't match anything beginning with
--   <tt>.</tt>.)
--   
--   If the given <a>FilePath</a> is <tt>[]</tt>,
--   <a>getCurrentDirectory</a> will be used.
--   
--   If the given <a>Pattern</a> starts with a drive (as defined by
--   <a>FilePath</a>), it is not relative to the given directory and the
--   <a>FilePath</a> parameter is completely ignored! Similarly, if the
--   given <a>Pattern</a> starts with a path separator, only the drive part
--   of the <a>FilePath</a> is used. On Posix systems these behaviours are
--   equivalent: <a>Pattern</a>s starting with <tt>/</tt> work relative to
--   <tt>/</tt>. On Windows, <a>Pattern</a>s starting with <tt>/</tt> or
--   <tt>\</tt> work relative only to the drive part of the <a>FilePath</a>
--   and <a>Pattern</a>s starting with absolute paths ignore the
--   <a>FilePath</a>.
--   
--   Note that in some cases results outside the given directory may be
--   returned: for instance the <tt>.*</tt> pattern matches the <tt>..</tt>
--   directory.
--   
--   Any results deeper than in the given directory are enumerated lazily,
--   using <tt>unsafeInterleaveIO</tt>.
--   
--   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 <a>globDir</a>, for when you only have
--   one <a>Pattern</a> 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 <a>String</a> instead of a
--   <a>Pattern</a> to avoid the need for a call to <a>compile</a>,
--   simplifying usage further.
--   
--   Can also be seen as a convenience wrapper on top of <a>globDir1</a>,
--   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 <tt>matchWith</tt> or
--   <tt>globDirWith</tt> functions: with these you can selectively toggle
--   certain features at matching time.
data MatchOptions
MatchOptions :: Bool -> Bool -> Bool -> MatchOptions

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

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

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

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

-- | Like <a>globDir</a>, but applies the given <a>MatchOptions</a> 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
--   <tt>zsh</tt> shell.
--   
--   Currently identical to <a>matchPosix</a>.
matchDefault :: MatchOptions

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

-- | Factors out the directory component of a <a>Pattern</a>. Useful in
--   conjunction with <a>globDir</a>.
--   
--   Preserves the number of path separators: <tt>commonDirectory (compile
--   "foo///bar")</tt> becomes <tt>("foo///", compile "bar")</tt>.
commonDirectory :: Pattern -> (FilePath, Pattern)
