System.Directory.Contents

Modeled after the linux tree command (when invoked with the follow-symlinks option), this module recursively lists the contents of a directory while avoiding symlink loops. See the documentation of buildDirTree for an example.

In addition to building the directory-contents tree, this module provides facilities for filtering, displaying, and navigating the directory hierarchy.

See DirZipper for zipper-based navigation.

Directory hierarchy tree

data DirTree a

The contents of a directory, represented as a tree. See Symlink for special handling of symlinks.

Constructors

DirTree_Dir FilePath (Map FileName (DirTree a))

DirTree_File FilePath a

DirTree_Symlink FilePath (Symlink a)

Instances

Functor DirTree

Defined in System.Directory.Contents.Types

Methods

fmap :: (a -> b) -> DirTree a -> DirTree b

(<$) :: a -> DirTree b -> DirTree a

Foldable DirTree

Defined in System.Directory.Contents.Types

Methods

fold :: Monoid m => DirTree m -> m

foldMap :: Monoid m => (a -> m) -> DirTree a -> m

foldr :: (a -> b -> b) -> b -> DirTree a -> b

foldr' :: (a -> b -> b) -> b -> DirTree a -> b

foldl :: (b -> a -> b) -> b -> DirTree a -> b

foldl' :: (b -> a -> b) -> b -> DirTree a -> b

foldr1 :: (a -> a -> a) -> DirTree a -> a

foldl1 :: (a -> a -> a) -> DirTree a -> a

toList :: DirTree a -> [a]

null :: DirTree a -> Bool

length :: DirTree a -> Int

elem :: Eq a => a -> DirTree a -> Bool

maximum :: Ord a => DirTree a -> a

minimum :: Ord a => DirTree a -> a

sum :: Num a => DirTree a -> a

product :: Num a => DirTree a -> a

Traversable DirTree

Defined in System.Directory.Contents.Types

Methods

traverse :: Applicative f => (a -> f b) -> DirTree a -> f (DirTree b)

sequenceA :: Applicative f => DirTree (f a) -> f (DirTree a)

mapM :: Monad m => (a -> m b) -> DirTree a -> m (DirTree b)

sequence :: Monad m => DirTree (m a) -> m (DirTree a)

Eq a => Eq (DirTree a)

Defined in System.Directory.Contents.Types

Methods

(==) :: DirTree a -> DirTree a -> Bool

(/=) :: DirTree a -> DirTree a -> Bool

Data a => Data (DirTree a)

Defined in System.Directory.Contents.Types

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> DirTree a -> c (DirTree a)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (DirTree a)

toConstr :: DirTree a -> Constr

dataTypeOf :: DirTree a -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (DirTree a))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (DirTree a))

gmapT :: (forall b. Data b => b -> b) -> DirTree a -> DirTree a

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> DirTree a -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> DirTree a -> r

gmapQ :: (forall d. Data d => d -> u) -> DirTree a -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> DirTree a -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> DirTree a -> m (DirTree a)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> DirTree a -> m (DirTree a)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> DirTree a -> m (DirTree a)

Ord a => Ord (DirTree a)

Defined in System.Directory.Contents.Types

Methods

compare :: DirTree a -> DirTree a -> Ordering

(<) :: DirTree a -> DirTree a -> Bool

(<=) :: DirTree a -> DirTree a -> Bool

(>) :: DirTree a -> DirTree a -> Bool

(>=) :: DirTree a -> DirTree a -> Bool

max :: DirTree a -> DirTree a -> DirTree a

min :: DirTree a -> DirTree a -> DirTree a

Read a => Read (DirTree a)

Defined in System.Directory.Contents.Types

Methods

readsPrec :: Int -> ReadS (DirTree a)

readList :: ReadS [DirTree a]

readPrec :: ReadPrec (DirTree a)

readListPrec :: ReadPrec [DirTree a]

Show a => Show (DirTree a)

Defined in System.Directory.Contents.Types

Methods

showsPrec :: Int -> DirTree a -> ShowS

show :: DirTree a -> String

showList :: [DirTree a] -> ShowS

Generic (DirTree a)

Defined in System.Directory.Contents.Types

Associated Types

type Rep (DirTree a) :: Type -> Type

Methods

from :: DirTree a -> Rep (DirTree a) x

to :: Rep (DirTree a) x -> DirTree a

type Rep (DirTree a)

Defined in System.Directory.Contents.Types

type Rep (DirTree a) = D1 (MetaData "DirTree" "System.Directory.Contents.Types" "directory-contents-0.2.0.0-inplace" False) (C1 (MetaCons "DirTree_Dir" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Map FileName (DirTree a)))) :+: (C1 (MetaCons "DirTree_File" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 a)) :+: C1 (MetaCons "DirTree_Symlink" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Symlink a)))))

data Symlink a

Symlink cycles are prevented by separating symlinks into two categories: those that point to paths already within the directory hierarchy being recursively listed, and those that are not. In the former case, rather than following the symlink and listing the target redundantly, we simply store the symlink reference itself. In the latter case, we treat the symlink as we would any other folder and produce a list of its contents.

The String argument represents the symlink reference (e.g., "../somefile"). In the Symlink_Internal case, the second (FilePath) argument is the path to the symlink target. In the Symlink_External case, the second ([DirTree a]) argument contains the contents of the symlink target.

Constructors

Symlink_Internal String FilePath

Symlink_External String (Map FileName (DirTree a))

Instances

Functor Symlink

Defined in System.Directory.Contents.Types

Methods

fmap :: (a -> b) -> Symlink a -> Symlink b

(<$) :: a -> Symlink b -> Symlink a

Foldable Symlink

Defined in System.Directory.Contents.Types

Methods

fold :: Monoid m => Symlink m -> m

foldMap :: Monoid m => (a -> m) -> Symlink a -> m

foldr :: (a -> b -> b) -> b -> Symlink a -> b

foldr' :: (a -> b -> b) -> b -> Symlink a -> b

foldl :: (b -> a -> b) -> b -> Symlink a -> b

foldl' :: (b -> a -> b) -> b -> Symlink a -> b

foldr1 :: (a -> a -> a) -> Symlink a -> a

foldl1 :: (a -> a -> a) -> Symlink a -> a

toList :: Symlink a -> [a]

null :: Symlink a -> Bool

length :: Symlink a -> Int

elem :: Eq a => a -> Symlink a -> Bool

maximum :: Ord a => Symlink a -> a

minimum :: Ord a => Symlink a -> a

sum :: Num a => Symlink a -> a

product :: Num a => Symlink a -> a

Traversable Symlink

Defined in System.Directory.Contents.Types

Methods

traverse :: Applicative f => (a -> f b) -> Symlink a -> f (Symlink b)

sequenceA :: Applicative f => Symlink (f a) -> f (Symlink a)

mapM :: Monad m => (a -> m b) -> Symlink a -> m (Symlink b)

sequence :: Monad m => Symlink (m a) -> m (Symlink a)

Eq a => Eq (Symlink a)

Defined in System.Directory.Contents.Types

Methods

(==) :: Symlink a -> Symlink a -> Bool

(/=) :: Symlink a -> Symlink a -> Bool

Data a => Data (Symlink a)

Defined in System.Directory.Contents.Types

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Symlink a -> c (Symlink a)

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c (Symlink a)

toConstr :: Symlink a -> Constr

dataTypeOf :: Symlink a -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c (Symlink a))

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c (Symlink a))

gmapT :: (forall b. Data b => b -> b) -> Symlink a -> Symlink a

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Symlink a -> r

gmapQr :: (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Symlink a -> r

gmapQ :: (forall d. Data d => d -> u) -> Symlink a -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Symlink a -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Symlink a -> m (Symlink a)

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Symlink a -> m (Symlink a)

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Symlink a -> m (Symlink a)

Ord a => Ord (Symlink a)

Defined in System.Directory.Contents.Types

Methods

compare :: Symlink a -> Symlink a -> Ordering

(<) :: Symlink a -> Symlink a -> Bool

(<=) :: Symlink a -> Symlink a -> Bool

(>) :: Symlink a -> Symlink a -> Bool

(>=) :: Symlink a -> Symlink a -> Bool

max :: Symlink a -> Symlink a -> Symlink a

min :: Symlink a -> Symlink a -> Symlink a

Read a => Read (Symlink a)

Defined in System.Directory.Contents.Types

Methods

readsPrec :: Int -> ReadS (Symlink a)

readList :: ReadS [Symlink a]

readPrec :: ReadPrec (Symlink a)

readListPrec :: ReadPrec [Symlink a]

Show a => Show (Symlink a)

Defined in System.Directory.Contents.Types

Methods

showsPrec :: Int -> Symlink a -> ShowS

show :: Symlink a -> String

showList :: [Symlink a] -> ShowS

Generic (Symlink a)

Defined in System.Directory.Contents.Types

Associated Types

type Rep (Symlink a) :: Type -> Type

Methods

from :: Symlink a -> Rep (Symlink a) x

to :: Rep (Symlink a) x -> Symlink a

type Rep (Symlink a)

Defined in System.Directory.Contents.Types

type Rep (Symlink a) = D1 (MetaData "Symlink" "System.Directory.Contents.Types" "directory-contents-0.2.0.0-inplace" False) (C1 (MetaCons "Symlink_Internal" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 FilePath)) :+: C1 (MetaCons "Symlink_External" PrefixI False) (S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 String) :*: S1 (MetaSel (Nothing :: Maybe Symbol) NoSourceUnpackedness NoSourceStrictness DecidedLazy) (Rec0 (Map FileName (DirTree a)))))

type FileName = String

File names, as opposed to file paths, are used to uniquely identify siblings at each level

Constructing directory trees

buildDirTree :: FilePath -> IO (Maybe (DirTree FilePath))

Recursively list the contents of a FilePath, representing the results as a hierarchical DirTree. This function should produce results similar to the linux command tree -l.

For example, given this directory and symlink structure (as shown by tree -l):

test
├── A
│   ├── a
│   ├── A -> ../A  [recursive, not followed]
│   └── B -> ../B
│       ├── A -> ../A  [recursive, not followed]
│       └── b
├── B
│   ├── A -> ../A  [recursive, not followed]
│   └── b
└── C -> ../C
    └── c

this function will produce the following (as rendered by drawDirTree):

test
|
+- A
|  |
|  +- A -> ../A
|  |
|  +- B -> ../B
|  |
|  `- a
|
+- B
|  |
|  +- A -> ../A
|  |
|  `- b
|
`- C -> ../C
   |
   `- c

dereferenceSymlinks :: DirTree FilePath -> IO (DirTree FilePath)

De-reference one layer of symlinks

Example

Given:

tmp
|
+- A
|  |
|  `- a
|
+- a -> A/a
|
`- C
   |
   `- A -> ../A

This function will follow one level of symlinks, producing:

tmp
|
+- A
|  |
|  `- a
|
+- a
|
`- C
   |
   `- A
      |
      `- a

Lower level tree construction

Extracting basic file information

filePath :: DirTree a -> FilePath

Extract the FilePath from a DirTree node

fileName :: DirTree a -> FileName

Generate the key used to identify siblings

Building and manipulating a map of sibling files

fileNameMap :: [DirTree a] -> Map FileName (DirTree a)

Construct a map of files indexed by filename. Should only be used for a particular generation or level in the directory hierarchy (since that's the only time we can be sure that names are unique)

insertSibling :: DirTree a -> Map FileName (DirTree a) -> Map FileName (DirTree a)

Add a sibling to a map of files

removeSibling :: DirTree a -> Map FileName (DirTree a) -> Map FileName (DirTree a)

Remove sibling from a map of files

withFirstChild :: Map FileName (DirTree a) -> (DirTree a -> Map FileName (DirTree a) -> x) -> Maybe x

Map a function over the first child and the rest of the children

Basic directory tree navigation

walkDirTree :: FilePath -> DirTree a -> Maybe (DirTree a)

Starting from the root directory, try to walk the given filepath and return the DirTree at the end of the route. For example, given the following tree:

src
└── System
    └── Directory
            └── Contents.hs

walkDirTree "src/System" should produce

Directory
|
`- Contents.hs

This function does not dereference symlinks, nor does it handle the special paths . and ... For more advanced navigation, including handling of special paths, see DirZipper.

walkContents :: FilePath -> DirTree a -> Maybe (DirTree a)

Like walkDirTree but skips the outermost containing directory. Useful for walking paths relative from the root directory passed to buildDirTree.

Given the following DirTree:

src
└── System
    └── Directory
            └── Contents.hs

walkContents System should produce

Directory
|
`- Contents.hs

For more advanced navigation, see DirZipper.

Filtering a directory tree

pruneDirTree :: DirTree a -> Maybe (DirTree a)

Remove empty directories from the DirTree

newtype DirTreeMaybe a

This wrapper really just represents the no-path/empty case so that filtering works

Constructors

DirTreeMaybe

Fields

• unDirTreeMaybe :: Maybe (DirTree a)

Instances

Functor DirTreeMaybe

Defined in System.Directory.Contents

Methods

fmap :: (a -> b) -> DirTreeMaybe a -> DirTreeMaybe b

(<$) :: a -> DirTreeMaybe b -> DirTreeMaybe a

Foldable DirTreeMaybe

Defined in System.Directory.Contents

Methods

fold :: Monoid m => DirTreeMaybe m -> m

foldMap :: Monoid m => (a -> m) -> DirTreeMaybe a -> m

foldr :: (a -> b -> b) -> b -> DirTreeMaybe a -> b

foldr' :: (a -> b -> b) -> b -> DirTreeMaybe a -> b

foldl :: (b -> a -> b) -> b -> DirTreeMaybe a -> b

foldl' :: (b -> a -> b) -> b -> DirTreeMaybe a -> b

foldr1 :: (a -> a -> a) -> DirTreeMaybe a -> a

foldl1 :: (a -> a -> a) -> DirTreeMaybe a -> a

toList :: DirTreeMaybe a -> [a]

null :: DirTreeMaybe a -> Bool

length :: DirTreeMaybe a -> Int

elem :: Eq a => a -> DirTreeMaybe a -> Bool

maximum :: Ord a => DirTreeMaybe a -> a

minimum :: Ord a => DirTreeMaybe a -> a

sum :: Num a => DirTreeMaybe a -> a

product :: Num a => DirTreeMaybe a -> a

Traversable DirTreeMaybe

Defined in System.Directory.Contents

Methods

traverse :: Applicative f => (a -> f b) -> DirTreeMaybe a -> f (DirTreeMaybe b)

sequenceA :: Applicative f => DirTreeMaybe (f a) -> f (DirTreeMaybe a)

mapM :: Monad m => (a -> m b) -> DirTreeMaybe a -> m (DirTreeMaybe b)

sequence :: Monad m => DirTreeMaybe (m a) -> m (DirTreeMaybe a)

Witherable DirTreeMaybe

Defined in System.Directory.Contents

Methods

wither :: Applicative f => (a -> f (Maybe b)) -> DirTreeMaybe a -> f (DirTreeMaybe b)

witherM :: Monad m => (a -> m (Maybe b)) -> DirTreeMaybe a -> m (DirTreeMaybe b)

filterA :: Applicative f => (a -> f Bool) -> DirTreeMaybe a -> f (DirTreeMaybe a)

Filterable DirTreeMaybe

Defined in System.Directory.Contents

Methods

mapMaybe :: (a -> Maybe b) -> DirTreeMaybe a -> DirTreeMaybe b

catMaybes :: DirTreeMaybe (Maybe a) -> DirTreeMaybe a

filter :: (a -> Bool) -> DirTreeMaybe a -> DirTreeMaybe a

Eq a => Eq (DirTreeMaybe a)

Defined in System.Directory.Contents

Methods

(==) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

(/=) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

Ord a => Ord (DirTreeMaybe a)

Defined in System.Directory.Contents

Methods

compare :: DirTreeMaybe a -> DirTreeMaybe a -> Ordering

(<) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

(<=) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

(>) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

(>=) :: DirTreeMaybe a -> DirTreeMaybe a -> Bool

max :: DirTreeMaybe a -> DirTreeMaybe a -> DirTreeMaybe a

min :: DirTreeMaybe a -> DirTreeMaybe a -> DirTreeMaybe a

Read a => Read (DirTreeMaybe a)

Defined in System.Directory.Contents

Methods

readsPrec :: Int -> ReadS (DirTreeMaybe a)

readList :: ReadS [DirTreeMaybe a]

readPrec :: ReadPrec (DirTreeMaybe a)

readListPrec :: ReadPrec [DirTreeMaybe a]

Show a => Show (DirTreeMaybe a)

Defined in System.Directory.Contents

Methods

showsPrec :: Int -> DirTreeMaybe a -> ShowS

show :: DirTreeMaybe a -> String

showList :: [DirTreeMaybe a] -> ShowS

withDirTreeMaybe :: (DirTreeMaybe a -> DirTreeMaybe b) -> DirTree a -> Maybe (DirTree b)

Map a function that could produce an empty result over a DirTree

withDirTreeMaybeF :: Functor f => (DirTreeMaybe a -> f (DirTreeMaybe b)) -> DirTree a -> f (Maybe (DirTree b))

Map a function that could produce an empty result in the given functor

witherDirTree :: Applicative f => (a -> f (Maybe b)) -> DirTree a -> f (Maybe (DirTree b))

wither for DirTree. This represents the case of no paths left after filtering with Nothing (something that the DirTree type can't represent on its own). NB: Filtering does not remove directories, only files. The directory structure remains intact. To remove empty directories, see pruneDirTree.

filterADirTree :: Applicative f => (a -> f Bool) -> DirTree a -> f (Maybe (DirTree a))

filterA for DirTree. See witherDirTree.

mapMaybeDirTree :: (a -> Maybe b) -> DirTree a -> Maybe (DirTree b)

mapMaybe for DirTree. See witherDirTree.

catMaybesDirTree :: DirTree (Maybe a) -> Maybe (DirTree a)

catMaybes for DirTree. See witherDirTree.

filterDirTree :: (a -> Bool) -> DirTree a -> Maybe (DirTree a)

filter for DirTree. See witherDirTree.

Displaying a directory tree

drawDirTree :: DirTree a -> Text

Produces a tree drawing (using only text) of a DirTree hierarchy.

drawDirTreeWith :: (String -> a -> String) -> DirTree a -> String

Apply a rendering function to each file when drawing the directory hierarchy

printDirTree :: DirTree a -> IO ()

Print the DirTree as a tree. For example:

System
|
`- Directory
   |
   `- Contents.hs

Miscellaneous

mkRelative :: FilePath -> FilePath -> FilePath

Make one filepath relative to another

alternative :: Alternative f => [f a] -> f a

Get the first Alternative