- HsShellScript has facilities for managing command line arguments, which are - easier to use than the GHC library GetOpt. Command line - arguments are specified as lists of properties. HsShellScript builds on top - of GHC's GetOpt, but hides it completely. Command line arguments handling - has been added because GetOpt was found to be too cumbersome.
-- Calling programs and recognizing errors (via exitcode or exception) is made more easy. There are front end functions for common programs, such as - /bin/mv or /bin/chmod.
-- Dealing with paths is not as trivial as it sounds. Take, for example - ../foo.bar//./../baz/ (and split off the extension of the file - name...). HsShellScript solves this thoroughly and provides functions for such - tasks as splitting a path in directory and file name parts, splitting a path - into path components, or syntactically normalising paths.
-- HsShellScript defines operators like ->- and ->>- which work like - redirection operators in shells.
-- Reading the output of an external program, or piping the output of one - program into the input of another, is almost as easy as in shells. - HsShellScript provides corresponding operators.
-- Error handling is one thing which is done more thoroughly in - HsShellScript than in shells. Failed programs won't be silently ignored. - Exceptions are used for error handling. Non zero exit codes - are thrown as exceptions.
-- Taking care of shell metacharacters usually isn't done right. HsShellScript - provides functions for doing it safely.
-- The standard C library has mkstemp, mktemp, tempnam, tmpfile and tmpnam, which are all broken, - non-portable or unsuitable in some way.
- - --HsShellScript User Manual main page
- - diff --git a/manual/imports.html b/manual/imports.html deleted file mode 100644 --- a/manual/imports.html +++ /dev/null @@ -1,27 +0,0 @@ - - - - -In order to use HsShellScript's exception handling, you'll have to import
-some and restrict some GHC-libraries (all of which are included in GHC). The
-following source code will to the trick:
-
-
-
-
-
-
-
import Prelude hiding (catch)
-
import IO hiding (catch)
-
import Control.Exception
-
import HsShellScript
-
-HsShellScript User Manual main page
- - - diff --git a/manual/index.html b/manual/index.html deleted file mode 100644 --- a/manual/index.html +++ /dev/null @@ -1,28 +0,0 @@ - - - - -This is the user manual for the HsShellScript -Haskell shell scripting library, version 3.3.2. It has been released 2014-08-06. The API -documentation is in a separate document.
-HsShellScript is a library which makes things easy to program in -Haskell, which are typically done by shell scripts on Unix-like -systems. You can use Haskell for writing your shell scripts.
-So your Haskell scripts can grow to become real programs. It's all ready. - -
Features
-
Requirements
-
Installation
-
Usage
-
Necessary import declarations
-
License
-Last changed 2014-08-06
- - diff --git a/manual/install.html b/manual/install.html deleted file mode 100644 --- a/manual/install.html +++ /dev/null @@ -1,48 +0,0 @@ - - - - -HsShellScript is cabalized, which means that building and installing is a - matter of some calls to cabal. However, it also provides a - Makefile, which further simplifies the installation. - -
In order to install, unpack the source distribution somewhere. Go to the - directory, and call make. This will compile the library. If you want - to install it locally, in your user account, then do make - install-user. This calls cabal install --user. If you want to - install the library globally, do make install-global. You will be - prompted for the root password, which is needed in this case. This - calls sudo cabal install --global. - -
If installed as a user package, then the location of the API documentation - is ~/.cabal/share/doc/hsshellscript-3.3.1/html/index.html. If it is - installed globaly, it - is /usr/local/share/doc/hsshellscript-3.3.1/html/index.html. - -
Cabal's Simple Build Infrastructure doesn't provide any means to add extra - documenation to a project. Therefore the user manual isn't installed by default. - If you need it, you can just copy the "manual" directory anywhere you like, - but the Makefile privides - the make target install-manual, which copies the files to - /usr/local/share/hsshellscript/manual. - - -
Further information about the Cabal can be found here: -The Haskell Cabal - - -
HsShellScript User Manual main - page
- - diff --git a/manual/requirements.html b/manual/requirements.html deleted file mode 100644 --- a/manual/requirements.html +++ /dev/null @@ -1,39 +0,0 @@ - - - - -Requirements for using and for building -
The Glasgow Haskell - Compiler. - It works with GHC-7.8.3, and - should also work with versions 7.8.0 upwards. Because of incompatible - changes in GHC, it does not work with GHC-7.6 and older. -
- -A Unix like system. HsShellScript is being developed and tested on Linux.
-Requirements only for building -
-GHC and Haddock are included in - the The Haskell Platform. - -
-HsShellScript User Manual main page
- - - diff --git a/manual/usage.html b/manual/usage.html deleted file mode 100644 --- a/manual/usage.html +++ /dev/null @@ -1,26 +0,0 @@ - - - - -HsShellScript registers itself in GHC's package management system during installation. Therefore all you need is to add
-"-package hsshellscript" to the command line when compiling and linking.
-HsShellScript User Manual main page
- - - diff --git a/src/HsShellScript.hs b/src/HsShellScript.hs --- a/src/HsShellScript.hs +++ b/src/HsShellScript.hs @@ -1,11 +1,11 @@ -- HsShellScript main module module HsShellScript ( -- * Command Line Arguments - -- Command line arguments are handled by the module "HsShellScript.Args", which is reexported by "HsShellScript". module HsShellScript.Args, -- * Paths and Directories mkdir, rmdir, pwd, cd, realpath, realpath_s, path_exists, path_exists', is_file, is_dir, with_wd, + -- ** Parsing and Composing Paths module HsShellScript.Paths, @@ -14,7 +14,8 @@ -- * Manipulating Files rm, chmod, chown, cp, mv, - HsShellScript.Commands.rename, rename_mv, force_rename, force_mv, force_rename_mv, force_cmd, force_writeable, force_writeable2, + HsShellScript.Commands.rename, rename_mv, force_rename, force_mv, force_rename_mv, force_cmd, + force_writeable, force_writeable2, getFileStatus', fileAccess', setFileMode', -- * Interfaces to Some Specific External Commands @@ -55,13 +56,15 @@ pipe_to, h_pipe_to, pipe_from, lazy_pipe_from, h_pipe_from, pipe_from2, lazy_pipe_from2, h_pipe_from2, + pipe_from_full, pipe_from_full2, pipes, -- * Shell-like Quoting module HsShellScript.Shell, -- * Creating temporary files and directories - tmp_file, tmp_dir, temp_file, temp_dir, temp_path, with_tmp_file, with_tmp_dir, with_temp_file, with_temp_dir, + tmp_file, tmp_dir, temp_file, temp_dir, temp_path, with_tmp_file, with_tmp_dir, with_temp_file, + with_temp_dir, -- * Reading mount information Mntent(..), read_mounts, read_mtab, read_fstab, @@ -287,7 +290,7 @@ thrown, and the process continues with normal error handling. Normally, the @exec@ functions are used in conjunction with some of the functions which fork a child process. They also handle errors, so the forked action doesn't - need to cope with failure of @exec@. The error handling and + need to deal with failure of @exec@. The error handling and termination is done via the 'child' function. Sometimes you want to pass an open file descriptor to the program. In this diff --git a/src/HsShellScript/Args.chs b/src/HsShellScript/Args.chs --- a/src/HsShellScript/Args.chs +++ b/src/HsShellScript/Args.chs @@ -1,6 +1,6 @@ -- | -- This module provides a more convient way of parsing command line --- arguments than the GHC GetOpt package. It uses GetOpt, but hides +-- arguments than the GHC GetOpt package. It builds on top of 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 @@ -23,7 +23,7 @@ -- > -- >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 {-...-} ] +-- >d_switch = argdesc [ desc_long "doit", desc_at_most_once {-...-} ] -- >-- ... -- > -- >args = unsafe_getargs header descs @@ -146,13 +146,13 @@ deriving (Eq, Show, Ord) --- | Argument value tester function. This tests the format of an argument's value for errors. The tester function is specified by --- 'desc_tester' or such, as part of the argument description. +-- | Argument value tester function. This tests the format of an argument's value for errors. The tester function +-- is specified by 'desc_tester' or such, as part of the argument description. -- --- The tester is passed the argument value. If the format is correct, then it returns @Nothing@. If there is an error, then it returns @Just msgf@, --- with @msgf@ 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 'argname' or 'argname_a') to be included --- in the error message. +-- The tester is passed the argument value. If the format is correct, then it returns @Nothing@. If there is an +-- error, then it returns @Just msgf@, with @msgf@ 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 'argname' or 'argname_a') to be included in the error message. type Argtester = String -- Argument value to be tested -> Maybe (ArgumentDescription -- Argument description for message generation -> String -- Error message @@ -161,20 +161,22 @@ -- | Description of one command line argument. These are generated by -- @argdesc@ from a list of argument properties, and subsequently used by one of the --- @getargs@... functions. +-- @getargs@... functions. + data ArgumentDescription = ArgumentDescription { - argdesc_short_args :: [Char], -- ^ Short option names - argdesc_long_args :: [String], -- ^ Long option names - argdesc_argarg :: ArgumentValueSpec, -- ^ What about a possible value of the argument? - argdesc_times :: Maybe (Int,Int), -- ^ Minimum and maximum of number of occurences allowed - argdesc_argargname :: Maybe String, -- ^ Name for argument's value, for message generation - argdesc_description :: Maybe String, -- ^ Descrition of the argument, for message generation - argdesc_argarg_tester :: Maybe Argtester -- ^ Argument value tester + argdesc_short_args :: [Char], -- ^ Short option names + argdesc_long_args :: [String], -- ^ Long option names + argdesc_argarg :: ArgumentValueSpec, -- ^ What about a possible value of the argument? + argdesc_times :: Maybe (Int,Int), -- ^ Minimum and maximum of number of occurences allowed + argdesc_argargname :: Maybe String, -- ^ Name for argument's value, for message generation + argdesc_description :: Maybe String, -- ^ Descrition of the argument, for message generation + argdesc_argarg_tester :: Maybe Argtester -- ^ Argument value tester } -- excluding tester ad_tup ad = - (argdesc_short_args ad, argdesc_long_args ad, argdesc_argarg ad, argdesc_times ad, argdesc_argargname ad, argdesc_description ad) + (argdesc_short_args ad, argdesc_long_args ad, argdesc_argarg ad, argdesc_times ad, + argdesc_argargname ad, argdesc_description ad) instance Eq ArgumentDescription where d == e = ad_tup d == ad_tup e @@ -185,10 +187,12 @@ -- value for maximum number of times unlimited = -1 + -- Whether two argument descriptions describe the same argument. -- Every short or long argument name occurs in only one argument -- descriptor (this is checked). Every argument has a short or a long -- name (short = [], long = [""] for direct arguments). + same_arg :: ArgumentDescription -> ArgumentDescription -> Bool same_arg arg1 arg2 = case (argdesc_short_args arg1, argdesc_short_args arg2) of @@ -198,8 +202,10 @@ (_,[]) -> unnamed (l1,l2) -> head l1 == head l2 _ -> False - where unnamed = error "Bug in argument description: nameless, non-direct argument. desc_short or desc_long must be specified." + where unnamed = error "Bug in argument description: nameless, non-direct argument. \ + \desc_short or desc_long must be specified." + -- | A property of a command line argument. These are generated by the -- @desc_@... functions, and condensed to argument -- descriptions of type @ArgumentDescription@ by @argdesc@. This type is abstract. @@ -242,7 +248,8 @@ argvalues' l where argvalues' ((d,v):r) = if same_arg desc d then v else argvalues' r - argvalues' [] = abort "Bug using HsShellScript: Value of unknown argument queried (add it to getarg's list)" desc + argvalues' [] = abort "Bug using HsShellScript: Value of unknown argument queried \ + \(add it to getarg's list)" desc -- used internally to represent one occurence of a specific argument type ArgOcc = (ArgumentDescription, Maybe String) @@ -250,7 +257,8 @@ -- | 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 @make_usage_info@ or @print_usage_info@. +-- The usage information is generated by the deprecated function usage_info. Better ignore this, and use the newer +-- @make_usage_info@ or @print_usage_info@. -- -- See 'make_usage_info', 'print_usage_info', 'usage_info'. data ArgError = ArgError { @@ -269,8 +277,8 @@ throw (ArgError mess (make_usage_info1 descl)) --- | --- Make @ArgError@ an instance of @Exception@, so we can throw and catch it, using GHC-6.10\'s new exception library. +-- | Make @ArgError@ an instance of @Exception@, so we can throw and catch it, using GHC-6.10\'s new exception +-- library. instance Exception ArgError @@ -309,11 +317,9 @@ else desc { argdesc_short_args = c : argdesc_short_args desc } ) --- | --- Long name of the argument. This specifies a GNU style long name for the argument, which is --- introduced by two dashes, like @--arg@ or @--arg=...@. 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. +-- | Long name of the argument. This specifies a GNU style long name for the argument, which is introduced by two +-- dashes, like @--arg@ or @--arg=...@. 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 'desc_direct' desc_long :: String -- ^ The long name of the argument. @@ -346,7 +352,8 @@ , argdesc_argarg = ArgumentValue_required , argdesc_argargname = Just "" } - else abort_conflict "desc_direct conflicts with desc_long, desc_short, desc_value_required and desc_value_optional." desc + else abort_conflict "desc_direct conflicts with desc_long, desc_short, desc_value_required \ + \and desc_value_optional." desc ) -- | @@ -442,11 +449,12 @@ else abort "Bug in HsShellScript argument description: Multiple argument descriptions specified" desc ) --- | 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 --- @getargs@ or related), all the testers are applied to the respective argument values, and an 'ArgError' 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. --- @myarg = read (reqarg_req args d_myarg)@. +-- | 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 @getargs@ or related), all the testers are +-- applied to the respective argument values, and an 'ArgError' 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. @myarg = read (reqarg_req args d_myarg)@. -- -- An argument tester is a function of type 'Argtester'. -- @@ -457,25 +465,27 @@ (\desc -> case argdesc_argarg_tester desc of Nothing -> desc { argdesc_argarg_tester = Just t } - Just _ -> abort "Bug in HsShellScript argument description: Multiple argument value testers specified" desc + Just _ -> abort "Bug in HsShellScript argument description: Multiple argument value testers specified" + desc ) --- | --- Build an argument tester from a @reads@ like function. Typically, a specialisation of the standard prelude function @read@ is used. --- Example: @readtester \"Integer expected.\" (reads :: ReadS Int)@ +-- | Build an argument tester from a @reads@ like function. Typically, a specialisation of the standard prelude +-- function @read@ is used. Example: @readtester \"Integer expected.\" (reads :: ReadS Int)@ readtester :: ReadS a -- Reader function, like the standard prelude function @reads@ -> String -- Additional message -> Argtester -- Argument tester to be passed to 'desc_tester' readtester reader msg val = case filter ((== "") . snd) $ reader val of [(_,"")] -> Nothing - [] -> Just (\arg -> "Format error in the value of the " ++ argname_a arg ++ ". " ++ msg ++ "\nValue: " ++ quote val) - _ -> Just (\arg -> "Ambigious value of the " ++ argname_a arg ++ ". " ++ msg ++ "\nValue: " ++ quote val) + [] -> Just (\arg -> "Format error in the value of the " ++ argname_a arg ++ ". " ++ msg ++ + "\nValue: " ++ quote val) + _ -> Just (\arg -> "Ambigious value of the " ++ argname_a arg ++ ". " ++ msg ++ "\nValue: " ++ + quote val) -{- | 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. +{- | 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. >desc_integer = desc_tester (readtester (reads :: ReadS Int) "Integer expected.") @@ -485,15 +495,17 @@ desc_integer = desc_tester (readtester (reads :: ReadS Int) "Integer expected.") -{- | 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. +{- | 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. ->desc_nonneg_integer = desc_tester (readtester ((filter (\(a,_) -> a >= 0) . reads) :: ReadS Int) "Non-negative integer expected." ) +>desc_nonneg_integer = desc_tester (readtester ((filter (\(a,_) -> a >= 0) . reads) :: ReadS Int) \ +> "Non-negative integer expected." ) See 'desc_tester'. -} desc_nonneg_integer :: ArgumentProperty -desc_nonneg_integer = desc_tester (readtester ((filter (\(a,_) -> a >= 0) . reads) :: ReadS Int) "Non-negative integer expected." ) +desc_nonneg_integer = desc_tester (readtester ((filter (\(a,_) -> a >= 0) . reads) :: ReadS Int) + "Non-negative integer expected." ) abort_conflict msg = abort ("Conflicting properties in argument description. " ++ msg) @@ -514,7 +526,8 @@ argname desc = if (argdesc_short_args desc, argdesc_long_args desc) == ([],[""]) then "(direct argument)" else if (argdesc_short_args desc, argdesc_long_args desc) == ([],[]) then "yet unnamed argument" - else concat (intersperse "/" ( map (\s -> "-"++[s]) (argdesc_short_args desc) ++ map ("--" ++) (argdesc_long_args desc) )) + else concat (intersperse "/" ( map (\s -> "-"++[s]) (argdesc_short_args desc) ++ + map ("--" ++) (argdesc_long_args desc) )) -- | -- Generate a descriptive argument name from an argument description, beginning @@ -556,22 +569,22 @@ > == "-a/-b Name" See 'argdesc', 'desc_direct'. 'argname_long'. --} +-} argname_short :: ArgumentDescription -- ^ Argument description, as returned by @argdesc@ -> String -- ^ Printable name for the argument argname_short desc = - if (argdesc_short_args desc, argdesc_long_args desc) == ([],[""]) + if (argdesc_short_args desc, argdesc_long_args desc) == ([],[""]) then "" - else if (argdesc_short_args desc, argdesc_long_args desc) == ([],[]) + else if (argdesc_short_args desc, argdesc_long_args desc) == ([],[]) then "yet unnamed argument" - else + else case (argdesc_short_args desc, argdesc_argargname desc) of ([], _) -> "" (sl, Just name) -> concat (intersperse "/" (map (\s -> "-" ++ [s]) sl)) ++ " " ++ name (sl, Nothing) -> concat (intersperse "/" (map (\s -> "-" ++ [s]) sl)) - + {- | 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. @@ -594,22 +607,22 @@ > == "--foo/--bar Name" See 'argdesc', 'desc_direct'. 'argname_long'. --} +-} argname_long :: ArgumentDescription -- ^ Argument description, as returned by @argdesc@ -> String -- ^ Printable name for the argument argname_long desc = - if (argdesc_short_args desc, argdesc_long_args desc) == ([],[""]) + if (argdesc_short_args desc, argdesc_long_args desc) == ([],[""]) then "" - else if (argdesc_short_args desc, argdesc_long_args desc) == ([],[]) + else if (argdesc_short_args desc, argdesc_long_args desc) == ([],[]) then "yet unnamed argument" - else + else case (argdesc_long_args desc, argdesc_argargname desc) of ([], _) -> "" (sl, Just name) -> concat (intersperse "/" (map (\s -> "--" ++ s) sl)) ++ " " ++ name (sl, Nothing) -> concat (intersperse "/" (map (\s -> "--" ++ s) sl)) - + up1 "" = "" up1 (x:xs) = toUpper x : xs @@ -629,11 +642,13 @@ } ) + -- | -- Make an argument description from a list of argument properties. This -- condenses the list to an argument description, -- which can be used by the @getargs@... functions and the -- argument value extraction functions. + argdesc :: [ArgumentProperty] -- ^ List of properties, which describe the command line argument. -> ArgumentDescription -- ^ The corresponding argument description. argdesc propl = @@ -643,8 +658,10 @@ -- Parse command line arguments. getargs0 :: String -- Header for usage info -> ArgOrder ArgOcc -- HsShellScript.GetOpt.Permute or HsShellScript.GetOpt.RequireOrder - -- Permute: Named arguments (like -x or --arg) and direct arguments may occur in any order. - -- RequireOrder: All arguments after the first direct argument are regarded as direct arguments. + -- Permute: Named arguments (like -x or --arg) and direct arguments + -- may occur in any order. + -- RequireOrder: All arguments after the first direct argument are + -- regarded as direct arguments. -> [String] -- The command line arguments as returned by System.Environment.getArgs -> [ArgumentDescription] -- The arguments descriptions -> Either ArgError -- Error @@ -661,7 +678,8 @@ test_unique :: (Show a, Ord a) => (ArgumentDescription -> [a]) -> String -> b -> b test_unique extr what x = case nonunique (sort (concat (map extr descs))) of - Just y -> error ("Bug: Several occurences of " ++ what ++ " " ++ show y ++ " in command line argument specifications") + Just y -> error ("Bug: Several occurences of " ++ what ++ " " ++ show y ++ + " in command line argument specifications") Nothing -> x optdescr = map make_optdescr descs_regular @@ -696,9 +714,12 @@ ) _ -> -- several descriptions for direct arguments - error "Bug in argument descriptions: Several descriptions for direct arguments (desc_direct) specified." + error "Bug in argument descriptions: Several descriptions for direct arguments \ + \(desc_direct) specified." - add :: (ArgumentDescription, Maybe String) -> [(ArgumentDescription, [Maybe String])] -> [(ArgumentDescription, [Maybe String])] + add :: (ArgumentDescription, Maybe String) + -> [(ArgumentDescription, [Maybe String])] + -> [(ArgumentDescription, [Maybe String])] add (a,str) [] = [(a,[str])] add (b,str) ((a,l):r) = if same_arg a b then (a,str:l) : r @@ -744,7 +765,8 @@ case argdesc_argarg_tester desc of Just argdesc_argarg_tester -> if argdesc_argarg desc == ArgumentValue_none - then abort "Bug in HsShellScript argument descriptions: Argument value tester specified,\n\ + then abort "Bug in HsShellScript argument descriptions: Argument value tester \ + \specified,\n\ \but no argument value has been allowed. Add desc_value_optional or\n\ \desc_value_required." desc @@ -864,8 +886,8 @@ -- or @--@ no longer take effect. -- -- See 'usage_info', 'make_usage_info', 'print_usage_info'. -getargs_ordered' :: String -- ^ Header to be used by the deprecated @usage_info@ function. - -> [String] -- ^ Command line to be parsed. +getargs_ordered' :: String -- ^ Header to be used by the deprecated @usage_info@ function. + -> [String] -- ^ Command line to be parsed. -> [ArgumentDescription] -- ^ The argument descriptions. -> Either ArgError Arguments -- ^ The contents of the command line. getargs_ordered' header args descs = getargs0 header RequireOrder args descs @@ -911,7 +933,8 @@ -> [Maybe String] -- ^ The occurences of the argument. args_opt args desc = test_desc desc (argdesc_argarg desc == ArgumentValue_optional && snd (fromJust (argdesc_times desc)) /= 1) - "Bug: Querying argument which doesn't take an optional value, or may not occur several times, with args_opt." + "Bug: Querying argument which doesn't take an optional value, or may not occur several times, \ + \with args_opt." $ argvalues args desc -- | @@ -922,7 +945,8 @@ -> [String] -- ^ The values of the argument. args_req args desc = test_desc desc (argdesc_argarg desc == ArgumentValue_required && snd (fromJust (argdesc_times desc)) /= 1) - "Bug: Querying argument which doesn't require a value, or may not occur several times, with args_req." $ + "Bug: Querying argument which doesn't require a value, or may not occur several times, with \ + \args_req." $ map fromJust (argvalues args desc) -- | @@ -935,9 +959,11 @@ -> Maybe String -- ^ The value of the argument, if it occurs. reqarg_opt args desc = test_desc desc (argdesc_argarg desc == ArgumentValue_optional && argdesc_times desc == Just (1,1)) - "Bug: Querying argument which doesn't take an optional value, or which must not occur exactly once, with reqarg_opt." $ + "Bug: Querying argument which doesn't take an optional value, or which must not occur exactly \ + \once, with reqarg_opt." $ head (argvalues args desc) + -- | -- Query the value of a required argument. This is for arguments which must -- occur exactly once, and require a value. @@ -959,11 +985,15 @@ -> ArgumentDescription -- ^ Description of the argument. -> Maybe (Maybe String) -- ^ The occurence of the argument and its value (see above). optarg_opt args desc = - test_desc desc (argdesc_argarg desc == ArgumentValue_optional) "Bug: Querying argument with non-optional value with optarg_opt." $ - test_desc desc (fst (fromJust (argdesc_times desc)) == 0) "Bug: Querying argument which isn't optional with optarg_opt." $ - test_desc desc (snd (fromJust (argdesc_times desc)) == 1) "Bug: Querying argument which may occur several times optarg_opt." $ + test_desc desc (argdesc_argarg desc == ArgumentValue_optional) + "Bug: Querying argument with non-optional value with optarg_opt." $ + test_desc desc (fst (fromJust (argdesc_times desc)) == 0) + "Bug: Querying argument which isn't optional with optarg_opt." $ + test_desc desc (snd (fromJust (argdesc_times desc)) == 1) + "Bug: Querying argument which may occur several times optarg_opt." $ maybe_head (argvalues args desc) + -- | -- 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 @@ -973,9 +1003,12 @@ -> ArgumentDescription -- ^ Description of the argument. -> Maybe String -- ^ The value of the argument, if it occurs. optarg_req args desc = - test_desc desc (argdesc_argarg desc == ArgumentValue_required) "Bug: Querying argument with non-required value with optarg_req." - $ test_desc desc (fst (fromJust (argdesc_times desc)) == 0) "Bug: Querying argument which isn't optional with optarg_req." - $ test_desc desc (snd (fromJust (argdesc_times desc)) == 1) "Bug: Querying argument which may occur several times optarg_req." + test_desc desc (argdesc_argarg desc == ArgumentValue_required) + "Bug: Querying argument with non-required value with optarg_req." + $ test_desc desc (fst (fromJust (argdesc_times desc)) == 0) + "Bug: Querying argument which isn't optional with optarg_req." + $ test_desc desc (snd (fromJust (argdesc_times desc)) == 1) + "Bug: Querying argument which may occur several times optarg_req." $ fmap fromJust (maybe_head (argvalues args desc)) @@ -1040,8 +1073,8 @@ -- At least one of the specified arguments must be present. -- -- Otherwise throw an ArgError. -args_at_least_one :: [ArgumentDescription] -- ^ List of the arguments, of which at least one must be present. - -> Arguments -- ^ Command line parse result. +args_at_least_one :: [ArgumentDescription] -- ^ List of the arguments, of which at least one must be present. + -> Arguments -- ^ Command line parse result. -> IO () args_at_least_one descs args@(Arguments argl) = when (occuring descs args == 0) $ @@ -1080,9 +1113,9 @@ occuring [desc] args == 1 --- | --- /Deprecated/. This is left here for backwards compatibility. New programs should use @make_usage_info@ and/or @print_usage_info@. --- +-- | /Deprecated/. This is left here for backwards compatibility. New programs should use @make_usage_info@ and/or +-- @print_usage_info@. +-- -- Get the usage information from the parsed arguments. The usage info -- contains the header specified to the corresponding @getargs...@ -- function, and descriptions of the command line arguments. @@ -1097,15 +1130,17 @@ -{- | @getargs@ as a pure function, instead of an IO action. This allows to make evaluated command line arguments global values. This calls @getargs@ - to parse the command line arguments. @GHC.IO.unsafePerformIO@ is used to take the result out of the IO monad. +{- | @getargs@ as a pure function, instead of an IO action. This allows to make evaluated command line arguments +global values. This calls @getargs@ to parse the command line arguments. @GHC.IO.unsafePerformIO@ is used to take +the result out of the IO monad. >unsafe_getargs header descs = GHC.IO.unsafePerformIO $ getargs "" descs - The @getargs@ action is performed on demand, when the parse result is evaluated. It may result in an 'ArgError' being thrown. In order to avoid - this happening at unexpected times, the @main@ function should, start with the line @seq args (return ())@, where @args@ is the result of - @unsafe_getargs@,. 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 @seq@). + The @getargs@ action is performed on demand, when the parse result is evaluated. It may result in an 'ArgError' + being thrown. In order to avoid this happening at unexpected times, the @main@ function should, start with the + line @seq args (return ())@, where @args@ is the result of @unsafe_getargs@,. 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 + @seq@). The header is used only by the deprecated @usage_info@ function. If you don't use it, you don't need to specify a header. Just pass an empty string. @@ -1132,8 +1167,8 @@ GHC.IO.unsafePerformIO $ getargs header descs -{- | @getargs_ordered@ as a pure function, instead of an IO action. This is exactly like @unsafe_getargs@, but using @getargs_ordered@ instead of - @getargs@. +{- | @getargs_ordered@ as a pure function, instead of an IO action. This is exactly like @unsafe_getargs@, but + using @getargs_ordered@ instead of @getargs@. The header is used only by the deprecated @usage_info@ function. If you don't use it, you don't need to specify a header. Just pass an empty string. @@ -1144,7 +1179,7 @@ See 'unsafe_getargs', 'usage_info', 'make_usage_info', 'print_usage_info'. -} -unsafe_getargs_ordered :: String -- ^ Header to be used by the deprecated @usage_info@ function. +unsafe_getargs_ordered :: String -- ^ Header to be used by the deprecated @usage_info@ function. -> [ArgumentDescription] -- ^ The argument descriptions -> Arguments -- ^ The parsed command line arguments unsafe_getargs_ordered header descs = @@ -1173,18 +1208,21 @@ -- The specified maximum breadths must fit in the specified width, or an error -- is raised. This happens, when @colsleft + colsshort + 2 + colslong + 2 + 2 > -- width@. --- +-- -- See 'print_usage_info', 'getargs', 'usage_info', 'ArgumentDescription', -- 'desc_description', 'argdesc', 'terminal_width', 'terminal_width_ioe'. -make_usage_info :: [ArgumentDescription] -- ^ List of argument descriptions, as created by a @argdesc@ - -> Int -- ^ The output is indented this many columns. Probably zero. - -> Int -- ^ Maximum width of the column of the short form of each argument. When this many aren't - -- needed, less are used. - -> Int -- ^ Maximum width of the column of the long form of each argument. When this many aren't - -- needed, less are used. - -> Int -- ^ Wrap everything at this column. Should probably be the terminal width. - -> [String] -- ^ Pretty printed usage information, in paragraphs, which contain one or several - -- lines, which are separated by newlines. + +make_usage_info :: [ArgumentDescription] -- ^ List of argument descriptions, as created by a @argdesc@ + -> Int -- ^ The output is indented this many columns. Probably zero. + -> Int -- ^ Maximum width of the column of the short form of each argument. + -- When this many aren'tneeded, less are used. + -> Int -- ^ Maximum width of the column of the long form of each argument. + -- When this many aren't needed, less are used. + -> Int -- ^ Wrap everything at this column. Should probably be the + -- terminal width. + -> [String] -- ^ Pretty printed usage information, in paragraphs, which contain + -- one or several lines, which are separated by newlines. + make_usage_info descs colsleft colsshort colslong width = if colsleft + colsshort + 2 + colslong + 2 + 2 > width @@ -1194,47 +1232,47 @@ \colsshort = " ++ show colsshort ++ " \n\ \colslong = " ++ show colslong ++ " \n\ \width = " ++ show width - else - map unlines (verbinden (zll' (filter (\d -> not (is_direct d)) + else + map unlines (verbinden (zll' (filter (\d -> not (is_direct d)) descs) )) - + where - -- Die Argumentbeschreibung, auf die richtige Breite umgebrochen + -- The argument description, wrapped to the right width. beschr :: ArgumentDescription -> [String] beschr desc = wrap (width - colsleft - gesamtbr_kurz - 2 - gesamtbr_lang - 2) (fromMaybe "" (argdesc_description desc)) - - -- Eine ArgumentDescription rendern. Die fertigen Zeilen sind alle gleich viele (mit "" aufgefüllt). + + -- Render an argument description. auff1 :: ArgumentDescription -> ([String], [String], [String]) auff1 desc = auff (kurzname desc) (langname desc) (beschr desc) - - -- Wir haben für eine Argumentbeschreibung die Listen von Zeilen, aus denen der kurze, und lange Argumentname besteht, sowie die Zeilen, aus - -- denen die Argumentbeschreibung besteht. + + -- Wir haben für eine Argumentbeschreibung die Listen von Zeilen, aus denen der kurze, und lange + -- Argumentname besteht, sowie die Zeilen, aus denen die Argumentbeschreibung besteht. zus :: ([String], [String], [String]) -> [(String, String, String)] zus (as, bs, cs) = zip3 as bs cs - + -- Die für die Kurzform einses Arguments benötigte Zahl von Spalten kurzbr :: ArgumentDescription -> Int kurzbr desc = foldr max 0 (map length (kurzname desc)) - + -- Die für die Langform einses Arguments benötigte Zahl von Spalten langbr :: ArgumentDescription -> Int langbr desc = foldr max 0 (map length (langname desc)) - + -- Breite der Kurzform, über alle Argumente hinweg gesamtbr_kurz = foldr max 0 (map (\desc -> kurzbr desc) descs) - + -- Breite der Langform, über alle Argumente hinweg gesamtbr_lang = foldr max 0 (map (\desc -> langbr desc) descs) - + -- Breite der Beschreibungen breite_descr :: Int breite_descr = width - colsleft - gesamtbr_kurz - 2 - gesamtbr_lang - 2 @@ -1244,63 +1282,63 @@ -> [[(String, String, String)]] zll descs = map (zus . auff1) descs - + -- Für jedes Kommandozeilenargument die Liste der Zeilen, aufgefüllt auf einheitliche Breite zll' :: [ArgumentDescription] -> [[(String, String, String)]] - zll' [] = + zll' [] = [] - zll' descs = - map (\l -> map (\(a,b,c) -> (fuell gesamtbr_kurz a, - fuell gesamtbr_lang b, + zll' descs = + map (\l -> map (\(a,b,c) -> (fuell gesamtbr_kurz a, + fuell gesamtbr_lang b, c)) l) (zll descs) - - -- Die Tripel + + -- Die Tripel verbinden :: [[(String, String, String)]] -> [[String]] verbinden l = - map (\l' -> map (\(a,b,c) -> take colsleft (repeat ' ') + map (\l' -> map (\(a,b,c) -> take colsleft (repeat ' ') ++ a ++ " " ++ b ++ " " ++ c) l') l - + -- Die Kurzform des angegebenen Arguments. In Zeilen heruntergebrochen, -- wenn die Breite colsshort überschritten wird. kurzname :: ArgumentDescription -> [String] kurzname desc = wrap colsshort (argname_short desc) - + -- Die Langform des angegebenen Arguments. In Zeilen heruntergebrochen, -- wenn die Breite colslong überschritten wird langname :: ArgumentDescription -> [String] langname desc = wrap colslong (argname_long desc) - - -- Den gegebenen String um so viele Leerzeichen ergänzen, daß daraus ein String der gegebenen Länge wird. Ist er dafür zu lang, denn den - -- unveränderten String zurückgeben. + + -- Den gegebenen String um so viele Leerzeichen ergänzen, daß daraus ein String der gegebenen Länge + -- wird. Ist er dafür zu lang, denn den unveränderten String zurückgeben. fuell :: Int -> String -> String fuell br txt = txt ++ take (br - length txt) (repeat ' ') - + -- Complete three lists of Strings. All three strings are made to be made up -- of the same number of entries. Missing entries at the end are filled up with -- empty strings. auff :: [String] -> [String] -> [String] -> ([String], [String], [String]) auff a b c = (reverse x, reverse y, reverse z) - + where (x,y,z) = auff' a b c [] [] [] - + auff' :: [String] -> [String] -> [String] -> [String] -> [String] -> [String] -> ([String], [String], [String]) - + auff' [] [] [] a1 b1 c1 = (a1, b1, c1) - + auff' a b c a1 b1 c1 = auff' (if null a then [] else tail a) (if null b then [] else tail b) @@ -1308,10 +1346,10 @@ ((if null a then "" else head a) : a1) ((if null b then "" else head b) : b1) ((if null c then "" else head c) : c1) - + -- | -- Print the usage information (about the command line arguments), for the -- specified header and arguments to the specified handle. When the handle is @@ -1329,7 +1367,7 @@ -- -- 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 @\\n\\n@. This also applies +-- have several paragraphs, separate them by a double @\\n\\n@. 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 @@ -1360,20 +1398,20 @@ else -} - if w < 12 + if w < 12 then hPutStr h "Terminal too narrow" else do -- Wrap and print the header hPutStr h (unlines (wrap w header)) - + -- Print the argument descriptions. mapM_ (hPutStr h) - (make_usage_info descs - 0 - (w `div` 5) + (make_usage_info descs + 0 + (w `div` 5) (w `div` 3) w) - + -- | -- Break down a text to lines, such that each one has the specified diff --git a/src/HsShellScript/Commands.chs b/src/HsShellScript/Commands.chs --- a/src/HsShellScript/Commands.chs +++ b/src/HsShellScript/Commands.chs @@ -25,9 +25,8 @@ import System.Random import System.Directory --- | --- Do a call to the @realpath(3)@ system library function. This makes the path absolute, normalizes it and expands all symbolic links. In case of an --- error, an @IOError@ is thrown. +-- | Do a call to the @realpath(3)@ system library function. This makes the path absolute, normalizes it and +-- expands all symbolic links. In case of an error, an @IOError@ is thrown. realpath :: String -- ^ path -> IO String -- ^ noramlized, absolute path, with symbolic links expanded realpath path = @@ -37,10 +36,11 @@ then throwErrno' "realpath" Nothing (Just path) else peekCString res --- | Determine the target of a symbolic link. This uses the @readlink(2)@ 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 @IOError@ is thrown. The path is included and can be accessed with --- @IO.ioeGetFileName@. Note that, if the path to the symlink ends with a slash, this path denotes the directory pointed to, /not/ the symlink. In --- this case the call to will fail because of \"Invalid argument\". +-- | Determine the target of a symbolic link. This uses the @readlink(2)@ 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 @IOError@ is +-- thrown. The path is included and can be accessed with @IO.ioeGetFileName@. Note that, if the path to the symlink +-- ends with a slash, this path denotes the directory pointed to, /not/ the symlink. In this case the call to will +-- fail because of \"Invalid argument\". readlink :: String -- ^ Path of the symbolic link -> IO String -- ^ The link target - where the symbolic link points to readlink path = @@ -50,10 +50,11 @@ then throwErrno' "readlink" Nothing (Just path) else peekCString res --- | Determine the target of a symbolic link. This uses the @readlink(2)@ 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, /not/ the symlink. In this case the call to @readlink@ will fail with an @IOError@ because of \"Invalid argument\". In case of any error, a --- proper @IOError@ is thrown. +-- | Determine the target of a symbolic link. This uses the @readlink(2)@ 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, /not/ the symlink. In this case the call +-- to @readlink@ will fail with an @IOError@ because of \"Invalid argument\". In case of any error, a proper +-- @IOError@ is thrown. readlink' :: String -- ^ path of the symbolic link -> IO String -- ^ target; where the symbolic link points to readlink' symlink = do @@ -61,8 +62,8 @@ return (absolute_path' target (fst (split_path symlink))) --- | Determine whether a path is a symbolic link. The result for a dangling symlink is @True@. The path must exist in the file system. In case of an --- error, a proper @IOError@ is thrown. +-- | Determine whether a path is a symbolic link. The result for a dangling symlink is @True@. The path must exist +-- in the file system. In case of an error, a proper @IOError@ is thrown. is_symlink :: String -- ^ path -> IO Bool -- ^ Whether the path is a symbolic link. is_symlink path = @@ -72,9 +73,10 @@ (\(ioe::IOError) -> if (ioeGetErrorType ioe == InvalidArgument) then return False else ioError ioe) --- | 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 @realpath@ program reports with the @-s@ 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 'cd' for details. +-- | 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 @realpath@ program +-- reports with the @-s@ 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 'cd' for details. -- -- See 'cd', 'normalise_path'. realpath_s :: String -- ^ path @@ -84,10 +86,9 @@ return (normalise_path (absolute_path_by cwd pfad)) --- | --- Make a symbolic link. This is the @symlink(2)@ function. Any error results in an @IOError@ thrown. The path of the intended symlink is included in --- the @IOError@ and --- can be accessed with @ioeGetFileName@ from the Haskell standard library @IO@. +-- | Make a symbolic link. This is the @symlink(2)@ function. Any error results in an @IOError@ thrown. The path of +-- the intended symlink is included in the @IOError@ and can be accessed with @ioeGetFileName@ from the Haskell +-- standard library @IO@. symlink :: String -- ^ contents of the symlink -> String -- ^ path of the symlink -> IO () @@ -98,8 +99,7 @@ when (res == -1) $ throwErrno' ("symlink " ++ shell_quote oldpath ++ " to " ++ shell_quote newpath) Nothing (Just newpath) --- | --- Call the @du@ program. See du(1). +-- | Call the @du@ program. See du(1). du :: (Integral int, Read int, Show int) => int -- ^ block size, this is the @--block-size@ option. -> String -- ^ path of the file or directory to determine the size of @@ -115,9 +115,8 @@ --- | --- Create directory. This is a shorthand to @System.Directory.createDirectory@ from the Haskell standard --- library. In case of an error, the path is included in the @IOError@, which GHC's implementation neglects to do. +-- | Create directory. This is a shorthand to @System.Directory.createDirectory@ from the Haskell standard library. +-- In case of an error, the path is included in the @IOError@, which GHC's implementation neglects to do. mkdir :: String -- ^ path -> IO () mkdir path = @@ -125,10 +124,8 @@ `catch` (\(ioe::IOError) -> ioError (ioe { ioe_filename = Just path })) --- | --- Remove directory. This is --- @Directory.removeDirectory@ from the Haskell standard --- library. In case of an error, the path is included in the @IOError@, which GHC's implementation neglects to do. +-- | Remove directory. This is @Directory.removeDirectory@ from the Haskell standard library. In case of an error, +-- the path is included in the @IOError@, which GHC's implementation neglects to do. rmdir :: String -- ^ path -> IO () rmdir path = @@ -136,26 +133,29 @@ `catch` (\(ioe::IOError) -> ioError (ioe { ioe_filename = Just path })) --- | Remove file. This is @Directory.removeFile@ from the Haskell standard library, which is a direct frontend to the @unlink(2)@ system call in GHC. +-- | Remove file. This is @Directory.removeFile@ from the Haskell standard library, which is a direct frontend to +-- the @unlink(2)@ system call in GHC. rm :: String -- ^ path -> IO () rm = removeFile -{- | Change directory. This is an alias for @Directory.setCurrentDirectory@ from the Haskell standard - library. In case of an error, the path is included in the @IOError@, which GHC's implementation neglects to do. +{- | Change directory. This is an alias for @Directory.setCurrentDirectory@ from the Haskell standard library. In +case of an error, the path is included in the @IOError@, which GHC's implementation neglects to do. - Note that this command is subtly different from the shell's @cd@ 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 - /not/ expanded. The shell's idea of the working directory is different from the working directory which a process has. +Note that this command is subtly different from the shell's @cd@ 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 /not/ 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 @cd@ commands, when done in a real shell script, will lead into the same directory. But the working directory - as reported by the shell's @pwd@ command may differ from the corresponding one, reported by @getCurrentDirectory@. +This means that the same sequence of @cd@ commands, when done in a real shell script, will lead into the same +directory. But the working directory as reported by the shell's @pwd@ command may differ from the corresponding +one, reported by @getCurrentDirectory@. - (When talking about the \"shell\", I'm talking about bash, regardless of whether started as @\/bin\/bash@ or in compatibility mode, as @\/bin\/sh@. I - presume it's the standard behavior for the POSIX standard shell.) +(When talking about the \"shell\", I'm talking about bash, regardless of whether started as @\/bin\/bash@ or in +compatibility mode, as @\/bin\/sh@. I presume it's the standard behavior for the POSIX standard shell.) - See 'pwd', 'with_wd' +See 'pwd', 'with_wd' -} cd :: String -- ^ path -> IO () @@ -177,8 +177,8 @@ --- | Change the working directory temporarily. This executes the specified IO action with a new working directory, and restores it afterwards --- (exception-safely). +-- | 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 -- ^ New working directory -> IO a -- ^ Action to run -> IO a @@ -221,8 +221,9 @@ -- | -- Execute the mv program. -- --- This calls the @\/bin\/mv@ 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 @rename@ instead, when possible. +-- This calls the @\/bin\/mv@ 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 @rename@ instead, when +-- possible. -- -- See 'rename'. mv :: String -- ^ source @@ -280,11 +281,9 @@ --- | --- The @rename(2)@ system call to rename and\/or move a file. The @renameFile@ action from the Haskell standard library doesn\'t do it, because --- the two paths may not refer to directories. Failure results in an @IOError@ thrown. The /new/ path is included in --- the @IOError@ and --- can be accessed with @IO.ioeGetFileName@. +-- | The @rename(2)@ system call to rename and\/or move a file. The @renameFile@ action from the Haskell standard +-- library doesn\'t do it, because the two paths may not refer to directories. Failure results in an @IOError@ +-- thrown. The /new/ path is included in the @IOError@ and can be accessed with @IO.ioeGetFileName@. rename :: String -- ^ Old path -> String -- ^ New path -> IO () @@ -296,9 +295,8 @@ --- | --- Rename a file. This first tries 'rename', which is most efficient. If it fails, because source and target path point to different file systems --- (as indicated by the @errno@ value @EXDEV@), then @\/bin\/mv@ is called. +-- | Rename a file. This first tries 'rename', which is most efficient. If it fails, because source and target path +-- point to different file systems (as indicated by the @errno@ value @EXDEV@), then @\/bin\/mv@ is called. -- -- See 'rename', 'mv'. rename_mv :: FilePath -- ^ Old path @@ -309,8 +307,9 @@ `catch` (\(ioe::IOError) -> if ioeGetErrorType ioe == UnsupportedOperation then do errno <- getErrno - -- Foreign.C.Error.errnoToIOError matches many errno values to UnsupportedOperation. In order to determine - -- if it is the right one, the errno is taken again. This relies on no system calls in between. + -- Foreign.C.Error.errnoToIOError matches many errno values to + -- UnsupportedOperation. In order to determine if it is the right one, the + -- errno is taken again. This relies on no system calls in between. if (errno == eXDEV) then run "/bin/mv" ["--", old, new] else ioError ioe @@ -318,14 +317,15 @@ ) -{- | Rename a file or directory, and cope with read only issues. +{- | Rename a file or directory, and manage read only issues. -This renames a file or directory, using @rename@, sets the necessary write permissions beforehand, and restores them afterwards. This is more -efficient than @force_mv@, because no external program needs to be called, but it can rename files only inside the same file system. See @force_cmd@ -for a detailed description. +This renames a file or directory, using @rename@, sets the necessary write permissions beforehand, and restores +them afterwards. This is more efficient than @force_mv@, because no external program needs to be called, but it can +rename files only inside the same file system. See @force_cmd@ 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 @mv@). The -new path is then completed with the file name component of the old path. You won't get an \"already exists\" error. +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 @mv@). The new path is then completed with the file name component of the old path. You won't +get an \"already exists\" error. >force_rename = force_cmd rename @@ -337,11 +337,11 @@ force_rename = force_cmd HsShellScript.Commands.rename -{- | Move a file or directory, and cope with read only issues. +{- | Move a file or directory, and manage read only issues. -This moves a file or directory, using the external command @mv@, sets the necessary write permissions beforehand, and restores them afterwards. -This is less efficient than @force_rename@, because the external program @mv@ needs to be called, but it can move files between file systems. See -@force_cmd@ for a detailed description. +This moves a file or directory, using the external command @mv@, sets the necessary write permissions beforehand, +and restores them afterwards. This is less efficient than @force_rename@, because the external program @mv@ needs +to be called, but it can move files between file systems. See @force_cmd@ for a detailed description. >force_mv src tgt = fill_in_location "force_mv" $ force_cmd (\src tgt -> run "/bin/mv" ["--", src, tgt]) src tgt @@ -355,12 +355,12 @@ force_cmd (\src tgt -> run "/bin/mv" ["--", src, tgt]) src tgt -{- | Rename a file with 'rename', or when necessary with 'mv', and cope with read only issues. +{- | Rename a file with 'rename', or when necessary with 'mv', and manage read only issues. The necessary write permissions are set, then the file is renamed, then the permissions are restored. -First, the 'rename' 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 @errno@ value @EXDEV@), then @\/bin\/mv@ is called. +First, the 'rename' 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 @errno@ value @EXDEV@), then @\/bin\/mv@ is called. >force_rename_mv old new = fill_in_location "force_rename_mv" $ force_cmd rename_mv old new @@ -374,26 +374,29 @@ force_cmd rename_mv old new -{- | Call a command which moves a file or directory, and cope with read only issues. +{- | Call a command which moves a file or directory, and manage 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 @rename@ or @run \"\/bin\/mv\"@. +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 +@rename@ or @run \"\/bin\/mv\"@. -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. +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. +This function concerns itself 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 @force_cmd@ after executing it. +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 @force_cmd@ 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 @mv@). 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. +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 @mv@). 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: @@ -429,8 +432,8 @@ -{- | 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. +{- | 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. >force_writeable path io = force_writeable2 path (io >>= \res -> return (path, res)) @@ -449,13 +452,15 @@ force_writeable2 path (io >>= \res -> return (path, res)) -{- | 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. +{- | 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 @force_writeable2@ 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. +The writeable status is only changed back if it has been changed by @force_writeable2@ 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 'force_cmd', 'force_writeable'. +See 'force_cmd', 'force_writeable'. -} force_writeable2 :: String -- ^ File or directory to make writeable -> IO (String, a) -- ^ Action to perform @@ -470,7 +475,8 @@ (\(e::SomeException) -> do when (not writeable) $ catch (set_user_readonly path_before) - ignore -- Don't let failure to restore the status make us loose the actual exception + ignore -- Don't let failure to restore the status make + -- us loose the actual exception. throwIO e ) when (not writeable) $ set_user_readonly path_after @@ -489,22 +495,21 @@ fill_in_filename path $ setFileMode' path (filemode .&. (complement ownerWriteMode)) --- | --- Call the @fdupes@ 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 @fdupes@ --- 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 @fdupes@ program. If you just want groups of identical files, then apply @map concat@ to the result. +-- | Call the @fdupes@ 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 @fdupes@ 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 @fdupes@ program. If you just want groups of identical files, then apply @map +-- concat@ to the result. -- --- /The/ @fdupes@ /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/ @fdupes@ /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 'normalise_path'). fdupes :: [String] -- ^ Options for the fdupes program -> [String] -- ^ Directories with files to compare - -> IO [[[String]]] -- ^ For each set of identical files, and each of the specified directories, the paths of the identical files in this - -- directory. + -> IO [[[String]]] -- ^ For each set of identical files, and each of the specified directories, + -- the paths of the identical files in this directory. fdupes opts paths = do let paths' = map normalise_path paths paths'' = map (++"/") paths' diff --git a/src/HsShellScript/Misc.chs b/src/HsShellScript/Misc.chs --- a/src/HsShellScript/Misc.chs +++ b/src/HsShellScript/Misc.chs @@ -22,9 +22,8 @@ --- | --- Format an @Int@ with leading zeros. If the string representation of the @Inŧ@ is longer than the number of characters to fill up, this produces as --- many characters as needed. +-- | Format an @Int@ with leading zeros. If the string representation of the @Inŧ@ is longer than the number of +-- characters to fill up, this produces as many characters as needed. zeros :: Int -- ^ How many characters to fill up -> Int -- ^ Value to represent as a string -> String -- ^ String representation of the value, using the specified number of characters @@ -46,13 +45,11 @@ in if xs' == "" && x == '\n' then "" else x:xs' -{- | Get contents of a file or of @stdin@. This is a simple frontend to -@hGetContents@. A file name of @\"-\"@ designates stdin. The contents are read -lazily as the string is evaluated. +{- | Get contents of a file or of @stdin@. This is a simple frontend to @hGetContents@. A file name of @\"-\"@ +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). +(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). >lazy_contents path = do > h <- if path == "-" then return stdin else openFile path ReadMode @@ -64,10 +61,10 @@ h <- if path == "-" then return stdin else openFile path ReadMode hGetContents h --- | --- Get contents of a file or of @stdin@ eagerly. This is the --- same as @lazy_contents@, except for the contents being --- read immediately. + +-- | Get contents of a file or of @stdin@ eagerly. This is the same as @lazy_contents@, except for the contents +-- being read immediately. + contents :: String -- ^ either the name of a file, or @\"-\"@ for @stdin@ -> IO String -- ^ the contents of the file or of standard input contents pfad = do @@ -76,9 +73,8 @@ return txt --- | --- Test for the existence of a path. This is the disjunction of --- @Directory.doesDirectoryExist@ and @Directory.doesFileExist@. For an dangling symlink, this will return @False@. +-- | Test for the existence of a path. This is the disjunction of @Directory.doesDirectoryExist@ and +-- @Directory.doesFileExist@. For an dangling symlink, this will return @False@. path_exists :: String -- ^ Path -> IO Bool -- ^ Whether the path exists in the file system path_exists pfad = do @@ -87,9 +83,8 @@ return (de || fe) --- | --- Test for the existence of a path. This uses @System.Posix.Files.getFileStatus@ to determine whether the path exists in any form in the file system. --- For a dangling symlink, the result is @True@. +-- | Test for the existence of a path. This uses @System.Posix.Files.getFileStatus@ to determine whether the path +-- exists in any form in the file system. For a dangling symlink, the result is @True@. path_exists' :: String -- ^ Path -> IO Bool -- ^ Whether the path exists in the file system path_exists' path = @@ -100,9 +95,8 @@ else ioError ioe) --- | --- Test if path points to a directory. This will return @True@ for a symlink pointing to a directory. It's a shortcut for --- @Directory.doesDirectoryExist@. +-- | Test if path points to a directory. This will return @True@ for a symlink pointing to a directory. It's a +-- shortcut for @Directory.doesDirectoryExist@. is_dir :: String -- ^ Path -> IO Bool -- ^ Whether the path exists and points to a directory. is_dir = doesDirectoryExist @@ -116,9 +110,9 @@ is_file = doesFileExist --- | --- This is the @System.Posix.Files.getFileStatus@ function from the GHC libraries, with improved error reporting. The GHC function doesn't include the --- file name in the @IOError@ when the call fails, making error messages much less useful. @getFileStatus\'@ rectifies this. +-- | This is the @System.Posix.Files.getFileStatus@ function from the GHC libraries, with improved error reporting. +-- The GHC function doesn't include the file name in the @IOError@ when the call fails, making error messages much +-- less useful. @getFileStatus\'@ rectifies this. -- -- See 'System.Posix.Files.getFileStatus'. getFileStatus' :: FilePath -- ^ Path of the file, whose status is to be queried @@ -128,9 +122,9 @@ `catch` (\ioe -> ioError (ioe { ioe_filename = Just path })) --- | --- This is the @System.Posix.Files.fileAccess@ function from the GHC libraries, with improved error reporting. The GHC function doesn't include the --- file name in the @IOError@ when the call fails, making error messages much less useful. @fileAccess\'@ rectifies this. +-- | This is the @System.Posix.Files.fileAccess@ function from the GHC libraries, with improved error reporting. +-- The GHC function doesn't include the file name in the @IOError@ when the call fails, making error messages much +-- less useful. @fileAccess\'@ rectifies this. -- -- See 'System.Posix.Files.fileAccess'. fileAccess' :: FilePath -> Bool -> Bool -> Bool -> IO Bool @@ -139,15 +133,16 @@ `catch` (\ioe -> ioError (ioe { ioe_filename = Just p })) --- | --- 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 @open(2)@ for details). +-- | 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 @open(2)@ for details). -- -- See 'tmp_file', 'temp_dir', 'with_temp_file'. -temp_file :: Int -- ^ Number of random characters to intersperse. Must be large enough, such that most combinations can't already +temp_file :: Int -- ^ Number of random characters to intersperse. Must be large enough, + -- such that most combinations can't already -- exist. -> String -- ^ Prefix for the path to generate. -> String -- ^ Suffix for the path to generate. @@ -169,19 +164,20 @@ when (res == -1) $ throwErrno' "temp_file" Nothing (Just path) return path --- | --- 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 +-- | 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 @mkdir(2)@) +-- 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 @mkdir(2)@) -- -- See 'tmp_dir', 'temp_file', 'with_temp_dir'. -temp_dir :: Int -- ^ Number of random characters to intersperse. Must be large enough, such that most combinations can't already - -- exist. +temp_dir :: Int -- ^ Number of random characters to intersperse. Must be large enough, + -- such that most combinations can't already exist. -> String -- ^ Prefix for the path to generate. -> String -- ^ Suffix for the path to generate. -> IO FilePath -- ^ Generated path. @@ -199,9 +195,9 @@ ) return path --- | --- 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). +-- | 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). -- -- @tmp_file prefix = temp_file 6 (prefix ++ \".\") \"\"@ -- @@ -211,10 +207,9 @@ tmp_file prefix = temp_file 6 (prefix ++ ".") "" --- | --- 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). +-- | 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). -- -- @tmp_dir prefix = temp_dir 6 (prefix ++ \".\") \"\"@ -- @@ -224,13 +219,13 @@ tmp_dir prefix = temp_dir 6 (prefix ++ ".") "" --- | --- Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end to the 'temp_file' 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. +-- | Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end +-- to the 'temp_file' 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 'temp_file', 'with_tmp_file', 'with_temp_dir'. -with_temp_file :: Int -- ^ Number of random characters to intersperse. Must be large enough, such that most combinations can't +with_temp_file :: Int -- ^ Number of random characters to intersperse. Must be large enough, + -- such that most combinations can't -- already exist. -> String -- ^ Prefix for the path to generate. -> String -- ^ Suffix for the path to generate. @@ -251,19 +246,19 @@ --- | --- Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to the 'temp_dir' 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. +-- | Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to +-- the 'temp_dir' 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. @with_temp_dir@ doesn't delete any files inside, so the directory --- could be removed. If the directory isn't empty, an @IOError@ 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). +-- The action must clean up any files it creates inside the directory by itself. @with_temp_dir@ doesn't delete any +-- files inside, so the directory could be removed. If the directory isn't empty, an @IOError@ 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 'temp_dir', 'with_tmp_dir', 'with_temp_file'. -with_temp_dir :: Int -- ^ Number of random characters to intersperse. Must be large enough, such that most combinations can't - -- already exist. +with_temp_dir :: Int -- ^ Number of random characters to intersperse. Must be large enough, + -- such that most combinations can't already exist. -> String -- ^ Prefix for the path to generate. -> String -- ^ Suffix for the path to generate. -> (FilePath -> IO a) -- ^ Action to perform. @@ -281,10 +276,9 @@ `catch` (\ioe -> ioError (ioe { ioe_filename = Just path })) --- | --- Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end to the 'tmp_file' 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. +-- | Create and open a temporary file, perform some action with it, and delete it afterwards. This is a front end +-- to the 'tmp_file' 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 'tmp_file', 'with_temp_file', 'with_tmp_dir'. with_tmp_file :: String -- ^ Prefix for the path to generate. @@ -304,15 +298,15 @@ return e ) --- | --- Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to the 'tmp_dir' 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. +-- | Create a temporary directory, perform some action with it, and delete it afterwards. This is a front end to +-- the 'tmp_dir' 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. @with_temp_dir@ doesn't delete any files inside, so the directory --- could be removed. If the directory isn't empty, an @IOError@ 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). +-- The action must clean up any files it creates inside the directory by itself. @with_temp_dir@ doesn't delete any +-- files inside, so the directory could be removed. If the directory isn't empty, an @IOError@ 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). -- -- >with_tmp_dir prefix io = with_temp_dir 6 (prefix ++ ".") "" io -- @@ -323,17 +317,18 @@ with_tmp_dir prefix io = with_temp_dir 6 (prefix ++ ".") "" io --- | --- 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. +-- | 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. -- --- /Avoid relying on the generated path not to exist in the file system./ Or else you'll get a potential race condition, since some other process might --- create the path after @temp_path@, before you use it. This is a security risk. The global random number generator (@Random.randomRIO@) is used to --- generate the random characters. These might not be that random after all, and could potentially be guessed. Rather use @temp_file@ or @temp_dir@. +-- /Avoid relying on the generated path not to exist in the file system./ Or else you'll get a potential race +-- condition, since some other process might create the path after @temp_path@, before you use it. This is a +-- security risk. The global random number generator (@Random.randomRIO@) is used to generate the random +-- characters. These might not be that random after all, and could potentially be guessed. Rather use @temp_file@ +-- or @temp_dir@. -- -- See 'temp_file', 'temp_dir'. -temp_path :: Int -- ^ Number of random characters to intersperse. Must be large enough, such that most combinations can't already - -- exist. +temp_path :: Int -- ^ Number of random characters to intersperse. Must be large enough, + -- such that most combinations can't already exist. -> String -- ^ Prefix for the path to generate. -> String -- ^ Suffix for the path to generate. -> IO FilePath -- ^ Generated path. @@ -354,8 +349,8 @@ else untilIO io cond -{- | One entry of mount information. This is the same as @struct mntent@ from @\