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


-- | Recursively manipulate and traverse filesystems as rose trees.
--   
--   Recursively manipulate and traverse filesystems as rose trees.
@package filesystem-trees
@version 0.0

module System.File.Tree

-- | A representation of a filesystem tree. The root label contains the
--   path context, and every child node is a single file/directory name.
--   
--   For example, say we have the following directory structure on our
--   filesystem:
--   
--   <pre>
--   
--   /example$ tree foo --charset ASCII
--   foo
--   `-- bar
--       `-- test
--           |-- a
--           |-- A
--           |   |-- x
--           |   `-- y
--           |-- b
--           `-- B
--   </pre>
--   
--   then calling <a>getDirectory</a> "/example/foo/bar/test" will yield a
--   FSTree with the following structure:
--   
--   <pre>
--   /example$ ghci
--   Prelude Data.Tree System.Directory.Tree&gt; putStrLn . drawTree . toTree =&lt;&lt; getDirectory "/example/foo/bar/test"
--   /example/foo/bar/test
--   |
--   +- A
--   |  |
--   |  +- x
--   |  |
--   |  `- y
--   |
--   +- B
--   |
--   +- a
--   |
--   `- b
--   </pre>
newtype FSTree
FSTree :: Tree FilePath -> FSTree
toTree :: FSTree -> Tree FilePath

-- | A pseudo-constructor for <a>FSTree</a>.
mkFSTree :: FilePath -> FSForest -> FSTree
type FSForest = [FSTree]

-- | Multi-way trees, also known as <i>rose trees</i>.
data Tree a :: * -> *
Node :: a -> Forest a -> Tree a

-- | label value
rootLabel :: Tree a -> a

-- | zero or more child trees
subForest :: Tree a -> Forest a
type Forest a = [Tree a]

-- | Overloaded lenses for <a>Tree</a> and <a>FSTree</a>
class TreeLens t a | t -> a
label :: TreeLens t a => Lens t a
children :: TreeLens t a => Lens t [t]

-- | Lazily retrieves a representation of a directory and its contents
--   recursively.
--   
--   Relative paths are not converted to absolute. Thus, a FSTree formed
--   from a relative path will contain a "relative tree", and the usual
--   caveats of current directories and relative paths apply to the tree as
--   a whole.
getDirectory :: FilePath -> IO FSTree

-- | A strict variant of <a>getDirectory</a>.
--   
--   Though race conditionals are still a possibility, this function will
--   avoid some race conditions that could be caused from the use of lazy
--   IO. For large directories, this function can easily cause memory
--   leaks.
getDirectory' :: FilePath -> IO FSTree

-- | Copy a filesystem tree to a new location, creating directories as
--   necessary. The resulting <a>FSTree</a> represents all of the copied
--   directories/files in their new home.
--   
--   Note that an single exception will halt the entire operation.
copyTo :: FilePath -> FSTree -> IO FSTree
copyTo_ :: FilePath -> FSTree -> IO ()

-- | Move a filesystem tree to a new location, deleting any file/directory
--   that was present at the given destination path.
--   
--   Directories listed in the source filesystem tree are removed if the
--   move operation empties their contents completely. The resulting
--   <a>FSTree</a> represents all the moved directories/files in their new
--   home.
--   
--   Note that an single exception will halt the entire operation.
moveTo :: FilePath -> FSTree -> IO FSTree
moveTo_ :: FilePath -> FSTree -> IO ()

-- | This is similar to <a>moveTo</a>, except that whatever was present at
--   the destination path isn't deleted before the move operation
--   commences.
--   
--   Note that an single exception will halt the entire operation.
mergeInto :: FilePath -> FSTree -> IO FSTree
mergeInto_ :: FilePath -> FSTree -> IO ()

-- | Remove a given filesystem tree. Directories are only removed if the
--   remove operation empties its contents.
--   
--   Note that an single exception will halt the entire operation.
remove :: FSTree -> IO ()

-- | A variant of <a>remove</a>. <tt>IOExceptions</tt> do not stop the
--   removal process, and all <tt>IOExceptions</tt> are accumulated into a
--   list as the result of the operation.
tryRemove :: FSTree -> IO [IOException]

-- | A variant of <a>remove</a>. Allows you to specify your own exception
--   handler to handle exceptions for each removal operation.
tryRemoveWith :: (IOException -> IO a) -> FSTree -> IO [a]

-- | Remove the root node of a filesystem tree, while preserving the paths
--   of its children. In other words, this function does not alter where
--   any paths point to.
pop :: FSTree -> (FilePath, FSForest)

-- | <pre>
--   pop_ = snd . pop
--   </pre>
pop_ :: FSTree -> FSForest

-- | Flattens a filesystem tree into a list of its contents. This is a
--   pre-order traversal of the tree.
flatten :: FSTree -> [FilePath]

-- | A post-order traversal of the filesystem tree.
flattenPostOrder :: FSTree -> [FilePath]

-- | Applies a function over the filepaths of a directory tree.
--   
--   Because we can't guarantee that the internal <a>FSTree</a>
--   representation is preserved in any way, the result is a regular
--   <a>Tree</a>.
map :: (FilePath -> b) -> FSTree -> Tree b

-- | Applies a monadic action to every filepath in a filesystem tree.
mapM :: Monad m => (FilePath -> m b) -> FSTree -> m (Tree b)

-- | <a>mapM</a> with the result discarded.
mapM_ :: Monad m => (FilePath -> m b) -> FSTree -> m ()

-- | Find all sub-forests within a forest that match the given predicate.
find :: (FilePath -> Bool) -> FSForest -> FSForest

-- | Monadic <a>find</a>.
findM :: Monad m => (FilePath -> m Bool) -> FSForest -> m FSForest

-- | Applies a predicate to each path name in a filesystem forest, and
--   removes all unsuccessful paths from the result.
--   
--   Note that if a directory fails the predicate test, then all of its
--   children are removed as well.
filter :: (FilePath -> Bool) -> FSForest -> FSForest

-- | Monadic <a>filter</a>.
filterM :: Monad m => (FilePath -> m Bool) -> FSForest -> m FSForest

-- | Checks if a path refers to a file.
isFile :: FilePath -> IO Bool

-- | Checks if a path refer to a directory.
isDir :: FilePath -> IO Bool

-- | Checks if a path refers to a symbolic link
isSymLink :: FilePath -> IO Bool

-- | Checks if a path refers to a symbolically linked directory
isSymDir :: FilePath -> IO Bool

-- | Checks if a path refers to a symbolically linked file
isSymFile :: FilePath -> IO Bool

-- | Checks if a path refers to a real file (not a symbolic link)
isRealFile :: FilePath -> IO Bool

-- | Checks if a path refers to a real directory (not a symbolic link)
isRealDir :: FilePath -> IO Bool

-- | A combination of a <a>find</a> and a <a>map</a>. This could be useful
--   if you want to handle certain directories specially from others within
--   a sub-filesystem.
extract :: (FilePath -> Bool) -> FSForest -> (FSForest, FSForest)

-- | Monadic <a>extract</a>.
extractM :: Monad m => (FilePath -> m Bool) -> FSForest -> m (FSForest, FSForest)

-- | Truncate a tree to a given maximum level, where root is level 0.
truncateAt :: TreeLens t a => Word -> t -> t

-- | A generalization of the various move, copy, and remove operations.
--   This operation pairs each node of a <a>FSTree</a> with a second path
--   formed by rerooting the filesystem tree to the given destination path.
zipWithDest :: (FilePath -> FilePath -> a) -> FilePath -> FSTree -> [a]

-- | Monadic <a>zipWithDest</a>
zipWithDestM :: Monad m => (FilePath -> FilePath -> m a) -> FilePath -> FSTree -> m [a]

-- | A variant of <a>zipWithDestM</a> where the result is discarded and
--   instead the rerooted filesystem tree is returned.
zipWithDestM_ :: Monad m => (FilePath -> FilePath -> m a) -> FilePath -> FSTree -> m FSTree
instance Typeable FSTree
instance Data FSTree
instance Eq FSTree
instance Read FSTree
instance Show FSTree
instance TreeLens FSTree FilePath
instance TreeLens (Tree a) a