-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Conveniently run shell commands
--
-- This is a standalone version of the powerful and intuitive command
-- line functions present in the Shake build system.
--
-- They are intended as an easy-to-remember, easy-to-use alternative to
-- the System.Process functions.
--
-- All credit goes to the Shake author! I hope he'll take it over as a
-- standalone project.
--
-- CHANGELOG
--
-- Version 0.1.0
--
--
-- - Initial version, copied from Shake.
--
@package command
@version 0.1.1
module System.Command
-- | Execute a system command. Before running command make sure you
-- need any files that are required by the command.
--
-- This function takes a list of options (often just [], see
-- CmdOption for the available options), the name of the
-- executable (either a full name, or a program on the $PATH)
-- and a list of arguments. The result is often (), but can be a
-- tuple containg any of Stdout, Stderr and Exit.
-- Some examples:
--
--
-- command_ [] "gcc" ["-c","myfile.c"] -- compile a file, throwing an exception on failure
-- Exit c <- command [] "gcc" ["-c",myfile] -- run a command, recording the exit code
-- (Exit c, Stderr err) <- command [] "gcc" ["-c","myfile.c"] -- run a command, recording the exit code and error output
-- Stdout out <- command [] "gcc" ["-MM","myfile.c"] -- run a command, recording the output
-- command_ [Cwd "generated"] "gcc" ["-c",myfile] -- run a command in a directory
--
--
-- Unless you retrieve the ExitCode using Exit, any
-- ExitFailure will throw an error, including the Stderr in
-- the exception message. If you capture the Stdout or
-- Stderr, that stream will not be echoed to the console, unless
-- you use the option EchoStdout or EchoStderr.
--
-- If you use command inside a do block and do not use
-- the result, you may get a compile-time error about being unable to
-- deduce CmdResult. To avoid this error, use command_.
command :: CmdResult r => [CmdOption] -> String -> [String] -> IO r
-- | A version of command where you do not require any results, used
-- to avoid errors about being unable to deduce CmdResult.
command_ :: [CmdOption] -> String -> [String] -> IO ()
-- | A variable arity version of command.
--
--
-- - String arguments are treated as whitespace separated
-- arguments.
-- - [String] arguments are treated as literal arguments.
-- - CmdOption arguments are used as options.
--
--
-- To take the examples from command:
--
--
-- () <- cmd "gcc -c myfile.c" -- compile a file, throwing an exception on failure
-- Exit c <- cmd "gcc -c" [myfile] -- run a command, recording the exit code
-- (Exit c, Stderr err) <- cmd "gcc -c myfile.c" -- run a command, recording the exit code and error output
-- Stdout out <- cmd "gcc -MM myfile.c" -- run a command, recording the output
-- cmd (Cwd "generated") "gcc -c" [myfile] :: IO () -- run a command in a directory
--
--
-- When passing file arguments we use [myfile] so that if the
-- myfile variable contains spaces they are properly escaped.
--
-- If you use cmd inside a do block and do not use the
-- result, you may get a compile-time error about being unable to deduce
-- CmdResult. To avoid this error, bind the result to (),
-- or include a type signature.
cmd :: CmdArguments args => args :-> IO r
-- | Collect the stdout of the process. If you are collecting the
-- stdout, it will not be echoed to the terminal, unless you
-- include EchoStdout.
newtype Stdout
Stdout :: String -> Stdout
fromStdout :: Stdout -> String
-- | Collect the stderr of the process. If you are collecting the
-- stderr, it will not be echoed to the terminal, unless you
-- include EchoStderr.
newtype Stderr
Stderr :: String -> Stderr
fromStderr :: Stderr -> String
-- | Collect the ExitCode of the process. If you do not collect the
-- exit code, any ExitFailure will cause an exception.
newtype Exit
Exit :: ExitCode -> Exit
fromExit :: Exit -> ExitCode
-- | A class for specifying what results you want to collect from a
-- process. Values are formed of Stdout, Stderr,
-- Exit and tuples of those.
class CmdResult a
-- | Options passed to command or cmd to control how
-- processes are executed.
data CmdOption
-- | Change the current directory in the spawned process. By default uses
-- this processes current directory.
Cwd :: FilePath -> CmdOption
-- | Change the environment variables in the spawned process. By default
-- uses this processes environment.
Env :: [(String, String)] -> CmdOption
-- | Given as the stdin of the spawned process. By default no
-- stdin is given.
Stdin :: String -> CmdOption
-- | Pass the command to the shell without escaping - any arguments will be
-- joined with spaces. By default arguments are escaped properly.
Shell :: CmdOption
-- | Treat the stdin/stdout/stderr messages as
-- binary. By default streams use text encoding.
BinaryPipes :: CmdOption
-- | Name to use with traced, or "" for no tracing. By
-- default traces using the name of the executable.
Traced :: String -> CmdOption
-- | Should I include the stderr in the exception if the command
-- fails? Defaults to True.
WithStderr :: Bool -> CmdOption
-- | Should I echo the stdout? Defaults to True unless a
-- Stdout result is required.
EchoStdout :: Bool -> CmdOption
-- | Should I echo the stderr? Defaults to True unless a
-- Stderr result is required.
EchoStderr :: Bool -> CmdOption
instance Eq CmdOption
instance Ord CmdOption
instance Show CmdOption
instance Eq Result
instance Arg [CmdOption]
instance Arg CmdOption
instance Arg [String]
instance Arg String
instance CmdResult r => CmdArguments (IO r)
instance (Arg a, CmdArguments r) => CmdArguments (a -> r)
instance (CmdResult x1, CmdResult x2, CmdResult x3) => CmdResult (x1, x2, x3)
instance (CmdResult x1, CmdResult x2) => CmdResult (x1, x2)
instance CmdResult ()
instance CmdResult Stderr
instance CmdResult Stdout
instance CmdResult ExitCode
instance CmdResult Exit