Copyright	Bryan O'Sullivan
License	BSD3
Maintainer	Bryan O'Sullivan <bos@serpentine.com>
Stability	unstable
Portability	Unix-like systems (requires newtype deriving)
Safe Haskell	None
Language	Haskell98

System.FilePath.Find

Contents

Simple entry points
More expressive entry points
Helper functions
Combinators for controlling recursion and filtering behaviour

Description

This module provides functions for traversing a filesystem hierarchy. The find function generates a lazy list of matching files, while fold performs a left fold.

Both find and fold allow fine control over recursion, using the FindClause type. This type is also used to pre-filter the results returned by find.

The FindClause type lets you write filtering and recursion control expressions clearly and easily.

For example, this clause matches C source files.

extension ==? ".c" ||? extension ==? ".h"

Because FindClause is a monad, you can use the usual monad machinery to, for example, lift pure functions into it.

Here's a clause that will return True for any file whose directory name contains the word "temp".

(isInfixOf "temp") `liftM` directory

Synopsis

Documentation

data FileInfo Source

Information collected during the traversal of a directory.

Constructors

FileInfo
Fields infoPath :: FilePath file path infoDepth :: Int current recursion depth infoStatus :: FileStatus status of file

Instances

Eq FileInfo

data FileType Source

Constructors

BlockDevice
CharacterDevice
NamedPipe
RegularFile
Directory
SymbolicLink
Socket
Unknown

Instances

Eq FileType
Ord FileType
Show FileType

data FindClause a Source

Monadic container for file information, allowing for clean construction of combinators. Wraps the State monad, but doesn't allow get or put.

Instances

Monad FindClause
Functor FindClause
Applicative FindClause

type FilterPredicate = FindClause Bool Source

type RecursionPredicate = FindClause Bool Source

Simple entry points

find Source

Arguments

:: RecursionPredicate	control recursion into subdirectories
-> FilterPredicate	decide whether a file appears in the result
-> FilePath	directory to start searching
-> IO [FilePath]	files that matched the `FilterPredicate`

Search a directory recursively, with recursion controlled by a RecursionPredicate. Lazily return a sorted list of all files matching the given FilterPredicate. Any errors that occur are ignored, with warnings printed to stderr.

fold :: RecursionPredicate -> (a -> FileInfo -> a) -> a -> FilePath -> IO a Source

Search a directory recursively, with recursion controlled by a RecursionPredicate. Fold over all files found. Any errors that occur are ignored, with warnings printed to stderr. The fold function is run from "left" to "right", so it should be strict in its left argument to avoid space leaks. If you need a right-to-left fold, use foldr on the result of findWithHandler instead.

More expressive entry points

findWithHandler Source

Arguments

:: (FilePath -> IOException -> IO [FilePath])	error handler
-> RecursionPredicate	control recursion into subdirectories
-> FilterPredicate	decide whether a file appears in the result
-> FilePath	directory to start searching
-> IO [FilePath]	files that matched the `FilterPredicate`

Search a directory recursively, with recursion controlled by a RecursionPredicate. Lazily return a sorted list of all files matching the given FilterPredicate. Any errors that occur are dealt with by the given handler.

foldWithHandler Source

Arguments

:: (FilePath -> a -> IOException -> IO a)	error handler
-> RecursionPredicate	control recursion into subdirectories
-> (a -> FileInfo -> a)	function to fold with
-> a	seed value for fold
-> FilePath	directory to start searching
-> IO a	final value after folding

Search a directory recursively, with recursion controlled by a RecursionPredicate. Fold over all files found. Any errors that occur are dealt with by the given handler. The fold is strict, and run from "left" to "right", so the folded function should be strict in its left argument to avoid space leaks. If you need a right-to-left fold, use foldr on the result of findWithHandler instead.

Helper functions

evalClause :: FindClause a -> FileInfo -> a Source

Run the given FindClause on the given FileInfo and return its result. This can be useful if you are writing a function to pass to fold.

Example:

myFoldFunc :: a -> FileInfo -> a
myFoldFunc a i = let useThisFile = evalClause (fileName ==? "foo") i
                 in if useThisFile
                    then fiddleWith a
                    else a

statusType :: FileStatus -> FileType Source

Return the type of a file. This is much more useful for case analysis than the usual functions on FileStatus values.

liftOp :: Monad m => (a -> b -> c) -> m a -> b -> m c Source

Lift a binary operator into the FindClause monad, so that it becomes a combinator. The left hand side of the combinator should be a FindClause a, while the right remains a normal value of type a.

Combinators for controlling recursion and filtering behaviour

filePath :: FindClause FilePath Source

Return the name of the file being visited.

fileStatus :: FindClause FileStatus Source

Return the FileStatus for the current file.

depth :: FindClause Int Source

Return the current recursion depth.

fileInfo :: FindClause FileInfo Source

Return the current FileInfo.

always :: FindClause Bool Source

Unconditionally return True.

extension :: FindClause FilePath Source

Return the file name extension.

Example:

extension "foo/bar.txt" => ".txt"

directory :: FindClause FilePath Source

Return the directory name, without the file name.

What this means in practice:

directory "foo/bar.txt" => "foo"

Example in a clause:

let hasSuffix = liftOp isSuffixOf
in directory `hasSuffix` "tests"

fileName :: FindClause FilePath Source

Return the file name, without the directory name.

What this means in practice:

fileName "foo/bar.txt" => "bar.txt"

Example:

fileName ==? "init.c"

fileType :: FindClause FileType Source

Return the type of file currently being visited.

Example:

fileType ==? RegularFile

contains :: FilePath -> FindClause Bool Source

Return True if the given path exists, relative to the current file. For example, if "foo" is being visited, and you call contains "bar", this combinator will return True if "foo/bar" exists.

Combinator versions of `FileStatus` functions from System.Posix.Files

These are simply lifted versions of the FileStatus accessor functions in the System.Posix.Files module. The definitions all have the following form:

deviceID :: FindClause System.Posix.Types.DeviceID
deviceID = System.Posix.Files.deviceID `liftM` fileStatus

deviceID :: FindClause DeviceID Source

fileID :: FindClause FileID Source

fileOwner :: FindClause UserID Source

fileGroup :: FindClause GroupID Source

fileSize :: FindClause FileOffset Source

linkCount :: FindClause LinkCount Source

specialDeviceID :: FindClause DeviceID Source

fileMode :: FindClause FileMode Source

accessTime :: FindClause EpochTime Source

modificationTime :: FindClause EpochTime Source

statusChangeTime :: FindClause EpochTime Source

Convenience combinators for file status

filePerms :: FindClause FileMode Source

Return the permission bits of the FileMode.

anyPerms :: FileMode -> FindClause Bool Source

Return True if any of the given permission bits is set.

Example:

anyPerms 0444

Combinators for canonical path and name

canonicalPath :: FindClause FilePath Source

Return the canonical path of the file being visited.

See canonicalizePath for details of what canonical path means.

canonicalName :: FindClause FilePath Source

Return the canonical name of the file (canonical path with the directory part removed).

Combinators that operate on symbolic links

readLink :: FindClause (Maybe FilePath) Source

If the current file is a symbolic link, return Just the target of the link, otherwise Nothing.

followStatus :: FindClause (Maybe FileStatus) Source

If the current file is a symbolic link, return Just the status of the ultimate endpoint of the link. Otherwise (including in the case of an error), return Nothing.

Example:

statusType `liftM` followStatus ==? RegularFile

Common binary operators, lifted as combinators

These are lifted versions of the most commonly used binary operators. They have the same fixities and associativities as their unlifted counterparts. They are lifted using liftOp, like so: