-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | A replacement for System.Exit and System.Process -- -- Specifically, this library replaces System.Exit.ExitCode with -- an abstract data type. @package Command @version 0.0.1 module System.Command -- | This is the most general way to spawn an external process. The process -- can be a command line to be executed by a shell or a raw command with -- a list of arguments. The stdin, stdout, and stderr streams of the new -- process may individually be attached to new pipes, to existing -- Handles, or just inherited from the parent (the default.) -- -- The details of how to create the process are passed in the -- CreateProcess record. To make it easier to construct a -- CreateProcess, the functions proc and shell are -- supplied that fill in the fields with default values which can be -- overriden as needed. -- -- createProcess returns (mb_stdin_hdl, mb_stdout_hdl, -- mb_stderr_hdl, p), where -- -- -- -- Similarly for mb_stdout_hdl and mb_stderr_hdl. -- -- For example, to execute a simple ls command: -- -- 
--   r <- createProcess (proc "ls" [])
--
-- -- To create a pipe from which to read the output of ls: -- -- 
--   (_, Just hout, _, _) <-
--       createProcess (proc "ls" []){ std_out = CreatePipe }
--
-- -- To also set the directory in which to run ls: -- -- 
--   (_, Just hout, _, _) <-
--       createProcess (proc "ls" []){ cwd = Just "\home\bob",
--                                     std_out = CreatePipe }
--
createProcess :: CreateProcess -> IO (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -- | Construct a CreateProcess record for passing to -- createProcess, representing a command to be passed to the -- shell. shell :: String -> CreateProcess -- | Construct a CreateProcess record for passing to -- createProcess, representing a raw command with arguments. proc :: FilePath -> [String] -> CreateProcess data CreateProcess :: * CreateProcess :: CmdSpec -> Maybe FilePath -> Maybe [(String, String)] -> StdStream -> StdStream -> StdStream -> Bool -> CreateProcess -- | Executable & arguments, or shell command cmdspec :: CreateProcess -> CmdSpec -- | Optional path to the working directory for the new process cwd :: CreateProcess -> Maybe FilePath -- | Optional environment (otherwise inherit from the current process) env :: CreateProcess -> Maybe [(String, String)] -- | How to determine stdin std_in :: CreateProcess -> StdStream -- | How to determine stdout std_out :: CreateProcess -> StdStream -- | How to determine stderr std_err :: CreateProcess -> StdStream -- | Close all file descriptors except stdin, stdout and stderr in the new -- process (on Windows, only works if std_in, std_out, and std_err are -- all Inherit) close_fds :: CreateProcess -> Bool data CmdSpec :: * -- | a command line to execute using the shell ShellCommand :: String -> CmdSpec -- | the filename of an executable with a list of arguments RawCommand :: FilePath -> [String] -> CmdSpec data StdStream :: * -- | Inherit Handle from parent Inherit :: StdStream -- | Use the supplied Handle UseHandle :: Handle -> StdStream -- | Create a new pipe. The returned Handle will use the default -- encoding and newline translation mode (just like Handles -- created by openFile). CreatePipe :: StdStream data ProcessHandle :: * -- | readProcessWithExitCode creates an external process, reads its -- standard output and standard error strictly, waits until the process -- terminates, and then returns the ExitCode of the process, the -- standard output, and the standard error. -- -- readProcess and readProcessWithExitCode are fairly -- simple wrappers around createProcess. Constructing variants -- of these functions is quite easy: follow the link to the source code -- to see how readProcess is implemented. readProcessWithExitCode :: FilePath -> [String] -> String -> IO (ExitCode, String, String) -- | Runs a command using the shell. runCommand :: String -> IO ProcessHandle -- | Runs a raw command, optionally specifying Handles from which to -- take the stdin, stdout and stderr channels -- for the new process (otherwise these handles are inherited from the -- current process). -- -- Any Handles passed to runProcess are placed immediately -- in the closed state. -- -- Note: consider using the more general createProcess instead of -- runProcess. runProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> Maybe Handle -> Maybe Handle -> Maybe Handle -> IO ProcessHandle -- | Runs a command using the shell, and returns Handles that may be -- used to communicate with the process via its stdin, -- stdout, and stderr respectively. The Handles -- are initially in binary mode; if you need them to be in text mode then -- use hSetBinaryMode. runInteractiveCommand :: String -> IO (Handle, Handle, Handle, ProcessHandle) -- | Runs a raw command, and returns Handles that may be used to -- communicate with the process via its stdin, stdout -- and stderr respectively. -- -- For example, to start a process and feed a string to its stdin: -- -- 
--   (inp,out,err,pid) <- runInteractiveProcess "..."
--   forkIO (hPutStr inp str)
--
-- -- The Handles are initially in binary mode; if you need them to -- be in text mode then use hSetBinaryMode. runInteractiveProcess :: FilePath -> [String] -> Maybe FilePath -> Maybe [(String, String)] -> IO (Handle, Handle, Handle, ProcessHandle) -- | readProcess forks an external process, reads its standard output -- strictly, blocking until the process terminates, and returns the -- output string. -- -- Output is returned strictly, so this is not suitable for interactive -- applications. -- -- Users of this function should compile with -threaded if they -- want other Haskell threads to keep running while waiting on the result -- of readProcess. -- -- 
--   > readProcess "date" [] []
--   "Thu Feb  7 10:03:39 PST 2008\n"
--
-- -- The arguments are: -- -- readProcess :: FilePath -> [String] -> String -> IO String -- | Computation system cmd returns the exit code produced when -- the operating system runs the shell command cmd. -- -- This computation may fail with -- -- -- -- On Windows, system passes the command to the Windows command -- interpreter (CMD.EXE or COMMAND.COM), hence Unixy -- shell tricks will not work. system :: String -> IO ExitCode -- | The computation rawSystem cmd args runs the operating -- system command cmd in such a way that it receives as -- arguments the args strings exactly as given, with no funny -- escaping or shell meta-syntax expansion. It will therefore behave more -- portably between operating systems than system. -- -- The return codes and possible failures are the same as for -- system. rawSystem :: String -> [String] -> IO ExitCode -- | The result of running a process data ExitCode -- | Construct a process result. A value of 0 denotes success, -- otherwise, failure. exitCode :: Int -> ExitCode -- | Construct a process result with the value 0. success :: ExitCode -- | Returns true if the given process result was constructed with the -- value 0, otherwise false. isSuccess :: ExitCode -> Bool -- | Returns false if the given process result was constructed with the -- value 0, otherwise true. isFailure :: ExitCode -> Bool -- | Returns the value that the given process result was constructed with. exitValue :: ExitCode -> Int -- | Computation exitWith code throws ExitCode -- code. Normally this terminates the program, returning -- code to the program's caller. Before the program terminates, -- any open or semi-closed handles are first closed. -- -- A program that fails in any other way is treated as if it had called -- exitFailure. A program that terminates successfully without -- calling exitWith explicitly is treated as it it had called -- exitWith ExitSuccess. -- -- As an ExitCode is not an IOError, exitWith -- bypasses the error handling in the IO monad and cannot be -- intercepted by catch from the Prelude. However it is a -- SomeException, and can be caught using the functions of -- Control.Exception. This means that cleanup computations added -- with bracket (from Control.Exception) are also executed -- properly on exitWith. -- -- Note: in GHC, exitWith should be called from the main program -- thread in order to exit the process. When called from another thread, -- exitWith will throw an ExitException as normal, but -- the exception will not cause the process itself to exit. exitWith :: ExitCode -> IO a -- | The computation exitFailure is equivalent to exitWith -- ('exitCode exitfail'), where exitfail is -- implementation-dependent. exitFailure :: IO a -- | The computation exitSuccess is equivalent to exitWith -- success, It terminates the program sucessfully. exitSuccess :: IO a -- | Runs the first action. -- -- Only if the result is successful, run the second action. (->>) :: Monad m => m ExitCode -> m ExitCode -> m ExitCode -- | Runs the second action. -- -- Only if the result is successful, run the first action. (<<-) :: Monad m => m ExitCode -> m ExitCode -> m ExitCode -- | Run the structure of actions stopping at the first failure. runExitCodes :: (Monad m, Foldable f) => f (m ExitCode) -> m ExitCode -- | Waits for the specified process to terminate, and returns its exit -- code. waitForProcess :: ProcessHandle -> IO ExitCode -- | This is a non-blocking version of waitForProcess. If the -- process is still running, Nothing is returned. If the process -- has exited, then Just e is returned where e -- is the exit code of the process. getProcessExitCode :: ProcessHandle -> IO (Maybe ExitCode) -- | Attempts to terminate the specified process. This function should not -- be used under normal circumstances - no guarantees are given regarding -- how cleanly the process is terminated. To check whether the process -- has indeed terminated, use getProcessExitCode. -- -- On Unix systems, terminateProcess sends the process the SIGTERM -- signal. On Windows systems, the Win32 TerminateProcess -- function is called, passing an exit code of 1. -- -- Note: on Windows, if the process was a shell command created by -- createProcess with shell, or created by -- runCommand or runInteractiveCommand, then -- terminateProcess will only terminate the shell, not the command -- itself. On Unix systems, both processes are in a process group and -- will be terminated together. terminateProcess :: ProcessHandle -> IO () instance Typeable ExitCode instance Eq ExitCode instance Ord ExitCode instance Data ExitCode instance Monoid ExitCode instance Exception ExitCode instance Show ExitCode instance Read ExitCode