process-extras-0.7.1: Process extras

Safe Haskell | None
Language | Haskell2010

System.Process.ListLike

Contents

- Classes for process IO monad, output type, and creation type
- The generalized process runners
- Utility functions based on showCommandForUser
- The Chunk type
- Re-exports from process
- Orphan instances

Description

Re-export all symbols and instances of the process-extras package. Adds the Chunk type with a ProcessOutput instance, and a collectOutput function to turn a list of chunks into any instance of ProcessOutput, such as (ExitCode, String, String). This means you can have readCreateProcess output a list of Chunk, operate on it to do progress reporting, and finally convert it to the type that readProcessWithExitCode woud have returned.

Synopsis

- class ListLikeIO text char => ListLikeProcessIO text char where
- class (IsString text, Monoid text, ListLike text char) => ProcessText text char
- class Monoid result => ProcessResult text result | result -> text where
- class ProcessMaker a where
- readCreateProcess :: (ProcessMaker maker, ProcessResult text result, ListLikeProcessIO text char) => maker -> text -> IO result
- readCreateProcessStrict :: (ProcessMaker maker, ProcessResult text result, ListLikeProcessIO text char) => maker -> text -> IO result
- readCreateProcessLazy :: (ProcessMaker maker, ProcessResult a b, ListLikeProcessIO a c) => maker -> a -> IO b
- readCreateProcessWithExitCode :: (ProcessMaker maker, ListLikeProcessIO text char) => maker -> text -> IO (ExitCode, text, text)
- readProcessWithExitCode :: ListLikeProcessIO text char => FilePath -> [String] -> text -> IO (ExitCode, text, text)
- showCreateProcessForUser :: CreateProcess -> String
- showCmdSpecForUser :: CmdSpec -> String
- data Chunk a
  - = ProcessHandle ProcessHandle
  - | Stdout a
  - | Stderr a
  - | Result ExitCode
  - | Exception SomeException
- collectOutput :: ProcessResult a b => [Chunk a] -> b
- foldOutput :: (ProcessHandle -> r) -> (a -> r) -> (a -> r) -> (SomeException -> r) -> (ExitCode -> r) -> Chunk a -> r
- writeOutput :: ListLikeIO a c => [Chunk a] -> IO [Chunk a]
- writeChunk :: ListLikeIO a c => Chunk a -> IO (Chunk a)
- data CmdSpec :: *
  - = ShellCommand String
  - | RawCommand FilePath [String]
- data CreateProcess :: * = CreateProcess {
  - cmdspec :: CmdSpec
  - cwd :: Maybe FilePath
  - env :: Maybe [(String, String)]
  - std_in :: StdStream
  - std_out :: StdStream
  - std_err :: StdStream
  - close_fds :: Bool
  - create_group :: Bool
  - delegate_ctlc :: Bool
  - detach_console :: Bool
  - create_new_console :: Bool
  - new_session :: Bool
  - child_group :: Maybe GroupID
  - child_user :: Maybe UserID
  }
- proc :: FilePath -> [String] -> CreateProcess
- shell :: String -> CreateProcess
- showCommandForUser :: FilePath -> [String] -> String

# Classes for process IO monad, output type, and creation type

class ListLikeIO text char => ListLikeProcessIO text char where #

Process IO is based on the `ListLikeIO` class from the ListLike package

Minimal complete definition

forceOutput, readChunks

Methods

forceOutput :: text -> IO text #

class (IsString text, Monoid text, ListLike text char) => ProcessText text char #

class Monoid result => ProcessResult text result | result -> text where #

Minimal complete definition

pidf, outf, errf, intf, codef

Methods

pidf :: ProcessHandle -> result #

outf :: text -> result #

errf :: text -> result #

intf :: SomeException -> result #

codef :: ExitCode -> result #

Instances

ListLikeProcessIO a c => ProcessResult a [Chunk a] # |
Methods pidf :: ProcessHandle -> [Chunk a] # outf :: a -> [Chunk a] # errf :: a -> [Chunk a] # intf :: SomeException -> [Chunk a] # codef :: ExitCode -> [Chunk a] #
ListLikeProcessIO a c => ProcessResult a (ExitCode, [Chunk a]) # |
Methods pidf :: ProcessHandle -> (ExitCode, [Chunk a]) # outf :: a -> (ExitCode, [Chunk a]) # errf :: a -> (ExitCode, [Chunk a]) # intf :: SomeException -> (ExitCode, [Chunk a]) # codef :: ExitCode -> (ExitCode, [Chunk a]) #
ListLikeProcessIO text char => ProcessResult text (ExitCode, text, text) # |
Methods pidf :: ProcessHandle -> (ExitCode, text, text) # outf :: text -> (ExitCode, text, text) # errf :: text -> (ExitCode, text, text) # intf :: SomeException -> (ExitCode, text, text) # codef :: ExitCode -> (ExitCode, text, text) #

class ProcessMaker a where #

Minimal complete definition

process, showProcessMakerForUser

Methods

process :: a -> IO (Handle, Handle, Handle, ProcessHandle) #

showProcessMakerForUser :: a -> String #

Instances

ProcessMaker CreateProcess # | This is the usual maker argument to `readCreateProcessLazy`.
Methods process :: CreateProcess -> IO (Handle, Handle, Handle, ProcessHandle) # showProcessMakerForUser :: CreateProcess -> String #
ProcessMaker (CreateProcess, BufferMode, BufferMode) # | Passing this to `readCreateProcessLazy` as the maker argument allows you to set the buffer mode of the process stdout and stderr handles just after the handles are created. These are set to BlockBuffering by default, but for running console commands LineBuffering is probably what you want.
Methods process :: (CreateProcess, BufferMode, BufferMode) -> IO (Handle, Handle, Handle, ProcessHandle) # showProcessMakerForUser :: (CreateProcess, BufferMode, BufferMode) -> String #

# The generalized process runners

readCreateProcess :: (ProcessMaker maker, ProcessResult text result, ListLikeProcessIO text char) => maker -> text -> IO result #

readCreateProcessStrict :: (ProcessMaker maker, ProcessResult text result, ListLikeProcessIO text char) => maker -> text -> IO result #

readCreateProcessLazy :: (ProcessMaker maker, ProcessResult a b, ListLikeProcessIO a c) => maker -> a -> IO b #

Like readCreateProcessStrict, but the output is read lazily.

readCreateProcessWithExitCode #

Arguments

:: (ProcessMaker maker, ListLikeProcessIO text char) |
=> maker | command and arguments to run
-> text | standard input
-> IO (ExitCode, text, text) | exitcode, stdout, stderr

readProcessWithExitCode #

Arguments

:: ListLikeProcessIO text char |
=> FilePath | command to run
-> [String] | any arguments
-> text | standard input
-> IO (ExitCode, text, text) | exitcode, stdout, stderr

Like `readProcessWithExitCode`, but with generalized input and output type. Aside from the usual text-like types, the output can be a list of Chunk a. This lets you process the chunks received from stdout and stderr lazil, in the order they are received, as well as the exit code. Utilities to handle Chunks are provided in System.Process.ListLike.

# Utility functions based on showCommandForUser

showCreateProcessForUser :: CreateProcess -> String #

System.Process utility functions.

showCmdSpecForUser :: CmdSpec -> String #

# The Chunk type

data Chunk a #

This type is a concrete representation of the methods of class ProcessOutput. If you take your process output as this type you could, for example, echo all the output and then use collectOutput below to convert it to any other instance of ProcessOutput.

Constructors

ProcessHandle ProcessHandle | This will always come first, before any output or exit code.
Stdout a |
Stderr a |
Result ExitCode |
Exception SomeException | Note that the instances below do not use this constructor.

Instances

ListLikeProcessIO a c => ProcessResult a [Chunk a] # |
Methods pidf :: ProcessHandle -> [Chunk a] # outf :: a -> [Chunk a] # errf :: a -> [Chunk a] # intf :: SomeException -> [Chunk a] # codef :: ExitCode -> [Chunk a] #
ListLikeProcessIO a c => ProcessResult a (ExitCode, [Chunk a]) # |
Methods pidf :: ProcessHandle -> (ExitCode, [Chunk a]) # outf :: a -> (ExitCode, [Chunk a]) # errf :: a -> (ExitCode, [Chunk a]) # intf :: SomeException -> (ExitCode, [Chunk a]) # codef :: ExitCode -> (ExitCode, [Chunk a]) #
Show a => Show (Chunk a) # |
Methods showsPrec :: Int -> Chunk a -> ShowS # show :: Chunk a -> String # showList :: [Chunk a] -> ShowS #

collectOutput :: ProcessResult a b => [Chunk a] -> b #

Turn a `[Chunk a]` into any other instance of `ProcessOutput`. I usually use this after processing the chunk list to turn it into the (ExitCode, String, String) type returned by readProcessWithExitCode.

foldOutput #

Arguments

:: (ProcessHandle -> r) | called when the process handle becomes known
-> (a -> r) | stdout handler
-> (a -> r) | stderr handler
-> (SomeException -> r) | exception handler
-> (ExitCode -> r) | exit code handler
-> Chunk a |
-> r |

writeOutput :: ListLikeIO a c => [Chunk a] -> IO [Chunk a] #

Send Stdout chunks to stdout and Stderr chunks to stderr. Returns input list unmodified.

writeChunk :: ListLikeIO a c => Chunk a -> IO (Chunk a) #

# Re-exports from process

data CmdSpec :: * #

Constructors

ShellCommand String | A command line to execute using the shell
RawCommand FilePath [String] | The name of an executable with a list of arguments The `FilePath` argument names the executable, and is interpreted according to the platform's standard policy for searching for executables. Specifically: on Unix systems the execvp(3) semantics is used, where if the executable filename does not contain a slash (`/`) then the `PATH` environment variable is searched for the executable. on Windows systems the Win32 `CreateProcess` semantics is used. Briefly: if the filename does not contain a path, then the directory containing the parent executable is searched, followed by the current directory, then some standard locations, and finally the current `PATH`. An `.exe` extension is added if the filename does not already have an extension. For full details see the documentation for the Windows `SearchPath` API.

Instances

IsString CmdSpec | construct a `ShellCommand` from a string literal Since: 1.2.1.0
Methods fromString :: String -> CmdSpec #

data CreateProcess :: * #

Constructors

CreateProcess |
Fields cmdspec :: CmdSpec Executable & arguments, or shell command cwd :: Maybe FilePath Optional path to the working directory for the new process env :: Maybe [(String, String)] Optional environment (otherwise inherit from the current process) std_in :: StdStream How to determine stdin std_out :: StdStream How to determine stdout std_err :: StdStream How to determine stderr close_fds :: Bool 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) create_group :: Bool Create a new process group delegate_ctlc :: Bool Delegate control-C handling. Use this for interactive console processes to let them handle control-C themselves (see below for details). On Windows this has no effect. Since: 1.2.0.0 detach_console :: Bool Use the windows DETACHED_PROCESS flag when creating the process; does nothing on other platforms. Since: 1.3.0.0 create_new_console :: Bool Use the windows CREATE_NEW_CONSOLE flag when creating the process; does nothing on other platforms. Default: `False` Since: 1.3.0.0 new_session :: Bool Use posix setsid to start the new process in a new session; does nothing on other platforms. Since: 1.3.0.0 child_group :: Maybe GroupID Use posix setgid to set child process's group id; does nothing on other platforms. Default: `Nothing` Since: 1.4.0.0 child_user :: Maybe UserID Use posix setuid to set child process's user id; does nothing on other platforms. Default: `Nothing` Since: 1.4.0.0

Instances

ProcessMaker CreateProcess # | This is the usual maker argument to `readCreateProcessLazy`.
Methods process :: CreateProcess -> IO (Handle, Handle, Handle, ProcessHandle) # showProcessMakerForUser :: CreateProcess -> String #
ProcessMaker (CreateProcess, BufferMode, BufferMode) # | Passing this to `readCreateProcessLazy` as the maker argument allows you to set the buffer mode of the process stdout and stderr handles just after the handles are created. These are set to BlockBuffering by default, but for running console commands LineBuffering is probably what you want.
Methods process :: (CreateProcess, BufferMode, BufferMode) -> IO (Handle, Handle, Handle, ProcessHandle) # showProcessMakerForUser :: (CreateProcess, BufferMode, BufferMode) -> String #

proc :: FilePath -> [String] -> CreateProcess #

Construct a `CreateProcess` record for passing to `createProcess`, representing a raw command with arguments.

See `RawCommand` for precise semantics of the specified `FilePath`.

shell :: String -> CreateProcess #

Construct a `CreateProcess` record for passing to `createProcess`, representing a command to be passed to the shell.

showCommandForUser :: FilePath -> [String] -> String #

Given a program `p` and arguments `args`, `showCommandForUser p args` returns a string suitable for pasting into `/bin/sh` (on Unix systems) or `CMD.EXE` (on Windows).

# Orphan instances

Show ProcessHandle # |
Methods showsPrec :: Int -> ProcessHandle -> ShowS # show :: ProcessHandle -> String # showList :: [ProcessHandle] -> ShowS #
ListLikeProcessIO String Char # | Like `readProcessWithExitCode` that takes a `CreateProcess`.
Methods forceOutput :: String -> IO String # readChunks :: Handle -> IO [String] #
ProcessText String Char # |