directory-ospath-streaming-0.2.2: Stream directory entries in constant memory in vanilla IO

Copyright | (c) Sergey Vinokurov 2024
License | Apache-2.0 (see LICENSE)
Maintainer | serg.foo@gmail.com
Safe Haskell | None
Language | Haskell2010

System.Directory.OsPath.Streaming

Contents

- File types
- Get directory contents
- Utilities

Description

You’ll most likely be interested in either

- `getDirectoryContentsRecursive` to search directory hierarchy recursively
- `DirStream`, `openDirStream`, `readDirStream`, and `closeDirStream` to traverse single directory efficiently

Synopsis

- data DirStream
- openDirStream :: OsPath -> IO DirStream
- readDirStream :: DirStream -> IO (Maybe (OsPath, FileType))
- closeDirStream :: DirStream -> IO ()
- data SymlinkType
  - = Regular
  - | Symlink
- data FileType
  - = File !SymlinkType
  - | Directory !SymlinkType
  - | Other !SymlinkType
- newtype Basename a = Basename {
  - unBasename :: a
  }
- getFileType :: OsPath -> IO FileType
- getDirectoryContentsRecursive :: OsPath -> IO [(OsPath, FileType)]
- getDirectoryContentsWithFilterRecursive :: (Basename OsPath -> SymlinkType -> Bool) -> (Basename OsPath -> Bool) -> OsPath -> IO [(OsPath, FileType)]
- listContentsRecFold :: forall f a b. (Foldable f, Coercible b OsPath) => Maybe Int -> (forall c. OsPath -> b -> Relative OsPath -> Basename OsPath -> SymlinkType -> (a -> IO c -> IO c) -> (IO c -> IO c) -> IO c -> IO c) -> (OsPath -> b -> Relative OsPath -> Basename OsPath -> FileType -> IO (Maybe a)) -> f b -> IO [a]
- regularFile :: FileType
- regularDirectory :: FileType
- regularOther :: FileType
- symlinkFile :: FileType
- symlinkDirectory :: FileType
- symlinkOther :: FileType

# Documentation

data DirStream Source #

Abstract handle to directory contents.

May be closed multiple times and will be automatically closed by GC when it goes out of scope.

openDirStream :: OsPath -> IO DirStream Source #

readDirStream :: DirStream -> IO (Maybe (OsPath, FileType)) Source #

closeDirStream :: DirStream -> IO () Source #

Deallocate directory handle. It’s safe to close `DirStream` multiple times, unlike the underlying OS-specific directory stream handle.

# File types

data SymlinkType Source #

Constructors

Regular |
Symlink |

#### Instances

Instances details

NFData SymlinkType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: SymlinkType -> () Source #
Generic SymlinkType Source # |

Instance details

Defined in System.Directory.OsPath.Types

Associated Types

type Rep SymlinkType |
Instance details Defined in System.Directory.OsPath.Types type Rep SymlinkType = D1 ('MetaData "SymlinkType" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'False) (C1 ('MetaCons "Regular" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Symlink" 'PrefixI 'False) (U1 :: Type -> Type))

Methods

from :: SymlinkType -> Rep SymlinkType x Source #

to :: Rep SymlinkType x -> SymlinkType Source #

Read SymlinkType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods readsPrec :: Int -> ReadS SymlinkType Source # readList :: ReadS [SymlinkType] Source # readPrec :: ReadPrec SymlinkType Source # readListPrec :: ReadPrec [SymlinkType] Source #
Show SymlinkType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> SymlinkType -> ShowS Source # show :: SymlinkType -> String Source # showList :: [SymlinkType] -> ShowS Source #
Eq SymlinkType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: SymlinkType -> SymlinkType -> Bool Source # (/=) :: SymlinkType -> SymlinkType -> Bool Source #
Ord SymlinkType Source # |

Instance details

Defined in System.Directory.OsPath.Types

Methods

compare :: SymlinkType -> SymlinkType -> Ordering Source #

(<) :: SymlinkType -> SymlinkType -> Bool Source #

(<=) :: SymlinkType -> SymlinkType -> Bool Source #

(>) :: SymlinkType -> SymlinkType -> Bool Source #

(>=) :: SymlinkType -> SymlinkType -> Bool Source #

max :: SymlinkType -> SymlinkType -> SymlinkType Source #

min :: SymlinkType -> SymlinkType -> SymlinkType Source #

type Rep SymlinkType Source # |
Instance details Defined in System.Directory.OsPath.Types type Rep SymlinkType = D1 ('MetaData "SymlinkType" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'False) (C1 ('MetaCons "Regular" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Symlink" 'PrefixI 'False) (U1 :: Type -> Type))

data FileType Source #

Constructors

File !SymlinkType |
Directory !SymlinkType |
Other !SymlinkType |

#### Instances

Instances details

NFData FileType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: FileType -> () Source #
Generic FileType Source # |

Instance details

Defined in System.Directory.OsPath.Types

Associated Types

type Rep FileType |

Instance details

Defined in System.Directory.OsPath.Types

type Rep FileType = D1 ('MetaData "FileType" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'False) (C1 ('MetaCons "File" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType)) :+: (C1 ('MetaCons "Directory" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType)) :+: C1 ('MetaCons "Other" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType))))

Methods

from :: FileType -> Rep FileType x Source #

to :: Rep FileType x -> FileType Source #

Read FileType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods readsPrec :: Int -> ReadS FileType Source # readList :: ReadS [FileType] Source # readPrec :: ReadPrec FileType Source # readListPrec :: ReadPrec [FileType] Source #
Show FileType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> FileType -> ShowS Source # show :: FileType -> String Source # showList :: [FileType] -> ShowS Source #
Eq FileType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: FileType -> FileType -> Bool Source # (/=) :: FileType -> FileType -> Bool Source #
Ord FileType Source # |
Instance details Defined in System.Directory.OsPath.Types Methods compare :: FileType -> FileType -> Ordering Source # (<) :: FileType -> FileType -> Bool Source # (<=) :: FileType -> FileType -> Bool Source # (>) :: FileType -> FileType -> Bool Source # (>=) :: FileType -> FileType -> Bool Source # max :: FileType -> FileType -> FileType Source # min :: FileType -> FileType -> FileType Source #
type Rep FileType Source # |

Instance details

Defined in System.Directory.OsPath.Types

type Rep FileType = D1 ('MetaData "FileType" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'False) (C1 ('MetaCons "File" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType)) :+: (C1 ('MetaCons "Directory" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType)) :+: C1 ('MetaCons "Other" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'SourceUnpack 'SourceStrict 'DecidedStrict) (Rec0 SymlinkType))))

newtype Basename a Source #

Basename part of filename, without directory separators.

Constructors

Basename |

Fields

- unBasename :: a

#### Instances

Instances details

Functor Basename Source # |
Instance details Defined in System.Directory.OsPath.Types Methods fmap :: (a -> b) -> Basename a -> Basename b Source # (<$) :: a -> Basename b -> Basename a Source #
Foldable Basename Source # |

Instance details

Defined in System.Directory.OsPath.Types

Methods

fold :: Monoid m => Basename m -> m Source #

foldMap :: Monoid m => (a -> m) -> Basename a -> m Source #

foldMap' :: Monoid m => (a -> m) -> Basename a -> m Source #

foldr :: (a -> b -> b) -> b -> Basename a -> b Source #

foldr' :: (a -> b -> b) -> b -> Basename a -> b Source #

foldl :: (b -> a -> b) -> b -> Basename a -> b Source #

foldl' :: (b -> a -> b) -> b -> Basename a -> b Source #

foldr1 :: (a -> a -> a) -> Basename a -> a Source #

foldl1 :: (a -> a -> a) -> Basename a -> a Source #

toList :: Basename a -> [a] Source #

null :: Basename a -> Bool Source #

length :: Basename a -> Int Source #

elem :: Eq a => a -> Basename a -> Bool Source #

maximum :: Ord a => Basename a -> a Source #

minimum :: Ord a => Basename a -> a Source #

sum :: Num a => Basename a -> a Source #

product :: Num a => Basename a -> a Source #

Traversable Basename Source # |
Instance details Defined in System.Directory.OsPath.Types Methods traverse :: Applicative f => (a -> f b) -> Basename a -> f (Basename b) Source # sequenceA :: Applicative f => Basename (f a) -> f (Basename a) Source # mapM :: Monad m => (a -> m b) -> Basename a -> m (Basename b) Source # sequence :: Monad m => Basename (m a) -> m (Basename a) Source #
Generic1 Basename Source # |

Instance details

Defined in System.Directory.OsPath.Types

Associated Types

type Rep1 Basename |
Instance details Defined in System.Directory.OsPath.Types type Rep1 Basename = D1 ('MetaData "Basename" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))

Methods

from1 :: Basename a -> Rep1 Basename a Source #

to1 :: Rep1 Basename a -> Basename a Source #

NFData a => NFData (Basename a) Source # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: Basename a -> () Source #
Generic (Basename a) Source # |

Instance details

Defined in System.Directory.OsPath.Types

Associated Types

type Rep (Basename a) |
Instance details Defined in System.Directory.OsPath.Types type Rep (Basename a) = D1 ('MetaData "Basename" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))

Methods

from :: Basename a -> Rep (Basename a) x Source #

to :: Rep (Basename a) x -> Basename a Source #

Show a => Show (Basename a) Source # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> Basename a -> ShowS Source # show :: Basename a -> String Source # showList :: [Basename a] -> ShowS Source #
Eq a => Eq (Basename a) Source # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: Basename a -> Basename a -> Bool Source # (/=) :: Basename a -> Basename a -> Bool Source #
Ord a => Ord (Basename a) Source # |

Instance details

Defined in System.Directory.OsPath.Types

Methods

compare :: Basename a -> Basename a -> Ordering Source #

(<) :: Basename a -> Basename a -> Bool Source #

(<=) :: Basename a -> Basename a -> Bool Source #

(>) :: Basename a -> Basename a -> Bool Source #

(>=) :: Basename a -> Basename a -> Bool Source #

max :: Basename a -> Basename a -> Basename a Source #

min :: Basename a -> Basename a -> Basename a Source #

type Rep1 Basename Source # |
Instance details Defined in System.Directory.OsPath.Types type Rep1 Basename = D1 ('MetaData "Basename" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
type Rep (Basename a) Source # |
Instance details Defined in System.Directory.OsPath.Types type Rep (Basename a) = D1 ('MetaData "Basename" "System.Directory.OsPath.Types" "directory-ospath-streaming-0.2.2-cBThjfpkvuB7SOa12kyJN" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))

getFileType :: OsPath -> IO FileType Source #

# Get directory contents

getDirectoryContentsRecursive :: OsPath -> IO [(OsPath, FileType)] Source #

Recursively list all the files and directories in a directory and all subdirectories.

The directory structure is traversed depth-first.

The result is generated lazily so is not well defined if the source directory structure changes before the list is fully consumed.

Symlinks within directory structure may cause result to be infinitely long.

getDirectoryContentsWithFilterRecursive Source #

Arguments

:: (Basename OsPath -> SymlinkType -> Bool) | Whether to visit a directory
-> (Basename OsPath -> Bool) | Whether to collect given directory element, either file or directory.
-> OsPath |
-> IO [(OsPath, FileType)] |

Recursively list all the files and directories that satisfy given predicate in a directory and all subdirectories. Descending into some subdirectories may be avoided by filtering them out with a visiting predicate.

Not visited directory entry may still be reported depending on the collection predicate.

The directory structure is traversed depth-first.

The result is generated lazily so is not well defined if the source directory structure changes before the list is fully consumed.

Symlinks within directory structure may cause result to be infinitely long, but they can be filtered out with a suitable directory visiting predicate.

listContentsRecFold Source #

Arguments

:: forall f a b. (Foldable f, Coercible b OsPath) |
=> Maybe Int | Depth limit if specified, negative values treated the same as positive ones.

-> (forall c. OsPath -> b -> Relative OsPath -> Basename OsPath -> SymlinkType -> (a -> IO c -> IO c) -> (IO c -> IO c) -> IO c -> IO c)

Decide how to fold directory and its children given its path.

Can do IO actions to plan what to do and typically should derive its result from last `IO c` argument.

Returns `IO c` where `c` is hidden from the user so the only way to make it is to construct from the passed `IO c` action.

Arguments:

- `OsPath` - absolute path to the visited directory
- `b` - root of the visited directory as passed originally in `f b` to the bigger fold function
- `Relative OsPath` - path to the visited directory relative to the previous `b` argument
- `Basename OsPath` - name of the visited directory without slashes
- `SymlinkType` - symlink status of the visited directory
- `(a -> IO c -> IO c)` - can be used to record some output (`a`) about the directory itself
- `(IO c -> IO c)` - traverse inside this directory, can be ignored to skip its children
- `IO c` - continue scanning not yet visited parts, must be used to construct return value (otherwise it won’t typecheck!)

The passed `(IO c -> IO c)` argument function should (but is not required to) be applied in the returned function and it will prepend results for subdirectories of the directory being analyzed. If not applied these subdirectories will be skipped, this way ignoring particular directory and all its children can be achieved.

-> (OsPath -> b -> Relative OsPath -> Basename OsPath -> FileType -> IO (Maybe a)) | What to do with file
-> f b | Roots to search in, either absolute or relative
-> IO [a] |

The most general form of gathering directory contents.

Treats symlinks the same as regular files and directories. Folding functions can decide how to handle symlinks.

Both directory and file actions can throw exceptions and this function will try to close finished directory streams promptly (they’ll be closed by GC in the worst case).

# Utilities

regularFile :: FileType Source #

Auxiliary constants to refer to different file types without allocations.

regularDirectory :: FileType Source #

Auxiliary constants to refer to different file types without allocations.

regularOther :: FileType Source #

Auxiliary constants to refer to different file types without allocations.

symlinkFile :: FileType Source #

Auxiliary constants to refer to different file types without allocations.

symlinkDirectory :: FileType Source #

Auxiliary constants to refer to different file types without allocations.

symlinkOther :: FileType Source #

Auxiliary constants to refer to different file types without allocations.