-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Haskell for Unix shell scripting tasks
--   
--   A Haskell-library for tasks which are usually done in shell scripts.
--   This includes parsing command line arguments; dealing with paths; some
--   commands for dealing with files; calling external programs and
--   subroutines as separate processes; pipes and redirection of input and
--   output; and error handling.
@package hsshellscript
@version 3.4.5

module HsShellScript.Paths

-- | Split a path in components. Repeated "<tt>/</tt>" characters don't
--   lead to empty components. "<tt>.</tt>" path components are removed. If
--   the path is absolute, the first component will start with
--   "<tt>/</tt>". "<tt>..</tt>" components are left intact. They can't be
--   simply removed, because the preceding component might be a symlink. In
--   this case, <tt>realpath</tt> is probably what you need.
--   
--   The case that the path is empty is treated like "<tt>.</tt>", yielding
--   an empty path components list.
--   
--   Examples:
--   
--   <pre>
--   slice_path "/"        = ["/"]
--   slice_path "/foo/bar" = ["/foo","bar"]
--   slice_path "..//./"   = [".."]
--   slice_path "."        = []
--   slice_path ""         = []
--   </pre>
--   
--   See <a>unslice_path</a>, <tt>realpath</tt>, <tt>realpath_s</tt>.
slice_path :: String -> [String]

-- | Form a path from path components. This isn't the inverse of
--   <a>slice_path</a>, since <tt><a>unslice_path</a> .
--   <a>slice_path</a></tt> normalises the path.
--   
--   <pre>
--   unslice_path [] = "."
--   unslice_path cs = concat (intersperse "/" cs)
--   </pre>
--   
--   See <a>slice_path</a>, <a>unsplit_parts</a>.
unslice_path :: [String] -> String

-- | Normalise a path. This is done by reducing repeated <tt>/</tt>
--   characters to one, and removing <tt>.</tt> path components.
--   <tt>..</tt> path components are left intact, because of possible
--   symlinks.
--   
--   Note that the normalised path isn't 100% equivalent to the original
--   one. Any trailing slash is removed. When the last path component is a
--   symbolic link, then both paths denote the same thing, except for in
--   the context of the <tt>readlink</tt> call. It will fail when the
--   trailing slash is present (because then the path denotes the directory
--   which the link points to), but it will succeed when it is absent.
--   
--   <pre>
--   normalise_path = unslice_path . slice_path
--   </pre>
--   
--   See <a>unslice_path</a>, <a>slice_path</a>.
normalise_path :: String -> String

-- | Split a file name in components. This are the base file name and the
--   suffixes, which are separated by dots. If the name starts with a dot,
--   it is regarded as part of the base name. The result is a list of file
--   name components. The filename may be a path. In this case, everything
--   up to the last path component will be returned as part of the base
--   file name. The path gets normalised thereby.
--   
--   No empty suffixes are returned. If the file name contains several
--   consecutive dots, they are regared as part of the preceding file name
--   component.
--   
--   Concateneting the name components and adding dots, reproduces the
--   original name, with a normalised path: <tt>concat . intersperse "." .
--   <a>slice_filename</a> == <tt>normalise</tt></tt>.
--   
--   Note that the last path component might be "<tt>..</tt>". Then it is
--   not possible to deduce the refered directory's name from the path. An
--   IO action for getting the real path is then necessary.
--   
--   Examples:
--   
--   <pre>
--   slice_filename "a.b//./.foo.tar.gz" = ["a.b/.foo","tar","gz"]
--   slice_filename ".x..y."             = [".x.", "y."]
--   </pre>
--   
--   See <a>unslice_filename</a>, <tt>slice_filename'</tt>.
slice_filename :: String -> [String]

-- | This is a variant of <a>slice_filename</a>. It is like
--   <a>slice_filename</a>, except for being more efficient, and the
--   filename must not contain any preceding path, since this case isn't
--   considered.
--   
--   See <a>slice_filename</a>, <a>unslice_filename</a>.
slice_filename' :: String -> [String]

-- | Form file name from file name components, interspersing dots. This is
--   the inverse of <a>slice_filename</a>, except for normalisation of any
--   path.
--   
--   <pre>
--   unslice_filename = concat . intersperse "."
--   </pre>
--   
--   See <a>slice_filename</a>.
unslice_filename :: [String] -> String

-- | Split a path in directory and file name. Only in the case that the
--   supplied path is empty, both parts are empty strings. Otherwise,
--   <tt>"."</tt> is filled in for the corresponding part, if necessary.
--   Unless the path is empty, concatenating the returned path and file
--   name components with a slash in between, makes a valid path to the
--   file.
--   
--   <tt>split_path</tt> splits off the last path component. This isn't the
--   same as the text after the last <tt>/</tt>.
--   
--   Note that the last path component might be <tt>".."</tt>. Then it is
--   not possible to deduce the refered directory's name from the path.
--   Then an IO action for getting the real path is necessary.
--   
--   Examples:
--   
--   <pre>
--   split_path "/a/b/c"      == ("/a/b", "c")
--   split_path "foo"         == (".", "foo")
--   split_path "foo/bar"     == ("foo", "bar")
--   split_path "foo/.."      == ("foo", "..")
--   split_path "."           == (".", ".")
--   split_path ""            == ("", "")
--   split_path "/foo"        == ("/", "foo")
--   split_path "foo/"        == (".", "foo")
--   split_path "foo/."       == (".", "foo")
--   split_path "foo///./bar" == ("foo", "bar")
--   split_path "/"           == ("/", ".")
--   </pre>
--   
--   See <a>slice_path</a>.
split_path :: String -> (String, String)

-- | Get the directory part of a path.
--   
--   <pre>
--   dir_part = fst . split_path
--   </pre>
--   
--   See <a>split_path</a>.
dir_part :: String -> String

-- | Get the last path component of a path.
--   
--   <pre>
--   filename_part = snd . split_path
--   </pre>
--   
--   Examples:
--   
--   <pre>
--   filename_part "foo/bar" == "bar"
--   filename_part "."       == "."
--   </pre>
--   
--   See <a>split_path</a>.
filename_part :: String -> String

-- | Inverse of <a>split_path</a>, except for normalisation.
--   
--   This forms a path from two parts, and takes care of <tt>"."</tt> and
--   empty parts. When the two components are in normalised form, then
--   <tt>unsplit_path</tt> creates a normalised path.
--   
--   The definition:
--   
--   <pre>
--   unsplit_path ("", "") = ""
--   unsplit_path (p, q)   = unsplit_parts [p, q]
--   </pre>
--   
--   Examples:
--   
--   <pre>
--   unsplit_path ("", "")     == ""
--   unsplit_path (".", "")    == "."
--   unsplit_path (".", ".")   == "."
--   unsplit_path ("foo", ".") == "foo"
--   </pre>
--   
--   See <a>split_path</a>, <a>slice_path</a>, <a>unsplit_parts</a>.
unsplit_path :: (String, String) -> String

-- | Concatenate a list of path parts. The idea is that you can throw in
--   reasonably formed parts, and get a reasonably formed version of the
--   concatenated path out.
--   
--   <tt>"."</tt> parts are removed. Empty parts are treated as
--   <tt>"."</tt> parts. One leading slash in each of any but the first
--   part is removed. The result is then interspersed with slashes and
--   string wise concatenated. The interior of the parts isn't examined.
--   <tt>".."</tt> components aren't treated specially.
--   
--   Examples:
--   
--   <pre>
--   unsplit_parts []                       == "."
--   unsplit_parts [""]                     == "."
--   unsplit_parts ["/"]                    == "/"
--   unsplit_parts ["/", "foo"]             == "/foo"
--   unsplit_parts ["", "/foo"]             == "foo"
--   unsplit_parts ["/foo", "bar"]          == "/foo/bar"
--   unsplit_parts ["/foo", "/bar"]         == "/foo/bar"
--   unsplit_parts ["foo/", "bar"]          == "foo//bar"
--   unsplit_parts ["foo", "", ".", "bar"]  == "foo/bar"
--   unsplit_parts ["foo", "bar//./baz/"]   == "foo/bar//./baz/"
--   </pre>
--   
--   See <a>unsplit_path</a>, <a>unslice_path</a>, <a>split_path</a>.
unsplit_parts :: [String] -> String

-- | Split a file name in prefix and suffix. If there isn't any suffix in
--   the file name, then return an empty suffix. A dot at the beginning or
--   at the end is not regarded as introducing a suffix.
--   
--   The last path component is what is being split. This isn't the same as
--   splitting the string at the last dot. For instance, if the file name
--   doesn't contain any dot, dots in previous path component's aren't
--   mistaken as introducing suffixes.
--   
--   The path part is returned in normalised form. This means, <tt>"."</tt>
--   components are removed, and multiple "<tt>/</tt>"s are reduced to one.
--   
--   Note that there isn't any plausibility check performed on the suffix.
--   If the file name doesn't have a suffix, but happens to contain a dot,
--   then this dot is mistaken as introducing a suffix.
--   
--   Examples:
--   
--   <pre>
--   split_filename "path/to/foo.bar"                             = ("path/to/foo","bar")
--   split_filename "path/to/foo"                                 = ("path/to/foo","")
--   split_filename "/path.to/foo"                                = ("/path.to/foo","")
--   split_filename "a///./x"                                     = ("a/x","")
--   split_filename "dir.suffix/./"                               = ("dir","suffix")
--   split_filename "Photographie, Das 20. Jahrhundert (300 dpi)" = ("Photographie, Das 20", " Jahrhundert (300 dpi)")
--   </pre>
--   
--   See <a>slice_path</a>, 'split_filename\''
split_filename :: String -> (String, String)

-- | Variant of <a>split_filename</a>. This is a more efficient version of
--   <a>split_filename</a>, for the case that you know the string is is a
--   pure file name without any slashes.
--   
--   See <a>split_filename</a>.
split_filename' :: String -> (String, String)

-- | Inverse of <a>split_filename</a>. Concatenate prefix and suffix,
--   adding a dot in between, iff the suffix is not empty. The path part of
--   the prefix is normalised.
--   
--   See <a>split_filename</a>.
unsplit_filename :: (String, String) -> String

-- | Split a path in directory, base file name and suffix.
split3 :: String -> (String, String, String)

-- | Form path from directory, base file name and suffix parts.
unsplit3 :: (String, String, String) -> String

-- | Test a path for a specific suffix and split it off.
--   
--   If the path ends with the suffix, then the result is <tt>Just
--   prefix</tt>, where <tt>prefix</tt> is the normalised path without the
--   suffix. Otherwise it's <tt>Nothing</tt>.
test_suffix :: String -> String -> Maybe String

-- | Make a path absolute, using the current working directory.
--   
--   This makes a relative path absolute with respect to the current
--   working directory. An absolute path is returned unmodified.
--   
--   The current working directory is determined with
--   <tt>getCurrentDirectory</tt> which means that symbolic links in it are
--   expanded and the path is normalised. This is different from
--   <tt>pwd</tt>.
absolute_path :: String -> IO String

-- | Make a path absolute.
--   
--   This makes a relative path absolute with respect to a specified
--   directory. An absolute path is returned unmodified.
--   
--   The directory must be an absolute path.
--   
--   <pre>
--   absolute_path_by absdir path@('/':p) = path
--   absolute_path_by absdir path = absdir ++ "/" ++ path
--   </pre>
absolute_path_by :: String -> String -> String

-- | Make a path absolute.
--   
--   This makes a relative path absolute with respect to a specified
--   directory. An absolute path is returned unmodified.
--   
--   The order of the arguments can be confusing. You should rather use
--   <a>absolute_path_by</a>. <tt>absolute_path'</tt> is included for
--   backwards compatibility.
absolute_path' :: String -> String -> String

-- | Guess the <tt>".."</tt>-component free form of a path, specified as a
--   list of path components, by syntactically removing them, along with
--   the preceding path components. This will produce erroneous results
--   when the path contains symlinks. If the path contains leading
--   <tt>".."</tt> components, or more <tt>".."</tt> components than
--   preceeding normal components, then the <tt>".."</tt> components can't
--   be normalised away. In this case, the result is <tt>Nothing</tt>.
guess_dotdot_comps :: [String] -> Maybe [String]

-- | Guess the <tt>".."</tt>-component free, normalised form of a path. The
--   transformation is purely syntactic. <tt>".."</tt> path components will
--   be removed, along with their preceding path components. This will
--   produce erroneous results when the path contains symlinks. If the path
--   contains leading <tt>".."</tt> components, or more <tt>".."</tt>
--   components than preceeding normal components, then the <tt>".."</tt>
--   components can't be normalised away. In this case, the result is
--   <tt>Nothing</tt>.
--   
--   <pre>
--   guess_dotdot = fmap unslice_path . guess_dotdot_comps . slice_path
--   </pre>
--   
--   <pre>
--   guess_dotdot "foo/../bar"    = Just "bar"
--   guess_dotdot "foo/..//bar/." = Just "bar"
--   guess_dotdot "foo/../../bar" = Nothing
--   guess_dotdot "../bar" = Nothing
--   </pre>
guess_dotdot :: String -> Maybe String

module HsShellScript.Shell

-- | Generate command (for a shell) which corresponds to the specified
--   program name and argument list. The program name and arguments are the
--   usual parameters for calling an external program, like when using
--   <tt>runProcess</tt> or <tt>run</tt>. The generated shell command would
--   achieve the same effect. The name and the arguments are properly
--   quoted, using <a>shell_quote</a>.
--   
--   Note: The quoted strings are correctly recognized in shell scripts.
--   But the shell bash has an annoying history expansion "feature", which
--   causes it to choke on exclamation marks, when in interactive mode,
--   even when quoted with double quotes. You can turn it off with <tt>set
--   +o histexpand</tt>.
shell_command :: String -> [String] -> String

-- | Quote shell metacharacters.
--   
--   This function quotes strings, such that they are not misinterpreted by
--   the shell. It tries to be friendly to a human reader - when special
--   characters are present, then the string is quoted with double quotes.
--   If not, it is left unchanged.
--   
--   The list of exacly which characters need to be quoted has been taken
--   from the bash source code. Bash in turn, implements POSIX 1003.2. So
--   the result produced should be correct. From the bash info pages: "...
--   the rules for evaluation and quoting are taken from the POSIX 1003.2
--   specification for the <tt>standard</tt> Unix shell."
--   
--   Note: The quoted strings are correctly recognized in shell scripts.
--   But the shell bash has an annoying history expansion "feature", which
--   causes it to choke on exclamation marks, when in interactive mode,
--   even when quoted with double quotes. You can turn it off with <tt>set
--   +o histexpand</tt>.
--   
--   See <a>quote</a>.
shell_quote :: String -> String

-- | Quote special characters inside a string for the shell
--   
--   This quotes special characters inside a string, such that it is
--   recognized as one string by the shell when enclosed in double quotes.
--   Doesn't add the double quotes.
--   
--   Note: The quoted strings are correctly recognized in shell scripts.
--   But the shell bash has an annoying history expansion "feature", which
--   causes it to choke on exclamation marks, when in interactive mode,
--   even when quoted with double quotes. You can turn it off with <tt>set
--   +o histexpand</tt>.
--   
--   See <a>quote</a>, <a>shell_quote</a>.
quote0 :: String -> String

-- | Quote a string for the shell
--   
--   This encloses a string in double quotes and quotes any special
--   characters inside, such that it will be recognized as one string by a
--   shell. The double quotes are added even when they aren't needed for
--   this purpose.
--   
--   Note: The quoted strings are correctly recognized in shell scripts.
--   But the shell bash has an annoying history expansion "feature", which
--   causes it to choke on exclamation marks, when in interactive mode,
--   even when quoted with double quotes. You can turn it off with <tt>set
--   +o histexpand</tt>.
--   
--   See <a>quote0</a>, <a>shell_quote</a>.
quote :: String -> String


-- | This module provides a more convient way of parsing command line
--   arguments than the GHC GetOpt package. It uses GetOpt, but hides it
--   from the user. It is reexported from module HsShellScript.
--   
--   For each command line argument, a description is to be created with
--   <tt>argdesc</tt>. Then the command line arguments are evaluated with
--   one of the <tt>getargs</tt>... functions. In case of an error, this
--   will cause a exception, which provides an expressive error message to
--   be printed. Then the <tt>arg</tt>... functions are used to extract the
--   values contained in the arguments, with the right type. The typical
--   use of HsShellScript.Args looks something like this:
--   
--   <pre>
--   import HsShellScript
--   import Control.Exception
--   import Control.Monad
--   import System.Environment
--   import System.Exit
--   import System.IO
--   
--   header = "mclapep - My Command Line Argument Parser Example Program, version 1.0.0\n\n"
--   descs  = [d_onevalue, d_values, d_switch {-...-}]
--   
--   d_onevalue = argdesc [ desc_short 'o', desc_at_most_once, desc_argname "a", desc_value_required {-...-}]
--   d_values   = argdesc [ desc_direct, desc_any_times {-...-} ]
--   d_switch   = argdesc [ desc_long "doit", desc_at_most_once {-...-} ] 
--   -- ...
--   
--   args = unsafe_getargs header descs
--   val  = optarg_req args d_onevalue        -- val  :: Maybe String
--   vals = args_req   args d_values          -- vals :: [String]
--   doit = arg_switch args d_switch          -- doit :: Bool
--   -- ...
--   
--   main = mainwrapper $ do
--      args0 &lt;- getArgs
--      when (null args0) $ do
--         -- No command line arguments - print usage information
--         print_usage_info stdout header descs
--         exitWith ExitSuccess
--      -- trigger argument errors
--      seq args (return ())
--   
--      -- Do something with the arguments
--   </pre>
--   
--   Errors in the argument descriptions are regarded as bugs, and handled
--   by aborting the program with a message which is meaningful to the
--   programmer. It is assumed that the argument description is a constant
--   for a given program.
--   
--   Errors in the arguments are reported using HsShellScript's error
--   handling scheme. An error description value is generated, and either
--   returned via an <tt>Either</tt> value, or thrown as an exception.
module HsShellScript.Args

-- | A property of a command line argument. These are generated by the
--   <tt>desc_</tt>... functions, and condensed to argument descriptions of
--   type <tt>ArgumentDescription</tt> by <tt>argdesc</tt>. This type is
--   abstract.
newtype ArgumentProperty
ArgumentProperty :: (ArgumentDescription -> ArgumentDescription) -> ArgumentProperty
[argumentproperty] :: ArgumentProperty -> ArgumentDescription -> ArgumentDescription

-- | Description of one command line argument. These are generated by
--   <tt>argdesc</tt> from a list of argument properties, and subsequently
--   used by one of the <tt>getargs</tt>... functions.
data ArgumentDescription
ArgumentDescription :: [Char] -> [String] -> ArgumentValueSpec -> Maybe (Int, Int) -> Maybe String -> Maybe String -> Maybe Argtester -> ArgumentDescription

-- | Short option names
[argdesc_short_args] :: ArgumentDescription -> [Char]

-- | Long option names
[argdesc_long_args] :: ArgumentDescription -> [String]

-- | What about a possible value of the argument?
[argdesc_argarg] :: ArgumentDescription -> ArgumentValueSpec

-- | Minimum and maximum of number of occurences allowed
[argdesc_times] :: ArgumentDescription -> Maybe (Int, Int)

-- | Name for argument's value, for message generation
[argdesc_argargname] :: ArgumentDescription -> Maybe String

-- | Descrition of the argument, for message generation
[argdesc_description] :: ArgumentDescription -> Maybe String

-- | Argument value tester
[argdesc_argarg_tester] :: ArgumentDescription -> Maybe Argtester

-- | Does the command line argument take an value?
data ArgumentValueSpec

-- | No value
ArgumentValue_none :: ArgumentValueSpec

-- | Value required
ArgumentValue_required :: ArgumentValueSpec

-- | Value optional
ArgumentValue_optional :: ArgumentValueSpec

-- | Argument value tester function. This tests the format of an argument's
--   value for errors. The tester function is specified by
--   <a>desc_tester</a> or such, as part of the argument description.
--   
--   The tester is passed the argument value. If the format is correct,
--   then it returns <tt>Nothing</tt>. If there is an error, then it
--   returns <tt>Just msgf</tt>, with <tt>msgf</tt> being an error message
--   generation function. This function gets passed the argument
--   description, and produces the error message. The argument description
--   typically is used to extract a descriptive name of the argument (using
--   <a>argname</a> or <a>argname_a</a>) to be included in the error
--   message.
type Argtester = String -> Maybe (ArgumentDescription -> String)

-- | Make an argument description from a list of argument properties. This
--   condenses the list to an argument description, which can be used by
--   the <tt>getargs</tt>... functions and the argument value extraction
--   functions.
argdesc :: [ArgumentProperty] -> ArgumentDescription

-- | Short name of the argument. This specifies a character for a one
--   letter style argument, like <tt>-x</tt>. There can be specified
--   several for the same argument. Each argument needs at least either a
--   short or a long name.
desc_short :: Char -> ArgumentProperty

-- | Long name of the argument. This specifies a GNU style long name for
--   the argument, which is introduced by two dashes, like <tt>--arg</tt>
--   or <tt>--arg=...</tt>. There can be specified several names for the
--   same argument. Each argument needs at least either a short or a long
--   name. Except for direct arguments, which don't have a name.
--   
--   See <a>desc_direct</a>
desc_long :: String -> ArgumentProperty

-- | Signal that this is the description of direct arguments. Direct
--   arguments are the ones not introduced by any short or long argument
--   names (like <tt>-x</tt> or <tt>--arg</tt>). After the special argument
--   <tt>--</tt>, also everything is a direct argument, even when starting
--   with <tt>-</tt> or <tt>--</tt>. The presence of <tt>desc_direct</tt>
--   in the argument properties list signals <tt>argdesc</tt> that this is
--   the description of the direct arguments. There may be at most one such
--   description.
--   
--   The <tt>is_direct</tt> function can be used in order to determine if a
--   specific argument is the direct argument.
--   
--   See <a>is_direct</a>.
desc_direct :: ArgumentProperty

-- | Signal that the argument requires a value.
desc_value_required :: ArgumentProperty

-- | Signal that the argument optionally has a value. The user may or may
--   not specify a value to this argument.
desc_value_optional :: ArgumentProperty

-- | Specify lower and upper bound on the number of times an argument may
--   occur.
desc_times :: Int -> Int -> ArgumentProperty

-- | Signal that the argument must be present exactly once. This is
--   meaningful only for arguments which can take a value.
desc_once :: ArgumentProperty

-- | Signal that the argument must occur at least one time.
desc_at_least_once :: ArgumentProperty

-- | Signal that the argument must occur at most one time.
desc_at_most_once :: ArgumentProperty

-- | Signal that the argument may occur any number of times.
desc_any_times :: ArgumentProperty

-- | Signal that the argument must have at least the specified number of
--   occurences, and has no upper limit of occurences.
desc_at_least :: Int -> ArgumentProperty

-- | Signal that the argument does not need to be present, and may occur at
--   most the specified number of times.
desc_at_most :: Int -> ArgumentProperty

-- | Specify the descriptive name for command line argument's value. Used
--   for the generation of the usage message. The name should be very
--   short.
desc_argname :: String -> ArgumentProperty

-- | Specify a description of what the argument does. Used for usage
--   message generation. This can be arbitratily long, long lines are
--   wrapped.
desc_description :: String -> ArgumentProperty

-- | Specify a tester for this argument. The tester is a function which
--   tests the argument value for format errors. Typically, it tests
--   whether the value can be parsed to some target type. If the test
--   fails, the tester produces an error message. When parsing the command
--   line arguments (which <tt>getargs</tt> or related), all the testers
--   are applied to the respective argument values, and an <a>ArgError</a>
--   is thrown in case of failure. By using a tester, it can be ensured
--   that the argument values abide a specific format when extracting them,
--   such that they can be parsed without errors, e.g. <tt>myarg = read
--   (reqarg_req args d_myarg)</tt>.
--   
--   An argument tester is a function of type <a>Argtester</a>.
--   
--   See <a>readtester</a>, <a>desc_integer</a>,
--   <a>desc_nonneg_integer</a>, <a>Argtester</a>.
desc_tester :: Argtester -> ArgumentProperty

-- | Specify that the value of this argument, if present, is a positive
--   integer. This will cause an error when the command line is parsed, and
--   the argument's value doesn't specify an integer.
--   
--   <pre>
--   desc_integer = desc_tester (readtester (reads :: ReadS Int) "Integer expected.")
--   </pre>
--   
--   See <a>desc_tester</a>.
desc_integer :: ArgumentProperty

-- | Specify that the value of this argument, if present, is a non-negative
--   integer. This will cause an error when the command line is parsed, and
--   the value doesn't specify a non-negative integer.
--   
--   <pre>
--   desc_nonneg_integer = desc_tester (readtester ((filter (\(a,_) -&gt; a &gt;= 0) . reads) :: ReadS Int) "Non-negative integer expected." )
--   </pre>
--   
--   See <a>desc_tester</a>.
desc_nonneg_integer :: ArgumentProperty

-- | Build an argument tester from a <tt>reads</tt> like function.
--   Typically, a specialisation of the standard prelude function
--   <tt>read</tt> is used. Example: <tt>readtester "Integer expected."
--   (reads :: ReadS Int)</tt>
readtester :: ReadS a -> String -> Argtester

-- | Whether the specified argument is the direct argument. Direct
--   arguments are the ones which are specified without introducing "-" or
--   "--", in the command line, or which occur after the special argument
--   "--".
--   
--   See <a>argdesc</a>, <a>desc_direct</a>.
is_direct :: ArgumentDescription -> Bool

-- | This represents the parsed contents of the command line. It is
--   returned by the <tt>getargs</tt>... functions, and passed on to the
--   value extraction functions by the user.
--   
--   See <a>getargs</a>, <a>getargs_ordered</a>, 'getargs\'',
--   'getargs_ordered\''.
data Arguments

-- | Parse command line arguments. The arguments are taken from a call to
--   <tt>getArgs</tt> and parsed. Any error is thrown as a
--   <tt>ArgError</tt> exception. The result is a value from which the
--   information in the command line can be extracted by the
--   <tt>arg</tt>..., <tt>reqarg</tt>... and <tt>optarg</tt>... functions.
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   Named arguments (like <tt>-x</tt> or <tt>--arg</tt>) and direct
--   arguments may occur in any order.
--   
--   See <a>usage_info</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>.
getargs :: String -> [ArgumentDescription] -> IO Arguments

-- | Parse command line arguments. The arguments are taken from a call to
--   <tt>getArgs</tt> and parsed. Any error is thrown as a
--   <tt>ArgError</tt> exception. The result is a value from which the
--   information in the command line can be extracted by the
--   <tt>arg</tt>..., <tt>reqarg</tt>... and <tt>optarg</tt>... functions.
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   All arguments after the first direct argument are regarded as direct
--   arguments. This means that argument names introduced by <tt>-</tt> or
--   <tt>--</tt> no longer take effect.
--   
--   See <a>usage_info</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>.
getargs_ordered :: String -> [ArgumentDescription] -> IO Arguments

-- | Parse the specified command line. Any error is returned as <tt>Left
--   argerror</tt>. In case of success, the result is returned as <tt>Right
--   res</tt>. From the result, the information in the command line can be
--   extracted by the <tt>arg</tt>..., <tt>reqarg</tt>... and
--   <tt>optarg</tt>... functions.
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   Named arguments (like <tt>-x</tt> or <tt>--arg</tt>) and direct
--   arguments may occur in any order.
--   
--   See <a>usage_info</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>.
getargs' :: String -> [String] -> [ArgumentDescription] -> Either ArgError Arguments

-- | Parse the specified command line. Any error is returned as <tt>Left
--   argerror</tt>. In case of success, the result is returned as <tt>Right
--   res</tt>. From the result, the information in the command line can be
--   extracted by the <tt>arg</tt>..., <tt>reqarg</tt>... and
--   <tt>optarg</tt>... functions.
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   All arguments after the first direct argument are regarded as direct
--   arguments. This means that argument names introduced by <tt>-</tt> or
--   <tt>--</tt> no longer take effect.
--   
--   See <a>usage_info</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>.
getargs_ordered' :: String -> [String] -> [ArgumentDescription] -> Either ArgError Arguments

-- | <tt>getargs</tt> as a pure function, instead of an IO action. This
--   allows to make evaluated command line arguments global values. This
--   calls <tt>getargs</tt> to parse the command line arguments.
--   <tt>GHC.IO.unsafePerformIO</tt> is used to take the result out of the
--   IO monad.
--   
--   <pre>
--   unsafe_getargs header descs = GHC.IO.unsafePerformIO $ getargs "" descs
--   </pre>
--   
--   The <tt>getargs</tt> action is performed on demand, when the parse
--   result is evaluated. It may result in an <a>ArgError</a> being thrown.
--   In order to avoid this happening at unexpected times, the
--   <tt>main</tt> function should, start with the line <tt>seq args
--   (return ())</tt>, where <tt>args</tt> is the result of
--   <tt>unsafe_getargs</tt>,. This will trigger any command line argument
--   errors at the beginning of the program. (See section 6.2 of the Hakell
--   Report for the definition of <tt>seq</tt>).
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   A typical use of <tt>unsafe_getargs</tt> looks like this:
--   
--   <pre>
--   descs = [ d_myflag, ... ]
--   
--   d_myflag = argdesc [ ... ]
--   
--   args = unsafe_getargs "" descs
--   myflag = arg_switch args d_myflag
--   
--   main = mainwrapper $ do
--      seq args (return ())
--      ...
--   </pre>
--   
--   See <a>getargs</a>, <a>unsafe_getargs_ordered</a>.
unsafe_getargs :: String -> [ArgumentDescription] -> Arguments

-- | <tt>getargs_ordered</tt> as a pure function, instead of an IO action.
--   This is exactly like <tt>unsafe_getargs</tt>, but using
--   <tt>getargs_ordered</tt> instead of <tt>getargs</tt>.
--   
--   The header is used only by the deprecated <tt>usage_info</tt>
--   function. If you don't use it, you don't need to specify a header.
--   Just pass an empty string.
--   
--   The definition is:
--   
--   <pre>
--   unsafe_getargs_ordered = GHC.IO.unsafePerformIO $ getargs_ordered "" descs
--   </pre>
--   
--   See <a>unsafe_getargs</a>, <a>usage_info</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>.
unsafe_getargs_ordered :: String -> [ArgumentDescription] -> Arguments

-- | Query whether a certain switch is specified on the command line. A
--   switch is an argument which is allowed zero or one time, and has no
--   value.
arg_switch :: Arguments -> ArgumentDescription -> Bool

-- | Query the number of occurences of an argument.
arg_times :: Arguments -> ArgumentDescription -> Int

-- | Query the values of an argument with optional value. This is for
--   arguments which take an optional value, and may occur several times.
--   The occurences with value are represented as <tt>Just value</tt>, the
--   occurences without are represented as <tt>Nothing</tt>.
args_opt :: Arguments -> ArgumentDescription -> [Maybe String]

-- | Query the values of an argument with required value. This is for
--   arguments which require a value, and may occur several times.
args_req :: Arguments -> ArgumentDescription -> [String]

-- | Query the optional value of a required argument. This is for arguments
--   which must occur once, and may have a value. If the argument is
--   specified, its value is returned as <tt>Just value</tt>. If it isn't,
--   the result is <tt>Nothing</tt>.
reqarg_opt :: Arguments -> ArgumentDescription -> Maybe String

-- | Query the value of a required argument. This is for arguments which
--   must occur exactly once, and require a value.
reqarg_req :: Arguments -> ArgumentDescription -> String

-- | Query the optional value of an optional argument. This is for
--   arguments which may occur zero or one time, and which may or may not
--   have a value. If the argument doesn't occur, the result is
--   <tt>Nothing</tt>. If it does occur, but has no value, then the result
--   is <tt>Just Nothing</tt>. If it does occur with value, the result is
--   <tt>Just (Just value)</tt>.
optarg_opt :: Arguments -> ArgumentDescription -> Maybe (Maybe String)

-- | Query the value of an optional argument. This is for optional
--   arguments which require a value, and may occur at most once. The
--   result is <tt>Just value</tt> if the argument occurs, and
--   <tt>Nothing</tt> if it doesn't occur.
optarg_req :: Arguments -> ArgumentDescription -> Maybe String

-- | Whether the specified argument occurs in the command line.
arg_occurs :: Arguments -> ArgumentDescription -> Bool

-- | None of the specifed arguments may be present.
--   
--   Throws an ArgError if any of the arguments are present.
args_none :: [ArgumentDescription] -> Arguments -> IO ()

-- | All of the specified arguments must be present.
--   
--   Throws an ArgError if any is missing.
args_all :: [ArgumentDescription] -> Arguments -> IO ()

-- | Exactly one of the specified arguments must be present.
--   
--   Otherwise throw an ArgError.
args_one :: [ArgumentDescription] -> Arguments -> IO ()

-- | At most one of the specified arguments may be present.
--   
--   Otherwise throw an ArgError.
args_at_most_one :: [ArgumentDescription] -> Arguments -> IO ()

-- | At least one of the specified arguments must be present.
--   
--   Otherwise throw an ArgError.
args_at_least_one :: [ArgumentDescription] -> Arguments -> IO ()

-- | When the specified argument is present, then none of the other
--   arguments may be present.
--   
--   Otherwise throw an ArgError.
arg_conflicts :: ArgumentDescription -> [ArgumentDescription] -> Arguments -> IO ()

-- | Error thrown when there is an error in the command line arguments.
--   
--   The usage information is generated by the deprecated function
--   usage_info. Better ignore this, and use the newer
--   <tt>make_usage_info</tt> or <tt>print_usage_info</tt>.
--   
--   See <a>make_usage_info</a>, <a>print_usage_info</a>,
--   <a>usage_info</a>.
data ArgError
ArgError :: String -> String -> ArgError

-- | Error message
[argerror_message] :: ArgError -> String

-- | Deprecated. Usage information, as generated by the now deprecated
--   function <a>usage_info</a>.
[argerror_usageinfo] :: ArgError -> String

-- | <i>Deprecated</i>. This is left here for backwards compatibility. New
--   programs should use <tt>make_usage_info</tt> and/or
--   <tt>print_usage_info</tt>.
--   
--   Get the usage information from the parsed arguments. The usage info
--   contains the header specified to the corresponding <tt>getargs...</tt>
--   function, and descriptions of the command line arguments.
--   
--   Descriptions can be several lines long. Lines get wrapped at column
--   80.
--   
--   See <a>make_usage_info</a>, <a>print_usage_info</a>, <a>wrap</a>.
usage_info :: Arguments -> String

-- | Generate pretty-printed information about the command line arguments.
--   This function gives you much control on how the usage information is
--   generated. <tt>print_usage_info</tt> might be more like what you need.
--   
--   The specified argument descriptions (as taken by the
--   <tt>getargs</tt>... functions) are processed in the given order. Each
--   one is formatted as a paragraph, detailing the argument. This is done
--   according to the specified geometry.
--   
--   The direct argument, in case there is one, is omitted. You should
--   detail the direct command line arguments separatly, such as in some
--   header.
--   
--   The specified maximum breadths must fit in the specified width, or an
--   error is raised. This happens, when <tt>colsleft + colsshort + 2 +
--   colslong + 2 + 2 &gt; width</tt>.
--   
--   See <a>print_usage_info</a>, <a>getargs</a>, <a>usage_info</a>,
--   <a>ArgumentDescription</a>, <a>desc_description</a>, <a>argdesc</a>,
--   <a>terminal_width</a>, <a>terminal_width_ioe</a>.
make_usage_info :: [ArgumentDescription] -> Int -> Int -> Int -> Int -> [String]

-- | Print the usage information (about the command line arguments), for
--   the specified header and arguments to the specified handle. When the
--   handle is connected to a terminal, the terminal's width (in columns)
--   is used to format the output, such that it fits the terminal. Both the
--   header and the argument descriptions are adapted to the width of the
--   terminal (by using <tt>wrap</tt>).
--   
--   When the handle does not connected to a terminal, 80 columns are used.
--   This may happen to <tt>stdout</tt> or <tt>stderr</tt>, for instance,
--   when the program is in a pipe, or the output has been redirected to a
--   file.
--   
--   When the terminal is too narrow for useful output, then instead of the
--   usage information, a short message (<tt>"Terminal too narrow"</tt>) is
--   printed. This applies to terminals with a width of less than 12.
--   
--   You should specify one long line for each paragraph in the header and
--   the argument descriptions, and let print_usage_info do the wrapping.
--   When you have several paragraphs, separate them by a double
--   <tt>\n\n</tt>. This also applies for an empty line, which should be
--   printed after the actual header.
--   
--   The arguments are printed in the order, in which they occur in the
--   argument description list.
--   
--   This function is a front end to <tt>terminal_width</tt> and
--   <tt>make_usage_info</tt>.
--   
--   See <a>argdesc</a>, <a>desc_description</a>, <a>terminal_width</a>,
--   <a>make_usage_info</a>, <a>usage_info</a>, <a>wrap</a>.
print_usage_info :: Handle -> String -> [ArgumentDescription] -> IO ()

-- | Generate a descriptive argument name from an argument description,
--   suitable for use in error messages and usage information. This uses
--   the long and short argument names (as specified by <a>desc_short</a>
--   and <a>desc_long</a>) and generates descriptive names of the argument
--   like "-f", "--myflag", "-f/--myflag", etc. All the argument names are
--   included. In case of direct arguments (see <a>desc_direct</a>), the
--   descriptive name is "<tt>(direct argument)</tt>".
--   
--   See <a>argdesc</a>.
argname :: ArgumentDescription -> String

-- | Generate a descriptive argument name from an argument description,
--   beginning with "argument". This uses the long and short argument names
--   (as specified by <a>desc_short</a> and <a>desc_long</a>) and generates
--   descriptive names of the argument like "argument -f", "argument
--   --myflag", "argument -f/--myflag", etc. All the argument names are
--   included. In case of direct arguments (see <a>desc_direct</a>), the
--   descriptive name is "direct argument".
--   
--   See <a>argdesc</a>.
argname_a :: ArgumentDescription -> String

-- | Create a string, which lists the short forms of one command line
--   argument. If it has an subargument, it's name is listed as well. For
--   arguments without short form, the result is the empty string.
--   
--   For the illegal command line argument, with neither short nor long
--   forms, and not being the direct argument either, the result is
--   <tt>"yet unnamed argument"</tt>. Such argument descriptions are
--   incomplete, and will be rejected by <tt>getargs</tt> and
--   <tt>unsafe_getargs</tt>.
--   
--   This is meant for refering to an argument, such as in error messages
--   or usage information.
--   
--   Examples:
--   
--   <pre>
--   argname_short (argdesc [ desc_short 'a'
--                          , desc_short 'b'
--                          , desc_value_required
--                          , desc_argname "Name"
--                          ])
--     == "-a/-b Name"
--   </pre>
--   
--   See <a>argdesc</a>, <a>desc_direct</a>. <a>argname_long</a>.
argname_short :: ArgumentDescription -> String

-- | Create a string, which lists the long forms of one command line
--   argument. If it has an subargument, it's name is listed as well. For
--   arguments without long form, the result is the empty string.
--   
--   For the illegal command line argument, with neither short nor long
--   forms, and not being the direct argument either, the result is
--   <tt>"yet unnamed argument"</tt>. Such argument descriptions are
--   incomplete, and will be rejected by <tt>getargs</tt> and
--   <tt>unsafe_getargs</tt>.
--   
--   This is meant for refering to an argument, such as in error messages
--   or usage information.
--   
--   Examples:
--   
--   <pre>
--   argname_long (argdesc [ desc_long "foo"
--                         , desc_long "bar"
--                         , desc_value_required
--                         , desc_argname "Name"
--                         ])
--     == "--foo/--bar Name"
--   </pre>
--   
--   See <a>argdesc</a>, <a>desc_direct</a>. <a>argname_long</a>.
argname_long :: ArgumentDescription -> String

-- | Break down a text to lines, such that each one has the specified
--   maximum width.
--   
--   Newline characters in the input text are respected. They terminate the
--   line, without it being filled up to the width.
--   
--   The text is wrapped at space characters. Words remain intact, except
--   when they are too long for one line.
wrap :: Int -> String -> [String]
instance GHC.Classes.Ord HsShellScript.Args.ArgumentValueSpec
instance GHC.Show.Show HsShellScript.Args.ArgumentValueSpec
instance GHC.Classes.Eq HsShellScript.Args.ArgumentValueSpec
instance GHC.Exception.Exception HsShellScript.Args.ArgError
instance GHC.Show.Show HsShellScript.Args.ArgError
instance GHC.Classes.Eq HsShellScript.Args.ArgumentDescription
instance GHC.Classes.Ord HsShellScript.Args.ArgumentDescription

module HsShellScript

-- | Create directory. This is a shorthand to
--   <tt>System.Directory.createDirectory</tt> from the Haskell standard
--   library. In case of an error, the path is included in the
--   <tt>IOError</tt>, which GHC's implementation neglects to do.
mkdir :: String -> IO ()

-- | Remove directory. This is <tt>Directory.removeDirectory</tt> from the
--   Haskell standard library. In case of an error, the path is included in
--   the <tt>IOError</tt>, which GHC's implementation neglects to do.
rmdir :: String -> IO ()

-- | Get program start working directory. This is the <tt>PWD</tt>
--   environent variable, which is kept by the shell (bash, at least). It
--   records the directory path in which the program has been started.
--   Symbolic links in this path aren't expanded. In this way, it differs
--   from <tt>getCurrentDirectory</tt> from the Haskell standard library.
--   
--   See <a>cd</a>, <a>with_wd</a>
pwd :: IO String

-- | Change directory. This is an alias for
--   <tt>Directory.setCurrentDirectory</tt> from the Haskell standard
--   library. In case of an error, the path is included in the
--   <tt>IOError</tt>, which GHC's implementation neglects to do.
--   
--   Note that this command is subtly different from the shell's
--   <tt>cd</tt> command. It changes the process' working directory. This
--   is always a realpath. Symlinks are expanded. The shell, on the other
--   hand, keeps track of the current working directory separately, in a
--   different way: symlinks are <i>not</i> expanded. The shell's idea of
--   the working directory is different from the working directory which a
--   process has.
--   
--   This means that the same sequence of <tt>cd</tt> commands, when done
--   in a real shell script, will lead into the same directory. But the
--   working directory as reported by the shell's <tt>pwd</tt> command may
--   differ from the corresponding one, reported by
--   <tt>getCurrentDirectory</tt>.
--   
--   (When talking about the "shell", I'm talking about bash, regardless of
--   whether started as <tt>/bin/bash</tt> or in compatibility mode, as
--   <tt>/bin/sh</tt>. I presume it's the standard behavior for the POSIX
--   standard shell.)
--   
--   See <a>pwd</a>, <a>with_wd</a>
cd :: String -> IO ()

-- | Do a call to the <tt>realpath(3)</tt> system library function. This
--   makes the path absolute, normalizes it and expands all symbolic links.
--   In case of an error, an <tt>IOError</tt> is thrown.
realpath :: String -> IO String

-- | Return the normalised, absolute version of a specified path. The path
--   is made absolute with the current working directory, and is
--   syntactically normalised afterwards. This is the same as what the
--   <tt>realpath</tt> program reports with the <tt>-s</tt> option. It's
--   almost the same as what it reports when called from a shell. The
--   difference lies in the shell's idea of the current working directory.
--   See <a>cd</a> for details.
--   
--   See <a>cd</a>, <a>normalise_path</a>.
realpath_s :: String -> IO String

-- | Test for the existence of a path. This is the disjunction of
--   <tt>Directory.doesDirectoryExist</tt> and
--   <tt>Directory.doesFileExist</tt>. For an dangling symlink, this will
--   return <tt>False</tt>.
path_exists :: String -> IO Bool

-- | Test for the existence of a path. This uses
--   <tt>System.Posix.Files.getFileStatus</tt> to determine whether the
--   path exists in any form in the file system. For a dangling symlink,
--   the result is <tt>True</tt>.
path_exists' :: String -> IO Bool

-- | Test if path points to a file. This is a shortcut for
--   <tt>Directory.doesFileExist</tt>.
is_file :: String -> IO Bool

-- | Test if path points to a directory. This will return <tt>True</tt> for
--   a symlink pointing to a directory. It's a shortcut for
--   <tt>Directory.doesDirectoryExist</tt>.
is_dir :: String -> IO Bool

-- | Change the working directory temporarily. This executes the specified
--   IO action with a new working directory, and restores it afterwards
--   (exception-safely).
with_wd :: FilePath -> IO a -> IO a

-- | Determine whether a path is a symbolic link. The result for a dangling
--   symlink is <tt>True</tt>. The path must exist in the file system. In
--   case of an error, a proper <tt>IOError</tt> is thrown.
is_symlink :: String -> IO Bool

-- | Make a symbolic link. This is the <tt>symlink(2)</tt> function. Any
--   error results in an <tt>IOError</tt> thrown. The path of the intended
--   symlink is included in the <tt>IOError</tt> and can be accessed with
--   <tt>ioeGetFileName</tt> from the Haskell standard library <tt>IO</tt>.
symlink :: String -> String -> IO ()

-- | Determine the target of a symbolic link. This uses the
--   <tt>readlink(2)</tt> system call. The result is a path which is either
--   absolute, or relative to the directory which the symlink is in. In
--   case of an error, an <tt>IOError</tt> is thrown. The path is included
--   and can be accessed with <tt>IO.ioeGetFileName</tt>. Note that, if the
--   path to the symlink ends with a slash, this path denotes the directory
--   pointed to, <i>not</i> the symlink. In this case the call to will fail
--   because of "Invalid argument".
readlink :: String -> IO String

-- | Determine the target of a symbolic link. This uses the
--   <tt>readlink(2)</tt> system call. The target is converted, such that
--   it is relative to the current working directory, if it isn't absolute.
--   Note that, if the path to the symlink ends with a slash, this path
--   denotes the directory pointed to, <i>not</i> the symlink. In this case
--   the call to <tt>readlink</tt> will fail with an <tt>IOError</tt>
--   because of "Invalid argument". In case of any error, a proper
--   <tt>IOError</tt> is thrown.
readlink' :: String -> IO String

-- | Remove file. This is <tt>Directory.removeFile</tt> from the Haskell
--   standard library, which is a direct frontend to the <tt>unlink(2)</tt>
--   system call in GHC.
rm :: String -> IO ()

-- | Execute <tt>/bin/chmod</tt>
--   
--   <pre>
--   chmod = run "/bin/chmod"
--   </pre>
chmod :: [String] -> IO ()

-- | Execute <tt>/bin/chown</tt>
--   
--   <pre>
--   chown = run "/bin/chown"
--   </pre>
chown :: [String] -> IO ()

-- | Execute the cp program
cp :: String -> String -> IO ()

-- | Execute the mv program.
--   
--   This calls the <tt>/bin/mv</tt> to rename a file, or move it to
--   another directory. You can move a file to another file system with
--   this. This starts a new process, which is rather slow. Consider using
--   <tt>rename</tt> instead, when possible.
--   
--   See <a>rename</a>.
mv :: String -> String -> IO ()

-- | The <tt>rename(2)</tt> system call to rename and/or move a file. The
--   <tt>renameFile</tt> action from the Haskell standard library doesn't
--   do it, because the two paths may not refer to directories. Failure
--   results in an <tt>IOError</tt> thrown. The <i>new</i> path is included
--   in the <tt>IOError</tt> and can be accessed with
--   <tt>IO.ioeGetFileName</tt>.
rename :: String -> String -> IO ()

-- | Rename a file. This first tries <a>rename</a>, which is most
--   efficient. If it fails, because source and target path point to
--   different file systems (as indicated by the <tt>errno</tt> value
--   <tt>EXDEV</tt>), then <tt>/bin/mv</tt> is called.
--   
--   See <a>rename</a>, <a>mv</a>.
rename_mv :: FilePath -> FilePath -> IO ()

-- | Rename a file or directory, and cope with read only issues.
--   
--   This renames a file or directory, using <tt>rename</tt>, sets the
--   necessary write permissions beforehand, and restores them afterwards.
--   This is more efficient than <tt>force_mv</tt>, because no external
--   program needs to be called, but it can rename files only inside the
--   same file system. See <tt>force_cmd</tt> for a detailed description.
--   
--   The new path may be an existing directory. In this case, it is assumed
--   that the old file is to be moved into this directory (like with
--   <tt>mv</tt>). The new path is then completed with the file name
--   component of the old path. You won't get an "already exists" error.
--   
--   <pre>
--   force_rename = force_cmd rename
--   </pre>
--   
--   See <a>force_cmd</a>, <a>rename</a>.
force_rename :: String -> String -> IO ()

-- | Move a file or directory, and cope with read only issues.
--   
--   This moves a file or directory, using the external command
--   <tt>mv</tt>, sets the necessary write permissions beforehand, and
--   restores them afterwards. This is less efficient than
--   <tt>force_rename</tt>, because the external program <tt>mv</tt> needs
--   to be called, but it can move files between file systems. See
--   <tt>force_cmd</tt> for a detailed description.
--   
--   <pre>
--   force_mv src tgt = fill_in_location "force_mv" $ force_cmd (\src tgt -&gt; run "/bin/mv" ["--", src, tgt]) src tgt
--   </pre>
--   
--   See <a>force_cmd</a>, <a>force_mv</a>.
force_mv :: String -> String -> IO ()

-- | Rename a file with <a>rename</a>, or when necessary with <a>mv</a>,
--   and cope with read only issues.
--   
--   The necessary write permissions are set, then the file is renamed,
--   then the permissions are restored.
--   
--   First, the <a>rename</a> system call is tried, which is most
--   efficient. If it fails, because source and target path point to
--   different file systems (as indicated by the <tt>errno</tt> value
--   <tt>EXDEV</tt>), then <tt>/bin/mv</tt> is called.
--   
--   <pre>
--   force_rename_mv old new = fill_in_location "force_rename_mv" $ force_cmd rename_mv old new
--   </pre>
--   
--   See <a>rename_mv</a>, <a>rename</a>, <a>mv</a>, <a>force_cmd</a>.
force_rename_mv :: FilePath -> FilePath -> IO ()

-- | Call a command which moves a file or directory, and cope with read
--   only issues.
--   
--   This function is for calling a command, which renames files.
--   Beforehand, write permissions are set in order to enable the
--   operation, and afterwards the permissions are restored. The command is
--   meant to be something like <tt>rename</tt> or <tt>run "/bin/mv"</tt>.
--   
--   In order to change the name of a file or dirctory, but leave it in the
--   super directory it is in, the super directory must be writeable. In
--   order to move a file or directory to a different super directory, both
--   super directories and the file/directory to be moved must be
--   writeable. I don't know what this behaviour is supposed to be good
--   for.
--   
--   This function copes with the case that the file/directory to be moved
--   or renamed, or the super directories are read only. It makes the
--   necessary places writeable, calls the command, and makes them read
--   only again, if they were before. The user needs the necessary
--   permissions for changing the corresponding write permissions. If an
--   error occurs (such as file not found, or insufficient permissions),
--   then the write permissions are restored to the state before, before
--   the exception is passed through to the caller.
--   
--   The command must take two arguments, the old path and the new path. It
--   is expected to create the new path in the file system, such that the
--   correct write permissions of the new path can be set by
--   <tt>force_cmd</tt> after executing it.
--   
--   The new path may be an existing directory. In this case, it is assumed
--   that the old file is to be moved into this directory (like with
--   <tt>mv</tt>). The new path is completed with the file name component
--   of the old path, before it is passed to the command, such that the
--   command is supplied the complete new path.
--   
--   Examples:
--   
--   <pre>
--   force_cmd rename from to
--   force_cmd (\from to -&gt; run "/bin/mv" ["-i", "-v", "--", from, to]) from to
--   </pre>
--   
--   See <a>force_rename</a>, <a>force_mv</a>, <a>rename</a>.
force_cmd :: (String -> String -> IO ()) -> String -> String -> IO ()

-- | Make a file or directory writeable for the user, perform an action,
--   and restore its writeable status. An IOError is raised when the user
--   doesn't have permission to make the file or directory writeable.
--   
--   <pre>
--   force_writeable path io = force_writeable2 path (io &gt;&gt;= \res -&gt; return (path, res))
--   </pre>
--   
--   Example:
--   
--   <pre>
--   -- Need to create a new directory in /foo/bar, even if that's write protected
--   force_writeable "/foo/bar" $ mkdir "/foo/bar/baz"
--   </pre>
--   
--   See <a>force_cmd</a>, <a>force_writeable2</a>.
force_writeable :: String -> IO a -> IO a

-- | Make a file or directory writeable for the user, perform an action,
--   and restore its writeable status. The action may change the name of
--   the file or directory. Therefore it returns the new name, along with
--   another return value, which is passed to the caller.
--   
--   The writeable status is only changed back if it has been changed by
--   <tt>force_writeable2</tt> before. An IOError is raised when the user
--   doesn'h have permission to make the file or directory writeable, or
--   when the new path doesn't exist.
--   
--   See <a>force_cmd</a>, <a>force_writeable</a>.
force_writeable2 :: String -> IO (String, a) -> IO a

-- | This is the <tt>System.Posix.Files.getFileStatus</tt> function from
--   the GHC libraries, with improved error reporting. The GHC function
--   doesn't include the file name in the <tt>IOError</tt> when the call
--   fails, making error messages much less useful. <tt>getFileStatus'</tt>
--   rectifies this.
--   
--   See <a>getFileStatus</a>.
getFileStatus' :: FilePath -> IO FileStatus

-- | This is the <tt>System.Posix.Files.fileAccess</tt> function from the
--   GHC libraries, with improved error reporting. The GHC function doesn't
--   include the file name in the <tt>IOError</tt> when the call fails,
--   making error messages much less useful. <tt>fileAccess'</tt> rectifies
--   this.
--   
--   See <a>fileAccess</a>.
fileAccess' :: FilePath -> Bool -> Bool -> Bool -> IO Bool

-- | Improved version of <tt>System.Posix.Files.setFileMode</tt>, which
--   sets the file name in the <tt>IOError</tt> which is thrown in case of
--   an error. The implementation in GHC 6.2.2 neglects to do this.
--   
--   <pre>
--   setFileMode' path mode =
--      fill_in_filename path $
--         setFileMode path mode
--   </pre>
setFileMode' :: FilePath -> FileMode -> IO ()

-- | Run the command <tt>mt status</tt> for querying the tape drive status,
--   and parse its output.
mt_status :: IO (Int, Int)

-- | Call the <tt>fdupes</tt> program in order to find identical files. It
--   outputs a list of groups of file names, such that the files in each
--   group are identical. Each of these groups is further analysed by the
--   <tt>fdupes</tt> action. It is split to a list of lists of paths, such
--   that each list of paths corresponds to one of the directories which
--   have been searched by the <tt>fdupes</tt> program. If you just want
--   groups of identical files, then apply <tt>map concat</tt> to the
--   result.
--   
--   <i>The</i> <tt>fdupes</tt> /program doesn't handle multiple occurences
--   of the same directory, or in recursive mode one specified directory
--   containing another, properly. The same file may get reported multiple
--   times, and identical files may not get reported./
--   
--   The paths are normalised (using <a>normalise_path</a>).
fdupes :: [String] -> [String] -> IO [[[String]]]

-- | Call the <tt>du</tt> program. See du(1).
du :: (Integral int, Read int, Show int) => int -> String -> IO int

-- | Execute an IO action as a separate process, and wait for it to finish.
--   Report errors as exceptions.
--   
--   This forks a child process, which performs the specified IO action. In
--   case the child process has been stopped by a signal, the parent
--   blocks.
--   
--   If the action throws an <tt>IOError</tt>, it is transmitted to the
--   parent. It is then raised there, as if it happened locally. The child
--   then aborts quietly with an exit code of 0.
--   
--   Exceptions in the child process, other than <tt>IOError</tt>s, result
--   in an error message on <tt>stderr</tt>, and a <tt>ProcessStatus</tt>
--   exception in the parent, with the value of <tt>Exited (ExitFailure
--   1)</tt>. The following exceptions are understood by <tt>subproc</tt>,
--   and result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   If the child process exits with an exit code other than zero, or it is
--   terminated by a signal, the corresponding <tt>ProcessStatus</tt> is
--   raised as an exception in the parent program. Only <tt>IOError</tt>s
--   are transmitted to the parent.
--   
--   When used in conjunction with an <tt>exec</tt> variant, this means
--   that the parent process can tell the difference between failure of the
--   <tt>exec</tt> call itself, and failure of the child program being
--   executed after a successful call of the <tt>exec</tt> variant. In case
--   of failure of the <tt>exec</tt> call, You get the <tt>IOError</tt>,
--   which happened in the child when calling <tt>executeFile</tt> (from
--   the GHC hierarchical libraries). In case of the called program
--   failing, you get the <tt>ProcessStatus</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally (unless it throws an <tt>IOError</tt>). The child process is
--   then properly terminated by <tt>subproc</tt>, such that no resources,
--   which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   If you want to run an external program, by calling one of the
--   <tt>exec</tt> variants in the child action, you might want to call
--   <tt>runprog</tt> instead of <tt>subproc</tt>.
--   
--   Examples:
--   
--   Run a program with the environment replaced:
--   
--   <pre>
--   subproc (execpe "foobar" ["1","2","3"] new_env)
--   </pre>
--   
--   This results in a <tt>ProcessStatus</tt> exception:
--   
--   <pre>
--   subproc (exec "/bin/false" [])
--   </pre>
--   
--   This results in an <tt>IOError</tt> (unless you actually have
--   <tt>/frooble</tt>):
--   
--   <pre>
--   subproc (exec "/frooble" [])
--   </pre>
--   
--   See <a>runprog</a>, <a>spawn</a>, <a>exec</a>, <a>execp</a>,
--   <a>exece</a>, <a>execpe</a>.
subproc :: IO a -> IO ()

-- | Execute an IO action as a separate process, and continue without
--   waiting for it to finish.
--   
--   The program forks a child process, which performs the specified action
--   and terminates. The child's process ID is returned.
--   
--   See <a>HsShellScript#subr</a> for further details.
--   
--   See <a>subproc</a>.
spawn :: IO a -> IO ProcessID

-- | Run an external program, and report errors as exceptions. The
--   executable is searched via the <tt>PATH</tt>. In case the child
--   process has been stopped by a signal, the parent blocks.
--   
--   In case the program exits in an way which indicates an error, or is
--   terminated by a signal, a <tt>RunError</tt> is thrown. It contains the
--   details of the call. The <tt>runprog</tt> action can also be converted
--   to throw <tt>IOError</tt>s instaed, by applying <tt>as_ioe</tt> to it.
--   Either can be used to generate an informative error message.
--   
--   In case of starting the program itself failed, an <tt>IOError</tt> is
--   thrown.
--   
--   <tt>runprog prog par</tt> is a simple front end to <tt>subproc</tt>.
--   It is essentially <tt>subproc (execp prog par)</tt>, apart from
--   building a <tt>RunError</tt> from a <tt>ProcessStatus</tt>.
--   
--   Example 1:
--   
--   <pre>
--   do runprog "foo" ["some", "args"]
--      ...
--   `catch` (\re -&gt; do errm (show_runerror re)
--                         ...
--              )
--   </pre>
--   
--   Example 2:
--   
--   <pre>
--   do as_ioe $ runprog "foo" ["some", "args"]
--      ...
--   `catch` (\ioe -&gt; do errm (show_ioerror ioe)
--                          ...
--              )
--   </pre>
--   
--   See <a>subproc</a>, <a>spawn</a>, <a>RunError</a>,
--   <a>show_runerror</a>, <a>to_ioe</a>, <a>as_ioe</a>.
runprog :: FilePath -> [String] -> IO ()

-- | An error which occured when calling an external program. The fields
--   specifiy the details of the call.
--   
--   See <a>show_runerror</a>, <a>to_ioe</a>, <a>as_ioe</a>,
--   <tt>System.Posix.ProcessStatus</tt>.
data RunError
RunError :: String -> [String] -> [(String, String)] -> String -> ProcessStatus -> Maybe CInt -> RunError

-- | Program name
[re_prog] :: RunError -> String

-- | Program arguments
[re_pars] :: RunError -> [String]

-- | The environment in use when the call was done
[re_env] :: RunError -> [(String, String)]

-- | The working directory when the call was done
[re_wd] :: RunError -> String

-- | The process status of the failure
[re_ps] :: RunError -> ProcessStatus

-- | The error (errno) code
[re_errno] :: RunError -> Maybe CInt

-- | Make a readable error message. This includes all the fields of
--   <tt>RunError</tt> except for the environment.
--   
--   See <a>RunError</a>.
show_runerror :: RunError -> String

-- | Convert a <tt>RunError</tt> to an <tt>IOError</tt>.
--   
--   The <tt>IOError</tt> type isn't capable of holding all the information
--   which is contained in a <tt>RunError</tt>. The environment is left
--   out, and most of the other fields are included only informally, in the
--   description.
--   
--   The fields of the generated <tt>IOError</tt> are:
--   
--   <ul>
--   <li>The handle (<tt>ioeGetHandle</tt>): <tt>Nothing</tt></li>
--   <li>The error type (<tt>ioeGetErrorType</tt>):
--   <tt>GHC.IO.Exception.SystemError</tt></li>
--   <li><tt>ioe_location</tt>: <tt>"runprog"</tt></li>
--   <li><tt>ioe_description</tt>: The error message, as procuded by
--   <tt>show_runerror</tt>.</li>
--   <li><tt>ioe_filename</tt>: This is <tt>Just (shell_command <i>prog</i>
--   <i>pars</i>)</tt>, with <i>prog</i> and <i>pars</i> being the program
--   and its arguments.</li>
--   </ul>
--   
--   See <a>as_ioe</a>, <a>runprog</a>, <a>show_runerror</a>.
to_ioe :: RunError -> IOError

-- | Call the specified IO action (which is expected to contain calls of
--   <tt>runprog</tt>) and convert any <tt>RunError</tt> exceptions to
--   <tt>IOError</tt>s.
--   
--   The conversion is done by <tt>to_ioe</tt>.
--   
--   See <a>to_ioe</a>, <a>runprog</a>.
as_ioe :: IO a -> IO a

-- | Execute an external program. This replaces the running process. The
--   path isn't searched, the environment isn't changed. In case of
--   failure, an IOError is thrown.
--   
--   <pre>
--   exec path args =
--      execute_file path False args Nothing
--   </pre>
--   
--   See <a>execute_file</a>, <a>HsShellScript#exec</a>.
exec :: String -> [String] -> IO a

-- | Execute an external program. This replaces the running process. The
--   path is searched, the environment isn't changed. In case of failure,
--   an IOError is thrown.
--   
--   <pre>
--   execp prog args =
--      execute_file prog True args Nothing
--   </pre>
--   
--   See <a>execute_file</a>, <a>HsShellScript#exec</a>.
execp :: String -> [String] -> IO a

-- | Execute an external program. This replaces the running process. The
--   path isn't searched, the environment of the program is set as
--   specified. In case of failure, an IOError is thrown.
--   
--   <pre>
--   exece path args env =
--      execute_file path False args (Just env)
--   </pre>
--   
--   See <a>execute_file</a>, <a>HsShellScript#exec</a>.
exece :: String -> [String] -> [(String, String)] -> IO a

-- | Execute an external program. This replaces the running process. The
--   path is searched, the environment of the program is set as specified.
--   In case of failure, an IOError is thrown.
--   
--   <pre>
--   execpe prog args env =
--      execute_file prog True args (Just env)
--   </pre>
--   
--   See <a>execute_file</a>, <a>HsShellScript#exec</a>.
execpe :: String -> [String] -> [(String, String)] -> IO a

-- | Print an action as a shell command, then perform it.
--   
--   This is used with actions such as <a>runprog</a>, <a>exec</a> or
--   <a>subproc</a>. For instance, <tt>echo runprog prog args</tt> is a
--   variant of <tt>runprog prog args</tt>, which prints what is being done
--   before doing it.
--   
--   See <a>runprog</a>, <a>subproc</a>, <a>exec</a>.
echo :: (FilePath -> [String] -> IO ()) -> FilePath -> [String] -> IO ()

-- | Run a subroutine as a child process, but don't let it produce any
--   messages. Read its <tt>stdout</tt> and <tt>stderr</tt> instead, and
--   append it to the contents of a mutable variable. The idea is that you
--   can run some commands silently, and report them and their messages to
--   the user only when something goes wrong.
--   
--   If the child process terminates in a way which indicates an error,
--   then the process status is thrown, in the same way as <a>runprog</a>
--   does. If the subroutine throws an <tt>(Exited ec)</tt> exception (of
--   type <tt>ProcessStatus</tt>), such as thrown by <a>runprog</a>, then
--   the child process exits with the same exit code, such that the parent
--   process reports it to the caller, again as a <tt>ProcessStatus</tt>
--   exception.
--   
--   When the subroutine finishes, the child process is terminated with
--   <tt><a>_exit</a> 0</tt>. When it throws an exception, an error message
--   is printed and it is terminated with <tt><a>_exit</a> 1</tt>. See
--   <a>HsShellScript#subr</a> for details.
--   
--   The standard output (and the standard error output) of the parent
--   process are flushed before the fork, such that no output appears
--   twice.
--   
--   Example:
--   
--   <pre>
--   let handler :: IORef String -&gt; ProcessStatus -&gt; IO ()
--       handler msgref ps = do hPutStrLn stderr ("Command failed with " ++ show ps ++ ". Actions so far: ")
--                              msg &lt;- readIORef msgref
--                              hPutStrLn stderr msg
--                              exitWith (ExitFailure 1)
--   
--   msgref &lt;- newIORef ""
--   do silently msgref $ do putStrLn "Now doing foobar:"
--                           echo exec "/foo/bar" ["arguments"]
--      silently msgref $ echo exec "/bar/baz" ["arguments"]
--   `catch` (handler msgref)
--   </pre>
--   
--   See <a>lazy_pipe_from</a>, <a>subproc</a>, <a>runprog</a>, Data.IORef.
silently :: IORef String -> IO () -> IO ()

-- | Call the shell to execute a command. In case of an error, a
--   <tt>RunError</tt> ist thrown. This is like the Haskell standard
--   library function <tt>system</tt>, except that error handling is
--   brought in accordance with HsShellScript's scheme. (It is <i>not</i> a
--   front end to <tt>system</tt>.)
--   
--   <pre>
--   system_runprog cmd = runprog "/bin/sh" ["-c", "--", cmd]
--   </pre>
--   
--   Example: Call "foo" and report Errors as <tt>IOError</tt>s, rather
--   than <tt>RunError</tt>s.
--   
--   <pre>
--   as_ioe $ system_runprog "foo" ["bar", "baz"]
--   </pre>
--   
--   See <a>RunError</a>, <a>as_ioe</a>
system_runprog :: String -> IO ()

-- | Call the shell to execute a command. In case of an error, throw the
--   <tt>ProcessStatus</tt> (such as <tt>(Exited (ExitFailure ec))</tt>) as
--   an exception. This is like the Haskell standard library function
--   <tt>system</tt>, except that error handling is brought in accordance
--   with HsShellScript's scheme.
--   
--   <tt>exitcode . system_throw</tt> is the same as the <tt>system</tt>
--   function, except that when the called shell is terminated or stopped
--   by a signal, this still lead to the <tt>ProcessStatus</tt> being
--   thrown. The Haskell library report says nothing about what happens in
--   this case, when using the <tt>system</tt> function.
--   
--   <pre>
--   system_throw cmd = run "/bin/sh" ["-c", "--", cmd]
--   </pre>
--   
--   This function is deprecated. You should rather use
--   <a>system_runprog</a>, which provides for much better error reporting.
system_throw :: String -> IO ()

-- | This is a replacement for <tt>System.Posix.Process.executeFile</tt>.
--   It does additional preparations, then calls <tt>executeFile</tt>.
--   <tt>executeFile</tt> <i>can't normally</i> <i>be used directly,
--   because it doesn't do the things which are</i> <i>outlined here.</i>
--   
--   This are the differences to <tt>executeFile</tt>:
--   
--   <ol>
--   <li><tt>stdout</tt> and <tt>stderr</tt> are flushed.</li>
--   <li>The standard file descriptors 0-2 are made copies of the file
--   descriptors which the standard handles currently use. This is
--   necessary because they might no longer use the standard handles. See
--   <a>HsShellScript#fdpipes</a>.</li>
--   </ol>
--   
--   If the standard handles <tt>stdin</tt>, <tt>stdout</tt>,
--   <tt>stderr</tt> aren't in closed state, and they aren't already
--   connected to the respective standard file descriptors, their file
--   descriptors are copied to the respective standard file descriptors
--   (with <tt>dup2</tt>). Backup copies are made of the file descriptors
--   which are overwritten. If some of the standard handles are closed, the
--   corresponding standard file descriptors are closed as well.
--   
--   <ol>
--   <li>All file descriptors, except for the standard ones, are set to
--   close-on-exec (see <tt>fcntl(2)</tt>), and will be closed on
--   successful replacement of the process. Before that, the old file
--   descriptor flags are saved.</li>
--   <li>The standard file descriptors are set to blocking mode, since GHC
--   6.2.2 sets file descriptors to non-blocking (except 0-2, which may get
--   overwritten by a non-blocking one in step 2). The called program
--   doesn't expect that.</li>
--   <li>In case replacing the process fails, the file descriptors are
--   reset to the original state. The file descriptors flags are restored,
--   and the file descriptors 0-2 are overwritten again, with their backup
--   copies. Then an IOError is thrown.</li>
--   <li>In any IOError, the program is filled in as the file name
--   (<tt>executeFile</tt> neglects this).</li>
--   <li>The return type is a generic <tt>a</tt>, rather than
--   <tt>()</tt>.</li>
--   </ol>
--   
--   Also see <a>HsShellScript#exec</a>.
execute_file :: FilePath -> Bool -> [String] -> Maybe [(String, String)] -> IO a

-- | Modify a subroutine action in order to make it suitable to run as a
--   child process.
--   
--   This is used by functions like <a>call</a>, <a>silently</a>,
--   <a>pipe_to</a> etc. The action is executed. When it returns, the
--   (child) process is terminated with <tt><a>_exit</a> 0</tt> (after
--   flushing <tt>stdout</tt>), circumventing normal program shutdown. When
--   it throws an exception, an error message is printed and the (child)
--   process is terminated with <tt><a>_exit</a> 1</tt>.
child :: IO a -> IO b

-- | Generate a human-readable description of a <tt>ProcessStatus</tt>.
--   
--   See <a>exec</a>, <a>runprog</a> and
--   <tt>System.Posix.ProcessStatus</tt> in the GHC hierarchical library
--   documentation.
explain_processstatus :: ProcessStatus -> String

-- | Execute an IO action as a separate process, and wait for it to finish.
--   Report errors as exceptions.
--   
--   <i>This function is included only for backwards compatibility. New
--   code should</i> <i>use</i> <a>subproc</a> instead<i>, which has better
--   error handling.</i>
--   
--   The program forks a child process and performs the specified action.
--   Then it waits for the child process to finish. If it exits in any way
--   which indicates an error, the <tt>ProcessStatus</tt> is thrown.
--   
--   The parent process waits for the child processes, which have been
--   stopped by a signal.
--   
--   See <a>HsShellScript#subr</a> for further details.
--   
--   See <a>subproc</a>, <a>spawn</a>.
call :: IO a -> IO ()

-- | Run an external program. This starts a program as a child process, and
--   waits for it to finish. The executable is searched via the
--   <tt>PATH</tt>.
--   
--   <i>This function is included for backwards compatibility only. New
--   code should</i> <i>use</i> <a>runprog</a><i>, which has much better
--   error handling.</i>
--   
--   When the specified program can't be executed, an error message is
--   printed, and the main process gets a <tt>ProcessStatus</tt> thrown,
--   with the value <tt>Exited (ExitFailure 1)</tt>. This means that the
--   main program can't distinguish between failure of calling the program
--   and the program exiting with an exit code of 1. However, an error
--   message "Error calling ...", including the description in the IOError
--   produced by the failed <tt>execp</tt> call, is printed on
--   <tt>stderr</tt>.
--   
--   <tt>run prog par</tt> is essentially <tt>call (execp prog par)</tt>.
--   
--   Example:
--   
--   <pre>
--   run "/usr/bin/foobar" ["some", "args"]
--      `catch` (\ps -&gt; do -- oops...
--                 )
--   </pre>
--   
--   See <a>runprog</a>, <a>subproc</a>, <a>spawn</a>.
run :: FilePath -> [String] -> IO ()

-- | Redirect the standard output of the specified IO action to a file. The
--   file will be overwritten, if it already exists.
--   
--   What's actually modified is the <tt>stdout</tt> handle, not the file
--   descriptor 1. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   runprog "/some/program" [] -&gt;- "/tmp/output"
--   </pre>
--   
--   Note: You can't redirect to <tt>"/dev/null"</tt> this way, because GHC
--   6.4's <tt>openFile</tt> throws an "invalid argument" IOError. (This
--   may be a bug in the GHC 6.4 libraries). Use <tt>-&gt;&gt;-</tt>
--   instead.
--   
--   See <a>subproc</a>, <a>runprog</a>, <a>-&gt;&gt;-</a>, <a>=&gt;-</a>.
(->-) :: IO a -> FilePath -> IO a
infixl 3 ->-

-- | Redirect the standard output of the specified IO action to a file. If
--   the file already exists, the output will be appended.
--   
--   What's actually modified is the <tt>stdout</tt> handle, not the file
--   descriptor 1. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   run "/some/noisy/program" [] -&gt;&gt;- "/dev/null"
--   </pre>
--   
--   See <a>subproc</a>, <a>runprog</a>, '(-&gt;-)', '(=&gt;&gt;-)'.
(->>-) :: IO a -> FilePath -> IO a
infixl 3 ->>-

-- | Redirect the standard error output of the specified IO action to a
--   file. If the file already exists, it will be overwritten.
--   
--   What's actually modified is the <tt>stderr</tt> handle, not the file
--   descriptor 2. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   Note: You can't redirect to <tt>"/dev/null"</tt> this way, because GHC
--   6.4's <tt>openFile</tt> throws an "invalid argument" IOError. (This
--   may be a bug in the GHC 6.4 libraries). Use <tt>=&gt;&gt;-</tt>
--   instead.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   run "/path/to/foo" [] =&gt;- "/tmp/errlog"
--   </pre>
--   
--   See <a>subproc</a>, <a>runprog</a>, '(-&gt;-)', '(=&gt;&gt;-)'.
(=>-) :: IO a -> FilePath -> IO a
infixl 3 =>-

-- | Redirect the standard error output of the specified IO action to a
--   file. If the file already exists, the output will be appended.
--   
--   What's actually modified is the <tt>stderr</tt> handle, not the file
--   descriptor 2. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   run "/some/program" [] =&gt;&gt;- "/dev/null"
--   </pre>
--   
--   See <a>subproc</a>, <a>runprog</a>, '(-&gt;&gt;-)', '(=&gt;-)'.
(=>>-) :: IO a -> FilePath -> IO a
infixl 3 =>>-

-- | Redirect stdin from a file. This modifies the specified action, such
--   that the standard input is read from a file.
--   
--   What's actually modified is the <tt>stdin</tt> handle, not the file
--   descriptor 0. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   The file is read in <i>text mode</i>. This means that the input is
--   converted from the system character set to Unicode. The system's
--   character set is determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   subproc (exec "/path/to/foo" [] -&lt;- "bar")
--   </pre>
--   
--   See <a>exec</a>, <a>runprog</a>, '(-&gt;-)', '(=&gt;-)'.
(-<-) :: IO a -> FilePath -> IO a
infixl 3 -<-

-- | Redirect both stdout and stderr to a file. This is equivalent to the
--   shell's <tt>&amp;&gt;</tt> operator. If the file already exists, it
--   will be overwritten.
--   
--   What's actually modified are the <tt>stdout</tt> and <tt>stderr</tt>
--   handles, not the file descriptors 1 and 2. The <tt>exec</tt> functions
--   know about this. See <a>HsShellScript#fdpipes</a> and
--   <a>HsShellScript#exec</a> for details.
--   
--   Note: You can't redirect to <tt>"/dev/null"</tt> this way, because GHC
--   6.4's <tt>openFile</tt> throws an "invalid argument" IOError. (This
--   may be a bug in the GHC 6.4 libraries). Use <tt>-&amp;&gt;&gt;-</tt>
--   instead.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   <pre>
--   (-&amp;&gt;-) io path = err_to_out io -&gt;- path
--   </pre>
--   
--   Example:
--   
--   <pre>
--   subproc (exec "/path/to/foo" [] -&amp;&gt;- "log")
--   </pre>
--   
--   See '(-&amp;&gt;&gt;-)', <a>err_to_out</a>.
(-&>-) :: IO a -> FilePath -> IO a
infixl 3 -&>-

-- | Redirect both stdout and stderr to a file. If the file already exists,
--   the output will be appended.
--   
--   What's actually modified are the <tt>stdout</tt> and <tt>stderr</tt>
--   handles, not the file descriptors 1 and 2. The <tt>exec</tt> functions
--   know about this. See <a>HsShellScript#fdpipes</a> and
--   <a>HsShellScript#exec</a> for details.
--   
--   The file is written in <i>text mode</i>. This means that the output is
--   converted from Unicode to the system character set, which is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   <pre>
--   (-&amp;&gt;&gt;-) io path = (err_to_out &gt;&gt; io) -&gt;&gt;- path
--   </pre>
--   
--   Example:
--   
--   <pre>
--   run "/some/noisy/program" [] -&amp;&gt;&gt;- "/dev/null"
--   </pre>
--   
--   See '(-&amp;&gt;-)', <a>out_to_err</a>.
(-&>>-) :: IO a -> FilePath -> IO a
infixl 3 -&>>-

-- | Send the error output of the specified action to its standard output.
--   
--   What's actually modified is the <tt>stdout</tt> handle, not the file
--   descriptor 1. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   <pre>
--   err_to_out = redirect stderr stdout
--   </pre>
--   
--   See <a>redirect</a>.
err_to_out :: IO a -> IO a

-- | Send the output of the specified action to its standard error output.
--   
--   What's actually modified is the <tt>stderr</tt> handle, not the file
--   descriptor 2. The <tt>exec</tt> functions know about this. See
--   <a>HsShellScript#fdpipes</a> and <a>HsShellScript#exec</a> for
--   details.
--   
--   <pre>
--   redirect stdout stderr
--   </pre>
--   
--   See <a>redirect</a>.
out_to_err :: IO a -> IO a

-- | Build left handed pipe of stdout.
--   
--   "<tt>p -|- q</tt>" builds an IO action from the two IO actions
--   <tt>p</tt> and <tt>q</tt>. <tt>q</tt> is executed in an external
--   process. The standard output of <tt>p</tt> is sent to the standard
--   input of <tt>q</tt> through a pipe. The result action consists of
--   forking off <tt>q</tt> (connected with a pipe), and <tt>p</tt>.
--   
--   The result action does <i>not</i> run <tt>p</tt> in a separate
--   process. So, the pipe itself can be seen as a modified action
--   <tt>p</tt>, forking a connected <tt>q</tt>. The pipe is called "left
--   handed", because <tt>p</tt> remains unforked, and not <tt>q</tt>.
--   
--   <i>The exit code of q is silently ignored.</i> The process ID of the
--   forked copy of <tt>q</tt> isn't returned to the caller, so it's lost.
--   
--   The pipe, which connects <tt>p</tt> and <tt>q</tt>, is in <i>text
--   mode</i>. This means that the output of <tt>p</tt> is converted from
--   Unicode to the system character set, which is determined by the
--   environment variable <tt>LANG</tt>.
--   
--   See <a>HsShellScript#subr</a> and <a>HsShellScript#exec</a> for
--   further details.
--   
--   Examples:
--   
--   <pre>
--   subproc (exec "/usr/bin/foo" [] -|- exec "/usr/bin/bar" [])
--   </pre>
--   
--   <pre>
--   sunproc (    execp "foo" ["..."]
--            -|= ( -- Do something with foo's output
--                  do cnt &lt;- lazy_contents "-"
--                     ...
--                )
--           )
--   </pre>
--   
--   <pre>
--   sunproc ( err_to_out foo
--             -|- exec "/usr/bin/tee" ["-a", "/tmp/foo.log"] )
--   </pre>
--   
--   See <a>subproc</a>, '(=|-)', '(-|=)', <a>redirect</a>
(-|-) :: IO a -> IO b -> IO a
infixr 2 -|-

-- | Build left handed pipe of stderr.
--   
--   "<tt>p =|- q</tt>" builds an IO action from the two IO actions
--   <tt>p</tt> and <tt>q</tt>. <tt>q</tt> is executed in an external
--   process. The standard error output of <tt>p</tt> is sent to the
--   standard input of <tt>q</tt> through a pipe. The result action
--   consists of forking off <tt>q</tt> (connected with a pipe), and
--   <tt>p</tt>.
--   
--   The result action does <i>not</i> run <tt>p</tt> in a separate
--   process. So, the pipe itself can be seen as a modified action
--   <tt>p</tt>, forking a connected <tt>q</tt>. The pipe is called "left
--   handed", because <tt>p</tt> has this property, and not <tt>q</tt>.
--   
--   <i>The exit code of q is silently ignored.</i> The process ID of the
--   forked copy of <tt>q</tt> isn't returned to the caller, so it's lost.
--   
--   The pipe, which connects <tt>p</tt> and <tt>q</tt>, is in <i>text
--   mode</i>. This means that the output of <tt>p</tt> is converted from
--   Unicode to the system character set, which is determined by the
--   environment variable <tt>LANG</tt>.
--   
--   See <a>HsShellScript#subr</a> and <a>HsShellScript#exec</a> for
--   further details.
--   
--   Example:
--   
--   <pre>
--   subproc (exec "/usr/bin/foo" [] =|- exec "/usr/bin/bar" [])
--   </pre>
--   
--   See <a>subproc</a>, '(-|-)', '(-|=)'.
(=|-) :: IO a -> IO b -> IO a
infixr 2 =|-

-- | Build right handed pipe of stdout.
--   
--   "<tt>p -|= q</tt>" builds an IO action from the two IO actions
--   <tt>p</tt> and <tt>q</tt>. <tt>p</tt> is executed in an external
--   process. The standard output of <tt>p</tt> is sent to the standard
--   input of <tt>q</tt> through a pipe. The result action consists of
--   forking off <tt>p</tt> (connected with a pipe), and <tt>q</tt>.
--   
--   The result action does <i>not</i> run <tt>q</tt> in a separate
--   process. So, the pipe itself can be seen as a modified action
--   <tt>q</tt>, forking a connected <tt>p</tt>. The pipe is called "right
--   handed", because <tt>q</tt> has this property, and not <tt>p</tt>.
--   
--   <i>The exit code of p is silently ignored.</i> The process ID of the
--   forked copy of <tt>q</tt> isn't returned to the caller, so it's lost.
--   
--   The pipe, which connects <tt>p</tt> and <tt>q</tt>, is in <i>text
--   mode</i>. This means that the output of <tt>p</tt> is converted from
--   Unicode to the system character set, which is determined by the
--   environment variable <tt>LANG</tt>.
--   
--   See <a>HsShellScript#subr</a> and <a>HsShellScript#exec</a> for
--   further details.
--   
--   Example:
--   
--   <pre>
--   subproc (exec \"\/usr\/bin\/foo\" [] -|= exec \"\/usr\/bin\/bar\" [])
--   </pre>
--   
--   See <a>subproc</a>, '(=|-)', '(=|=)'.
(-|=) :: IO a -> IO b -> IO b
infixl 2 -|=

-- | Build right handed pipe of stderr.
--   
--   "<tt>p =|= q</tt>" builds an IO action from the two IO actions
--   <tt>p</tt> and <tt>q</tt>. <tt>p</tt> is executed in an external
--   process. The standard error output of <tt>p</tt> is sent to the
--   standard input of <tt>q</tt> through a pipe. The result action
--   consists of forking off <tt>p</tt> (connected with a pipe), and
--   <tt>q</tt>.
--   
--   The result action does <i>not</i> run <tt>q</tt> in a separate
--   process. So, the pipe itself can be seen as a modified action
--   <tt>q</tt>, forking a connected <tt>p</tt>. The pipe is called "right
--   handed", because <tt>q</tt> has this property, and not <tt>p</tt>.
--   
--   <i>The exit code of p is silently ignored.</i> The process ID of the
--   forked copy of <tt>q</tt> isn't returned to the caller, so it's lost.
--   
--   The pipe, which connects <tt>p</tt> and <tt>q</tt>, is in <i>text
--   mode</i>. This means that the output of <tt>p</tt> is converted from
--   Unicode to the system character set, which is determined by the
--   environment variable <tt>LANG</tt>.
--   
--   See <a>HsShellScript#subr</a> and <a>HsShellScript#exec</a> for
--   further details.
--   
--   Example:
--   
--   <pre>
--   subproc (exec "/usr/bin/foo" [] =|= exec "/usr/bin/bar" [])
--   </pre>
--   
--   See <a>subproc</a>, <a>=|-</a>, <a>-|=</a>.
(=|=) :: IO a -> IO b -> IO b
infixl 2 =|=

-- | Temporarily replace a handle. This makes a backup copy of the original
--   handle (typically a standard handle), overwrites it with the specified
--   one, runs the specified action, and restores the handle from the
--   backup.
--   
--   Example:
--   
--   <pre>
--   h &lt;- openFile "/tmp/log" WriteMode
--   redirect stdout h io
--   hClose h
--   </pre>
--   
--   This is the same as
--   
--   <pre>
--   io -&gt;- "/tmp/log"
--   </pre>
--   
--   See <a>-|-</a>, <a>=|-</a>.
redirect :: Handle -> Handle -> IO a -> IO a

-- | Run an IO action as a separate process, and pipe some text to its
--   <tt>stdin</tt>. Then close the pipe and wait for the child process to
--   finish.
--   
--   This forks a child process, which executes the specified action. The
--   specified text is sent to the action's <tt>stdin</tt> through a pipe.
--   Then the pipe is closed. In case the action replaces the process by
--   calling an <tt>exec</tt> variant, it is made sure that the process
--   gets the text on it's file descriptor 0.
--   
--   In case the action fails (exits with an exit status other than 0, or
--   is terminated by a signal), the <tt>ProcessStatus</tt> is thrown, such
--   as reported by <a>getProcessStatus</a>. No attempt is made to create
--   more meaningful exceptions, like it is done by
--   <tt>runprog</tt>/<tt>subproc</tt>.
--   
--   Exceptions in the action result in an error message on
--   <tt>stderr</tt>, and the termination of the child. The parent gets a
--   <tt>ProcessStatus</tt> exception, with the value of <tt>Exited
--   (ExitFailure 1)</tt>. The following exceptions are understood, and
--   result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text are converted to the system character set. If
--   you need to pipe binary data, you should use <tt>h_pipe_to</tt>, and
--   set the returned handle to binary mode. This is accomplished by
--   <tt><a>hSetBinaryMode</a> h True</tt>. The system character set is
--   determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   pipe_to "blah" (exec "/usr/bin/foo" ["bar"])
--   </pre>
--   
--   Example: Access both <tt>stdin</tt> and <tt>stdout</tt> of an external
--   program.
--   
--   <pre>
--   import HsShellScript
--   
--   main = mainwrapper $ do
--   
--      res &lt;- pipe_from $
--         pipe_to "2\n3\n1" $
--            exec "/usr/bin/sort" []
--   
--      putStrLn res
--   </pre>
--   
--   See <a>subproc</a>, <a>runprog</a>, <a>-&lt;-</a>, <a>h_pipe_to</a>.
pipe_to :: String -> IO a -> IO ()

-- | Run an IO action as a separate process, and get a connection (a pipe)
--   to its <tt>stdin</tt> as a file handle.
--   
--   This forks a subprocess, which executes the specified action. A file
--   handle, which is connected to its <tt>stdin</tt>, is returned. The
--   child's <tt>ProcessID</tt> is returned as well. If the action replaces
--   the child process, by calling an <tt>exec</tt> variant, it is made
--   sure that its file descriptor 0 is connected to the returned file
--   handle.
--   
--   This gives you full control of the pipe, and of the forked process.
--   But you must cope with the child process by yourself.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Errors can only be detected by examining the child's process status
--   (using <a>getProcessStatus</a>). If the child action throws an
--   exception, an error message is printed on <tt>stderr</tt>, and the
--   child process exits with a <tt>ProcessStatus</tt> of <tt>Exited
--   (ExitFailure 1)</tt>. The following exceptions are understood, and
--   result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   If the child process exits in a way which signals an error, the
--   corresponding <tt>ProcessStatus</tt> is returned by
--   <tt>getProcessStatus</tt>. See <a>getProcessStatus</a> for details.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text are converted to the system character set. You
--   can set the returned handle to binary mode, by calling
--   <tt><a>hSetBinaryMode</a> handle True</tt>. The system character set
--   is determined by the environment variable <tt>LANG</tt>.
--   
--   Example:
--   
--   <pre>
--   (handle, pid) &lt;- h_pipe_to $ exec "/usr/bin/foo" ["bar"]
--   hPutStrLn handle "Some text to go through the pipe"
--   (Just ps) &lt;- getProcessStatus True False pid
--   when (ps /= Exited ExitSuccess) $
--      throw ps
--   </pre>
--   
--   See <a>-&lt;-</a>, <a>pipe_to</a>, <a>pipe_from</a>,
--   <a>pipe_from2</a>. See <a>HsShellScript#fdpipes</a> for more details.
h_pipe_to :: IO a -> IO (Handle, ProcessID)

-- | Run an IO action as a separate process, and read its <tt>stdout</tt>
--   strictly. Then wait for the child process to finish. This is like the
--   backquote feature of shells.
--   
--   This forks a child process, which executes the specified action. The
--   output of the child is read from its standard output. In case it
--   replaces the process by calling an <tt>exec</tt> variant, it is make
--   sure that the output is read from the new process' file descriptor 1.
--   
--   The end of the child's output is reached when either the standard
--   output is closed, or the child process exits. The program blocks until
--   the action exits, even if the child closes its standard output
--   earlier. So the parent process always notices a failure of the action
--   (when it exits in a way which indicates an error).
--   
--   When the child action exits in a way which indicates an error, the
--   corresponding <tt>ProcessStatus</tt> is thrown. See
--   <a>getProcessStatus</a>. No attempt is made to create more meaningful
--   exceptions, like it is done by <tt>runprog</tt>/<tt>subproc</tt>.
--   
--   Exceptions in the action result in an error message on
--   <tt>stderr</tt>, and the proper termination of the child. The parent
--   gets a <tt>ProcessStatus</tt> exception, with the value of <tt>Exited
--   (ExitFailure 1)</tt>. The following exceptions are understood, and
--   result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Unlike shells' backquote feature, <tt>pipe_from</tt> does not remove
--   any trailing newline characters. The entire output of the action is
--   returned. You might want to apply <tt>chomp</tt> to the result.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from stdin, is converted from
--   the system character set to Unicode. The system character set is
--   determined by the environment variable <tt>LANG</tt>. If you need to
--   read binary data from the forked process, you should use
--   <tt>h_pipe_from</tt> and set the returned handle to binary mode. This
--   is accomplished by <tt><a>hSetBinaryMode</a> h True</tt>.
--   
--   Example:
--   
--   <pre>
--   output &lt;- pipe_from $ exec "/bin/mount" []
--   </pre>
--   
--   Example: Access both <tt>stdin</tt> and <tt>stdout</tt> of an external
--   program.
--   
--   <pre>
--   import HsShellScript
--   
--   main = mainwrapper $ do
--   
--      res &lt;- pipe_from $
--         pipe_to "2\n3\n1" $
--            exec "/usr/bin/sort" []
--   
--      putStrLn res
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_to</a>, <a>pipe_from2</a>,
--   <a>h_pipe_from</a>, <a>lazy_pipe_from</a>, <tt>chomp</tt>,
--   <a>silently</a>.
pipe_from :: IO a -> IO String

-- | Run an IO action in a separate process, and read its standard output,
--   The output is read lazily, as the returned string is evaluated. The
--   child's output along with its process ID are returned.
--   
--   This forks a child process, which executes the specified action. The
--   output of the child is read lazily through a pipe, which connncts to
--   its standard output. In case the child replaces the process by calling
--   an <tt>exec</tt> variant, it is make sure that the output is read from
--   the new process' file descriptor 1.
--   
--   <tt>lazy_pipe_from</tt> calls <a>hGetContents</a>, in order to read
--   the pipe lazily. This means that the file handle goes to semi-closed
--   state. The handle holds a file descriptor, and as long as the string
--   isn't fully evaluated, this file descriptor won't be closed. For the
--   file descriptor to be closed, first its standard output needs to be
--   closed on the child side. This happens when the child explicitly
--   closes it, or the child process exits. When afterwards the string on
--   the parent side is completely evaluated, the handle, along with the
--   file descritor it holds, are closed and freed.
--   
--   If you use the string in such a way that you only access the beginning
--   of the string, the handle will remain in semi-closed state, holding a
--   file descriptor, even when the pipe is closed on the child side. When
--   you do that repeatedly, you may run out of file descriptors.
--   
--   Unless you're sure that your program will reach the string's end, you
--   should take care for it explicitly, by doing something like this:
--   
--   <pre>
--   (output, pid) &lt;- lazy_pipe_from (exec "\/usr\/bin\/foobar" [])
--   ...
--   seq (length output) (return ())
--   </pre>
--   
--   This will read the entire standard output of the child, even if it
--   isn't needed. You can't cut the child process' output short, when you
--   use <tt>lazy_pipe_from</tt>. If you need to do this, you should use
--   <tt>h_pipe_from</tt>, which gives you the handle, which can then be
--   closed by <a>hClose</a>, even if the child's output isn't completed:
--   
--   <pre>
--   (h, pid) &lt;- h_pipe_from io
--   
--   -- Lazily read io's output
--   output &lt;- hGetContents h
--   ...
--   -- Not eveyting read yet, but cut io short.
--   hClose h
--   
--   -- Wait for io to finish, and detect errors
--   (Just ps) &lt;- System.Posix.getProcessStatus True False pid
--   when (ps /= Exited ExitSuccess) $
--      throw ps
--   </pre>
--   
--   When you close the handle before all data has been read, then the
--   child gets a <tt>SIGPIPE</tt> signal.
--   
--   After all the output has been read, you should call
--   <tt>getProcessStatus</tt> on the child's process ID, in order to
--   detect errors. Be aware that you must evaluate the whole string,
--   before calling <tt>getProcessStatus</tt> blockingly, or you'll get a
--   deadlock.
--   
--   You won't get an exception, if the child action exits in a way which
--   indicates an error. Errors occur asynchronously, when the output
--   string is evaluated. You must detect errors by yourself, by calling
--   <a>getProcessStatus</a>.
--   
--   In case the action doesn't replace the child process with an external
--   program, an exception may be thrown out of the action. This results in
--   an error message on <tt>stderr</tt>, and the proper termination of the
--   child. The <tt>ProcessStatus</tt>, which can be accessed in the parent
--   process by <tt>getProcessStatus</tt>, is <tt>Exited (ExitFailure
--   1)</tt>. The following exceptions are understood, and result in
--   corresponding messages: <tt>ArgError</tt>, <tt>ProcessStatus</tt>,
--   <tt>RunError</tt>, <tt>IOError</tt> and <tt>ExitCode</tt>. Other
--   exceptions result in the generic message, as produced by
--   <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Unlike shells' backquote feature, <tt>lazy_pipe_from</tt> does not
--   remove any trailing newline characters. The entire output of the
--   action is returned. You might want to apply <tt>chomp</tt> to the
--   result.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from the IO action's stdout, are
--   converted from the system character set to Unicode. The system
--   character set is determined by the environment variable <tt>LANG</tt>.
--   If you need to read binary data from the forked process, you should
--   use h_pipe_from and set the returned handle to binary mode. This is
--   accomplished by <tt><a>hSetBinaryMode</a> h True</tt>. Then you can
--   lazily read the output of the action from the handle.
--   
--   Example: Lazily read binary data from an IO action. Don't forget to
--   collect the child process later, using <tt><a>getProcessStatus</a>
--   True False pid</tt>.
--   
--   <pre>
--   (h, pid) &lt;- h_pipe_from io
--   hSetBinaryMode h True
--   txt &lt;- hGetContents h
--   ...
--   (Just ps) &lt;- System.Posix.getProcessStatus True False pid
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_to</a>, <a>pipe_from</a>, <a>h_pipe_from</a>,
--   <a>lazy_pipe_from2</a>, <a>silently</a>.
lazy_pipe_from :: IO a -> IO (String, ProcessID)

-- | Run an IO action as a separate process, and connect to its
--   <tt>stdout</tt> with a file handle. This is like the backquote feature
--   of shells.
--   
--   This forks a subprocess, which executes the specified action. A file
--   handle, which is connected to its <tt>stdout</tt>, is returned. The
--   child's <tt>ProcessID</tt> is returned as well. If the action replaces
--   the child process, by calling an <tt>exec</tt> variant, it is made
--   sure that its file descriptor 1 is connected to the returned file
--   handle.
--   
--   This gives you full control of the pipe, and of the forked process.
--   But you must cope with the child process by yourself.
--   
--   When you call <tt>getProcessStatus</tt> blockingly, you must first
--   ensure that all data has been read, or close the handle. Otherwise
--   you'll get a deadlock. When you close the handle before all data has
--   been read, then the child gets a <tt>SIGPIPE</tt> signal.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Errors can only be detected by examining the child's process status
--   (using <a>getProcessStatus</a>). No attempt is made to create more
--   meaningful exceptions, like it is done by
--   <tt>runprog</tt>/<tt>subproc</tt>. If the child action throws an
--   exception, an error message is printed on <tt>stderr</tt>, and the
--   child process exits with a <tt>ProcessStatus</tt> of <tt>Exited
--   (ExitFailure 1)</tt>. The following exceptions are understood, and
--   result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from stdin, is converted from
--   the system character set to Unicode. The system character set is
--   determined by the environment variable <tt>LANG</tt>. If you need to
--   read binary data from the forked process, you can set the returned
--   handle to binary mode. This is accomplished by
--   <tt><a>hSetBinaryMode</a> h True</tt>.
--   
--   Example:
--   
--   <pre>
--   (h,pid) &lt;- h_pipe_from $ exec "/usr/bin/foo" ["bar"]
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_to</a>, <a>h_pipe_from2</a>,
--   <a>pipe_from</a>, <a>lazy_pipe_from</a>, <tt>chomp</tt>,
--   <a>silently</a>. See <a>HsShellScript#fdpipes</a> for more details.
h_pipe_from :: IO a -> IO (Handle, ProcessID)

-- | Run an IO action as a separate process, and read its standard error
--   output strictly. Then wait for the child process to finish. This is
--   like the backquote feature of shells. This function is exactly the
--   same as <tt>pipe_from</tt>, except that the standard error output is
--   read, instead of the standard output.
--   
--   This forks a child process, which executes the specified action. The
--   error output of the child is read from its standard error output. In
--   case it replaces the process by calling an <tt>exec</tt> variant, it
--   is made sure that the output is read from the new process' file
--   descriptor 2.
--   
--   The end of the child's error output is reached when either the
--   standard error output is closed, or the child process exits. The
--   program blocks until the action exits, even if the child closes its
--   standard error output earlier. So the parent process always notices a
--   failure of the action (which means it exits in a way which indicates
--   an error).
--   
--   When the child action exits in a way which indicates an error, the
--   corresponding <tt>ProcessStatus</tt> is thrown. See
--   <a>getProcessStatus</a>. No attempt is made to create more meaningful
--   exceptions, like it is done by <tt>runprog</tt>/<tt>subproc</tt>.
--   
--   Exceptions in the action result in an error message on
--   <tt>stderr</tt>, and the proper termination of the child. This means
--   that the error message is sent through the pipe, to the parent
--   process. The message can be found in the text which has been read from
--   the child process. It doesn't appear on the console.
--   
--   The parent gets a <tt>ProcessStatus</tt> exception, with the value of
--   <tt>Exited (ExitFailure 1)</tt>. The following exceptions are
--   understood, and result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Unlike shells' backquote feature, <tt>pipe_from2</tt> does not remove
--   any trailing newline characters. The entire error output of the action
--   is returned. You might want to apply <tt>chomp</tt> to the result.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from stdin, is converted from
--   the system character set to Unicode. The system character set is
--   determined by the environment variable <tt>LANG</tt>. If you need to
--   read binary data from the forked process, you should use
--   <tt>h_pipe_from</tt> and set the returned handle to binary mode. This
--   is accomplished by <tt><a>hSetBinaryMode</a> h True</tt>.
--   
--   Example:
--   
--   <pre>
--   output &lt;- pipe_from $ exec "/bin/mount" []
--   </pre>
--   
--   Example: Access both <tt>stdin</tt> and <tt>stdout</tt> of an external
--   program.
--   
--   <pre>
--   import HsShellScript
--   
--   main = mainwrapper $ do
--   
--      res &lt;- pipe_from $
--         pipe_to "2\n3\n1" $
--            exec "/usr/bin/sort" []
--   
--      putStrLn res
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_to</a>, <a>pipe_from</a>,
--   <a>h_pipe_from2</a>, <a>lazy_pipe_from2</a>, <a>silently</a>. See
--   <a>HsShellScript#fdpipes</a> for more details.
pipe_from2 :: IO a -> IO String

-- | Run an IO action in a separate process, and read its standard error
--   output, The output is read lazily, as the returned string is
--   evaluated. The child's error output along with its process ID are
--   returned.
--   
--   This forks a child process, which executes the specified action. The
--   error output of the child is read lazily through a pipe, which
--   connncts to its standard error output. In case the child replaces the
--   process by calling an <tt>exec</tt> variant, it is make sure that the
--   output is read from the new process' file descriptor 1.
--   
--   <tt>lazy_pipe_from</tt> calls <a>hGetContents</a>, in order to read
--   the pipe lazily. This means that the file handle goes to semi-closed
--   state. The handle holds a file descriptor, and as long as the string
--   isn't fully evaluated, this file descriptor won't be closed. For the
--   file descriptor to be closed, first its standard error output needs to
--   be closed on the child side. This happens when the child explicitly
--   closes it, or the child process exits. When afterwards the string on
--   the parent side is completely evaluated, the handle, along with the
--   file descritor it holds, are closed and freed.
--   
--   If you use the string in such a way that you only access the beginning
--   of the string, the handle will remain in semi-closed state, holding a
--   file descriptor, even when the pipe is closed on the child side. When
--   you do that repeatedly, you may run out of file descriptors.
--   
--   Unless you're sure that your program will reach the string's end, you
--   should take care for it explicitly, by doing something like this:
--   
--   <pre>
--   (errmsg, pid) &lt;- lazy_pipe_from2 (exec "/usr/bin/foobar" [])
--   ...
--   seq (length errmsg) (return ())
--   </pre>
--   
--   This will read the entire standard error output of the child, even if
--   it isn't needed. You can't cut the child process' output short, when
--   you use <tt>lazy_pipe_from</tt>. If you need to do this, you should
--   use <tt>h_pipe_from</tt>, which gives you the handle, which can then
--   be closed by <a>hClose</a>, even if the child's output isn't
--   completed:
--   
--   <pre>
--   (h, pid) &lt;- h_pipe_from io
--   
--   -- Lazily read io's output
--   output &lt;- hGetContents h
--   ...
--   -- Not eveyting read yet, but cut io short.
--   hClose h
--   
--   -- Wait for io to finish, and detect errors
--   (Just ps) &lt;- System.Posix.getProcessStatus True False pid
--   when (ps /= Exited ExitSuccess) $
--      throw ps
--   </pre>
--   
--   When you close the handle before all data has been read, then the
--   child gets a <tt>SIGPIPE</tt> signal.
--   
--   After all the output has been read, you should call
--   <tt>getProcessStatus</tt> on the child's process ID, in order to
--   detect errors. Be aware that you must evaluate the whole string,
--   before calling <tt>getProcessStatus</tt> blockingly, or you'll get a
--   deadlock.
--   
--   You won't get an exception, if the child action exits in a way which
--   indicates an error. Errors occur asynchronously, when the output
--   string is evaluated. You must detect errors by yourself, by calling
--   <a>getProcessStatus</a>.
--   
--   In case the action doesn't replace the child process with an external
--   program, an exception may be thrown out of the action. This results in
--   an error message on <tt>stderr</tt>. This means that the message is
--   sent through the pipe, to the parent process. Then the child process
--   is properly terminated. The <tt>ProcessStatus</tt>, which can be
--   accessed in the parent process by <tt>getProcessStatus</tt>, is
--   <tt>Exited (ExitFailure 1)</tt>. The following exceptions are
--   understood, and result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from stdin, is converted from
--   the system character set to Unicode. The system character set is
--   determined by the environment variable <tt>LANG</tt>. If you need to
--   read binary data from the forked process, you can set the returned
--   handle to binary mode. This is accomplished by
--   <tt><a>hSetBinaryMode</a> h True</tt>.
--   
--   Unlike shells' backquote feature, <tt>lazy_pipe_from</tt> does not
--   remove any trailing newline characters. The entire output of the
--   action is returned. You might want to apply <tt>chomp</tt> to the
--   result.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from the IO action's stdout, are
--   converted from the system character set to Unicode. The system
--   character set is determined by the environment variable <tt>LANG</tt>.
--   If you need to read binary data from the forked process' standard
--   error output, you should use h_pipe_from2 and set the returned handle
--   to binary mode. This is accomplished by <tt><a>hSetBinaryMode</a> h
--   True</tt>. Then you can lazily read the output of the action from the
--   handle.
--   
--   Example: Lazily read binary data from an IO action. Don't forget to
--   collect the child process later, using <tt><a>getProcessStatus</a>
--   True False pid</tt>.
--   
--   <pre>
--   (h, pid) &lt;- h_pipe_from2 io
--   hSetBinaryMode h True
--   txt &lt;- hGetContents h
--   ...
--   (Just ps) &lt;- System.Posix.getProcessStatus True False pid
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_to</a>, <a>pipe_from2</a>,
--   <a>h_pipe_from2</a>, <a>lazy_pipe_from</a>, <a>silently</a>.
lazy_pipe_from2 :: IO a -> IO (String, ProcessID)

-- | Run an IO action as a separate process, and connect to its
--   <tt>stderr</tt> with a file handle.
--   
--   This forks a subprocess, which executes the specified action. A file
--   handle, which is connected to its <tt>stderr</tt>, is returned. The
--   child's <tt>ProcessID</tt> is returned as well. If the action replaces
--   the child process, by calling an <tt>exec</tt> variant, it is made
--   sure that its file descriptor 2 is connected to the returned file
--   handle.
--   
--   This gives you full control of the pipe, and of the forked process.
--   But you must cope with the child process by yourself.
--   
--   When you call <tt>getProcessStatus</tt> blockingly, you must first
--   ensure that all data has been read, or close the handle. Otherwise
--   you'll get a deadlock. When you close the handle before all data has
--   been read, then the child gets a <tt>SIGPIPE</tt> signal.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. The child process is then properly terminated, such that no
--   resources, which have been duplicated by the fork, cause problems. See
--   <a>HsShellScript#subr</a> for details.
--   
--   Errors can only be detected by examining the child's process status
--   (using <a>getProcessStatus</a>). No attempt is made to create more
--   meaningful exceptions, like it is done by
--   <tt>runprog</tt>/<tt>subproc</tt>. If the child action throws an
--   exception, an error message is printed on <tt>stderr</tt>. This means
--   that the message goes through the pipe to the parent process. Then the
--   child process exits with a <tt>ProcessStatus</tt> of <tt>Exited
--   (ExitFailure 1)</tt>. The following exceptions are understood, and
--   result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   The pipe is set to <i>text mode</i>. This means that the Unicode
--   characters in the text, which is read from stdin, is converted from
--   the system character set to Unicode. The system character set is
--   determined by the environment variable <tt>LANG</tt>. If you need to
--   read binary data from the forked process, you can set the returned
--   handle to binary mode. This is accomplished by
--   <tt><a>hSetBinaryMode</a> h True</tt>.
--   
--   Example:
--   
--   <pre>
--   (h,pid) &lt;- h_pipe_from $ exec "/usr/bin/foo" ["bar"]
--   </pre>
--   
--   See <a>exec</a>, <a>pipe_from</a>, <a>pipe_from2</a>,
--   <a>h_pipe_from</a>, <a>pipe_to</a>, <a>lazy_pipe_from</a>,
--   <tt>chomp</tt>, <a>silently</a>.
h_pipe_from2 :: IO a -> IO (Handle, ProcessID)

-- | Run an IO action as a separate process, and optionally connect to its
--   <tt>stdin</tt>, its <tt>stdout</tt> and its <tt>stderr</tt> output
--   with pipes.
--   
--   This forks a subprocess, which executes the specified action. The
--   child's <tt>ProcessID</tt> is returned. Some of the action's standard
--   handles are made to connected to pipes, which the caller can use in
--   order to communicate with the new child process. Which, this is
--   determined by the first three arguments.
--   
--   You get full control of the pipes, and of the forked process. But you
--   must cope with the child process by yourself.
--   
--   Errors in the child process can only be detected by examining its
--   process status (using <a>getProcessStatus</a>). If the child action
--   throws an exception, an error message is printed on <tt>stderr</tt>,
--   and the child process exits with a <tt>ProcessStatus</tt> of
--   <tt>Exited (ExitFailure 1)</tt>. The following exceptions are
--   understood, and result in corresponding messages: <tt>ArgError</tt>,
--   <tt>ProcessStatus</tt>, <tt>RunError</tt>, <tt>IOError</tt> and
--   <tt>ExitCode</tt>. Other exceptions result in the generic message, as
--   produced by <tt>show</tt>.
--   
--   Unless you replace the child process, calling an <tt>exec</tt>
--   variant, the child should let the control flow leave the action
--   normally. It is then properly take care of.
--   
--   The pipes are set to <i>text mode</i>. When connecting to the child's
--   <tt>stdin</tt>, this means that the Unicode characters in the Haskell
--   side text are converted to the system character set. When reading from
--   the child's <tt>stdout</tt> or <tt>stderr</tt>, the text is converted
--   from the system character set to Unicode in the Haskell-side strings.
--   The system character set is determined by the environment variable
--   <tt>LANG</tt>. If you need to read or write binary data, then this is
--   no problem. Just call <tt><a>hSetBinaryMode</a> handle True</tt>. This
--   sets the corresponding pipe to binary mode.
--   
--   See <a>pipe_from</a>, <a>h_pipe_from</a>, <a>pipe_from2</a>,
--   <a>h_pipe_from2</a>, <a>pipe_to</a>, <a>h_pipe_to</a>,
--   <a>lazy_pipe_from</a>, <a>lazy_pipe_from2</a>
pipes :: IO a -> Bool -> Bool -> Bool -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessID)

-- | Create a temporary file. This will create a new, empty file, with
--   read-write permissions for the user, and no permissons for the group
--   and others. The path consists of the specified prefix, a dot, and six
--   random characters (digits and letters).
--   
--   <pre>
--   tmp_file prefix = temp_file 6 (prefix ++ ".") ""
--   </pre>
--   
--   See <a>temp_file</a>, <a>tmp_dir</a>, <a>with_tmp_file</a>.
tmp_file :: String -> IO FilePath

-- | Create a temporary directory. This will create a new directory, with
--   read-write-execute permissions for the user (unless further restricted
--   by the process's umask), and no permissons for the group and others.
--   The path consists of the specified prefix, a dot, and six random
--   characters (digits and letters).
--   
--   <pre>
--   tmp_dir prefix = temp_dir 6 (prefix ++ ".") ""
--   </pre>
--   
--   See <a>temp_dir</a>, <a>tmp_file</a>, <a>with_tmp_dir</a>.
tmp_dir :: String -> IO FilePath

-- | Create a temporary file. This will create a new, empty file, with a
--   path which did not previously exist in the file system. The path
--   consists of the specified prefix, a sequence of random characters
--   (digits and letters), and the specified suffix. The file is created
--   with read-write permissions for the user, and no permissons for the
--   group and others. The ownership is set to the effective user ID of the
--   process. The group ownership is set either to the effective group ID
--   of the process or to the group ID of the parent directory (depending
--   on filesystem type and mount options on Linux - see <tt>open(2)</tt>
--   for details).
--   
--   See <a>tmp_file</a>, <a>temp_dir</a>, <a>with_temp_file</a>.
temp_file :: Int -> String -> String -> IO FilePath

-- | Create a temporary directory. This will create a new directory, with a
--   path which did not previously exist in the file system. The path
--   consists of the specified prefix, a sequence of random characters
--   (digits and letters), and the specified suffix. The directory is
--   normally created with read-write-execute permissions for the user, and
--   no permissons for the group and others. But this may be further
--   restricted by the process's umask in the usual way.
--   
--   The newly created directory will be owned by the effective uid of the
--   process. If the directory containing the it has the set group id bit
--   set, or if the filesystem is mounted with BSD group semantics, the new
--   directory will inherit the group ownership from its parent; otherwise
--   it will be owned by the effective gid of the process. (See
--   <tt>mkdir(2)</tt>)
--   
--   See <a>tmp_dir</a>, <a>temp_file</a>, <a>with_temp_dir</a>.
temp_dir :: Int -> String -> String -> IO FilePath

-- | Create a temporary path. This will generate a path which does not yet
--   exist in the file system. It consists of the specified prefix, a
--   sequence of random characters (digits and letters), and the specified
--   suffix.
--   
--   <i>Avoid relying on the generated path not to exist in the file
--   system.</i> Or else you'll get a potential race condition, since some
--   other process might create the path after <tt>temp_path</tt>, before
--   you use it. This is a security risk. The global random number
--   generator (<tt>Random.randomRIO</tt>) is used to generate the random
--   characters. These might not be that random after all, and could
--   potentially be guessed. Rather use <tt>temp_file</tt> or
--   <tt>temp_dir</tt>.
--   
--   See <a>temp_file</a>, <a>temp_dir</a>.
temp_path :: Int -> String -> String -> IO FilePath

-- | Create and open a temporary file, perform some action with it, and
--   delete it afterwards. This is a front end to the <a>tmp_file</a>
--   function. The file and its path are created in the same way. The IO
--   action is passed a handle of the new file. When it finishes - normally
--   or with an exception - the file is deleted.
--   
--   See <a>tmp_file</a>, <a>with_temp_file</a>, <a>with_tmp_dir</a>.
with_tmp_file :: String -> (Handle -> IO a) -> IO a

-- | Create a temporary directory, perform some action with it, and delete
--   it afterwards. This is a front end to the <a>tmp_dir</a> function. The
--   directory and its path are created in the same way. The IO action is
--   passed the path of the new directory. When it finishes - normally or
--   with an exception - the directory is deleted.
--   
--   The action must clean up any files it creates inside the directory by
--   itself. <tt>with_temp_dir</tt> doesn't delete any files inside, so the
--   directory could be removed. If the directory isn't empty, an
--   <tt>IOError</tt> results (with the path filled in). When the action
--   throws an exception, and the temporary directory cannot be removed,
--   then the exception is passed through, rather than replacing it with
--   the IOError. (This is because it's probably exactly because of that
--   exception that the directory isn't empty and can't be removed).
--   
--   <pre>
--   with_tmp_dir prefix io = with_temp_dir 6 (prefix ++ ".") "" io
--   </pre>
--   
--   See <a>tmp_dir</a>, <a>with_temp_dir</a>, <a>with_tmp_file</a>.
with_tmp_dir :: String -> (FilePath -> IO a) -> IO a

-- | Create and open a temporary file, perform some action with it, and
--   delete it afterwards. This is a front end to the <a>temp_file</a>
--   function. The file and its path are created in the same way. The IO
--   action is passed a handle of the new file. When it finishes - normally
--   or with an exception - the file is deleted.
--   
--   See <a>temp_file</a>, <a>with_tmp_file</a>, <a>with_temp_dir</a>.
with_temp_file :: Int -> String -> String -> (Handle -> IO a) -> IO a

-- | Create a temporary directory, perform some action with it, and delete
--   it afterwards. This is a front end to the <a>temp_dir</a> function.
--   The directory and its path are created in the same way. The IO action
--   is passed the path of the new directory. When it finishes - normally
--   or with an exception - the directory is deleted.
--   
--   The action must clean up any files it creates inside the directory by
--   itself. <tt>with_temp_dir</tt> doesn't delete any files inside, so the
--   directory could be removed. If the directory isn't empty, an
--   <tt>IOError</tt> results (with the path filled in). When the action
--   throws an exception, and the temporary directory cannot be removed,
--   then the exception is passed through, rather than replacing it with
--   the IOError. (This is because it's probably exactly because of that
--   exception that the directory isn't empty and can't be removed).
--   
--   See <a>temp_dir</a>, <a>with_tmp_dir</a>, <a>with_temp_file</a>.
with_temp_dir :: Int -> String -> String -> (FilePath -> IO a) -> IO a

-- | One entry of mount information. This is the same as <tt>struct
--   mntent</tt> from <tt>&lt;mntent.h&gt;</tt>. A list of these is
--   returned by the functions which read mount information.
--   
--   See <a>read_mounts</a>, <a>read_mtab</a>, <a>read_fstab</a>.
data Mntent
Mntent :: String -> String -> String -> String -> Int -> Int -> Mntent

-- | Device file ("name of mounted file system")
[mnt_fsname] :: Mntent -> String

-- | Mount point
[mnt_dir] :: Mntent -> String

-- | Which kind of file system ("see mntent.h")
[mnt_type] :: Mntent -> String

-- | Mount options ("see mntent.h")
[mnt_opts] :: Mntent -> String

-- | Dump frequency in days
[mnt_freq] :: Mntent -> Int

-- | "Pass number on parallel fsck"
[mnt_passno] :: Mntent -> Int

-- | Read mount information. This is a front end to the
--   <tt>setmntent(3)</tt>, <tt>getmntent(3)</tt>, <tt>endmntent(3)</tt>
--   system library functions.
--   
--   When the <tt>setmntent</tt> call fails, the <tt>errno</tt> value is
--   converted to an <tt>IOError</tt> and thrown.
--   
--   See <a>read_mtab</a>, <a>read_fstab</a>.
read_mounts :: String -> IO [Mntent]

-- | Get the currently mounted file systems.
--   
--   <pre>
--   read_mtab = read_mounts "/etc/mtab"
--   </pre>
--   
--   See <a>read_mounts</a>.
read_mtab :: IO [Mntent]

-- | Get the system wide file system table.
--   
--   <pre>
--   read_fstab = read_mounts "/etc/fstab"
--   </pre>
--   
--   See <a>read_mounts</a>.
read_fstab :: IO [Mntent]

-- | Print text to <tt>stdout</tt>.
--   
--   This is a shorthand for <tt>putStrLn</tt>, except for <tt>stderr</tt>
--   being flushed beforehand. This way normal output and error output
--   appear in order, even when they aren't buffered as by default.
--   
--   An additional newline is printed at the end.
--   
--   <pre>
--   outm msg = do
--      hFlush stderr
--      putStrLn msg
--   </pre>
outm :: String -> IO ()

-- | Print text to <tt>stdout</tt>.
--   
--   This is a shorthand for <tt>putStr</tt>, except for <tt>stderr</tt>
--   being flushed beforehand. This way normal output and error output
--   appear in order, even when they aren't buffered as by default.
--   
--   No newline is printed at the end.
--   
--   <pre>
--   outm_ msg = do
--      hFlush stderr
--      putStr msg
--   </pre>
outm_ :: String -> IO ()

-- | Colorful log message to <tt>stderr</tt>.
--   
--   This prints a message to <tt>stderr</tt>. When <tt>stderr</tt> is
--   connected to a terminal (as determined by <tt>isatty(3)</tt>),
--   additional escape sequences are printed, which make the message appear
--   in cyan. Additionally, a newline character is output at the end.
--   
--   <tt>stdout</tt> is flushed beforehand. So normal output and error
--   output appear in order, even when they aren't buffered as by default.
--   
--   See <a>logm_</a>, <a>errm</a>, <a>errm_</a>.
logm :: String -> IO ()

-- | Colorful log message to <tt>stderr</tt>.
--   
--   This prints a message to <tt>stderr</tt>. When <tt>stderr</tt> is
--   connected to a terminal (as determined by <tt>isatty(3)</tt>),
--   additional escape sequences are printed, which make the message appear
--   in cyan. No a newline character is output at the end.
--   
--   <tt>stdout</tt> is flushed beforehand. So normal output and error
--   output appear in order, even when they aren't buffered as by default.
--   
--   See <a>logm</a>, <a>errm</a>, <a>errm_</a>.
logm_ :: String -> IO ()

-- | Colorful error message to <tt>stderr</tt>.
--   
--   This prints a message to <tt>stderr</tt>. When <tt>stderr</tt> is
--   connected to a terminal (as determined by <tt>isatty(3)</tt>),
--   additional escape sequences are printed, which make the message appear
--   in red. Additionally, a newline character is output at the end.
--   
--   <tt>stdout</tt> is flushed beforehand. So normal output and error
--   output appear in order, even when they aren't buffered as by default.
--   
--   See <a>logm</a>, <a>logm_</a>, <a>errm_</a>.
errm :: String -> IO ()

-- | Colorful error message to <tt>stderr</tt>.
--   
--   This prints a message to <tt>stderr</tt>. When <tt>stderr</tt> is
--   connected to a terminal (as determined by <tt>isatty(3)</tt>),
--   additional escape sequences are printed, which make the message appear
--   in red. No a newline character is output at the end.
--   
--   <tt>stdout</tt> is flushed beforehand. So normal output and error
--   output appear in order, even when they aren't buffered as by default.
--   
--   See <a>logm</a>, <a>logm_</a>, <a>errm</a>.
errm_ :: String -> IO ()

-- | Check if a handle is connected to a terminal.
--   
--   This is a front end to the <tt>isatty(3)</tt> function (see man page).
--   It is useful, for instance, to determine if color escape sequences
--   should be generated.
isatty :: Handle -> IO Bool

-- | Determine the terminal width in columns.
--   
--   This value can be used to format output to fit the terminal.
--   
--   This queries the terminal which is connected to stdout. It may happen,
--   that stdout isn't connected to a terminal, for instance when the
--   program is part of a pipe. In this case, <tt>Nothing</tt> is returned.
--   No exception is thrown.
--   
--   See <a>terminal_width_ioe</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>, <a>usage_info</a>, <a>wrap</a>.
terminal_width :: Handle -> IO (Maybe Int)

-- | Determine the terminal width in columns.
--   
--   This value can be used to format output to fit the terminal.
--   
--   This queries the terminal which is connected to stdout. It may happen,
--   that stdout isn't connected to a terminal. For instance when the
--   program is part of a pipe. In this case, an IOError is thrown.
--   
--   See <a>terminal_width</a>, <a>make_usage_info</a>,
--   <a>print_usage_info</a>, <a>usage_info</a>, <a>wrap</a>.
terminal_width_ioe :: Handle -> IO Int

-- | Format an <tt>Int</tt> with leading zeros. If the string
--   representation of the <tt>Inŧ</tt> is longer than the number of
--   characters to fill up, this produces as many characters as needed.
zeros :: Int -> Int -> String

-- | Remove trailing newlines. This is silimar to perl's <tt>chomp</tt>
--   procedure.
chomp :: String -> String

-- | Get contents of a file or of <tt>stdin</tt>. This is a simple frontend
--   to <tt>hGetContents</tt>. A file name of <tt>"-"</tt> designates
--   stdin. The contents are read lazily as the string is evaluated.
--   
--   (The handle which we read from will be in semi-closed state. Once all
--   input has read, it is closed automatically (Haskell Library Report
--   11.2.1). Therefore we don't need to return it).
--   
--   <pre>
--   lazy_contents path = do
--       h   &lt;- if path == "-" then return stdin else openFile path ReadMode
--       hGetContents h
--   </pre>
lazy_contents :: String -> IO String

-- | Get contents of a file or of <tt>stdin</tt> eagerly. This is the same
--   as <tt>lazy_contents</tt>, except for the contents being read
--   immediately.
contents :: String -> IO String

-- | This is an interface to the POSIX <tt>glob</tt> function, which does
--   wildcard expansion in paths. The sorted list of matched paths is
--   returned. It's empty for no match (rather than the original pattern).
--   In case anything goes wrong (such as permission denied), an IOError is
--   thrown.
--   
--   This does <i>not</i> do tilde expansion, which is done (among many
--   unwanted other things) by <tt>wordexp</tt>. The only flag used for the
--   call to <tt>glob</tt> is <tt>GLOB_ERR</tt>.
--   
--   The behaviour in case of non-existing path components is inconsistent
--   in the GNU version of the underlying <tt>glob</tt> function. <tt>glob
--   "/doesnt_exist/foo"</tt> will return the empty list, whereas <tt>glob
--   "/doesnt_exist/*"</tt> causes a "No such file or directory" IOError.
--   
--   See man pages <tt>glob(3)</tt> and <tt>wordexp(3)</tt>.
glob :: String -> IO [String]

-- | Quote special characters for use with the <tt>glob</tt> function.
--   
--   The characters <tt>*</tt>, <tt>?</tt>, <tt>[</tt> and <tt>\</tt> must
--   be quoted by preceding backslashs, when they souldn't have their
--   special meaning. The <tt>glob_quote</tt> function does this.
--   
--   You can't use <tt>quote</tt> or <tt>shell_quote</tt>.
--   
--   See <a>glob</a>, <tt>quote</tt>, <tt>shell_quote</tt>
glob_quote :: String -> String

-- | Error reporting wrapper for the <tt>main</tt> function. This catches
--   any HsShellScript generated exceptions, and <tt>IOError</tt>s, prints
--   an error message and exits with <tt>exitFailure</tt>. The
--   <tt>main</tt> function typically looks like this:
--   
--   <pre>
--   main = mainwrapper $ do ...
--   </pre>
--   
--   The exceptions caught are <a>ArgError</a>, <a>RunError</a>,
--   <a>ProcessStatus</a> and <tt>IOError</tt>.
mainwrapper :: IO a -> IO a

-- | Read the global system error number. This is the POSIX <tt>errno</tt>
--   value. This function is redundant. Use
--   <tt>Foreign.C.Error.getErrno</tt> instead.
errno :: IO Errno

-- | Generate an error message from an <tt>errno</tt> value. This is the
--   POSIX <tt>strerror</tt> system library function.
--   
--   See the man page <tt>strerror(3)</tt>.
strerror :: Errno -> IO String

-- | Print error message corresponding to the specified <tt>errno</tt>
--   error number. This is similar to the POSIX system library function
--   <tt>perror</tt>.
--   
--   See the man page <tt>perror(3)</tt>.
perror' :: Errno -> String -> IO ()

-- | Print error message corresponding to the global <tt>errno</tt> error
--   number. This is the same as the POSIX system library function
--   <tt>perror</tt>.
--   
--   See the man page <tt>perror(3)</tt>.
perror :: String -> IO ()

-- | Forcibly terminate the program, circumventing normal program shutdown.
--   
--   This is the <tt>_exit(2)</tt> system call. No cleanup actions
--   installed with <tt>bracket</tt> are performed, no data buffered by
--   file handles is written out, etc.
_exit :: Int -> IO a

-- | Print a message to <tt>stderr</tt> and exit with an exit code
--   indicating an error.
--   
--   <pre>
--   failIO msg = hPutStrLn stderr msg &gt;&gt; exitFailure
--   </pre>
failIO :: String -> IO a

-- | Modify an IO action to return the exit code of a failed program call,
--   instead of throwing an exception.
--   
--   This is used to modify the error reporting behaviour of an IO action
--   which uses 'run'/'runprog' or 'call'/'subproc'. When an external
--   program exits with an exit code which indicates an error, normally an
--   exception is thrown. After <tt>exitcode</tt> has been applied, the
--   exit code is retruned instead.
--   
--   The caught exceptions are <a>RunError</a> and <a>ProcessStatus</a>.
--   Termination by a signal is still reported by an exception, which is
--   passed through.
--   
--   Example: <tt>ec &lt;- exitcode $ runprog "foo" ["bar"]</tt>
--   
--   See <a>runprog</a>, <a>subproc</a>, <a>run</a>, <a>call</a>.
exitcode :: IO () -> IO ExitCode

-- | Create and throw an <tt>IOError</tt> from the current <tt>errno</tt>
--   value, an optional handle and an optional file name.
--   
--   This is an extended version of the <tt>Foreign.C.Error.throwErrno</tt>
--   function from the GHC libraries, which additionally allows to specify
--   a handle and a file name to include in the <tt>IOError</tt> thrown.
--   
--   See <tt>Foreign.C.Error.throwErrno</tt>,
--   <tt>Foreign.C.Error.errnoToIOError</tt>.
throwErrno' :: String -> Maybe Handle -> Maybe FilePath -> IO a

-- | Convert an <tt>IOError</tt> to a string.
--   
--   There is an instance declaration of <tt>IOError</tt> in <tt>Show</tt>
--   in the <tt>GHC.IO</tt> library, but <tt>show_ioerror</tt> produces a
--   more readable, and more complete, message.
show_ioerror :: IOError -> String

-- | In case the specified action throws an IOError, fill in its filename
--   field. This way, more useful error messages can be produced.
--   
--   Example:
--   
--   <pre>
--   -- Oh, the GHC libraries neglect to fill in the file name
--   executeFile' prog a b c =
--      fill_in_filename prog $ executeFile prog a b c
--   </pre>
--   
--   See <a>fill_in_location</a>, <a>add_location</a>.
fill_in_filename :: String -> IO a -> IO a

-- | In case the specified action throws an IOError, fill in its location
--   field. This way, more useful error messages can be produced.
--   
--   Example:
--   
--   <pre>
--   my_fun a b c = do
--      -- ...
--      fill_in_location "my_fun" $  -- Give the caller a more useful location information in case of failure
--         rename "foo" "bar"
--      -- ...
--   </pre>
--   
--   See <a>fill_in_filename</a>.
fill_in_location :: String -> IO a -> IO a

-- | In case the specified action throws an IOError, add a line to its
--   location field. This way, more useful error messages can be produced.
--   The specified string is prepended to the old location, separating it
--   with a newline from the previous location, if any. When using this
--   thoroughly, you get a reverse call stack in IOErrors.
--   
--   Example:
--   
--   <pre>
--   my_fun =
--      add_location "my_fun" $ do
--         -- ...
--   </pre>
--   
--   See <a>fill_in_filename</a>, <a>fill_in_location</a>.
add_location :: String -> IO a -> IO a
