Hledger.Cli.Script

One or none.

It is useful for modelling any computation that is allowed to fail.

Examples

Using the Alternative instance of Control.Monad.Except, the following functions:

>>> import Control.Monad.Except

>>> canFail = throwError "it failed" :: Except String Int>>> final = return 42                :: Except String Int

Can be combined by allowing the first function to fail:

>>> runExcept $ canFail *> finalLeft "it failed"

>>> runExcept $ optional canFail *> finalRight 42

Fork a thread and call the supplied function when the thread is about to terminate, with an exception or a returned value. The function is called with asynchronous exceptions masked.

forkFinally action and_then =
  mask $ \restore ->
    forkIO $ try (restore action) >>= and_then

This function is useful for informing the parent when a child terminates, for example.

Block the current thread until data is available to read on the given file descriptor (GHC only).

This will throw an IOError if the file descriptor was closed while this thread was blocked. To safely close a file descriptor that has been used with threadWaitRead, use closeFdWith.

Returns an STM action that can be used to wait for data to read from a file descriptor. The second returned value is an IO action that can be used to deregister interest in the file descriptor.

Block the current thread until data can be written to the given file descriptor (GHC only).

This will throw an IOError if the file descriptor was closed while this thread was blocked. To safely close a file descriptor that has been used with threadWaitWrite, use closeFdWith.

Returns an STM action that can be used to wait until data can be written to a file descriptor. The second returned value is an IO action that can be used to deregister interest in the file descriptor.

Duplicate a Chan: the duplicate channel begins empty, but data written to either channel from then on will be available from both. Hence this creates a kind of broadcast channel, where data written by anyone is seen by everyone else.

(Note that a duplicated channel is not equal to its original. So: fmap (c /=) $ dupChan c returns True for all c.)

Return a lazy list representing the contents of the supplied Chan, much like GHC.Internal.System.IO.hGetContents.

Build and return a new instance of Chan.

Read the next value from the Chan. Blocks when the channel is empty. Since the read end of a channel is an MVar, this operation inherits fairness guarantees of MVars (e.g. threads blocked in this operation are woken up in FIFO order).

Throws BlockedIndefinitelyOnMVar when the channel is empty and no other thread holds a reference to the channel.

Write a value to a Chan.

Write an entire list of items to a Chan.

Build a new QSem with a supplied initial quantity. The initial quantity must be at least 0.

Signal that a unit of the QSem is available.

Wait for a unit to become available.

Build a new QSemN with a supplied initial quantity. The initial quantity must be at least 0.

Signal that a given quantity is now available from the QSemN.

Wait for the specified quantity to become available.

Convert a single digit Char to the corresponding Int. This function fails unless its argument satisfies isHexDigit, but recognises both upper- and lower-case hexadecimal digits (that is, '0'..'9', 'a'..'f', 'A'..'F').

Examples

Characters '0' through '9' are converted properly to 0..9:

>>> map digitToInt ['0'..'9'][0,1,2,3,4,5,6,7,8,9]

Both upper- and lower-case 'A' through 'F' are converted as well, to 10..15.

>>> map digitToInt ['a'..'f'][10,11,12,13,14,15]>>> map digitToInt ['A'..'F'][10,11,12,13,14,15]

Anything else throws an exception:

>>> digitToInt 'G'*** Exception: Char.digitToInt: not a digit 'G'>>> digitToInt '♥'*** Exception: Char.digitToInt: not a digit '\9829'

Selects alphabetic Unicode characters (lower-case, upper-case and title-case letters, plus letters of caseless scripts and modifiers letters). This function is equivalent to isAlpha.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• UppercaseLetter

• LowercaseLetter

• TitlecaseLetter

• ModifierLetter

• OtherLetter

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Letter".

Examples

Basic usage:

>>> isLetter 'a'True>>> isLetter 'A'True>>> isLetter 'λ'True>>> isLetter '0'False>>> isLetter '%'False>>> isLetter '♥'False>>> isLetter '\31'False

Ensure that isLetter and isAlpha are equivalent.

>>> let chars = [(chr 0)..]>>> let letters = map isLetter chars>>> let alphas = map isAlpha chars>>> letters == alphasTrue

Selects Unicode mark characters, for example accents and the like, which combine with preceding characters.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• NonSpacingMark

• SpacingCombiningMark

• EnclosingMark

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Mark".

Examples

Basic usage:

>>> isMark 'a'False>>> isMark '0'False

Combining marks such as accent characters usually need to follow another character before they become printable:

>>> map isMark "ò"[False,True]

Puns are not necessarily supported:

>>> isMark '✓'False

Selects Unicode numeric characters, including digits from various scripts, Roman numerals, et cetera.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• DecimalNumber

• LetterNumber

• OtherNumber

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Number".

Examples

Basic usage:

>>> isNumber 'a'False>>> isNumber '%'False>>> isNumber '3'True

ASCII '0' through '9' are all numbers:

>>> and $ map isNumber ['0'..'9']True

Unicode Roman numerals are "numbers" as well:

>>> isNumber 'Ⅸ'True

Selects Unicode space and separator characters.

This function returns True if its argument has one of the following GeneralCategorys, or False otherwise:

• Space

• LineSeparator

• ParagraphSeparator

These classes are defined in the Unicode Character Database, part of the Unicode standard. The same document defines what is and is not a "Separator".

Examples

Basic usage:

>>> isSeparator 'a'False>>> isSeparator '6'False>>> isSeparator ' 'True

Warning: newlines and tab characters are not considered separators.

>>> isSeparator '\n'False>>> isSeparator '\t'False

But some more exotic characters are (like HTML's  ):

>>> isSeparator '\160'True

Use compareLength xs n as a safer and faster alternative to compare (length xs) n. Similarly, it's better to write compareLength xs 10 == LT instead of length xs < 10.

While length would force and traverse the entire spine of xs (which could even diverge if xs is infinite), compareLength traverses at most n elements to determine its result.

>>> compareLength [] 0EQ>>> compareLength [] 1LT>>> compareLength ['a'] 1EQ>>> compareLength ['a', 'b'] 1GT>>> compareLength [0..] 100GT>>> compareLength undefined (-1)GT>>> compareLength ('a' : undefined) 0GT

The inits1 function returns all non-empty initial segments of the argument, shortest first.

Laziness

Note that inits1 has the following strictness property: inits1 (xs ++ _|_) = inits1 xs ++ _|_

In particular, inits1 _|_ = _|_

Examples

>>> inits1 "abc"['a' :| "",'a' :| "b",'a' :| "bc"]

>>> inits1 [][]

inits1 is productive on infinite lists:

>>> take 3 $ inits1 [1..][1 :| [],1 :| [2],1 :| [2,3]]

Same as nub, but asymptotically faster, taking only O(n log d) time, where d is the number of distinct elements in the list.

Overloaded version of nubOrd.

The supplied comparison relation is supposed to be reflexive, transitive and antisymmetric, same as for sortBy.

\mathcal{O}(n). The tails1 function returns all non-empty final segments of the argument, longest first.

Laziness

Note that tails1 has the following strictness property: tails1 _|_ = _|_

>>> tails1 undefined*** Exception: Prelude.undefined

>>> drop 1 (tails1 [undefined, 1, 2])[1 :| [2],2 :| []]

Examples

>>> tails1 "abc"['a' :| "bc",'b' :| "c",'c' :| ""]

>>> tails1 [1, 2, 3][1 :| [2,3],2 :| [3],3 :| []]

>>> tails1 [][]

Write given error message to stderr and terminate with exitFailure.

The computation exitFailure is equivalent to exitWith (ExitFailure exitfail), where exitfail is implementation-dependent.

The computation exitSuccess is equivalent to exitWith ExitSuccess, It terminates the program successfully.

Computation exitWith code throws ExitCode code. Normally this terminates the program, returning code to the program's caller.

On program termination, the standard Handles stdout and stderr are flushed automatically; any other buffered Handles need to be flushed manually, otherwise the buffered data will be discarded.

A program that fails in any other way is treated as if it had called exitFailure. A program that terminates successfully without calling exitWith explicitly is treated as if it had called exitWith ExitSuccess.

As an ExitCode is an Exception, it can be caught using the functions of Control.Exception. This means that cleanup computations added with bracket (from Control.Exception) are also executed properly on exitWith.

Note: in GHC, exitWith should be called from the main program thread in order to exit the process. When called from another thread, exitWith will throw an ExitCode as normal, but the exception will not cause the process itself to exit.

Calls perror to indicate that there is a type error or similar in the given argument.

Calls perror to indicate an unknown format letter for a given type.

Calls perror to indicate that there is a missing argument in the argument list.

Calls perror to indicate that the format string ended early.

Formatter for Char values.

Formatter for Int values.

Formatter for Integer values.

Formatter for RealFloat values.

Similar to printf, except that output is via the specified Handle. The return type is restricted to (IO a).

Raises an error with a printf-specific prefix on the message string.

Format a variable number of arguments with the C-style formatting string.

>>> printf "%s, %d, %.4f" "hello" 123 pihello, 123, 3.1416

The return value is either String or (IO a) (which should be (IO ()), but Haskell's type system makes this hard).

The format string consists of ordinary characters and conversion specifications, which specify how to format one of the arguments to printf in the output string. A format specification is introduced by the % character; this character can be self-escaped into the format string using %%. A format specification ends with a format character that provides the primary information about how to format the value. The rest of the conversion specification is optional. In order, one may have flag characters, a width specifier, a precision specifier, and type-specific modifier characters.

Unlike C printf(3), the formatting of this printf is driven by the argument type; formatting is type specific. The types formatted by printf "out of the box" are:

• Integral types, including Char

• String

• RealFloat types

printf is also extensible to support other types: see below.

A conversion specification begins with the character %, followed by zero or more of the following flags:

-      left adjust (default is right adjust)
+      always use a sign (+ or -) for signed conversions
space  leading space for positive numbers in signed conversions
0      pad with zeros rather than spaces
#      use an \"alternate form\": see below

When both flags are given, - overrides 0 and + overrides space. A negative width specifier in a * conversion is treated as positive but implies the left adjust flag.

The "alternate form" for unsigned radix conversions is as in C printf(3):

%o           prefix with a leading 0 if needed
%x           prefix with a leading 0x if nonzero
%X           prefix with a leading 0X if nonzero
%b           prefix with a leading 0b if nonzero
%[eEfFgG]    ensure that the number contains a decimal point

Any flags are followed optionally by a field width:

num    field width
*      as num, but taken from argument list

The field width is a minimum, not a maximum: it will be expanded as needed to avoid mutilating a value.

Any field width is followed optionally by a precision:

.num   precision
.      same as .0
.*     as num, but taken from argument list

Negative precision is taken as 0. The meaning of the precision depends on the conversion type.

Integral    minimum number of digits to show
RealFloat   number of digits after the decimal point
String      maximum number of characters

The precision for Integral types is accomplished by zero-padding. If both precision and zero-pad are given for an Integral field, the zero-pad is ignored.

Any precision is followed optionally for Integral types by a width modifier; the only use of this modifier being to set the implicit size of the operand for conversion of a negative operand to unsigned:

hh     Int8
h      Int16
l      Int32
ll     Int64
L      Int64

The specification ends with a format character:

c      character               Integral
d      decimal                 Integral
o      octal                   Integral
x      hexadecimal             Integral
X      hexadecimal             Integral
b      binary                  Integral
u      unsigned decimal        Integral
f      floating point          RealFloat
F      floating point          RealFloat
g      general format float    RealFloat
G      general format float    RealFloat
e      exponent format float   RealFloat
E      exponent format float   RealFloat
s      string                  String
v      default format          any type

The "%v" specifier is provided for all built-in types, and should be provided for user-defined type formatters as well. It picks a "best" representation for the given type. For the built-in types the "%v" specifier is converted as follows:

c      Char
u      other unsigned Integral
d      other signed Integral
g      RealFloat
s      String

Mismatch between the argument types and the format string, as well as any other syntactic or semantic errors in the format string, will cause an exception to be thrown at runtime.

Note that the formatting for RealFloat types is currently a bit different from that of C printf(3), conforming instead to showEFloat, showFFloat and showGFloat (and their alternate versions showFFloatAlt and showGFloatAlt). This is hard to fix: the fixed versions would format in a backward-incompatible way. In any case the Haskell behavior is generally more sensible than the C behavior. A brief summary of some key differences:

• Haskell printf never uses the default "6-digit" precision used by C printf.

• Haskell printf treats the "precision" specifier as indicating the number of digits after the decimal point.

• Haskell printf prints the exponent of e-format numbers without a gratuitous plus sign, and with the minimum possible number of digits.

• Haskell printf will place a zero after a decimal point when possible.

Substitute a 'v' format character with the given default format character in the FieldFormat. A convenience for user-implemented types, which should support "%v".

Create a help flag triggered by -?/--help. The user may optionally modify help by specifying the format, such as:

--help=all          - help for all modes
--help=html         - help in HTML format
--help=100          - wrap the text at 100 characters
--help=100,one      - full text wrapped at 100 characters

Create a help flag triggered by -?/--help.

Create a version flag triggered by --numeric-version.

Create a version flag triggered by -V/--version.

Create verbosity flags triggered by -v/--verbose and -q/--quiet

Process the flags obtained by getArgs and expandArgsAt with a mode. Displays an error and exits with failure if the command line fails to parse, or returns the associated value. Implemented in terms of process. This function makes use of the following environment variables:

• $CMDARGS_COMPLETE - causes the program to produce completions using complete, then exit. Completions are based on the result of getArgs, the index of the current argument is taken from $CMDARGS_COMPLETE (set it to - to complete the last argument), and the index within that argument is taken from $CMDARGS_COMPLETE_POS (if set).

• $CMDARGS_HELPER/$CMDARGS_HELPER_PROG - uses the helper mechanism for entering command line programs as described in System.Console.CmdArgs.Helper.

Process a list of flags (usually obtained from getArgs and expandArgsAt) with a mode. Throws an error if the command line fails to parse, or returns the associated value. Implemeneted in terms of process. This function does not take account of any environment variables that may be set (see processArgs).

If you are in IO you will probably get a better user experience by calling processValueIO.

Like processValue but on failure prints to stderr and exits the program.

Given a current state, return the set of commands you could type now, in preference order.

Expand @ directives in a list of arguments, usually obtained from getArgs. As an example, given the file test.txt with the lines hello and world:

expandArgsAt ["@test.txt","!"] == ["hello","world","!"]

Any @ directives in the files will be recursively expanded (raising an error if there is infinite recursion).

To supress @ expansion, pass any @ arguments after --.

Generate a help message from a mode. The first argument is a prefix, which is prepended when not using HelpFormatBash or HelpFormatZsh.

Process a list of flags (usually obtained from getArgs/expandArgsAt) with a mode. Returns Left and an error message if the command line fails to parse, or Right and the associated value.

Given a sequence of arguments, join them together in a manner that could be used on the command line, giving preference to the Windows cmd shell quoting conventions.

For an alternative version, intended for actual running the result in a shell, see "System.Process.showCommandForUser"

Given a string, split into the available arguments. The inverse of joinArgs.

Check that a mode is well formed.

Create an argument flag, with an update function and the type of the argument.

Create a boolean flag, with a list of flag names, an update function and some help text.

Create a flag taking no argument value, with a list of flag names, an update function and some help text.

Create a flag taking an optional argument value, with an optional value, a list of flag names, an update function, the type of the argument and some help text.

Create a flag taking a required argument value, with a list of flag names, an update function, the type of the argument and some help text.

Extract the value from inside a FlagOpt or FlagOptRare, or raises an error.

Convert a group into a list.

Create a mode with a name, an initial value, some help text, a way of processing arguments and a list of flags.

Create an empty mode specifying only modeValue. All other fields will usually be populated using record updates.

Extract the flags from a Mode

Extract the modes from a Mode

Create a list of modes, with a program name, an initial value, some help text and the child modes.

Parse a boolean, accepts as True: true yes on enabled 1.

Restricted version of remap where the values are isomorphic.

Version of remap for the Update type alias.

Convert a list into a group, placing all fields in groupUnnamed.

Make a path absolute, normalize the path, and remove as many indirections from it as possible. Any trailing path separators are discarded via dropTrailingPathSeparator. Additionally, on Windows the letter case of the path is canonicalized.

Note: This function is a very big hammer. If you only need an absolute path, makeAbsolute is sufficient for removing dependence on the current working directory.

Indirections include the two special directories . and .., as well as any symbolic links (and junction points on Windows). The input path need not point to an existing file or directory. Canonicalization is performed on the longest prefix of the path that points to an existing file or directory. The remaining portion of the path that does not point to an existing file or directory will still be normalized, but case canonicalization and indirection removal are skipped as they are impossible to do on a nonexistent path.

Most programs should not worry about the canonicity of a path. In particular, despite the name, the function does not truly guarantee canonicity of the returned path due to the presence of hard links, mount points, etc.

If the path points to an existing file or directory, then the output path shall also point to the same file or directory, subject to the condition that the relevant parts of the file system do not change while the function is still running. In other words, the function is definitively not atomic. The results can be utterly wrong if the portions of the path change while this function is running.

Since some indirections (symbolic links on all systems, .. on non-Windows systems, and junction points on Windows) are dependent on the state of the existing filesystem, the function can only make a conservative attempt by removing such indirections from the longest prefix of the path that still points to an existing file or directory.

Note that on Windows parent directories .. are always fully expanded before the symbolic links, as consistent with the rest of the Windows API (such as GetFullPathName). In contrast, on POSIX systems parent directories .. are expanded alongside symbolic links from left to right. To put this more concretely: if L is a symbolic link for R/P, then on Windows L\.. refers to ., whereas on other operating systems L/.. refers to R.

Similar to System.FilePath.normalise, passing an empty path is equivalent to passing the current directory.

canonicalizePath can resolve at least 64 indirections in a single path, more than what is supported by most operating systems. Therefore, it may return the fully resolved path even though the operating system itself would have long given up.

On Windows XP or earlier systems, junction expansion is not performed due to their lack of GetFinalPathNameByHandle.

Changes since 1.2.3.0: The function has been altered to be more robust and has the same exception behavior as makeAbsolute.

Changes since 1.3.0.0: The function no longer preserves the trailing path separator. File symbolic links that appear in the middle of a path are properly dereferenced. Case canonicalization and symbolic link expansion are now performed on Windows.

Copy a file with its permissions. If the destination file already exists, it is replaced atomically. Neither path may refer to an existing directory. No exceptions are thrown if the permissions could not be copied.

Copy a file with its associated metadata. If the destination file already exists, it is overwritten. There is no guarantee of atomicity in the replacement of the destination file. Neither path may refer to an existing directory. If the source and/or destination are symbolic links, the copy is performed on the targets of the links.

On Windows, it behaves like the Win32 function CopyFile, which copies various kinds of metadata including file attributes and security resource properties.

On Unix-like systems, permissions, access time, and modification time are preserved. If possible, the owner and group are also preserved. Note that the very act of copying can change the access time of the source file, hence the access times of the two files may differ after the operation completes.

Copy the permissions of one file to another. This reproduces the permissions more accurately than using getPermissions followed by setPermissions.

On Windows, this copies only the read-only attribute.

On POSIX systems, this is equivalent to stat followed by chmod.

createDirectory 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:

• isPermissionError The process has insufficient privileges to perform the operation. [EROFS, EACCES]

• isAlreadyExistsError The operand refers to a directory that already exists. [EEXIST]

• HardwareFault A physical I/O error has occurred. [EIO]

• InvalidArgument The operand is not a valid directory name. [ENAMETOOLONG, ELOOP]

• isDoesNotExistError There is no path to the directory. [ENOENT, ENOTDIR]

• System.IO.isFullError Insufficient resources (virtual memory, process file descriptors, physical disk space, etc.) are available to perform the operation. [EDQUOT, ENOSPC, ENOMEM, EMLINK]

• InappropriateType The path refers to an existing non-directory object. [EEXIST]

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.

Create a directory symbolic link. The target path can be either absolute or relative and need not refer to an existing directory. The order of arguments follows the POSIX convention.

To remove an existing directory symbolic link, use removeDirectoryLink.

Although the distinction between file symbolic links and directory symbolic links does not exist on POSIX systems, on Windows this is an intrinsic property of every symbolic link and cannot be changed without recreating the link. A file symbolic link that actually points to a directory will fail to dereference and vice versa. Moreover, creating symbolic links on Windows may require privileges unavailable to users outside the Administrators group. Portable programs that use symbolic links should take both into consideration.

On Windows, the function is implemented using CreateSymbolicLink with SYMBOLIC_LINK_FLAG_DIRECTORY. Since 1.3.3.0, the SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE flag is also included if supported by the operating system. On POSIX, this is an alias for createFileLink and is therefore atomic.

Windows-specific errors: This operation may fail with permissionErrorType if the user lacks the privileges to create symbolic links. It may also fail with illegalOperationErrorType if the file system does not support symbolic links.

Create a file symbolic link. The target path can be either absolute or relative and need not refer to an existing file. The order of arguments follows the POSIX convention.

To remove an existing file symbolic link, use removeFile.

Although the distinction between file symbolic links and directory symbolic links does not exist on POSIX systems, on Windows this is an intrinsic property of every symbolic link and cannot be changed without recreating the link. A file symbolic link that actually points to a directory will fail to dereference and vice versa. Moreover, creating symbolic links on Windows may require privileges unavailable to users outside the Administrators group. Portable programs that use symbolic links should take both into consideration.

On Windows, the function is implemented using CreateSymbolicLink. Since 1.3.3.0, the SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE flag is included if supported by the operating system. On POSIX, the function uses symlink and is therefore atomic.

Windows-specific errors: This operation may fail with permissionErrorType if the user lacks the privileges to create symbolic links. It may also fail with illegalOperationErrorType if the file system does not support symbolic links.

The operation doesDirectoryExist returns True if the argument file exists and is either a directory or a symbolic link to a directory, and False otherwise.

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

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.

Filename extension for executable files (including the dot if any) (usually "" on POSIX systems and ".exe" on Windows or OS/2).

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.

Search for executable files in a list of system-defined locations, which generally includes PATH and possibly more.

On Windows, this only returns the first occurrence, if any. Its behavior is therefore equivalent to findExecutable.

On non-Windows platforms, the behavior is equivalent to findExecutablesInDirectories using the search directories from the PATH environment variable. Details can be found in the documentation of findExecutablesInDirectories.

Given a name or path, findExecutable appends the exeExtension to the query and searches for executable files in the list of given search directories and returns all occurrences.

The behavior is equivalent to findFileWith using the given search directories and testing each file for executable permissions. Details can be found in the documentation of findFileWith.

Unlike other similarly named functions, findExecutablesInDirectories does not use SearchPath from the Win32 API. The behavior of this function on Windows is therefore equivalent to those on non-Windows platforms.

Search through the given list of directories for the given file.

The behavior is equivalent to findFileWith, returning only the first occurrence. Details can be found in the documentation of findFileWith.

Search through a given list of directories for a file that has the given name and satisfies the given predicate and return the path of the first occurrence. The directories are checked in a left-to-right order.

This is essentially a more performant version of findFilesWith that always returns the first result, if any. Details can be found in the documentation of findFilesWith.

Search through the given list of directories for the given file and returns all paths where the given file exists.

The behavior is equivalent to findFilesWith. Details can be found in the documentation of findFilesWith.

findFilesWith predicate dirs name searches through the list of directories (dirs) for files that have the given name and satisfy the given predicate and returns the paths of those files. The directories are checked in a left-to-right order and the paths are returned in the same order.

If the name is a relative path, then for every search directory dir, the function checks whether dir </> name exists and satisfies the predicate. If so, dir </> name is returned as one of the results. In other words, the returned paths can be either relative or absolute depending on the search directories were used. If there are no search directories, no results are ever returned.

If the name is an absolute path, then the function will return a single result if the file exists and satisfies the predicate and no results otherwise. This is irrespective of what search directories were given.

Obtain the time at which the file or directory was last accessed.

The operation may fail with:

• isPermissionError if the user is not permitted to read the access time; or

• isDoesNotExistError if the file or directory does not exist.

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.

Obtain the path to a special directory for storing user-specific application data (traditional Unix location). Newer applications may prefer the the XDG-conformant location provided by getXdgDirectory (migration guide).

The argument is usually the name of the application. Since it will be integrated into the path, it must consist of valid path characters.

• On Unix-like systems, the path is ~/.<app>.

• On Windows, the path is %APPDATA%/<app> (e.g. C:/Users/<user>/AppData/Roaming/<app>)

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:

• UnsupportedOperation The operating system has no notion of application-specific data directory.

• isDoesNotExistError The home directory for the current user does not exist, or cannot be found.

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

Note that getCurrentDirectory is not guaranteed to return the same path received by setCurrentDirectory. On POSIX systems, the path returned will always be fully dereferenced (not contain any symbolic links). For more information, refer to the documentation of getcwd.

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]

• System.IO.isFullError Insufficient resources are available to perform the operation.

• UnsupportedOperation The operating system has no notion of current working directory.

Similar to listDirectory, but always includes the special entries (. and ..). (This applies to Windows as well.)

The operation may fail with the same exceptions as listDirectory.

Get the contents of the PATH environment variable.

Obtain the size of a file in bytes.

Returns 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 getXdgDirectory or getAppUserDataDirectory instead.

On Unix, getHomeDirectory behaves as follows:

• Returns $HOME env variable if set (including to an empty string).

• Otherwise uses home directory returned by getpwuid_r using the UID of the current process' user. This basically reads the /etc/passwd file. An empty home directory field is considered valid.

On Windows, the system is queried for a suitable path; a typical path might be C:/Users/<user>.

The operation may fail with:

• UnsupportedOperation The operating system has no notion of home directory.

• isDoesNotExistError The home directory for the current user does not exist, or cannot be found.

Obtain the time at which the file or directory was last modified.

The operation may fail with:

• isPermissionError if the user is not permitted to read the modification time; or

• isDoesNotExistError if the file or directory does not exist.

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.

Get the permissions of a file or directory.

On Windows, the writable permission corresponds to the "read-only" attribute. The executable permission is set if the file extension is of an executable file type. The readable permission is always set.

On POSIX systems, this returns the result of access.

The operation may fail with:

• isPermissionError if the user is not permitted to access the permissions, or

• isDoesNotExistError if the file or directory does not exist.

Retrieve the target path of either a file or directory symbolic link. The returned path may not be absolute, may not exist, and may not even be a valid path.

On Windows systems, this calls DeviceIoControl with FSCTL_GET_REPARSE_POINT. In addition to symbolic links, the function also works on junction points. On POSIX systems, this calls readlink.

Windows-specific errors: This operation may fail with illegalOperationErrorType if the file system does not support symbolic links.

Returns the current directory for temporary files.

On Unix, getTemporaryDirectory 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:

• TMP environment variable.

• TEMP environment variable.

• USERPROFILE environment variable.

• The Windows directory

The operation may fail with:

• UnsupportedOperation The operating system has no notion of temporary directory.

The function doesn't verify whether the path exists.

Returns 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 getXdgDirectory or getAppUserDataDirectory instead.

On Unix, getUserDocumentsDirectory 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:

• UnsupportedOperation The operating system has no notion of document directory.

• isDoesNotExistError The document directory for the current user does not exist, or cannot be found.

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 getAppUserDataDirectory, this function provides a more fine-grained hierarchy as well as greater flexibility for the user.

On Windows, XdgData and XdgConfig usually map to the same directory unless overridden.

Refer to the docs of XdgDirectory for more details.

The second argument is usually the name of the application. Since it will be integrated into the path, it must consist of valid path characters. Note: if the second argument is an absolute path, it will just return the second argument.

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

As of 1.3.5.0, the environment variable is ignored if set to a relative path, per revised XDG Base Directory Specification. See #100.

Similar to getXdgDirectory but retrieves the entire list of XDG directories.

On Windows, XdgDataDirs and XdgConfigDirs usually map to the same list of directories unless overridden.

Refer to the docs of XdgDirectoryList for more details.

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]

• System.IO.isFullError Insufficient resources are available to perform the operation. [EMFILE, ENFILE]

• InappropriateType The path refers to an existing non-directory object. [ENOTDIR]

Convert a path into an absolute path. If the given path is relative, the current directory is prepended and then the combined result is normalized. If the path is already absolute, the path is simply normalized. The function preserves the presence or absence of the trailing path separator unless the path refers to the root directory /.

If the path is already absolute, the operation never fails. Otherwise, the operation may fail with the same exceptions as getCurrentDirectory.

Construct a path relative to the current directory, similar to makeRelative.

The operation may fail with the same exceptions as getCurrentDirectory.

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.

removeDirectory 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:

• 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. [EROFS, EACCES, EPERM]

• UnsatisfiedConstraints Implementation-dependent constraints are not satisfied. [EBUSY, ENOTEMPTY, EEXIST]

• UnsupportedOperation The implementation does not support removal in this situation. [EINVAL]

• InappropriateType The operand refers to an existing non-directory object. [ENOTDIR]

Remove an existing directory symbolic link.

On Windows, this is an alias for removeDirectory. On POSIX systems, this is an alias for removeFile.

See also: removeFile, which can remove an existing file symbolic link.

removeDirectoryRecursive dir removes an existing directory dir together with its contents and subdirectories. Within this directory, symbolic links are removed without affecting their targets.

On Windows, the operation fails if dir is a directory symbolic link.

This operation is reported to be flaky on Windows so retry logic may be advisable. See: https://github.com/haskell/directory/pull/108

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:

• HardwareFault A physical I/O error has occurred. [EIO]

• InvalidArgument The operand is not a valid file name. [ENAMETOOLONG, ELOOP]

• isDoesNotExistError The file does not exist. [ENOENT, ENOTDIR]

• isPermissionError The process has insufficient privileges to perform the operation. [EROFS, EACCES, EPERM]

• UnsatisfiedConstraints Implementation-dependent constraints are not satisfied. [EBUSY]

• InappropriateType The operand refers to an existing directory. [EPERM, EINVAL]

Removes a file or directory at path together with its contents and subdirectories. Symbolic links are removed without affecting their targets. If the path does not exist, nothing happens.

Unlike other removal functions, this function will also attempt to delete files marked as read-only or otherwise made unremovable due to permissions. As a result, if the removal is incomplete, the permissions or attributes on the remaining files may be altered. If there are hard links in the directory, then permissions on all related hard links may be altered.

If an entry within the directory vanishes while removePathForcibly is running, it is silently ignored.

If an exception occurs while removing an entry, removePathForcibly will still try to remove as many entries as it can before failing with an exception. The first exception that it encountered is re-thrown.

renameDirectory 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 removeDirectory. 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, renameDirectory fails if the new directory already exists.

The operation may fail with:

• HardwareFault A physical I/O error has occurred. [EIO]

• InvalidArgument Either operand is not a valid directory name. [ENAMETOOLONG, ELOOP]

• isDoesNotExistError The original directory does not exist, or there is no path to the target. [ENOENT, ENOTDIR]

• isPermissionError The process has insufficient privileges to perform the operation. [EROFS, EACCES, EPERM]

• System.IO.isFullError Insufficient resources are available to perform the operation. [EDQUOT, ENOSPC, ENOMEM, EMLINK]

• UnsatisfiedConstraints Implementation-dependent constraints are not satisfied. [EBUSY, ENOTEMPTY, EEXIST]

• UnsupportedOperation The implementation does not support renaming in this situation. [EINVAL, EXDEV]

• InappropriateType Either path refers to an existing non-directory object. [ENOTDIR, EISDIR]

renameFile old new changes the name of an existing file system object from old to new. If the new object already exists, it is 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. On Windows, this does not support renaming across different physical devices; if you are looking to do so, consider using copyFileWithMetadata and removeFile.

On Windows, this calls MoveFileEx with MOVEFILE_REPLACE_EXISTING set, which is not guaranteed to be atomic (https://github.com/haskell/directory/issues/109).

On other platforms, this operation is atomic.

The operation may fail with:

• HardwareFault A physical I/O error has occurred. [EIO]

• InvalidArgument Either operand is not a valid file name. [ENAMETOOLONG, ELOOP]

• isDoesNotExistError The original file does not exist, or there is no path to the target. [ENOENT, ENOTDIR]

• isPermissionError The process has insufficient privileges to perform the operation. [EROFS, EACCES, EPERM]

• System.IO.isFullError Insufficient resources are available to perform the operation. [EDQUOT, ENOSPC, ENOMEM, EMLINK]

• UnsatisfiedConstraints Implementation-dependent constraints are not satisfied. [EBUSY]

• UnsupportedOperation The implementation does not support renaming in this situation. [EXDEV]

• InappropriateType Either path refers to an existing directory. [ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]

Rename a file or directory. If the destination path already exists, it is replaced atomically. The destination path must not point 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:

• HardwareFault A physical I/O error has occurred. [EIO]

• InvalidArgument Either operand is not a valid file name. [ENAMETOOLONG, ELOOP]

• isDoesNotExistError The original file does not exist, or there is no path to the target. [ENOENT, ENOTDIR]

• isPermissionError The process has insufficient privileges to perform the operation. [EROFS, EACCES, EPERM]

• System.IO.isFullError Insufficient resources are available to perform the operation. [EDQUOT, ENOSPC, ENOMEM, EMLINK]

• UnsatisfiedConstraints Implementation-dependent constraints are not satisfied. [EBUSY]

• UnsupportedOperation The implementation does not support renaming in this situation. [EXDEV]

• InappropriateType Either the destination path refers to an existing directory, or one of the parent segments in the destination path is not a directory. [ENOTDIR, EISDIR, EINVAL, EEXIST, ENOTEMPTY]

Change the time at which the file or directory was last accessed.

The operation may fail with:

• isPermissionError if the user is not permitted to alter the access time; or

• isDoesNotExistError if the file or directory does not exist.

Some caveats for POSIX systems:

• Not all systems support utimensat, in which case the function can only emulate the behavior by reading the modification time and then setting both the access and modification times together. On systems where utimensat is supported, the access time is set atomically with nanosecond precision.

• If compiled against a version of unix prior to 2.7.0.0, the function would not be able to set timestamps with sub-second resolution. In this case, there would also be loss of precision in the modification time.

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:

• 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]

• UnsupportedOperation The operating system has no notion of current working directory, or the working directory cannot be dynamically changed.

• InappropriateType The path refers to an existing non-directory object. [ENOTDIR]

Change the time at which the file or directory was last modified.

The operation may fail with:

• isPermissionError if the user is not permitted to alter the modification time; or

• isDoesNotExistError if the file or directory does not exist.

• InvalidArgument on FAT32 file system if the time is before DOS Epoch (1 January 1980).

Some caveats for POSIX systems:

• Not all systems support utimensat, in which case the function can only emulate the behavior by reading the access time and then setting both the access and modification times together. On systems where utimensat is supported, the modification time is set atomically with nanosecond precision.

• If compiled against a version of unix prior to 2.7.0.0, the function would not be able to set timestamps with sub-second resolution. In this case, there would also be loss of precision in the access time.

Set the permissions of a file or directory.

On Windows, this is only capable of changing the writable permission, which corresponds to the "read-only" attribute. Changing the other permissions has no effect.

On POSIX systems, this sets the owner permissions.

The operation may fail with:

• isPermissionError if the user is not permitted to set the permissions, or

• isDoesNotExistError if the file or directory does not exist.

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 getCurrentDirectory and setCurrentDirectory.

Returns width of a character in a monospace font: 0 for a combining character, 1 for a regular character, 2 for an East Asian wide character. Ambiguous characters are treated as width 1.

Remove the current extension and add another, equivalent to replaceExtension.

"/directory/path.txt" -<.> "ext" == "/directory/path.ext"
"/directory/path.txt" -<.> ".ext" == "/directory/path.ext"
"foo.o" -<.> "c" == "foo.c"

Add an extension, even if there is already one there, equivalent to addExtension.

"/directory/path" <.> "ext" == "/directory/path.ext"
"/directory/path" <.> ".ext" == "/directory/path.ext"

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"

Add an extension, even if there is already one there, equivalent to <.>.

addExtension "/directory/path" "ext" == "/directory/path.ext"
addExtension "file.txt" "bib" == "file.txt.bib"
addExtension "file." ".bib" == "file..bib"
addExtension "file" ".bib" == "file.bib"
addExtension "/" "x" == "/.x"
addExtension x "" == x
Valid x => takeFileName (addExtension (addTrailingPathSeparator x) "ext") == ".ext"
Windows: addExtension "\\\\share" ".txt" == "\\\\share\\.txt"

Add a trailing file path separator if one is not already present.

hasTrailingPathSeparator (addTrailingPathSeparator x)
hasTrailingPathSeparator x ==> addTrailingPathSeparator x == x
Posix:    addTrailingPathSeparator "test/rest" == "test/rest/"

An alias for </>.

Delete the drive, if it exists.

dropDrive x == snd (splitDrive x)

Remove last extension, and the "." preceding it.

dropExtension "/directory/path.ext" == "/directory/path"
dropExtension x == fst (splitExtension x)

Drop all extensions.

dropExtensions "/directory/path.ext" == "/directory/path"
dropExtensions "file.tar.gz" == "file"
not $ hasExtension $ dropExtensions x
not $ any isExtSeparator $ takeFileName $ dropExtensions x

Drop the filename. Unlike takeDirectory, this function will leave a trailing path separator on the directory.

dropFileName "/directory/file.ext" == "/directory/"
dropFileName x == fst (splitFileName x)
isPrefixOf (takeDrive x) (dropFileName x)

Remove any trailing path separators

dropTrailingPathSeparator "file/test/" == "file/test"
          dropTrailingPathSeparator "/" == "/"
Windows:  dropTrailingPathSeparator "\\" == "\\"
Posix:    not (hasTrailingPathSeparator (dropTrailingPathSeparator x)) || isDrive x

Equality of two FILEPATHs. If you call System.Directory.canonicalizePath first this has a much better chance of working. Note that this doesn't follow symlinks or DOSNAM~1s.

Similar to normalise, this does not expand "..", because of symlinks.

         x == y ==> equalFilePath x y
         normalise x == normalise y ==> equalFilePath x y
         equalFilePath "foo" "foo/"
         not (equalFilePath "/a/../c" "/c")
         not (equalFilePath "foo" "/foo")
Posix:   not (equalFilePath "foo" "FOO")
Windows: equalFilePath "foo" "FOO"
Windows: not (equalFilePath "C:" "C:/")

File extension character

extSeparator == '.'

Get a list of FILEPATHs in the $PATH variable.

Does a path have a drive.

not (hasDrive x) == null (takeDrive x)
Posix:   hasDrive "/foo" == True
Windows: hasDrive "C:\\foo" == True
Windows: hasDrive "C:foo" == True
         hasDrive "foo" == False
         hasDrive "" == False

Does the given filename have an extension?

hasExtension "/directory/path.ext" == True
hasExtension "/directory/path" == False
null (takeExtension x) == not (hasExtension x)

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

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

Is an element a drive

Posix:   isDrive "/" == True
Posix:   isDrive "/foo" == False
Windows: isDrive "C:\\" == True
Windows: isDrive "C:\\foo" == False
         isDrive "" == False

Is the character an extension character?

isExtSeparator a == (a == extSeparator)

Does the given filename have the specified extension?

"png" `isExtensionOf` "/directory/file.png" == True
".png" `isExtensionOf` "/directory/file.png" == True
".tar.gz" `isExtensionOf` "bar/foo.tar.gz" == True
"ar.gz" `isExtensionOf` "bar/foo.tar.gz" == False
"png" `isExtensionOf` "/directory/file.png.jpg" == False
"csv/table.csv" `isExtensionOf` "/data/csv/table.csv" == False

Rather than using (== pathSeparator), use this. Test if something is a path separator.

isPathSeparator a == (a `elem` pathSeparators)

Is a path relative, or is it fixed to the root?

Windows: isRelative "path\\test" == True
Windows: isRelative "c:\\test" == False
Windows: isRelative "c:test" == True
Windows: isRelative "c:\\" == False
Windows: isRelative "c:/" == False
Windows: isRelative "c:" == True
Windows: isRelative "\\\\foo" == False
Windows: isRelative "\\\\?\\foo" == False
Windows: isRelative "\\\\?\\UNC\\foo" == False
Windows: isRelative "/foo" == True
Windows: isRelative "\\foo" == True
Posix:   isRelative "test/path" == True
Posix:   isRelative "/test" == False
Posix:   isRelative "/" == False

According to [1]:

• "A UNC name of any format [is never relative]."

• "You cannot use the "\?" prefix with a relative path."

Is the character a file separator?

isSearchPathSeparator a == (a == searchPathSeparator)

Is a FilePath valid, i.e. could you create a file like it? This function checks for invalid names, and invalid characters, but does not check if length limits are exceeded, as these are typically filesystem dependent.

         isValid "" == False
         isValid "\0" == False
Posix:   isValid "/random_ path:*" == True
Posix:   isValid x == not (null x)
Windows: isValid "c:\\test" == True
Windows: isValid "c:\\test:of_test" == False
Windows: isValid "test*" == False
Windows: isValid "c:\\test\\nul" == False
Windows: isValid "c:\\test\\prn.txt" == False
Windows: isValid "c:\\nul\\file" == False
Windows: isValid "\\\\" == False
Windows: isValid "\\\\\\foo" == False
Windows: isValid "\\\\?\\D:file" == False
Windows: isValid "foo\tbar" == False
Windows: isValid "nul .txt" == False
Windows: isValid " nul.txt" == True

Join a drive and the rest of the path.

Valid x => uncurry joinDrive (splitDrive x) == x
Windows: joinDrive "C:" "foo" == "C:foo"
Windows: joinDrive "C:\\" "bar" == "C:\\bar"
Windows: joinDrive "\\\\share" "foo" == "\\\\share\\foo"
Windows: joinDrive "/:" "foo" == "/:\\foo"

Join path elements back together.

joinPath z == foldr (</>) "" z
joinPath ["/","directory/","file.ext"] == "/directory/file.ext"
Valid x => joinPath (splitPath x) == x
joinPath [] == ""
Posix: joinPath ["test","file","path"] == "test/file/path"

Contract a filename, based on a relative path. Note that the resulting path will never introduce .. paths, as the presence of symlinks means ../b may not reach a/b if it starts from a/c. For a worked example see this blog post.

The corresponding makeAbsolute function can be found in System.Directory.

         makeRelative "/directory" "/directory/file.ext" == "file.ext"
         Valid x => makeRelative (takeDirectory x) x `equalFilePath` takeFileName x
         makeRelative x x == "."
         Valid x y => equalFilePath x y || (isRelative x && makeRelative y x == x) || equalFilePath (y </> makeRelative y x) x
Windows: makeRelative "C:\\Home" "c:\\home\\bob" == "bob"
Windows: makeRelative "C:\\Home" "c:/home/bob" == "bob"
Windows: makeRelative "C:\\Home" "D:\\Home\\Bob" == "D:\\Home\\Bob"
Windows: makeRelative "C:\\Home" "C:Home\\Bob" == "C:Home\\Bob"
Windows: makeRelative "/Home" "/home/bob" == "bob"
Windows: makeRelative "/" "//" == "//"
Posix:   makeRelative "/Home" "/home/bob" == "/home/bob"
Posix:   makeRelative "/home/" "/home/bob/foo/bar" == "bob/foo/bar"
Posix:   makeRelative "/fred" "bob" == "bob"
Posix:   makeRelative "/file/test" "/file/test/fred" == "fred"
Posix:   makeRelative "/file/test" "/file/test/fred/" == "fred/"
Posix:   makeRelative "some/path" "some/path/a/b/c" == "a/b/c"

Take a FilePath and make it valid; does not change already valid FILEPATHs.

isValid (makeValid x)
isValid x ==> makeValid x == x
makeValid "" == "_"
makeValid "file\0name" == "file_name"
Windows: makeValid "c:\\already\\/valid" == "c:\\already\\/valid"
Windows: makeValid "c:\\test:of_test" == "c:\\test_of_test"
Windows: makeValid "test*" == "test_"
Windows: makeValid "c:\\test\\nul" == "c:\\test\\nul_"
Windows: makeValid "c:\\test\\prn.txt" == "c:\\test\\prn_.txt"
Windows: makeValid "c:\\test/prn.txt" == "c:\\test/prn_.txt"
Windows: makeValid "c:\\nul\\file" == "c:\\nul_\\file"
Windows: makeValid "\\\\\\foo" == "\\\\drive"
Windows: makeValid "\\\\?\\D:file" == "\\\\?\\D:\\file"
Windows: makeValid "nul .txt" == "nul _.txt"

Normalise a file

• // outside of the drive can be made blank

• / -> pathSeparator

• ./ -> ""

Does not remove "..", because of symlinks.

Posix:   normalise "/file/\\test////" == "/file/\\test/"
Posix:   normalise "/file/./test" == "/file/test"
Posix:   normalise "/test/file/../bob/fred/" == "/test/file/../bob/fred/"
Posix:   normalise "../bob/fred/" == "../bob/fred/"
Posix:   normalise "/a/../c" == "/a/../c"
Posix:   normalise "./bob/fred/" == "bob/fred/"
Windows: normalise "c:\\file/bob\\" == "C:\\file\\bob\\"
Windows: normalise "c:\\" == "C:\\"
Windows: normalise "c:\\\\\\\\" == "C:\\"
Windows: normalise "C:.\\" == "C:"
Windows: normalise "\\\\server\\test" == "\\\\server\\test"
Windows: normalise "//server/test" == "\\\\server\\test"
Windows: normalise "c:/file" == "C:\\file"
Windows: normalise "/file" == "\\file"
Windows: normalise "\\" == "\\"
Windows: normalise "/./" == "\\"
         normalise "." == "."
Posix:   normalise "./" == "./"
Posix:   normalise "./." == "./"
Posix:   normalise "/./" == "/"
Posix:   normalise "/" == "/"
Posix:   normalise "bob/fred/." == "bob/fred/"
Posix:   normalise "//home" == "/home"

The character that separates directories. In the case where more than one character is possible, pathSeparator is the 'ideal' one.

Windows: pathSeparator == '\\'
Posix:   pathSeparator ==  '/'
isPathSeparator pathSeparator

The list of all possible separators.

Windows: pathSeparators == ['\\', '/']
Posix:   pathSeparators == ['/']
pathSeparator `elem` pathSeparators

Set the base name.

replaceBaseName "/directory/other.ext" "file" == "/directory/file.ext"
replaceBaseName "file/test.txt" "bob" == "file/bob.txt"
replaceBaseName "fred" "bill" == "bill"
replaceBaseName "/dave/fred/bob.gz.tar" "new" == "/dave/fred/new.tar"
Valid x => replaceBaseName x (takeBaseName x) == x

Set the directory, keeping the filename the same.

replaceDirectory "root/file.ext" "/directory/" == "/directory/file.ext"
Valid x => replaceDirectory x (takeDirectory x) `equalFilePath` x

Set the extension of a file, overwriting one if already present, equivalent to -<.>.

replaceExtension "/directory/path.txt" "ext" == "/directory/path.ext"
replaceExtension "/directory/path.txt" ".ext" == "/directory/path.ext"
replaceExtension "file.txt" ".bob" == "file.bob"
replaceExtension "file.txt" "bob" == "file.bob"
replaceExtension "file" ".bob" == "file.bob"
replaceExtension "file.txt" "" == "file"
replaceExtension "file.fred.bob" "txt" == "file.fred.txt"
replaceExtension x y == addExtension (dropExtension x) y

Replace all extensions of a file with a new extension. Note that replaceExtension and addExtension both work for adding multiple extensions, so only required when you need to drop all extensions first.

replaceExtensions "file.fred.bob" "txt" == "file.txt"
replaceExtensions "file.fred.bob" "tar.gz" == "file.tar.gz"

Set the filename.

replaceFileName "/directory/other.txt" "file.ext" == "/directory/file.ext"
Valid x => replaceFileName x (takeFileName x) == x

The character that is used to separate the entries in the $PATH environment variable.

Windows: searchPathSeparator == ';'
Posix:   searchPathSeparator == ':'

Just as splitPath, but don't add the trailing slashes to each element.

         splitDirectories "/directory/file.ext" == ["/","directory","file.ext"]
         splitDirectories "test/file" == ["test","file"]
         splitDirectories "/test/file" == ["/","test","file"]
Windows: splitDirectories "C:\\test\\file" == ["C:\\", "test", "file"]
         Valid x => joinPath (splitDirectories x) `equalFilePath` x
         splitDirectories "" == []
Windows: splitDirectories "C:\\test\\\\\\file" == ["C:\\", "test", "file"]
         splitDirectories "/test///file" == ["/","test","file"]

Split a path into a drive and a path. On Posix, / is a Drive.

uncurry (<>) (splitDrive x) == x
Windows: splitDrive "file" == ("","file")
Windows: splitDrive "c:/file" == ("c:/","file")
Windows: splitDrive "c:\\file" == ("c:\\","file")
Windows: splitDrive "\\\\shared\\test" == ("\\\\shared\\","test")
Windows: splitDrive "\\\\shared" == ("\\\\shared","")
Windows: splitDrive "\\\\?\\UNC\\shared\\file" == ("\\\\?\\UNC\\shared\\","file")
Windows: splitDrive "\\\\?\\UNCshared\\file" == ("\\\\?\\","UNCshared\\file")
Windows: splitDrive "\\\\?\\d:\\file" == ("\\\\?\\d:\\","file")
Windows: splitDrive "/d" == ("","/d")
Posix:   splitDrive "/test" == ("/","test")
Posix:   splitDrive "//test" == ("//","test")
Posix:   splitDrive "test/file" == ("","test/file")
Posix:   splitDrive "file" == ("","file")

Split on the extension. addExtension is the inverse.

splitExtension "/directory/path.ext" == ("/directory/path",".ext")
uncurry (<>) (splitExtension x) == x
Valid x => uncurry addExtension (splitExtension x) == x
splitExtension "file.txt" == ("file",".txt")
splitExtension "file" == ("file","")
splitExtension "file/file.txt" == ("file/file",".txt")
splitExtension "file.txt/boris" == ("file.txt/boris","")
splitExtension "file.txt/boris.ext" == ("file.txt/boris",".ext")
splitExtension "file/path.txt.bob.fred" == ("file/path.txt.bob",".fred")
splitExtension "file/path.txt/" == ("file/path.txt/","")

Split on all extensions.

splitExtensions "/directory/path.ext" == ("/directory/path",".ext")
splitExtensions "file.tar.gz" == ("file",".tar.gz")
uncurry (<>) (splitExtensions x) == x
Valid x => uncurry addExtension (splitExtensions x) == x

Split a filename into directory and file. </> is the inverse. The first component will often end with a trailing slash.

splitFileName "/directory/file.ext" == ("/directory/","file.ext")
Valid x => uncurry (</>) (splitFileName x) == x || fst (splitFileName x) == "./"
Valid x => isValid (fst (splitFileName x))
splitFileName "file/bob.txt" == ("file/", "bob.txt")
splitFileName "file/" == ("file/", "")
splitFileName "bob" == ("./", "bob")
Posix:   splitFileName "/" == ("/","")
Windows: splitFileName "c:" == ("c:","")
Windows: splitFileName "\\\\?\\A:\\fred" == ("\\\\?\\A:\\","fred")
Windows: splitFileName "\\\\?\\A:" == ("\\\\?\\A:","")

Split a path by the directory separator.

splitPath "/directory/file.ext" == ["/","directory/","file.ext"]
concat (splitPath x) == x
splitPath "test//item/" == ["test//","item/"]
splitPath "test/item/file" == ["test/","item/","file"]
splitPath "" == []
Windows: splitPath "c:\\test\\path" == ["c:\\","test\\","path"]
Posix:   splitPath "/file/test" == ["/","file/","test"]

Take a string, split it on the searchPathSeparator character. Blank items are ignored on Windows, and converted to . on Posix. On Windows path elements are stripped of quotes.

Follows the recommendations in http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html

Posix:   splitSearchPath "File1:File2:File3"  == ["File1","File2","File3"]
Posix:   splitSearchPath "File1::File2:File3" == ["File1",".","File2","File3"]
Windows: splitSearchPath "File1;File2;File3"  == ["File1","File2","File3"]
Windows: splitSearchPath "File1;;File2;File3" == ["File1","File2","File3"]
Windows: splitSearchPath "File1;\"File2\";File3" == ["File1","File2","File3"]

Drop the given extension from a FilePath, and the "." preceding it. Returns Nothing if the FilePath does not have the given extension, or Just and the part before the extension if it does.

This function can be more predictable than dropExtensions, especially if the filename might itself contain . characters.

stripExtension "hs.o" "foo.x.hs.o" == Just "foo.x"
stripExtension "hi.o" "foo.x.hs.o" == Nothing
dropExtension x == fromJust (stripExtension (takeExtension x) x)
dropExtensions x == fromJust (stripExtension (takeExtensions x) x)
stripExtension ".c.d" "a.b.c.d"  == Just "a.b"
stripExtension ".c.d" "a.b..c.d" == Just "a.b."
stripExtension "baz"  "foo.bar"  == Nothing
stripExtension "bar"  "foobar"   == Nothing
stripExtension ""     x          == Just x

Get the base name, without an extension or path.

takeBaseName "/directory/file.ext" == "file"
takeBaseName "file/test.txt" == "test"
takeBaseName "dave.ext" == "dave"
takeBaseName "" == ""
takeBaseName "test" == "test"
takeBaseName (addTrailingPathSeparator x) == ""
takeBaseName "file/file.tar.gz" == "file.tar"

Get the directory name, move up one level.

          takeDirectory "/directory/other.ext" == "/directory"
          isPrefixOf (takeDirectory x) 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:\\"

Get the drive from a filepath.

takeDrive x == fst (splitDrive x)

Get the extension of a file, returns "" for no extension, .ext otherwise.

takeExtension "/directory/path.ext" == ".ext"
takeExtension x == snd (splitExtension x)
Valid x => takeExtension (addExtension x "ext") == ".ext"
Valid x => takeExtension (replaceExtension x "ext") == ".ext"

Get all extensions.

takeExtensions "/directory/path.ext" == ".ext"
takeExtensions "file.tar.gz" == ".tar.gz"

Get the file name.

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

(++) appends two lists, i.e.,

[x1, ..., xm] ++ [y1, ..., yn] == [x1, ..., xm, y1, ..., yn]
[x1, ..., xm] ++ [y1, ...] == [x1, ..., xm, y1, ...]

If the first list is not finite, the result is the first list.

Performance considerations

This function takes linear time in the number of elements of the first list. Thus it is better to associate repeated applications of (++) to the right (which is the default behaviour): xs ++ (ys ++ zs) or simply xs ++ ys ++ zs, but not (xs ++ ys) ++ zs. For the same reason GHC.Internal.Data.List.concat = GHC.Internal.Data.List.foldr (++) [] has linear performance, while GHC.Internal.Data.List.foldl (++) [] is prone to quadratic slowdown

Examples

>>> [1, 2, 3] ++ [4, 5, 6][1,2,3,4,5,6]

>>> [] ++ [1, 2, 3][1,2,3]

>>> [3, 2, 1] ++ [][3,2,1]

A variant of <*> with the types of the arguments reversed. It differs from flip (<*>) in that the effects are resolved in the order the arguments are presented.

Examples

>>> (<**>) (print 1) (id <$ print 2)12

>>> flip (<*>) (print 1) (id <$ print 2)21

>>> ZipList [4, 5, 6] <**> ZipList [(+1), (*2), (/3)]ZipList {getZipList = [5.0,10.0,2.0]}

Same as >>=, but with the arguments interchanged.

as >>= f == f =<< as

In many situations, the liftM operations can be replaced by uses of ap, which promotes function application.

return f `ap` x1 `ap` ... `ap` xn

is equivalent to

liftM<n> f x1 x2 ... xn

This function can be used to define `(*) = ap`, if Monad is already defined for a data type.

Examples

>>> pure (\x y z -> x + y * z) `ap` Just 1 `ap` Just 5 `ap` Just 10Just 51

The join function is the conventional monad join operator. It is used to remove one level of monadic structure, projecting its bound argument into the outer level.

'join bss' can be understood as the do expression

do bs <- bss
   bs

Examples

>>> join [[1, 2, 3], [4, 5, 6], [7, 8, 9]][1,2,3,4,5,6,7,8,9]

>>> join (Just (Just 3))Just 3

A common use of join is to run an IO computation returned from an GHC.Conc.STM transaction, since GHC.Conc.STM transactions can't perform IO directly. Recall that

GHC.Internal.Conc.atomically :: STM a -> IO a

is used to run GHC.Conc.STM transactions atomically. So, by specializing the types of GHC.Internal.Conc.atomically and join to

GHC.Internal.Conc.atomically :: STM (IO b) -> IO (IO b)
join       :: IO (IO b)  -> IO b

we can compose them as

join . GHC.Internal.Conc.atomically :: STM (IO b) -> IO b

to run an GHC.Conc.STM transaction and the IO action it returns.

Lift a function to actions. Equivalent to Functor's fmap but implemented using only Applicative's methods: liftA f a = pure f <*> a

As such this function may be used to implement a Functor instance from an Applicative one.

This function can be used to define `fmap = liftA`, if Applicative is already defined for a data type.

Examples

Using the Applicative instance for Lists:

>>> liftA (+1) [1, 2][2,3]

Or the Applicative instance for Maybe

>>> liftA (+1) (Just 3)Just 4

Lift a ternary function to actions.

Promote a function to a monad. This is equivalent to fmap but specialised to Monads.

This function can be used to define `fmap = liftM`, if Monad is already defined for a data type.

Promote a function to a monad, scanning the monadic arguments from left to right.

This function can be used to define `liftA2 = liftM2`, if Monad is already defined for a data type.

Examples

>>> liftM2 (+) [0,1] [0,2][0,2,1,3]

>>> liftM2 (+) (Just 1) NothingNothing

>>> liftM2 (+) (+ 3) (* 2) 518

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

Promote a function to a monad, scanning the monadic arguments from left to right (cf. liftM2).

\mathcal{O}(n). map f xs is the list obtained by applying f to each element of xs, i.e.,

map f [x1, x2, ..., xn] == [f x1, f x2, ..., f xn]
map f [x1, x2, ...] == [f x1, f x2, ...]

this means that map id == id

Examples

>>> map (+1) [1, 2, 3][2,3,4]

>>> map id [1, 2, 3][1,2,3]

>>> map (\n -> 3 * n + 1) [1, 2, 3][4,7,10]

The Prelude.fromEnum method restricted to the type Char.

Sequence two Applicative actions, discarding the result of the first one.

Defined as `thenA fa fb = (id fa) <* fb`.

This can be used to explicitly define `(*>) = thenA`, which is the default definition.

Sequence two monadic actions, discarding the result of the first one.

Defined as `thenM ma mb = ma >>= const mb`.

This can be used to define `(*>) = thenM`.

Conditional execution of Applicative expressions. For example,

Examples

when debug (putStrLn "Debugging")

will output the string Debugging if the Boolean value debug is True, and otherwise do nothing.

>>> putStr "pi:" >> when False (print 3.14159)pi:

The Prelude.toEnum method restricted to the type Char.

Like forkIO, this sparks off a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread.

However, forkOS creates a bound thread, which is necessary if you need to call foreign (non-Haskell) libraries that make use of thread-local state, such as OpenGL (see Control.Concurrent#boundthreads).

Using forkOS instead of forkIO makes no difference at all to the scheduling behaviour of the Haskell runtime system. It is a common misconception that you need to use forkOS instead of forkIO to avoid blocking all the Haskell threads when making a foreign call; this isn't the case. To allow foreign calls to be made without blocking all the Haskell threads (with GHC), it is only necessary to use the -threaded option when linking your program, and to make sure the foreign import is not marked unsafe.

Like forkIOWithUnmask, but the child thread is a bound thread, as with forkOS.

Returns True if the calling thread is bound, that is, if it is safe to use foreign libraries that rely on thread-local state from the calling thread.

True if bound threads are supported. If rtsSupportsBoundThreads is False, isCurrentThreadBound will always return False and both forkOS and runInBoundThread will fail.

Run the IO computation passed as the first argument. If the calling thread is not bound, a bound thread is created temporarily. runInBoundThread doesn't finish until the IO computation finishes.

You can wrap a series of foreign function calls that rely on thread-local state with runInBoundThread so that you can use them without knowing whether the current thread is bound.

Run the IO computation passed as the first argument. If the calling thread is bound, an unbound thread is created temporarily using forkIO. runInBoundThread doesn't finish until the IO computation finishes.

Use this function only in the rare case that you have actually observed a performance loss due to the use of bound threads. A program that doesn't need its main thread to be bound and makes heavy use of concurrency (e.g. a web server), might want to wrap its main action in runInUnboundThread.

Note that exceptions which are thrown to the current thread are thrown in turn to the thread that is executing the given computation. This ensures there's always a way of killing the forked thread.

Suspends the current thread for a given number of microseconds (GHC only).

There is no guarantee that the thread will be rescheduled promptly when the delay has expired, but the thread will never continue to run earlier than specified.

Be careful not to exceed maxBound :: Int, which on 32-bit machines is only 2147483647 μs, less than 36 minutes. Consider using Control.Concurrent.Thread.Delay.delay from unbounded-delays package.

Creates a new thread to run the IO computation passed as the first argument, and returns the ThreadId of the newly created thread.

The new thread will be a lightweight, unbound thread. Foreign calls made by this thread are not guaranteed to be made by any particular OS thread; if you need foreign calls to be made by a particular OS thread, then use forkOS instead.

The new thread inherits the masked state of the parent (see GHC.Control.Exception.mask).

The newly created thread has an exception handler that discards the exceptions BlockedIndefinitelyOnMVar, BlockedIndefinitelyOnSTM, and ThreadKilled, and passes all other exceptions to the uncaught exception handler.

WARNING: Exceptions in the new thread will not be rethrown in the thread that created it. This means that you might be completely unaware of the problem if/when this happens. You may want to use the async library instead.

Like forkIO, but the child thread is passed a function that can be used to unmask asynchronous exceptions. This function is typically used in the following way

 ... mask_ $ forkIOWithUnmask $ \unmask ->
                catch (unmask ...) handler

so that the exception handler in the child thread is established with asynchronous exceptions masked, meanwhile the main body of the child thread is executed in the unmasked state.

Note that the unmask function passed to the child thread should only be used in that thread; the behaviour is undefined if it is invoked in a different thread.

Like forkIO, but lets you specify on which capability the thread should run. Unlike a forkIO thread, a thread created by forkOn will stay on the same capability for its entire lifetime (forkIO threads can migrate between capabilities according to the scheduling policy). forkOn is useful for overriding the scheduling policy when you know in advance how best to distribute the threads.

The Int argument specifies a capability number (see getNumCapabilities). Typically capabilities correspond to physical processors, but the exact behaviour is implementation-dependent. The value passed to forkOn is interpreted modulo the total number of capabilities as returned by getNumCapabilities.

GHC note: the number of capabilities is specified by the +RTS -N option when the program is started. Capabilities can be fixed to actual processor cores with +RTS -qa if the underlying operating system supports that, although in practice this is usually unnecessary (and may actually degrade performance in some cases - experimentation is recommended).

Like forkIOWithUnmask, but the child thread is pinned to the given CPU, as with forkOn.

Returns the number of Haskell threads that can run truly simultaneously (on separate physical processors) at any given time. To change this value, use setNumCapabilities.

killThread raises the ThreadKilled exception in the given thread (GHC only).

killThread tid = throwTo tid ThreadKilled

labelThread stores a string as identifier for this thread. This identifier will be used in the debugging output to make distinction of different threads easier (otherwise you only have the thread state object's address in the heap). It also emits an event to the RTS eventlog.

Make a weak pointer to a ThreadId. It can be important to do this if you want to hold a reference to a ThreadId while still allowing the thread to receive the BlockedIndefinitely family of exceptions (e.g. BlockedIndefinitelyOnMVar). Holding a normal ThreadId reference will prevent the delivery of BlockedIndefinitely exceptions because the reference could be used as the target of throwTo at any time, which would unblock the thread.

Holding a Weak ThreadId, on the other hand, will not prevent the thread from receiving BlockedIndefinitely exceptions. It is still possible to throw an exception to a Weak ThreadId, but the caller must use deRefWeak first to determine whether the thread still exists.

Returns the ThreadId of the calling thread (GHC only).

Set the number of Haskell threads that can run truly simultaneously (on separate physical processors) at any given time. The number passed to forkOn is interpreted modulo this value. The initial value is given by the +RTS -N runtime flag.

This is also the number of threads that will participate in parallel garbage collection. It is strongly recommended that the number of capabilities is not set larger than the number of physical processor cores, and it may often be beneficial to leave one or more cores free to avoid contention with other processes in the machine.

Returns the number of the capability on which the thread is currently running, and a boolean indicating whether the thread is locked to that capability or not. A thread is locked to a capability if it was created with forkOn.

throwTo raises an arbitrary exception in the target thread (GHC only).

Exception delivery synchronizes between the source and target thread: throwTo does not return until the exception has been raised in the target thread. The calling thread can thus be certain that the target thread has received the exception. Exception delivery is also atomic with respect to other exceptions. Atomicity is a useful property to have when dealing with race conditions: e.g. if there are two threads that can kill each other, it is guaranteed that only one of the threads will get to kill the other.

Whatever work the target thread was doing when the exception was raised is not lost: the computation is suspended until required by another thread.

If the target thread is currently making a foreign call, then the exception will not be raised (and hence throwTo will not return) until the call has completed. This is the case regardless of whether the call is inside a mask or not. However, in GHC a foreign call can be annotated as interruptible, in which case a throwTo will cause the RTS to attempt to cause the call to return; see the GHC documentation for more details.

Important note: the behaviour of throwTo differs from that described in the paper "Asynchronous exceptions in Haskell" (http://research.microsoft.com/~simonpj/Papers/asynch-exns.htm). In the paper, throwTo is non-blocking; but the library implementation adopts a more synchronous design in which throwTo does not return until the exception is received by the target thread. The trade-off is discussed in Section 9 of the paper. Like any blocking operation, throwTo is therefore interruptible (see Section 5.3 of the paper). Unlike other interruptible operations, however, throwTo is always interruptible, even if it does not actually block.

There is no guarantee that the exception will be delivered promptly, although the runtime will endeavour to ensure that arbitrary delays don't occur. In GHC, an exception can only be raised when a thread reaches a safe point, where a safe point is where memory allocation occurs. Some loops do not perform any memory allocation inside the loop and therefore cannot be interrupted by a throwTo.

If the target of throwTo is the calling thread, then the behaviour is the same as throwIO, except that the exception is thrown as an asynchronous exception. This means that if there is an enclosing pure computation, which would be the case if the current IO operation is inside unsafePerformIO or unsafeInterleaveIO, that computation is not permanently replaced by the exception, but is suspended as if it had received an asynchronous exception.

Note that if throwTo is called with the current thread as the target, the exception will be thrown even if the thread is currently inside mask or uninterruptibleMask.

The yield action allows (forces, in a co-operative multitasking implementation) a context-switch to any other currently runnable threads (if any), and is occasionally useful when implementing concurrency abstractions.

Make a Weak pointer to an MVar, using the second argument as a finalizer to run when the MVar is garbage-collected

A slight variation on modifyMVar_ that allows a value to be returned (b) in addition to the modified value of the MVar.

Like modifyMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

Like modifyMVar_, but the IO action in the second argument is executed with asynchronous exceptions masked.

An exception-safe wrapper for modifying the contents of an MVar. Like withMVar, modifyMVar will replace the original contents of the MVar if an exception is raised during the operation. This function is only atomic if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time modifyMVar_ gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

Take a value from an MVar, put a new value into the MVar and return the value taken. This function is atomic only if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time swapMVar gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

withMVar is an exception-safe wrapper for operating on the contents of an MVar. This operation is exception-safe: it will replace the original contents of the MVar if an exception is raised (see Control.Exception). However, it is only atomic if there are no other producers for this MVar. In other words, it cannot guarantee that, by the time withMVar gets the chance to write to the MVar, the value of the MVar has not been altered by a write operation from another thread.

Like withMVar, but the IO action in the second argument is executed with asynchronous exceptions masked.

Strict version of <$>.

Right-to-left composition of Kleisli arrows. (>=>), with the arguments flipped.

Note how this operator resembles function composition (.):

(.)   ::            (b ->   c) -> (a ->   b) -> a ->   c
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> a -> m c

Left-to-right composition of Kleisli arrows.

'(bs >=> cs) a' can be understood as the do expression

do b <- bs a
   cs b

or in terms of (>>=) as

bs a >>= cs

This generalizes the list-based Data.List.filter function.

runIdentity (filterM (Identity . p) xs) == filter p xs

Examples

>>> filterM (\x -> do      putStrLn ("Keep: " ++ show x ++ "?")      answer <- getLine      pure (answer == "y"))    [1, 2, 3]Keep: 1?yKeep: 2?nKeep: 3?y[1,3]

>>> filterM (\x -> do      putStr (show x)      x' <- readLn      pure (x == x'))    [1, 2, 3]122233[2,3]

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

Like foldM, but discards the result.

Repeat an action indefinitely.

Examples

A common use of forever is to process input from network sockets, System.IO.Handles, and channels (e.g. MVar and Chan).

For example, here is how we might implement an echo server, using forever both to listen for client connections on a network socket and to echo client input on client connection handles:

echoServer :: Socket -> IO ()
echoServer socket = forever $ do
  client <- accept socket
  forkFinally (echo client) (\_ -> hClose client)
  where
    echo :: Handle -> IO ()
    echo client = forever $
      hGetLine client >>= hPutStrLn client

Note that "forever" isn't necessarily non-terminating. If the action is in a MonadPlus and short-circuits after some number of iterations. then forever actually returns mzero, effectively short-circuiting its caller.

Conditional failure of Alternative computations. Defined by

guard True  = pure ()
guard False = empty

Examples

Common uses of guard include conditionally signalling an error in an error monad and conditionally rejecting the current choice in an Alternative-based parser.

As an example of signalling an error in the error monad Maybe, consider a safe division function safeDiv x y that returns Nothing when the denominator y is zero and Just (x `div` y) otherwise. For example:

>>> safeDiv 4 0Nothing

>>> safeDiv 4 2Just 2

A definition of safeDiv using guards, but not guard:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y | y /= 0    = Just (x `div` y)
            | otherwise = Nothing

A definition of safeDiv using guard and Monad do-notation:

safeDiv :: Int -> Int -> Maybe Int
safeDiv x y = do
  guard (y /= 0)
  return (x `div` y)

The mapAndUnzipM function maps its first argument over a list, returning the result as a pair of lists. This function is mainly used with complicated data structures or a state monad.

Direct MonadPlus equivalent of Data.List.filter.

Examples

The Data.List.filter function is just mfilter specialized to the list monad:

Data.List.filter = ( mfilter :: (a -> Bool) -> [a] -> [a] )

An example using mfilter with the Maybe monad:

>>> mfilter odd (Just 1)Just 1>>> mfilter odd (Just 2)Nothing

replicateM n act performs the action act n times, and then returns the list of results.

replicateM n (pure x) == pure (replicate n x)

Examples

>>> replicateM 3 getLinehiheyahiya["hi","heya","hiya"]

>>> import Control.Monad.State>>> runState (replicateM 3 $ state $ \s -> (s, s + 1)) 1([1,2,3],4)

Like replicateM, but discards the result.

Examples

>>> replicateM_ 3 (putStr "a")aaa

The reverse of when.

Examples

>>> do x <- getLine       unless (x == "hi") (putStrLn "hi!")comingupwithexamplesisdifficulthi!

>>> unless (pi > exp 1) NothingJust ()

The zipWithM function generalizes zipWith to arbitrary applicative functors.

zipWithM_ is the extension of zipWithM which ignores the final result.

The implementation of mfix for IO.

This operation may fail with:

• FixIOException if the function passed to fixIO inspects its argument.

Examples

the IO-action is only executed once. The recursion is only on the values.

>>> take 3 <$> fixIO (\x -> putStr ":D" >> (:x) <$> readLn @Int):D2[2,2,2]

If we are strict in the value, just as with Data.Function.fix, we do not get termination:

>>> fixIO (\x -> putStr x >> pure ('x' : x))* hangs forever *

We can tie the knot of a structure within IO using fixIO:

data Node = MkNode Int (IORef Node)

foo :: IO ()
foo = do
  p <- fixIO (p -> newIORef (MkNode 0 p))
  q <- output p
  r <- output q
  _ <- output r
  pure ()

output :: IORef Node -> IO (IORef Node)
output ref = do
  MkNode x p <- readIORef ref
  print x
  pure p

>>> foo000

Case analysis for the Either type. If the value is Left a, apply the first function to a; if it is Right b, apply the second function to b.

Examples

We create two values of type Either String Int, one using the Left constructor and another using the Right constructor. Then we apply "either" the Prelude.length function (if we have a String) or the "times-two" function (if we have an Int):

>>> let s = Left "foo" :: Either String Int>>> let n = Right 3 :: Either String Int>>> either length (*2) s3>>> either length (*2) n6

Return the contents of a Left-value or a default value otherwise.

Examples

Basic usage:

>>> fromLeft 1 (Left 3)3>>> fromLeft 1 (Right "foo")1

Return the contents of a Right-value or a default value otherwise.

Examples

Basic usage:

>>> fromRight 1 (Right 3)3>>> fromRight 1 (Left "foo")1

Return True if the given value is a Left-value, False otherwise.

Examples

Basic usage:

>>> isLeft (Left "foo")True>>> isLeft (Right 3)False

Assuming a Left value signifies some sort of error, we can use isLeft to write a very simple error-reporting function that does absolutely nothing in the case of success, and outputs "ERROR" if any error occurred.

This example shows how isLeft might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )>>> let report e = when (isLeft e) $ putStrLn "ERROR">>> report (Right 1)>>> report (Left "parse error")ERROR

Return True if the given value is a Right-value, False otherwise.

Examples

Basic usage:

>>> isRight (Left "foo")False>>> isRight (Right 3)True

Assuming a Left value signifies some sort of error, we can use isRight to write a very simple reporting function that only outputs "SUCCESS" when a computation has succeeded.

This example shows how isRight might be used to avoid pattern matching when one does not care about the value contained in the constructor:

>>> import Control.Monad ( when )>>> let report e = when (isRight e) $ putStrLn "SUCCESS">>> report (Left "parse error")>>> report (Right 1)SUCCESS

Extracts from a list of Either all the Left elements. All the Left elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> lefts list["foo","bar","baz"]

Partitions a list of Either into two lists. All the Left elements are extracted, in order, to the first component of the output. Similarly the Right elements are extracted to the second component of the output.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list(["foo","bar","baz"],[3,7])

The pair returned by partitionEithers x should be the same pair as (lefts x, rights x):

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> partitionEithers list == (lefts list, rights list)True

Extracts from a list of Either all the Right elements. All the Right elements are extracted in order.

Examples

Basic usage:

>>> let list = [ Left "foo", Right 3, Left "bar", Right 7, Left "baz" ]>>> rights list[3,7]

Determines whether all elements of the structure satisfy the predicate.

Examples

Basic usage:

>>> all (> 3) []True

>>> all (> 3) [1,2]False

>>> all (> 3) [1,2,3,4,5]False

>>> all (> 3) [1..]False

>>> all (> 3) [4..]* Hangs forever *

and returns the conjunction of a container of Bools. For the result to be True, the container must be finite; False, however, results from a False value finitely far from the left end.

Examples

Basic usage:

>>> and []True

>>> and [True]True

>>> and [False]False

>>> and [True, True, False]False

>>> and (False : repeat True) -- Infinite list [False,True,True,True,...False

>>> and (repeat True)* Hangs forever *

Determines whether any element of the structure satisfies the predicate.

Examples

Basic usage:

>>> any (> 3) []False

>>> any (> 3) [1,2]False

>>> any (> 3) [1,2,3,4,5]True

>>> any (> 3) [1..]True

>>> any (> 3) [0, -1..]* Hangs forever *

The sum of a collection of actions using (<|>), generalizing concat.

asum is just like msum, but generalised to Alternative.

Examples

Basic usage:

>>> asum [Just "Hello", Nothing, Just "World"]Just "Hello"

The concatenation of all the elements of a container of lists.

Examples

Basic usage:

>>> concat (Just [1, 2, 3])[1,2,3]

>>> concat (Left 42)[]

>>> concat [[1, 2, 3], [4, 5], [6], []][1,2,3,4,5,6]

Map a function over all the elements of a container and concatenate the resulting lists.

Examples

Basic usage:

>>> concatMap (take 3) [[1..], [10..], [100..], [1000..]][1,2,3,10,11,12,100,101,102,1000,1001,1002]

>>> concatMap (take 3) (Just [1..])[1,2,3]

The find function takes a predicate and a structure and returns the leftmost element of the structure matching the predicate, or Nothing if there is no such element.

Examples

Basic usage:

>>> find (> 42) [0, 5..]Just 45

>>> find (> 12) [1..7]Nothing

forM_ is mapM_ with its arguments flipped. For a version that doesn't ignore the results see Data.Traversable.forM.

forM_ is just like for_, but specialised to monadic actions.

Map each element of a structure to a monadic action, evaluate these actions from left to right, and ignore the results. For a version that doesn't ignore the results see Data.Traversable.mapM.

mapM_ is just like traverse_, but specialised to monadic actions.

The largest element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple largest elements, the rightmost of them is chosen.

Examples

Basic usage:

>>> maximumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]"Longest"

WARNING: This function is partial for possibly-empty structures like lists.

The least element of a non-empty structure with respect to the given comparison function. Structure order is used as a tie-breaker: if there are multiple least elements, the leftmost of them is chosen.

Examples

Basic usage:

>>> minimumBy (compare `on` length) ["Hello", "World", "!", "Longest", "bar"]"!"

WARNING: This function is partial for possibly-empty structures like lists.

The sum of a collection of actions using (<|>), generalizing concat.

msum is just like asum, but specialised to MonadPlus.

Examples

Basic usage, using the MonadPlus instance for Maybe:

>>> msum [Just "Hello", Nothing, Just "World"]Just "Hello"

notElem is the negation of elem.

Examples

Basic usage:

>>> 3 `notElem` []True

>>> 3 `notElem` [1,2]True

>>> 3 `notElem` [1,2,3,4,5]False

For infinite structures, notElem terminates if the value exists at a finite distance from the left side of the structure:

>>> 3 `notElem` [1..]False

>>> 3 `notElem` ([4..] ++ [3])* Hangs forever *

or returns the disjunction of a container of Bools. For the result to be False, the container must be finite; True, however, results from a True value finitely far from the left end.

Examples

Basic usage:

>>> or []False

>>> or [True]True

>>> or [False]False

>>> or [True, True, False]True

>>> or (True : repeat False) -- Infinite list [True,False,False,False,...True

>>> or (repeat False)* Hangs forever *

Evaluate each monadic action in the structure from left to right, and ignore the results. For a version that doesn't ignore the results see Data.Traversable.sequence.

sequence_ is just like sequenceA_, but specialised to monadic actions.

Flipped version of <$.

Examples

Replace the contents of a Maybe Int with a constant String:

>>> Nothing $> "foo"Nothing

>>> Just 90210 $> "foo"Just "foo"

Replace the contents of an Either Int Int with a constant String, resulting in an Either Int String:

>>> Left 8675309 $> "foo"Left 8675309

>>> Right 8675309 $> "foo"Right "foo"

Replace each element of a list with a constant String:

>>> [1,2,3] $> "foo"["foo","foo","foo"]

Replace the second element of a pair with a constant String:

>>> (1,2) $> "foo"(1,"foo")

An infix synonym for fmap.

The name of this operator is an allusion to Prelude.$. Note the similarities between their types:

 ($)  ::              (a -> b) ->   a ->   b
(<$>) :: Functor f => (a -> b) -> f a -> f b

Whereas Prelude.$ is function application, <$> is function application lifted over a Functor.

Examples

Convert from a Maybe Int to a Maybe String using show:

>>> show <$> NothingNothing

>>> show <$> Just 3Just "3"

Convert from an Either Int Int to an Either Int String using show:

>>> show <$> Left 17Left 17

>>> show <$> Right 17Right "17"

Double each element of a list:

>>> (*2) <$> [1,2,3][2,4,6]

Apply even to the second element of a pair:

>>> even <$> (2,2)(2,True)