System.Posix.Recursive.ByteString.Unsafe

All modules profided by unix-recursive expose similar API. Make sure you're using the module wich best fits your needs based on: - Working with RawFilePath (faster and more packed) or FilePath (slower but easier to work with safely) - Exception free (Default) or Unsafe variants of functions

Usage

This module is designed to be imported as qualified:

import qualified System.Posix.Recursive.ByteString.Unsafe as PosixRecursive

Results

All functions return will return root path (the one they accept in argument) as a first item in the list:

head <$> PosixRecursive.list "System"
>>> "System"

Other than that, this library provides no guarantees about the order in which files appear in the resulting list to make it possible to change the underlaying strategy in future versions.

Laziness

All IO operations are guaranteed to be lazy and have constanct space characteristic. Only the IO required by lazy computation will be performed so for instance running code like:

take 20 <$> PosixRecursive.listDirectories "/"

Will perform only minimal ammount of IO needed to collect 20 directories on a root partition

Basic Listing

Functions for listing contents of directory recursively. These functions list all the content they encounter while traversing the file system tree including directories, files, symlinks, broken symlinks.

Functions from this module will throw IOError if it can't open the directory (i.e. becacuse permission error or other process removing the given path).

Functions from this section is gurantee to always return the root path as a first element even if this path does not exist.

PosixRecursive.list "i-dont-exist"
>>> ["i-dont-exist"]

In these cases the root path is considered the same way as symlink to non existing location.

list :: RawFilePath -> IO [RawFilePath]

List all files, directories & symlinks recursively. Symlinks are not followed. See followList.

followList :: RawFilePath -> IO [RawFilePath]

List all files, directories & symlinks recursively. Unlike list, symlinks are followed recursively as well.

listMatching :: (RawFilePath -> Bool) -> RawFilePath -> IO [RawFilePath]

Like list but uses provided function to test in which RawFilePath to recurse into.

followListMatching :: (RawFilePath -> Bool) -> RawFilePath -> IO [RawFilePath]

Like followList but uses provided function to test in which RawFilePath to recurse into.

File Type Based Listing

Functions for listing specific file type. Reading the file type requires ability to read the file.

These functions will throw IOError when tring to open unreadable file.

Include test is applied even for the root entry (path past in as an argument). This means that non existing paths are filtered.

PosixRecursive.listDirectories "i-dont-exist"
>>> []

listDirectories :: RawFilePath -> IO [RawFilePath]

List sub directories of given directory.

listRegularFiles :: RawFilePath -> IO [RawFilePath]

Lists only files (while recursing into directories still).

listSymbolicLinks :: RawFilePath -> IO [RawFilePath]

Lists only symbolic links (while recursing into directories still).

Custom Listing

All File Type Based Listing functions are based on top of this interface. This part of API exposes exposes access for writing custom filtering functions.

All paths are tested for filter functions so unreadble files won't appear in the result list:

PosixRecursive.listCustom PosixRecursive.defConf "i-dont-exist"
>>> []

It's not possible to turn of this behaviour because this functions must get the FileStatus type which requires reading each entry.

data Conf

Configuration arguments for listCustom.

Constructors

Conf

Fields

• filterPath :: !(RawFilePath -> Bool)

  Filter paths algorithm should recurse into

• includeFile :: !(FileStatus -> RawFilePath -> IO Bool)

  Test if file should be included in returned List

• followSymlinks :: !Bool

  Follow symbolic links

defConf :: Conf

Default Configuration.

listCustom defConf == listAccessible

• Recurses into all Paths
• Includes all file types
• Does not follow symlinks

listCustom :: Conf -> RawFilePath -> IO [RawFilePath]

Recursively list files using custom filters.