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


-- | A simple directory-like tree datatype, with useful IO functions
--   
--   A simple directory-like tree datatype, with useful IO functions and
--   Foldable and Traversable instance
--   
--   Provides a simple data structure mirroring a directory tree on the
--   filesystem, as well as useful functions for reading and writing file
--   and directory structures in the IO monad.
--   
--   Importing the library and optional (useful) Foldable and Traverable
--   libraries:
--   
--   <pre>
--   import System.Directory.Tree
--   import qualified Data.Foldable as F
--   import qualified Data.Traversable as T
--   </pre>
--   
--   Write a hand-made directory tree of textfiles (strings) to the disk.
--   Simulates creating a new user Tux's home directory on a unix machine:
--   
--   <pre>
--   writeDirectory$ "/home" :/ Dir "Tux" [File "README" "Welcome!"]
--   </pre>
--   
--   <a>read</a> a directory by opening all the files at a filepath with
--   readFile, returning an 'AnchoredDirTree String' (d2). Then check for
--   any IO failures:
--   
--   <pre>
--   do (base :/ d2) &lt;- readDirectory "../parent_dir/dir2/"
--      let failed = anyFailed d2
--      if failed then ...
--   </pre>
--   
--   Use Foldable instance function to concat a directory <a>dir</a> of
--   text files into a single file under the same directory:
--   
--   <pre>
--   do (b :/ dt) &lt;- readDirectory dir
--      let f = F.concat dt
--      return$ b :/ File "ALL_TEXT" f
--   </pre>
--   
--   Open all the files in the current directory as lazy bytestrings,
--   ignoring the base path in Anchored wrapper:
--   
--   <pre>
--   import qualified Data.ByteString.Lazy as B
--   do (_ :/ dTree) &lt;- readDirectoryWith B.readFile "./"
--   </pre>
--   
--   This version also offers an experimental function
--   <a>readDirectoryWithL</a> that does lazy directory IO, allowing you to
--   treat the returned <a>DirTree</a> as if it were a normal
--   lazily-generated data structure.
--   
--   For example, the following does only the amount of IO necessary to
--   list the file names of the children of the root directory, similar to
--   <a>ls /</a>:
--   
--   <pre>
--   do d &lt;- readDirectoryWithL readFile "/"
--      mapM_ (putStrLn . name) $ contents $ free d
--   </pre>
--   
--   Any ideas or suggestions for improvements are most welcome :-)
@package directory-tree
@version 0.9.0


-- | filesystem, as well as useful functions for reading and writing file
--   and directory structures in the IO monad.
--   
--   Errors are caught in a special constructor in the DirTree type.
--   
--   Defined instances of Functor, Traversable and Foldable allow for
--   easily operating on a directory of files. For example, you could use
--   Foldable.foldr to create a hash of the entire contents of a directory.
--   
--   The functions <a>readDirectoryWithL</a> and <a>buildL</a> allow for
--   doing directory-traversing IO lazily as required by the execution of
--   pure code. This allows you to treat large directories the same way as
--   you would a lazy infinite list.
--   
--   The AnchoredDirTree type is a simple wrapper for DirTree to keep track
--   of a base directory context for the DirTree.
--   
--   Please send me any requests, bugs, or other feedback on this module!
module System.Directory.Tree

-- | the String in the name field is always a file name, never a full path.
--   The free type variable is used in the File constructor and can hold
--   Handles, Strings representing a file's contents or anything else you
--   can think of. We catch any IO errors in the Failed constructor. an
--   Exception can be converted to a String with <a>show</a>.
data DirTree a
Failed :: FileName -> IOException -> DirTree a
name :: DirTree a -> FileName
err :: DirTree a -> IOException
Dir :: FileName -> [DirTree a] -> DirTree a
name :: DirTree a -> FileName
contents :: DirTree a -> [DirTree a]
File :: FileName -> a -> DirTree a
name :: DirTree a -> FileName
file :: DirTree a -> a

-- | a simple wrapper to hold a base directory name, which can be either an
--   absolute or relative path. This lets us give the DirTree a context,
--   while still letting us store only directory and file NAMES (not full
--   paths) in the DirTree. (uses an infix constructor; don't be scared)
data AnchoredDirTree a
(:/) :: FilePath -> DirTree a -> AnchoredDirTree a

-- | an element in a FilePath:
type FileName = String

-- | build an AnchoredDirTree, given the path to a directory, opening the
--   files using readFile. Uses <a>readDirectoryWith</a> internally and has
--   the effect of traversing the entire directory structure. See
--   <a>readDirectoryWithL</a> for lazy production of a DirTree structure.
readDirectory :: FilePath -> IO (AnchoredDirTree String)

-- | same as readDirectory but allows us to, for example, use
--   ByteString.readFile to return a tree of ByteStrings.
readDirectoryWith :: (FilePath -> IO a) -> FilePath -> IO (AnchoredDirTree a)

-- | A <a>lazy</a> version of <a>readDirectoryWith</a> that does IO
--   operations as needed i.e. as the tree is traversed in pure code.
--   <i>NOTE:</i> This function uses unsafePerformIO under the hood. I
--   believe our use here is safe, but this function is experimental in
--   this release:
readDirectoryWithL :: (FilePath -> IO a) -> FilePath -> IO (AnchoredDirTree a)

-- | write a DirTree of strings to disk. Clobbers files of the same name.
--   Doesn't affect files in the directories (if any already exist) with
--   different names. Returns a new AnchoredDirTree where failures were
--   lifted into a <a>Failed</a> constructor:
writeDirectory :: AnchoredDirTree String -> IO (AnchoredDirTree ())

-- | writes the directory structure to disk and uses the provided function
--   to write the contents of <tt>Files</tt> to disk. The return value of
--   the function will become the new <a>contents</a> of the returned,
--   where IO errors at each node are replaced with <a>Failed</a>
--   constructors. The returned tree can be compared to the passed tree to
--   see what operations, if any, failed:
writeDirectoryWith :: (FilePath -> a -> IO b) -> AnchoredDirTree a -> IO (AnchoredDirTree b)

-- | tuple up the complete filename with the File contents, by building up
--   the path, trie-style, from the root. The filepath will be relative to
--   the current directory. This allows us to, for example, mapM_ 'uncurry
--   writeFile' over a DirTree of strings, although <a>writeDirectory</a>
--   does a better job of this.
zipPaths :: AnchoredDirTree a -> DirTree (FilePath, a)

-- | builds a DirTree from the contents of the directory passed to it,
--   saving the base directory in the Anchored* wrapper. Errors are caught
--   in the tree in the Failed constructor. The <a>file</a> fields
--   initially are populated with full paths to the files they are
--   abstracting.
build :: FilePath -> IO (AnchoredDirTree FilePath)

-- | identical to <a>build</a> but does directory reading IO lazily as
--   needed:
buildL :: FilePath -> IO (AnchoredDirTree FilePath)

-- | a simple application of readDirectoryWith openFile:
openDirectory :: FilePath -> IOMode -> IO (AnchoredDirTree Handle)

-- | writes the directory structure (not files) of a DirTree to the
--   anchored directory. Returns a structure identical to the supplied tree
--   with errors replaced by <a>Failed</a> constructors:
writeJustDirs :: AnchoredDirTree a -> IO (AnchoredDirTree a)

-- | True if there are no Failed constructors in the tree
successful :: DirTree a -> Bool

-- | True if any Failed constructors in the tree
anyFailed :: DirTree a -> Bool

-- | returns true if argument is a <a>Failed</a> constructor:
failed :: DirTree a -> Bool

-- | returns a list of <a>Failed</a> constructors only:
failures :: DirTree a -> [DirTree a]

-- | maps a function to convert Failed DirTrees to Files or Dirs
failedMap :: (FileName -> IOException -> DirTree a) -> DirTree a -> DirTree a

-- | Flattens a <a>DirTree</a> into a (never empty) list of tree
--   constructors. <a>Dir</a> constructors will have [] as their
--   <a>contents</a>:
flattenDir :: DirTree a -> [DirTree a]

-- | Sort the <a>contents</a> of every <a>Dir</a> constructor, see Ord
--   instance above:
sortDir :: DirTree a -> DirTree a

-- | applies the predicate to each constructor in the tree, removing it
--   (and its children, of course) when the predicate returns False. The
--   topmost constructor will always be preserved:
filterDir :: (DirTree a -> Bool) -> DirTree a -> DirTree a

-- | strips away base directory wrapper:
free :: AnchoredDirTree a -> DirTree a

-- | Allows for a function on a bare DirTree to be applied to an
--   AnchoredDirTree within a Functor. Very similar to and useful in
--   combination with <a>&lt;$&gt;</a>:
(</$>) :: (Functor f) => (DirTree a -> DirTree b) -> f (AnchoredDirTree a) -> f (AnchoredDirTree b)
instance (Show a) => Show (AnchoredDirTree a)
instance Ord (AnchoredDirTree a)
instance Eq (AnchoredDirTree a)
instance (Show a) => Show (DirTree a)
instance Functor AnchoredDirTree
instance Traversable DirTree
instance Foldable DirTree
instance Functor DirTree
instance Ord (DirTree a)
instance Eq (DirTree a)