System.Directory.OsPath.Streaming

directory-ospath-streaming-0.2.1: 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)]
- 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 #

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 #

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

closeDirStream :: DirStream -> IO () #

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

# File types

data SymlinkType #

Constructors

Regular |
Symlink |

#### Instances

Instances details

NFData SymlinkType # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: SymlinkType -> () #
Generic SymlinkType # |
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.1-KCiX479tWYh9reBY6DxI1i" 'False) (C1 ('MetaCons "Regular" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Symlink" 'PrefixI 'False) (U1 :: Type -> Type))
Methods from :: SymlinkType -> Rep SymlinkType x # to :: Rep SymlinkType x -> SymlinkType #
Read SymlinkType # |
Instance details Defined in System.Directory.OsPath.Types Methods readsPrec :: Int -> ReadS SymlinkType # readList :: ReadS [SymlinkType] # readPrec :: ReadPrec SymlinkType # readListPrec :: ReadPrec [SymlinkType] #
Show SymlinkType # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> SymlinkType -> ShowS # show :: SymlinkType -> String # showList :: [SymlinkType] -> ShowS #
Eq SymlinkType # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: SymlinkType -> SymlinkType -> Bool # (/=) :: SymlinkType -> SymlinkType -> Bool #
Ord SymlinkType # |
Instance details Defined in System.Directory.OsPath.Types Methods compare :: SymlinkType -> SymlinkType -> Ordering # (<) :: SymlinkType -> SymlinkType -> Bool # (<=) :: SymlinkType -> SymlinkType -> Bool # (>) :: SymlinkType -> SymlinkType -> Bool # (>=) :: SymlinkType -> SymlinkType -> Bool # max :: SymlinkType -> SymlinkType -> SymlinkType # min :: SymlinkType -> SymlinkType -> SymlinkType #
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.1-KCiX479tWYh9reBY6DxI1i" 'False) (C1 ('MetaCons "Regular" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "Symlink" 'PrefixI 'False) (U1 :: Type -> Type))

data FileType #

Constructors

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

#### Instances

Instances details

NFData FileType # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: FileType -> () #
Generic FileType # |
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.1-KCiX479tWYh9reBY6DxI1i" '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 # to :: Rep FileType x -> FileType #
Read FileType # |
Instance details Defined in System.Directory.OsPath.Types Methods readsPrec :: Int -> ReadS FileType # readList :: ReadS [FileType] # readPrec :: ReadPrec FileType # readListPrec :: ReadPrec [FileType] #
Show FileType # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> FileType -> ShowS # show :: FileType -> String # showList :: [FileType] -> ShowS #
Eq FileType # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: FileType -> FileType -> Bool # (/=) :: FileType -> FileType -> Bool #
Ord FileType # |
Instance details Defined in System.Directory.OsPath.Types Methods compare :: FileType -> FileType -> Ordering # (<) :: FileType -> FileType -> Bool # (<=) :: FileType -> FileType -> Bool # (>) :: FileType -> FileType -> Bool # (>=) :: FileType -> FileType -> Bool # max :: FileType -> FileType -> FileType # min :: FileType -> FileType -> FileType #
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.1-KCiX479tWYh9reBY6DxI1i" '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 #

Basename part of filename, without directory separators.

Constructors

Basename |
Fields unBasename :: a

#### Instances

Instances details

Functor Basename # |
Instance details Defined in System.Directory.OsPath.Types Methods fmap :: (a -> b) -> Basename a -> Basename b # (<$) :: a -> Basename b -> Basename a #
Foldable Basename # |
Instance details Defined in System.Directory.OsPath.Types Methods fold :: Monoid m => Basename m -> m # foldMap :: Monoid m => (a -> m) -> Basename a -> m # foldMap' :: Monoid m => (a -> m) -> Basename a -> m # foldr :: (a -> b -> b) -> b -> Basename a -> b # foldr' :: (a -> b -> b) -> b -> Basename a -> b # foldl :: (b -> a -> b) -> b -> Basename a -> b # foldl' :: (b -> a -> b) -> b -> Basename a -> b # foldr1 :: (a -> a -> a) -> Basename a -> a # foldl1 :: (a -> a -> a) -> Basename a -> a # toList :: Basename a -> [a] # null :: Basename a -> Bool # length :: Basename a -> Int # elem :: Eq a => a -> Basename a -> Bool # maximum :: Ord a => Basename a -> a # minimum :: Ord a => Basename a -> a # sum :: Num a => Basename a -> a # product :: Num a => Basename a -> a #
Traversable Basename # |
Instance details Defined in System.Directory.OsPath.Types Methods traverse :: Applicative f => (a -> f b) -> Basename a -> f (Basename b) # sequenceA :: Applicative f => Basename (f a) -> f (Basename a) # mapM :: Monad m => (a -> m b) -> Basename a -> m (Basename b) # sequence :: Monad m => Basename (m a) -> m (Basename a) #
Generic1 Basename # |
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.1-KCiX479tWYh9reBY6DxI1i" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
Methods from1 :: Basename a -> Rep1 Basename a # to1 :: Rep1 Basename a -> Basename a #
NFData a => NFData (Basename a) # |
Instance details Defined in System.Directory.OsPath.Types Methods rnf :: Basename a -> () #
Generic (Basename a) # |
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.1-KCiX479tWYh9reBY6DxI1i" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))
Methods from :: Basename a -> Rep (Basename a) x # to :: Rep (Basename a) x -> Basename a #
Show a => Show (Basename a) # |
Instance details Defined in System.Directory.OsPath.Types Methods showsPrec :: Int -> Basename a -> ShowS # show :: Basename a -> String # showList :: [Basename a] -> ShowS #
Eq a => Eq (Basename a) # |
Instance details Defined in System.Directory.OsPath.Types Methods (==) :: Basename a -> Basename a -> Bool # (/=) :: Basename a -> Basename a -> Bool #
Ord a => Ord (Basename a) # |
Instance details Defined in System.Directory.OsPath.Types Methods compare :: Basename a -> Basename a -> Ordering # (<) :: Basename a -> Basename a -> Bool # (<=) :: Basename a -> Basename a -> Bool # (>) :: Basename a -> Basename a -> Bool # (>=) :: Basename a -> Basename a -> Bool # max :: Basename a -> Basename a -> Basename a # min :: Basename a -> Basename a -> Basename a #
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.1-KCiX479tWYh9reBY6DxI1i" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) Par1))
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.1-KCiX479tWYh9reBY6DxI1i" 'True) (C1 ('MetaCons "Basename" 'PrefixI 'True) (S1 ('MetaSel ('Just "unBasename") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 a)))

getFileType :: OsPath -> IO FileType #

# Get directory contents

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

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.

listContentsRecFold #

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 #

Auxiliary constants to refer to different file types without allocations.

regularDirectory :: FileType #

Auxiliary constants to refer to different file types without allocations.

regularOther :: FileType #

Auxiliary constants to refer to different file types without allocations.

symlinkFile :: FileType #

Auxiliary constants to refer to different file types without allocations.

symlinkDirectory :: FileType #

Auxiliary constants to refer to different file types without allocations.

symlinkOther :: FileType #

Auxiliary constants to refer to different file types without allocations.