Podenv.Prelude

Common functions

Documentation

module Relude

foldM :: (Foldable t, Monad m) => (b -> a -> m b) -> b -> t a -> m b

The foldM function is analogous to foldl, except that its result is encapsulated in a monad. Note that foldM works from left-to-right over the list arguments. This could be an issue where (>>) and the `folded function' are not commutative.

foldM f a1 [x1, x2, ..., xm]

==

do
  a2 <- f a1 x1
  a3 <- f a2 x2
  ...
  f am xm

If right-to-left evaluation is required, the input list should be reversed.

Note: foldM is the same as foldlM

lookup :: Eq a => a -> [(a, b)] -> Maybe b

\(\mathcal{O}(n)\). lookup key assocs looks up a key in an association list.

>>> lookup 2 [(1, "first"), (2, "second"), (3, "third")]
Just "second"

getEnv :: String -> IO String

Computation getEnv var returns the value of the environment variable var. For the inverse, the setEnv function can be used.

This computation may fail with:

• isDoesNotExistError if the environment variable does not exist.

orDie :: Maybe a -> Text -> Either Text a

mayFail :: Either Text a -> IO a

io

readFileM :: FilePath -> IO Text

hPutStrLn :: Handle -> String -> IO ()

The same as hPutStr, but adds a newline character.

base env

getExecutablePath :: IO FilePath

Returns the absolute pathname of the current executable.

Note that for scripts and interactive sessions, this is the path to the interpreter (e.g. ghci.)

Since base 4.11.0.0, getExecutablePath resolves symlinks on Windows. If an executable is launched through a symlink, getExecutablePath returns the absolute path of the original executable.

Since: base-4.6.0.0

xdg

getCacheDir :: IO FilePath

getConfigDir :: IO FilePath

getDataDir :: IO FilePath

directory

createDirectoryIfMissing

Arguments

:: Bool

Create its parents too?

-> FilePath

The path to the directory you want to make

-> IO ()

createDirectoryIfMissing 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.

getCurrentDirectory :: IO FilePath

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:

• HardwareFault A physical I/O error has occurred. [EIO]
• isDoesNotExistError There is no path referring to the working directory. [EPERM, ENOENT, ESTALE...]
• isPermissionError The process has insufficient privileges to perform the operation. [EACCES]
• isFullError Insufficient resources are available to perform the operation.
• UnsupportedOperation The operating system has no notion of current working directory.

doesFileExist :: FilePath -> IO Bool

The operation doesFileExist returns True if the argument file exists and is not a directory, and False otherwise.

doesPathExist :: FilePath -> IO Bool

Test whether the given path points to an existing filesystem object. If the user lacks necessary permissions to search the parent directories, this function may return false even if the file does actually exist.

Since: directory-1.2.7.0

doesSymlinkExist :: FilePath -> IO Bool

pathIsSymbolicLink :: FilePath -> IO Bool

Check whether an existing path is a symbolic link. If path is a regular file or directory, False is returned. If path does not exist or is otherwise inaccessible, an exception is thrown (see below).

On Windows, this checks for FILE_ATTRIBUTE_REPARSE_POINT. In addition to symbolic links, the function also returns true on junction points. On POSIX systems, this checks for S_IFLNK.

The operation may fail with:

• isDoesNotExistError if the symbolic link does not exist; or
• isPermissionError if the user is not permitted to read the symbolic link.

Since: directory-1.3.0.0

findExecutable :: String -> IO (Maybe FilePath)

Given the name or path of an executable file, findExecutable searches for such a file in a list of system-defined locations, which generally includes PATH and possibly more. The full path to the executable is returned if found. For example, (findExecutable "ghc") would normally give you the path to GHC.

The path returned by findExecutable name corresponds to the program that would be executed by createProcess when passed the same string (as a RawCommand, not a ShellCommand), provided that name is not a relative path with more than one segment.

On Windows, findExecutable calls the Win32 function SearchPath, which may search other places before checking the directories in the PATH environment variable. Where it actually searches depends on registry settings, but notably includes the directory containing the current executable.

On non-Windows platforms, the behavior is equivalent to findFileWith using the search directories from the PATH environment variable and testing each file for executable permissions. Details can be found in the documentation of findFileWith.

(</>) :: FilePath -> FilePath -> FilePath infixr 5

Combine two paths with a path separator. If the second path starts with a path separator or a drive letter, then it returns the second. The intention is that readFile (dir </> file) will access the same file as setCurrentDirectory dir; readFile file.

Posix:   "/directory" </> "file.ext" == "/directory/file.ext"
Windows: "/directory" </> "file.ext" == "/directory\\file.ext"
         "directory" </> "/file.ext" == "/file.ext"
Valid x => (takeDirectory x </> takeFileName x) `equalFilePath` x

Combined:

Posix:   "/" </> "test" == "/test"
Posix:   "home" </> "bob" == "home/bob"
Posix:   "x:" </> "foo" == "x:/foo"
Windows: "C:\\foo" </> "bar" == "C:\\foo\\bar"
Windows: "home" </> "bob" == "home\\bob"

Not combined:

Posix:   "home" </> "/bob" == "/bob"
Windows: "home" </> "C:\\bob" == "C:\\bob"

Not combined (tricky):

On Windows, if a filepath starts with a single slash, it is relative to the root of the current drive. In [1], this is (confusingly) referred to as an absolute path. The current behavior of </> is to never combine these forms.

Windows: "home" </> "/bob" == "/bob"
Windows: "home" </> "\\bob" == "\\bob"
Windows: "C:\\home" </> "\\bob" == "\\bob"

On Windows, from [1]: "If a file name begins with only a disk designator but not the backslash after the colon, it is interpreted as a relative path to the current directory on the drive with the specified letter." The current behavior of </> is to never combine these forms.

Windows: "D:\\foo" </> "C:bar" == "C:bar"
Windows: "C:\\foo" </> "C:bar" == "C:bar"

takeFileName :: FilePath -> FilePath

Get the file name.

takeFileName "/directory/file.ext" == "file.ext"
takeFileName "test/" == ""
takeFileName x `isSuffixOf` x
takeFileName x == snd (splitFileName x)
Valid x => takeFileName (replaceFileName x "fred") == "fred"
Valid x => takeFileName (x </> "fred") == "fred"
Valid x => isRelative (takeFileName x)

takeDirectory :: FilePath -> FilePath

Get the directory name, move up one level.

          takeDirectory "/directory/other.ext" == "/directory"
          takeDirectory x `isPrefixOf` x || takeDirectory x == "."
          takeDirectory "foo" == "."
          takeDirectory "/" == "/"
          takeDirectory "/foo" == "/"
          takeDirectory "/foo/bar/baz" == "/foo/bar"
          takeDirectory "/foo/bar/baz/" == "/foo/bar/baz"
          takeDirectory "foo/bar/baz" == "foo/bar"
Windows:  takeDirectory "foo\\bar" == "foo"
Windows:  takeDirectory "foo\\bar\\\\" == "foo\\bar"
Windows:  takeDirectory "C:\\" == "C:\\"

hasTrailingPathSeparator :: FilePath -> Bool

Is an item either a directory or the last character a path separator?

hasTrailingPathSeparator "test" == False
hasTrailingPathSeparator "test/" == True

listDirectory :: FilePath -> IO [FilePath]

listDirectory dir returns a list of all entries in dir without the special entries (. and ..).

The operation may fail with:

• HardwareFault A physical I/O error has occurred. [EIO]
• InvalidArgument The operand is not a valid directory name. [ENAMETOOLONG, ELOOP]
• isDoesNotExistError The directory does not exist. [ENOENT, ENOTDIR]
• isPermissionError The process has insufficient privileges to perform the operation. [EACCES]
• isFullError Insufficient resources are available to perform the operation. [EMFILE, ENFILE]
• InappropriateType The path refers to an existing non-directory object. [ENOTDIR]

Since: directory-1.2.5.0

posix

type UserID = CUid

getRealUserID :: IO UserID

getRealUserID calls getuid to obtain the real UserID associated with the current process.

lens

type Lens' s a = forall (f :: Type -> Type). Functor f => (a -> f a) -> s -> f s

The monomorphic lenses which don't change the type of the container (or of the value inside). It has a Functor constraint, and since both Const and Identity are functors, it can be used whenever a getter or a setter is needed.

• a is the type of the value inside of structure
• s is the type of the whole structure

Since: relude-0.5.0

(^.) :: s -> FoldLike a s t a b -> a infixl 8

(^.) :: s -> Getter s t a b -> a

Access the value referenced by a getter or lens.

(^.) :: Monoid a => s -> Fold s t a b -> a

Access the monoidal summary referenced by a traversal or a fold.

(.~) :: ASetter s t a b -> b -> s -> t infixr 4

Set all referenced fields to the given value.

(?~) :: ASetter s t a (Maybe b) -> b -> s -> t

(%~) :: ASetter s t a b -> (a -> b) -> s -> t infixr 4

Modify all referenced fields.

setWhenNothing :: ASetter s t (Maybe b) (Maybe b) -> b -> s -> t