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


-- | Expressive file and directory manipulation for Haskell.
--   
--   A Haskell library for working with files and directories. Includes
--   code for pattern matching, finding files, modifying file contents, and
--   more.
@package FileManipCompat
@version 0.18


-- | This module provides functions for traversing a filesystem hierarchy.
--   The <a>find</a> function generates a lazy list of matching files,
--   while <a>fold</a> performs a left fold.
--   
--   Both <a>find</a> and <a>fold</a> allow fine control over recursion,
--   using the <a>FindClause</a> type. This type is also used to pre-filter
--   the results returned by <a>find</a>.
--   
--   The <a>FindClause</a> type lets you write filtering and recursion
--   control expressions clearly and easily.
--   
--   For example, this clause matches C source files.
--   
--   <pre>
--   <a>extension</a> <a>==?</a> ".c" <a>||?</a> <a>extension</a> <a>==?</a> ".h"
--   </pre>
--   
--   Because <a>FindClause</a> is a monad, you can use the usual monad
--   machinery to, for example, lift pure functions into it.
--   
--   Here's a clause that will return <a>False</a> for any file whose
--   directory name contains the word <tt>"temp"</tt>.
--   
--   <pre>
--   (isInfixOf "temp") `liftM` <a>directory</a>
--   </pre>
module System.FilePath.FindCompat

-- | Information collected during the traversal of a directory.
data FileInfo
FileInfo :: FilePath -> Int -> FileStatus -> FileInfo

-- | file path
infoPath :: FileInfo -> FilePath

-- | current recursion depth
infoDepth :: FileInfo -> Int

-- | status of file
infoStatus :: FileInfo -> FileStatus
data FileType
BlockDevice :: FileType
CharacterDevice :: FileType
NamedPipe :: FileType
RegularFile :: FileType
Directory :: FileType
SymbolicLink :: FileType
Socket :: FileType
Unknown :: FileType

-- | Monadic container for file information, allowing for clean
--   construction of combinators. Wraps the <a>State</a> monad, but doesn't
--   allow <a>get</a> or <a>put</a>.
data FindClause a
type FilterPredicate = FindClause Bool
type RecursionPredicate = FindClause Bool

-- | Search a directory recursively, with recursion controlled by a
--   <a>RecursionPredicate</a>. Lazily return a sorted list of all files
--   matching the given <a>FilterPredicate</a>. Any errors that occur are
--   ignored, with warnings printed to <a>stderr</a>.
find :: RecursionPredicate -> FilterPredicate -> FilePath -> IO [FilePath]

-- | Search a directory recursively, with recursion controlled by a
--   <a>RecursionPredicate</a>. Fold over all files found. Any errors that
--   occur are ignored, with warnings printed to <a>stderr</a>. The fold
--   function is run from "left" to "right", so it should be strict in its
--   left argument to avoid space leaks. If you need a right-to-left fold,
--   use <a>foldr</a> on the result of <a>findWithHandler</a> instead.
fold :: RecursionPredicate -> (a -> FileInfo -> a) -> a -> FilePath -> IO a

-- | Search a directory recursively, with recursion controlled by a
--   <a>RecursionPredicate</a>. Lazily return a sorted list of all files
--   matching the given <a>FilterPredicate</a>. Any errors that occur are
--   dealt with by the given handler.
findWithHandler :: (FilePath -> SomeException -> IO [FilePath]) -> RecursionPredicate -> FilterPredicate -> FilePath -> IO [FilePath]

-- | Search a directory recursively, with recursion controlled by a
--   <a>RecursionPredicate</a>. Fold over all files found. Any errors that
--   occur are dealt with by the given handler. The fold is strict, and run
--   from "left" to "right", so the folded function should be strict in its
--   left argument to avoid space leaks. If you need a right-to-left fold,
--   use <a>foldr</a> on the result of <a>findWithHandler</a> instead.
foldWithHandler :: (FilePath -> a -> SomeException -> IO a) -> RecursionPredicate -> (a -> FileInfo -> a) -> a -> FilePath -> IO a

-- | Run the given <a>FindClause</a> on the given <a>FileInfo</a> and
--   return its result. This can be useful if you are writing a function to
--   pass to <a>fold</a>.
--   
--   Example:
--   
--   <pre>
--   myFoldFunc :: a -&gt; <a>FileInfo</a> -&gt; a
--   myFoldFunc a i = let useThisFile = <a>evalClause</a> (<a>fileName</a> <a>==?</a> "foo") i
--                    in if useThisFile
--                       then fiddleWith a
--                       else a
--   </pre>
evalClause :: FindClause a -> FileInfo -> a

-- | Return the type of a file. This is much more useful for case analysis
--   than the usual functions on <a>FileStatus</a> values.
statusType :: FileStatus -> FileType

-- | Lift a binary operator into the <a>FindClause</a> monad, so that it
--   becomes a combinator. The left hand side of the combinator should be a
--   <tt><a>FindClause</a> a</tt>, while the right remains a normal value
--   of type <tt>a</tt>.
liftOp :: Monad m => (a -> b -> c) -> m a -> b -> m c

-- | Return the name of the file being visited.
filePath :: FindClause FilePath

-- | Return the <a>FileStatus</a> for the current file.
fileStatus :: FindClause FileStatus

-- | Return the current recursion depth.
depth :: FindClause Int

-- | Return the current <a>FileInfo</a>.
fileInfo :: FindClause FileInfo

-- | Unconditionally return <a>True</a>.
always :: FindClause Bool

-- | Return the file name extension.
--   
--   Example:
--   
--   <pre>
--   <a>extension</a> "foo/bar.txt" =&gt; ".txt"
--   </pre>
extension :: FindClause FilePath

-- | Return the directory name, without the file name.
--   
--   What this means in practice:
--   
--   <pre>
--   <a>directory</a> "foo/bar.txt" =&gt; "foo"
--   </pre>
--   
--   Example in a clause:
--   
--   <pre>
--   let hasSuffix = <a>liftOp</a> <tt>isSuffixOf</tt>
--   in directory `hasSuffix` "tests"
--   </pre>
directory :: FindClause FilePath

-- | Return the file name, without the directory name.
--   
--   What this means in practice:
--   
--   <pre>
--   <a>fileName</a> "foo/bar.txt" =&gt; "bar.txt"
--   </pre>
--   
--   Example:
--   
--   <pre>
--   <a>fileName</a> <a>==?</a> "init.c"
--   </pre>
fileName :: FindClause FilePath

-- | Return the type of file currently being visited.
--   
--   Example:
--   
--   <pre>
--   <a>fileType</a> <a>==?</a> <a>RegularFile</a>
--   </pre>
fileType :: FindClause FileType

-- | Return <a>True</a> if the given path exists, relative to the current
--   file. For example, if <tt>"foo"</tt> is being visited, and you call
--   contains <tt>"bar"</tt>, this combinator will return <a>True</a> if
--   <tt>"foo/bar"</tt> exists.
contains :: FilePath -> FindClause Bool
deviceID :: FindClause DeviceID
fileID :: FindClause FileID
fileOwner :: FindClause UserID
fileGroup :: FindClause GroupID
fileSize :: FindClause FileOffset
linkCount :: FindClause LinkCount
specialDeviceID :: FindClause DeviceID
fileMode :: FindClause FileMode
accessTime :: FindClause EpochTime
modificationTime :: FindClause EpochTime
statusChangeTime :: FindClause EpochTime

-- | Return the permission bits of the <a>FileMode</a>.
filePerms :: FindClause FileMode

-- | Return <a>True</a> if any of the given permission bits is set.
--   
--   Example:
--   
--   <pre>
--   <a>anyPerms</a> 0444
--   </pre>
anyPerms :: FileMode -> FindClause Bool

-- | If the current file is a symbolic link, return <a>Just</a> the target
--   of the link, otherwise <a>Nothing</a>.
readLink :: FindClause (Maybe FilePath)

-- | If the current file is a symbolic link, return <a>Just</a> the status
--   of the ultimate endpoint of the link. Otherwise (including in the case
--   of an error), return <a>Nothing</a>.
--   
--   Example:
--   
--   <pre>
--   <a>statusType</a> `liftM` <a>followStatus</a> <a>==?</a> <a>RegularFile</a>
--   </pre>
followStatus :: FindClause (Maybe FileStatus)

-- | Return <a>True</a> if the current file's name matches the given
--   <tt>GlobPattern</tt>.
(==?) :: Eq a => FindClause a -> a -> FindClause Bool
(/=?) :: Eq a => FindClause a -> a -> FindClause Bool
(>?) :: Ord a => FindClause a -> a -> FindClause Bool
(<?) :: Ord a => FindClause a -> a -> FindClause Bool
(>=?) :: Ord a => FindClause a -> a -> FindClause Bool
(<=?) :: Ord a => FindClause a -> a -> FindClause Bool

-- | This operator is useful to check if bits are set in a <a>FileMode</a>.
(.&.?) :: Bits a => FindClause a -> a -> FindClause a
(&&?) :: FindClause Bool -> FindClause Bool -> FindClause Bool
(||?) :: FindClause Bool -> FindClause Bool -> FindClause Bool
instance Eq FileInfo
instance Functor FindClause
instance Monad FindClause
instance Eq FileType
instance Ord FileType
instance Show FileType
instance Eq FileStatus