-- 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 filemanip
@version 0.3.6.3


module System.FilePath.Manip

-- | Type class for string manipulation over files.
class Streamable a

-- | Read the entire contents of a <a>Handle</a>.
readAll :: Streamable a => Handle -> IO a

-- | Write an entire string to a <a>Handle</a>.
writeAll :: Streamable a => Handle -> a -> IO ()

-- | Use a renaming function to generate a new name for a file, then rename
--   it.
renameWith :: (FilePath -> FilePath) -> FilePath -> IO ()

-- | Modify a file in place using the given function. The new content is
--   written to a temporary file. Once this is complete, the file
--   manipulation action is called. Its arguments are the names of the
--   original and temporary files.
--   
--   Example:
--   
--   <pre>
--   <a>modifyInPlace</a> = <a>modifyWith</a> (flip rename)
--   </pre>
modifyWith :: Streamable a => (FilePath -> FilePath -> IO ()) -> (a -> a) -> FilePath -> IO ()

-- | Modify a file in place using the given function. The original copy of
--   the file is saved under a new name. This is performed by writing to a
--   temporary file; renaming the original file to its new name; then
--   renaming the temporary file to the original name.
--   
--   Example:
--   
--   <pre>
--   -- save original file with a ".bak" extension
--   <a>modifyWithBackup</a> (&lt;.&gt; "bak")
--   </pre>
modifyWithBackup :: Streamable a => (FilePath -> FilePath) -> (a -> a) -> FilePath -> IO ()

-- | Modify a file in place using the given function. This is performed by
--   writing to a temporary file, then renaming it on top of the existing
--   file when done.
modifyInPlace :: Streamable a => (a -> a) -> FilePath -> IO ()
instance System.FilePath.Manip.Streamable Data.ByteString.Internal.ByteString
instance System.FilePath.Manip.Streamable Data.ByteString.Lazy.Internal.ByteString
instance System.FilePath.Manip.Streamable GHC.Base.String


module System.FilePath.GlobPattern

-- | Glob pattern type.
type GlobPattern = String

-- | Match a file name against a glob pattern.
(~~) :: FilePath -> GlobPattern -> Bool

-- | Match a file name against a glob pattern, but return <a>True</a> if
--   the match <i>fail</i>s.
(/~) :: FilePath -> GlobPattern -> Bool
instance GHC.Show.Show System.FilePath.GlobPattern.MatchTerm
instance (GHC.Show.Show a, GHC.Arr.Ix a) => GHC.Show.Show (System.FilePath.GlobPattern.SRange a)


module System.FilePath.Glob

-- | Return a list of names matching a glob pattern. The list is generated
--   lazily.
namesMatching :: String -> IO [FilePath]


-- | 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>True</a> for any file whose
--   directory name contains the word <tt>"temp"</tt>.
--   
--   <pre>
--   (isInfixOf "temp") `liftM` <a>directory</a>
--   </pre>
module System.FilePath.Find

-- | 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 <tt>put</tt>.
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 -> IOException -> 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 -> IOException -> 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

-- | Return the canonical path of the file being visited.
--   
--   See <a>canonicalizePath</a> for details of what canonical path means.
canonicalPath :: FindClause FilePath

-- | Return the canonical name of the file (canonical path with the
--   directory part removed).
canonicalName :: FindClause FilePath

-- | 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
--   <a>GlobPattern</a>.
(~~?) :: FindClause FilePath -> GlobPattern -> FindClause Bool
infix 4 ~~?

-- | Return <a>True</a> if the current file's name does not match the given
--   <a>GlobPattern</a>.
(/~?) :: FindClause FilePath -> GlobPattern -> FindClause Bool
infix 4 /~?
(==?) :: Eq a => FindClause a -> a -> FindClause Bool
infix 4 ==?
(/=?) :: Eq a => FindClause a -> a -> FindClause Bool
infix 4 /=?
(>?) :: Ord a => FindClause a -> a -> FindClause Bool
infix 4 >?
(<?) :: Ord a => FindClause a -> a -> FindClause Bool
infix 4 <?
(>=?) :: Ord a => FindClause a -> a -> FindClause Bool
infix 4 >=?
(<=?) :: Ord a => FindClause a -> a -> FindClause Bool
infix 4 <=?

-- | This operator is useful to check if bits are set in a <a>FileMode</a>.
(.&.?) :: Bits a => FindClause a -> a -> FindClause a
infixl 7 .&.?
(&&?) :: FindClause Bool -> FindClause Bool -> FindClause Bool
infixr 3 &&?
(||?) :: FindClause Bool -> FindClause Bool -> FindClause Bool
infixr 2 ||?
instance GHC.Show.Show System.FilePath.Find.FileType
instance GHC.Classes.Ord System.FilePath.Find.FileType
instance GHC.Classes.Eq System.FilePath.Find.FileType
instance GHC.Base.Monad System.FilePath.Find.FindClause
instance GHC.Base.Applicative System.FilePath.Find.FindClause
instance GHC.Base.Functor System.FilePath.Find.FindClause
instance GHC.Classes.Eq System.FilePath.Find.FileInfo
instance GHC.Classes.Eq System.Posix.Files.Common.FileStatus
