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


-- | Optimised directory traversal using <a>FilePattern</a> values. All
--   results are guaranteed to be sorted.
--   
--   <i>Case Sensitivity</i>: 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
--   <a>doesDirectoryExist</a> rather than <a>getDirectoryContents</a>.
--   However, on case-insensitive file systems, if there is a directory
--   <tt>foo</tt>, then <tt>doesDirectoryExist "FOO"</tt> will report
--   <tt>True</tt>, but <tt>FOO</tt> won't be a result returned by
--   <a>getDirectoryContents</a>, which may result in different search
--   results depending on whether a certain optimisations kick in.
--   
--   If these optimisation differences are absolutely unacceptable use
--   <a>getDirectoryFilesIgnoreSlow</a>. However, normally these
--   differences are not a problem.
module System.FilePattern.Directory

-- | A type synonym for file patterns, containing <tt>**</tt> and
--   <tt>*</tt>. For the syntax and semantics of <a>FilePattern</a> see
--   <a>?==</a>.
--   
--   Most <a>FilePath</a> values lacking literal <tt>.</tt> and <tt>..</tt>
--   components are suitable as <a>FilePattern</a> values which match only
--   that specific file. On Windows <tt>\</tt> is treated as equivalent to
--   <tt>/</tt>.
--   
--   You can write <a>FilePattern</a> values as a literal string, or build
--   them up using the operators <tt>&lt;.&gt;</tt> and <tt>&lt;/&gt;</tt>
--   (but be aware that <tt>"" <tt>&lt;/&gt;</tt> "foo"</tt> produces
--   <tt>"./foo"</tt>).
type FilePattern = String

-- | Get the files below a certain root that match any of the
--   <a>FilePattern</a> values. Only matches files, not directories. Avoids
--   traversing into directories that it can detect won't have any matches
--   in.
--   
--   <pre>
--   getDirectoryFiles "myproject/src" ["**/*.h","**/*.c"]
--   </pre>
--   
--   If there are certain directories/files that should not be explored,
--   use <a>getDirectoryFilesIgnore</a>.
--   
--   <i>Warning</i>: 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
--   <a>FilePattern</a> values, but don't return any files which match any
--   ignore pattern (the final argument). Typically the ignore pattens will
--   end with <tt>/**</tt>, e.g. <tt>.git/**</tt>.
--   
--   <pre>
--   getDirectoryFilesIgnore "myproject/src" ["**/*.h","**/*.c"] [".git/**"]
--   </pre>
--   
--   <i>Warning</i>: 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 <a>getDirectoryFilesIgnore</a> but that the optimisations that
--   may change behaviour on a case-insensitive file system. Note that this
--   function will never return more results then
--   <a>getDirectoryFilesIgnore</a>, and may return less. However, it will
--   obey invariants such as:
--   
--   <pre>
--   getDirectoryFilesIgnoreSlow root [x] [] ++ getDirectoryFilesIgnoreSlow root [y] []
--       == getDirectoryFilesIgnoreSlow root [x,y] []
--   </pre>
--   
--   In contrast <a>getDirectoryFilesIgnore</a> only guarantees that
--   invariant on case-sensitive file systems.
getDirectoryFilesIgnoreSlow :: FilePath -> [FilePattern] -> [FilePattern] -> IO [FilePath]


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

-- | A type synonym for file patterns, containing <tt>**</tt> and
--   <tt>*</tt>. For the syntax and semantics of <a>FilePattern</a> see
--   <a>?==</a>.
--   
--   Most <a>FilePath</a> values lacking literal <tt>.</tt> and <tt>..</tt>
--   components are suitable as <a>FilePattern</a> values which match only
--   that specific file. On Windows <tt>\</tt> is treated as equivalent to
--   <tt>/</tt>.
--   
--   You can write <a>FilePattern</a> values as a literal string, or build
--   them up using the operators <tt>&lt;.&gt;</tt> and <tt>&lt;/&gt;</tt>
--   (but be aware that <tt>"" <tt>&lt;/&gt;</tt> "foo"</tt> produces
--   <tt>"./foo"</tt>).
type FilePattern = String

-- | Match a <a>FilePattern</a> against a <a>FilePath</a>. There are two
--   special forms:
--   
--   <ul>
--   <li><tt>*</tt> matches part of a path component, excluding any
--   separators.</li>
--   <li><tt>**</tt> as a path component matches an arbitrary number of
--   path components.</li>
--   </ul>
--   
--   Some examples:
--   
--   <ul>
--   <li><tt>test.c</tt> matches <tt>test.c</tt> and nothing else.</li>
--   <li><tt>*.c</tt> matches all <tt>.c</tt> files in the current
--   directory, so <tt>file.c</tt> matches, but <tt>file.h</tt> and
--   <tt>dir/file.c</tt> don't.</li>
--   <li><tt>**/*.c</tt> matches all <tt>.c</tt> files anywhere on the
--   filesystem, so <tt>file.c</tt>, <tt>dir/file.c</tt>,
--   <tt>dir1/dir2/file.c</tt> and <tt>/path/to/file.c</tt> all match, but
--   <tt>file.h</tt> and <tt>dir/file.h</tt> don't.</li>
--   <li><tt>dir/*/*</tt> matches all files one level below <tt>dir</tt>,
--   so <tt>dir/one/file.c</tt> and <tt>dir/two/file.h</tt> match, but
--   <tt>file.c</tt>, <tt>one/dir/file.c</tt>, <tt>dir/file.h</tt> and
--   <tt>dir/one/two/file.c</tt> don't.</li>
--   </ul>
--   
--   Patterns with constructs such as <tt>foo/../bar</tt> will never match
--   normalised <a>FilePath</a> values, so are unlikely to be correct.
(?==) :: FilePattern -> FilePath -> Bool

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

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

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

-- | Efficient matching of a set of <a>FilePattern</a>s against a set of
--   <a>FilePath</a>s. First call <a>step</a> passing in all the
--   <a>FilePattern</a>s, with a tag for each one. Next call the methods of
--   <a>Step</a>, providing the components of the <a>FilePath</a>s 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 <a>step</a> but using <tt>()</tt> as the tag for each
--   <a>FilePattern</a>.
step_ :: [FilePattern] -> Step ()

-- | The result of <a>step</a>, used to process successive path components
--   of a set of <a>FilePath</a>s.
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 <a>match</a>, along with the values passed to
--   <a>step</a>. These results are not necessarily in order.
[stepDone] :: Step a -> [(a, [String])]

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

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

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

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

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

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

-- | Efficiently match many <a>FilePattern</a>s against many
--   <a>FilePath</a>s in a single operation. Note that the returned matches
--   are not guaranteed to be in any particular order.
--   
--   <pre>
--   matchMany [(a, pat)] [(b, path)] == maybeToList (map (a,b,) (match pat path))
--   </pre>
matchMany :: [(a, FilePattern)] -> [(b, FilePath)] -> [(a, b, [String])]
