-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Interface to ‘directory’ package for users of ‘path’ -- -- Interface to ‘directory’ package for users of ‘path’. @package path-io @version 1.3.2 -- | This module provides an interface to System.Directory for users -- of the Path module. It also implements commonly used primitives -- like recursive scanning and copying of directories, working with -- temporary files/directories, etc. module Path.IO -- | createDir dir creates a new directory dir -- which is initially empty, or as near to empty as the operating system -- allows. -- -- The operation may fail with: -- -- createDir :: MonadIO m => Path b Dir -> m () -- | createDirIfMissing parents dir creates a new directory -- dir if it doesn't exist. If the first argument is True -- the function will also create all parent directories if they are -- missing. createDirIfMissing :: MonadIO m => Bool -> Path b Dir -> m () -- | Ensure that a directory exists creating it and its parent directories -- if necessary. This is just a handy shortcut: -- -- 
--   ensureDir = createDirIfMissing True
--
ensureDir :: MonadIO m => Path b Dir -> m () -- | removeDir dir removes an existing directory -- dir. The implementation may specify additional constraints -- which must be satisfied before a directory can be removed (e.g. the -- directory has to be empty, or may not be in use by other processes). -- It is not legal for an implementation to partially remove a directory -- unless the entire directory is removed. A conformant implementation -- need not support directory removal in all situations (e.g. removal of -- the root directory). -- -- The operation may fail with: -- -- removeDir :: MonadIO m => Path b Dir -> m () -- | removeDirRecur dir removes an existing directory -- dir together with its contents and sub-directories. Within -- this directory, symbolic links are removed without affecting their -- targets. removeDirRecur :: MonadIO m => Path b Dir -> m () -- | renameDir old new changes the name of an existing -- directory from old to new. If the new -- directory already exists, it is atomically replaced by the -- old directory. If the new directory is neither the -- old directory nor an alias of the old directory, it -- is removed as if by removeDir. A conformant implementation need -- not support renaming directories in all situations (e.g. renaming to -- an existing directory, or across different physical devices), but the -- constraints must be documented. -- -- On Win32 platforms, renameDir fails if the new -- directory already exists. -- -- The operation may fail with: -- -- renameDir :: MonadIO m => Path b0 Dir -> Path b1 Dir -> m () -- | listDir dir returns a list of all entries in -- dir without the special entries (. and ..). -- Entries are not sorted. -- -- The operation may fail with: -- -- listDir :: MonadIO m => Path b Dir -> m ([Path Abs Dir], [Path Abs File]) -- | Similar to listDir, but recursively traverses every -- sub-directory excluding symbolic links, and returns all files -- and directories found. This can fail with the same exceptions as -- listDir. -- -- Note: before version 1.3.0, this function followed -- symlinks. listDirRecur :: MonadIO m => Path b Dir -> m ([Path Abs Dir], [Path Abs File]) -- | Copies a directory recursively. It does not follow symbolic -- links and preserves permissions when possible. If the destination -- directory already exists, new files and sub-directories complement its -- structure, possibly overwriting old files if they happen to have the -- same name as the new ones. -- -- Note: before version 1.3.0, this function followed -- symlinks. copyDirRecur :: (MonadIO m, MonadCatch m) => Path b0 Dir -> Path b1 Dir -> m () -- | The same as copyDirRecur, but it does not preserve -- directory permissions. This may be useful, for example, if the -- directory you want to copy is “read-only”, but you want your copy to -- be editable. -- -- Note: before version 1.3.0, this function followed -- symlinks. copyDirRecur' :: (MonadIO m, MonadCatch m) => Path b0 Dir -> Path b1 Dir -> m () -- | Action returned by the traversal handler function. The action controls -- how the traversal will proceed. data WalkAction -- | Finish the entire walk altogether WalkFinish :: WalkAction -- | List of sub-directories to exclude from descending WalkExclude :: [Path Abs Dir] -> WalkAction -- | Traverse a directory tree using depth first pre-order traversal, -- calling a handler function at each directory node traversed. The -- absolute paths of the parent directory, sub-directories and the files -- in the directory are provided as arguments to the handler. -- -- The function is capable of detecting and avoiding traversal loops in -- the directory tree. Note that the traversal follows symlinks by -- default, an appropriate traversal handler can be used to avoid that -- when necessary. walkDir :: MonadIO m => (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m WalkAction) -> Path b Dir -> m () -- | Similar to walkDir but accepts a Monoid-returning output -- writer as well. Values returned by the output writer invocations are -- accumulated and returned. -- -- Both, the descend handler as well as the output writer can be used for -- side effects but keep in mind that the output writer runs before the -- descend handler. walkDirAccum :: (MonadIO m, Monoid o) => Maybe (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m WalkAction) -> (Path Abs Dir -> [Path Abs Dir] -> [Path Abs File] -> m o) -> Path b Dir -> m o -- | Obtain the current working directory as an absolute path. -- -- In a multithreaded program, the current working directory is a global -- state shared among all threads of the process. Therefore, when -- performing filesystem operations from multiple threads, it is highly -- recommended to use absolute rather than relative paths (see: -- makeAbsolute). -- -- The operation may fail with: -- -- getCurrentDir :: MonadIO m => m (Path Abs Dir) -- | Change the working directory to the given path. -- -- In a multithreaded program, the current working directory is a global -- state shared among all threads of the process. Therefore, when -- performing filesystem operations from multiple threads, it is highly -- recommended to use absolute rather than relative paths (see: -- makeAbsolute). -- -- The operation may fail with: -- -- setCurrentDir :: MonadIO m => Path b Dir -> m () -- | Run an IO action with the given working directory and restore -- the original working directory afterwards, even if the given action -- fails due to an exception. -- -- The operation may fail with the same exceptions as -- getCurrentDir and setCurrentDir. withCurrentDir :: (MonadIO m, MonadMask m) => Path b Dir -> m a -> m a -- | Return the current user's home directory. -- -- The directory returned is expected to be writable by the current user, -- but note that it isn't generally considered good practice to store -- application-specific data here; use getAppUserDataDir instead. -- -- On Unix, getHomeDir returns the value of the HOME -- environment variable. On Windows, the system is queried for a suitable -- path; a typical path might be C:/Users/<user>. -- -- The operation may fail with: -- -- getHomeDir :: MonadIO m => m (Path Abs Dir) -- | Obtain the path to a special directory for storing user-specific -- application data (traditional Unix location). -- -- The argument is usually the name of the application. Since it will be -- integrated into the path, it must consist of valid path characters. -- -- -- -- Note: the directory may not actually exist, in which case you would -- need to create it. It is expected that the parent directory exists and -- is writable. -- -- The operation may fail with: -- -- getAppUserDataDir :: MonadIO m => String -> m (Path Abs Dir) -- | Return the current user's document directory. -- -- The directory returned is expected to be writable by the current user, -- but note that it isn't generally considered good practice to store -- application-specific data here; use getAppUserDataDir instead. -- -- On Unix, getUserDocsDir returns the value of the HOME -- environment variable. On Windows, the system is queried for a suitable -- path; a typical path might be -- C:/Users/<user>/Documents. -- -- The operation may fail with: -- -- getUserDocsDir :: MonadIO m => m (Path Abs Dir) -- | Return the current directory for temporary files. -- -- On Unix, getTempDir returns the value of the TMPDIR -- environment variable or "/tmp" if the variable isn't defined. On -- Windows, the function checks for the existence of environment -- variables in the following order and uses the first path found: -- -- -- -- The operation may fail with: -- -- -- -- The function doesn't verify whether the path exists. getTempDir :: MonadIO m => m (Path Abs Dir) -- | Special directories for storing user-specific application data, -- configuration, and cache files, as specified by the XDG Base -- Directory Specification. -- -- Note: On Windows, XdgData and XdgConfig map to the same -- directory. data XdgDirectory :: * -- | For data files (e.g. images). Defaults to ~/.local/share and -- can be overridden by the XDG_DATA_HOME environment variable. -- On Windows, it is %APPDATA% (e.g. -- C:/Users/<user>/AppData/Roaming). Can be -- considered as the user-specific equivalent of /usr/share. XdgData :: XdgDirectory -- | For configuration files. Defaults to ~/.config and can be -- overridden by the XDG_CONFIG_HOME environment variable. On -- Windows, it is %APPDATA% (e.g. -- C:/Users/<user>/AppData/Roaming). Can be -- considered as the user-specific equivalent of /etc. XdgConfig :: XdgDirectory -- | For non-essential files (e.g. cache). Defaults to ~/.cache -- and can be overridden by the XDG_CACHE_HOME environment -- variable. On Windows, it is %LOCALAPPDATA% (e.g. -- C:/Users/<user>/AppData/Local). Can be -- considered as the user-specific equivalent of /var/cache. XdgCache :: XdgDirectory -- | Obtain the paths to special directories for storing user-specific -- application data, configuration, and cache files, conforming to the -- XDG Base Directory Specification. Compared with -- getAppUserDataDir, this function provides a more fine-grained -- hierarchy as well as greater flexibility for the user. -- -- It also works on Windows, although in that case XdgData and -- XdgConfig will map to the same directory. -- -- Note: The directory may not actually exist, in which case you would -- need to create it with file mode 700 (i.e. only accessible by -- the owner). -- -- Note also: this is a piece of conditional API, only available if -- directory-1.2.3.0 or later is used. getXdgDir :: MonadIO m => XdgDirectory -> Maybe (Path Rel Dir) -> m (Path Abs Dir) -- | Class of things (Paths) that can be canonicalized, made -- absolute, and made relative to a some base directory. class AnyPath path where type AbsPath path :: * type RelPath path :: * where { type family AbsPath path :: *; type family RelPath path :: *; } -- | Make a path absolute and remove as many indirections from it as -- possible. Indirections include the two special directories . -- and .., as well as any symbolic links. The input path need -- not point to an existing file or directory. -- -- Note: if you require only an absolute path, use -- makeAbsolute instead. Most programs need not care about whether -- a path contains symbolic links. -- -- Due to the fact that symbolic links are dependent on the state of the -- existing filesystem, the function can only make a conservative, -- best-effort attempt. Nevertheless, if the input path points to an -- existing file or directory, then the output path shall also point to -- the same file or directory. -- -- Formally, symbolic links are removed from the longest prefix of the -- path that still points to an existing file. The function is not -- atomic, therefore concurrent changes in the filesystem may lead to -- incorrect results. -- -- (Despite the name, the function does not guarantee canonicity of the -- returned path due to the presence of hard links, mount points, etc.) -- -- Known bug(s): on Windows, the function does not resolve -- symbolic links. -- -- Please note that before version 1.2.3.0 of the directory -- package, this function had unpredictable behavior on non-existent -- paths. canonicalizePath :: (AnyPath path, MonadIO m) => path -> m (AbsPath path) -- | Make a path absolute by prepending the current directory (if it isn't -- already absolute) and applying normalise to the result. -- -- If the path is already absolute, the operation never fails. Otherwise, -- the operation may fail with the same exceptions as -- getCurrentDir. makeAbsolute :: (AnyPath path, MonadIO m) => path -> m (AbsPath path) -- | Make a path relative to a given directory. makeRelative :: (AnyPath path, MonadThrow m) => Path Abs Dir -> path -> m (RelPath path) -- | Make a path relative to current working directory. makeRelativeToCurrentDir :: (AnyPath path, MonadIO m) => path -> m (RelPath path) -- | Append stringly-typed path to an absolute path and then canonicalize -- it. resolveFile :: MonadIO m => Path Abs Dir -> FilePath -> m (Path Abs File) -- | The same as resolveFile, but uses current working directory. resolveFile' :: MonadIO m => FilePath -> m (Path Abs File) -- | The same as resolveFile, but for directories. resolveDir :: MonadIO m => Path Abs Dir -> FilePath -> m (Path Abs Dir) -- | The same as resolveDir, but uses current working directory. resolveDir' :: MonadIO m => FilePath -> m (Path Abs Dir) -- | removeFile file removes the directory entry for an -- existing file file, where file is not itself a -- directory. The implementation may specify additional constraints which -- must be satisfied before a file can be removed (e.g. the file may not -- be in use by other processes). -- -- The operation may fail with: -- -- removeFile :: MonadIO m => Path b File -> m () -- | renameFile old new changes the name of an existing -- file system object from old to new. If the new -- object already exists, it is atomically replaced by the old -- object. Neither path may refer to an existing directory. A conformant -- implementation need not support renaming files in all situations (e.g. -- renaming across different physical devices), but the constraints must -- be documented. -- -- The operation may fail with: -- -- renameFile :: MonadIO m => Path b0 File -> Path b1 File -> m () -- | copyFile old new copies the existing file from -- old to new. If the new file already exists, -- it is atomically replaced by the old file. Neither path may -- refer to an existing directory. The permissions of old are -- copied to new, if possible. copyFile :: MonadIO m => Path b0 File -> Path b1 File -> m () -- | Given an executable file name, search for such file in the directories -- listed in system PATH. The returned value is the path to the -- found executable or Nothing if an executable with the given -- name was not found. For example (findExecutable "ghc") gives -- you the path to GHC. -- -- The path returned by findExecutable corresponds to the program -- that would be executed by createProcess when passed the same -- string (as a RawCommand, not a ShellCommand). -- -- On Windows, findExecutable calls the Win32 function -- SearchPath, which may search other places before checking the -- directories in PATH. Where it actually searches depends on -- registry settings, but notably includes the directory containing the -- current executable. See -- http://msdn.microsoft.com/en-us/library/aa365527.aspx for more -- details. findExecutable :: MonadIO m => Path Rel File -> m (Maybe (Path Abs File)) -- | Search through the given set of directories for the given file. findFile :: MonadIO m => [Path b Dir] -> Path Rel File -> m (Maybe (Path Abs File)) -- | Search through the given set of directories for the given file and -- return a list of paths where the given file exists. findFiles :: MonadIO m => [Path b Dir] -> Path Rel File -> m [Path Abs File] -- | Search through the given set of directories for the given file and -- with the given property (usually permissions) and return a list of -- paths where the given file exists and has the property. findFilesWith :: MonadIO m => (Path Abs File -> m Bool) -> [Path b Dir] -> Path Rel File -> m [Path Abs File] -- | Check if the given path is a symbolic link. isSymlink :: MonadIO m => Path b t -> m Bool -- | Use a temporary file that doesn't already exist. -- -- Creates a new temporary file inside the given directory, making use of -- the template. The temporary file is deleted after use. withTempFile :: (MonadIO m, MonadMask m) => Path b Dir -> String -> (Path Abs File -> Handle -> m a) -> m a -- | Create and use a temporary directory. -- -- Creates a new temporary directory inside the given directory, making -- use of the template. The temporary directory is deleted after use. withTempDir :: (MonadIO m, MonadMask m) => Path b Dir -> String -> (Path Abs Dir -> m a) -> m a -- | Create and use a temporary file in the system standard temporary -- directory. -- -- Behaves exactly the same as withTempFile, except that the -- parent temporary directory will be that returned by getTempDir. withSystemTempFile :: (MonadIO m, MonadMask m) => String -> (Path Abs File -> Handle -> m a) -> m a -- | Create and use a temporary directory in the system standard temporary -- directory. -- -- Behaves exactly the same as withTempDir, except that the parent -- temporary directory will be that returned by getTempDir. withSystemTempDir :: (MonadIO m, MonadMask m) => String -> (Path Abs Dir -> m a) -> m a -- | The function creates a temporary file in rw mode. The created -- file isn't deleted automatically, so you need to delete it manually. -- -- The file is created with permissions such that only the current user -- can read/write it. -- -- With some exceptions (see below), the file will be created securely in -- the sense that an attacker should not be able to cause openTempFile to -- overwrite another file on the filesystem using your credentials, by -- putting symbolic links (on Unix) in the place where the temporary file -- is to be created. On Unix the O_CREAT and O_EXCL -- flags are used to prevent this attack, but note that O_EXCL -- is sometimes not supported on NFS filesystems, so if you rely on this -- behaviour it is best to use local filesystems only. openTempFile :: MonadIO m => Path b Dir -> String -> m (Path Abs File, Handle) -- | Like openTempFile, but opens the file in binary mode. On -- Windows, reading a file in text mode (which is the default) will -- translate CRLF to LF, and writing will translate -- LF to CRLF. This is usually what you want with text -- files. With binary files this is undesirable; also, as usual under -- Microsoft operating systems, text mode treats control-Z as EOF. Binary -- mode turns off all special treatment of end-of-line and end-of-file -- characters. openBinaryTempFile :: MonadIO m => Path b Dir -> String -> m (Path Abs File, Handle) -- | Create a temporary directory. The created directory isn't deleted -- automatically, so you need to delete it manually. -- -- The directory is created with permissions such that only the current -- user can read/write it. createTempDir :: MonadIO m => Path b Dir -> String -> m (Path Abs Dir) -- | The operation doesFileExist returns True if the argument -- file exists and is not a directory, and False otherwise. doesFileExist :: MonadIO m => Path b File -> m Bool -- | The operation doesDirExist returns True if the argument -- file exists and is either a directory or a symbolic link to a -- directory, and False otherwise. doesDirExist :: MonadIO m => Path b Dir -> m Bool -- | Check if there is a file or directory on specified path. isLocationOccupied :: MonadIO m => Path b t -> m Bool -- | If argument of the function throws a doesNotExistErrorType, -- Nothing is returned (other exceptions propagate). Otherwise the -- result is returned inside a Just. forgivingAbsence :: (MonadIO m, MonadCatch m) => m a -> m (Maybe a) -- | The same as forgivingAbsence, but ignores result. ignoringAbsence :: (MonadIO m, MonadCatch m) => m a -> m () data Permissions :: * emptyPermissions :: Permissions readable :: Permissions -> Bool writable :: Permissions -> Bool executable :: Permissions -> Bool searchable :: Permissions -> Bool setOwnerReadable :: Bool -> Permissions -> Permissions setOwnerWritable :: Bool -> Permissions -> Permissions setOwnerExecutable :: Bool -> Permissions -> Permissions setOwnerSearchable :: Bool -> Permissions -> Permissions -- | The getPermissions operation returns the permissions for the -- file or directory. -- -- The operation may fail with: -- -- getPermissions :: MonadIO m => Path b t -> m Permissions -- | The setPermissions operation sets the permissions for the file -- or directory. -- -- The operation may fail with: -- -- setPermissions :: MonadIO m => Path b t -> Permissions -> m () -- | Set permissions for the object found on second given path so they -- match permissions of the object on the first path. copyPermissions :: MonadIO m => Path b0 t0 -> Path b1 t1 -> m () -- | Obtain the time at which the file or directory was last accessed. -- -- The operation may fail with: -- -- -- -- Caveat for POSIX systems: This function returns a timestamp with -- sub-second resolution only if this package is compiled against -- unix-2.6.0.0 or later and the underlying filesystem supports -- them. -- -- Note: this is a piece of conditional API, only available if -- directory-1.2.3.0 or later is used. getAccessTime :: MonadIO m => Path b t -> m UTCTime -- | Change the time at which the file or directory was last accessed. -- -- The operation may fail with: -- -- -- -- Some caveats for POSIX systems: -- -- -- -- Note: this is a piece of conditional API, only available if -- directory-1.2.3.0 or later is used. setAccessTime :: MonadIO m => Path b t -> UTCTime -> m () -- | Change the time at which the file or directory was last modified. -- -- The operation may fail with: -- -- -- -- Some caveats for POSIX systems: -- -- -- -- Note: this is a piece of conditional API, only available if -- directory-1.2.3.0 or later is used. setModificationTime :: MonadIO m => Path b t -> UTCTime -> m () -- | Obtain the time at which the file or directory was last modified. -- -- The operation may fail with: -- -- -- -- Caveat for POSIX systems: This function returns a timestamp with -- sub-second resolution only if this package is compiled against -- unix-2.6.0.0 or later and the underlying filesystem supports -- them. getModificationTime :: MonadIO m => Path b t -> m UTCTime instance GHC.Show.Show Path.IO.WalkAction instance GHC.Classes.Eq Path.IO.WalkAction instance Path.IO.AnyPath (Path.Internal.Path b Path.File) instance Path.IO.AnyPath (Path.Internal.Path b Path.Dir)