process-extras-0.7.4: 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
  - forceOutput :: text -> IO text
- class (IsString text, Monoid text, ListLike text char) => ProcessText text char
- class Monoid result => ProcessResult text result | result -> text where
  - pidf :: ProcessHandle -> result
  - outf :: text -> result
  - errf :: text -> result
  - intf :: SomeException -> result
  - codef :: ExitCode -> result
- class ProcessMaker a where
  - process :: a -> IO (Handle, Handle, Handle, ProcessHandle)
  - showProcessMakerForUser :: a -> String
- 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
  - use_process_jobs :: Bool
  }
- 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 Source #

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

Minimal complete definition

forceOutput, readChunks

Methods

forceOutput :: text -> IO text Source #

#### Instances

Instances details

ListLikeProcessIO Chars Char Source # | Like `readProcessWithExitCode`, but specialized for `Text`
Instance details Defined in System.Process.Chars Methods forceOutput :: Chars -> IO Chars Source # readChunks :: Handle -> IO [Chars] Source #
ListLikeProcessIO ByteString Word8 Source # | Like `readProcessWithExitCode`, but using `ByteString`
Instance details Defined in System.Process.ByteString Methods forceOutput :: ByteString -> IO ByteString Source # readChunks :: Handle -> IO [ByteString] Source #
ListLikeProcessIO ByteString Word8 Source # | Like `readProcessWithExitCode`, but using `ByteString`
Instance details Defined in System.Process.ByteString.Lazy Methods forceOutput :: ByteString -> IO ByteString Source # readChunks :: Handle -> IO [ByteString] Source #
ListLikeProcessIO Text Char Source # | Like `readProcessWithExitCode`, but using `Text`
Instance details Defined in System.Process.Text Methods forceOutput :: Text -> IO Text Source # readChunks :: Handle -> IO [Text] Source #
ListLikeProcessIO Builder Char Source # | Like `readProcessWithExitCode`, but using `Text`
Instance details Defined in System.Process.Text.Builder Methods forceOutput :: Builder -> IO Builder Source # readChunks :: Handle -> IO [Builder] Source #
ListLikeProcessIO Text Char Source # | Like `readProcessWithExitCode`, but using `Text`
Instance details Defined in System.Process.Text.Lazy Methods forceOutput :: Text -> IO Text Source # readChunks :: Handle -> IO [Text] Source #
ListLikeProcessIO String Char Source # | Like `readProcessWithExitCode` that takes a `CreateProcess`.
Instance details Defined in System.Process.ListLike Methods forceOutput :: String -> IO String Source # readChunks :: Handle -> IO [String] Source #

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

#### Instances

Instances details

ProcessText ByteString Word8 Source # |
Instance details Defined in System.Process.ByteString
ProcessText ByteString Word8 Source # |
Instance details Defined in System.Process.ByteString.Lazy
ProcessText Text Char Source # |
Instance details Defined in System.Process.Text
ProcessText Text Char Source # |
Instance details Defined in System.Process.Text.Lazy
ProcessText String Char Source # |
Instance details Defined in System.Process.ListLike

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

Methods

pidf :: ProcessHandle -> result Source #

outf :: text -> result Source #

errf :: text -> result Source #

intf :: SomeException -> result Source #

codef :: ExitCode -> result Source #

#### Instances

Instances details

ListLikeProcessIO a c => ProcessResult a [Chunk a] Source # |
Instance details Defined in System.Process.ListLike Methods pidf :: ProcessHandle -> [Chunk a] Source # outf :: a -> [Chunk a] Source # errf :: a -> [Chunk a] Source # intf :: SomeException -> [Chunk a] Source # codef :: ExitCode -> [Chunk a] Source #
ListLikeProcessIO a c => ProcessResult a (ExitCode, [Chunk a]) Source # |
Instance details Defined in System.Process.ListLike Methods pidf :: ProcessHandle -> (ExitCode, [Chunk a]) Source # outf :: a -> (ExitCode, [Chunk a]) Source # errf :: a -> (ExitCode, [Chunk a]) Source # intf :: SomeException -> (ExitCode, [Chunk a]) Source # codef :: ExitCode -> (ExitCode, [Chunk a]) Source #
ListLikeProcessIO text char => ProcessResult text (ExitCode, text, text) Source # |
Instance details Defined in System.Process.Common Methods pidf :: ProcessHandle -> (ExitCode, text, text) Source # outf :: text -> (ExitCode, text, text) Source # errf :: text -> (ExitCode, text, text) Source # intf :: SomeException -> (ExitCode, text, text) Source # codef :: ExitCode -> (ExitCode, text, text) Source #

class ProcessMaker a where Source #

Methods

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

showProcessMakerForUser :: a -> String Source #

#### Instances

Instances details

ProcessMaker CreateProcess Source # | This is the usual maker argument to `readCreateProcessLazy`.
Instance details Defined in System.Process.Common Methods process :: CreateProcess -> IO (Handle, Handle, Handle, ProcessHandle) Source # showProcessMakerForUser :: CreateProcess -> String Source #
ProcessMaker (CreateProcess, BufferMode, BufferMode) Source # | 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.
Instance details Defined in System.Process.Common Methods process :: (CreateProcess, BufferMode, BufferMode) -> IO (Handle, Handle, Handle, ProcessHandle) Source # showProcessMakerForUser :: (CreateProcess, BufferMode, BufferMode) -> String Source #

# The generalized process runners

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

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

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

Like readCreateProcessStrict, but the output is read lazily.

readCreateProcessWithExitCode Source #

Arguments

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

readProcessWithExitCode Source #

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 Source #

System.Process utility functions.

showCmdSpecForUser :: CmdSpec -> String Source #

# The Chunk type

data Chunk a Source #

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

Instances details

ListLikeProcessIO a c => ProcessResult a [Chunk a] Source # |
Instance details Defined in System.Process.ListLike Methods pidf :: ProcessHandle -> [Chunk a] Source # outf :: a -> [Chunk a] Source # errf :: a -> [Chunk a] Source # intf :: SomeException -> [Chunk a] Source # codef :: ExitCode -> [Chunk a] Source #
ListLikeProcessIO a c => ProcessResult a (ExitCode, [Chunk a]) Source # |
Instance details Defined in System.Process.ListLike Methods pidf :: ProcessHandle -> (ExitCode, [Chunk a]) Source # outf :: a -> (ExitCode, [Chunk a]) Source # errf :: a -> (ExitCode, [Chunk a]) Source # intf :: SomeException -> (ExitCode, [Chunk a]) Source # codef :: ExitCode -> (ExitCode, [Chunk a]) Source #
Show a => Show (Chunk a) Source # |
Instance details Defined in System.Process.ListLike Methods showsPrec :: Int -> Chunk a -> ShowS Source # show :: Chunk a -> String Source # showList :: [Chunk a] -> ShowS Source #

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

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 Source #

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] Source #

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

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

# Re-exports from process

data CmdSpec Source #

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.

Windows does not have a mechanism for passing multiple arguments. When using `RawCommand` on Windows, the command line is serialised into a string, with arguments quoted separately. Command line parsing is up individual programs, so the default behaviour may not work for some programs. If you are not getting the desired results, construct the command line yourself and use `ShellCommand`.

#### Instances

Instances details

IsString CmdSpec | construct a `ShellCommand` from a string literal Since: process-1.2.1.0
Instance details Defined in System.Process.Common Methods fromString :: String -> CmdSpec Source #
Show CmdSpec |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CmdSpec -> ShowS Source # show :: CmdSpec -> String Source # showList :: [CmdSpec] -> ShowS Source #
Eq CmdSpec |
Instance details Defined in System.Process.Common Methods (==) :: CmdSpec -> CmdSpec -> Bool Source # (/=) :: CmdSpec -> CmdSpec -> Bool Source #

data CreateProcess Source #

Constructors

CreateProcess |

Fields

- cmdspec :: CmdSpec

  Executable & arguments, or shell command. If `cwd` is `Nothing`, relative paths are resolved with respect to the current working directory. If `cwd` is provided, it is implementation-dependent whether relative paths are resolved with respect to `cwd` or the current working directory, so absolute paths should be used to ensure portability.

- 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 XXX verify what happens with fds in nodejs child processes

- 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). This implementation will call close on every fd from 3 to the maximum of open files, which can be slow for high maximum of open files.

- create_group :: Bool

  Create a new process group. On JavaScript this also creates a new session.

- delegate_ctlc :: Bool

  Delegate control-C handling. Use this for interactive console processes to let them handle control-C themselves (see below for details).

  Since: process-1.2.0.0

- detach_console :: Bool

  Use the windows DETACHED_PROCESS flag when creating the process; does nothing on other platforms.

  Since: process-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: process-1.3.0.0

- new_session :: Bool

  Use posix setsid to start the new process in a new session; starts process in a new session on JavaScript; does nothing on other platforms.

  Since: process-1.3.0.0

- child_group :: Maybe GroupID

  Use posix setgid to set child process's group id; works for JavaScript when system running nodejs is posix. does nothing on other platforms.

  Default: `Nothing`

  Since: process-1.4.0.0

- child_user :: Maybe UserID

  Use posix setuid to set child process's user id; works for JavaScript when system running nodejs is posix. does nothing on other platforms.

  Default: `Nothing`

  Since: process-1.4.0.0

- use_process_jobs :: Bool

  On Windows systems this flag indicates that we should wait for the entire process tree to finish before unblocking. On POSIX systems this flag is ignored. See $exec-on-windows for details.

  Default: `False`

  Since: process-1.5.0.0

#### Instances

Instances details

Show CreateProcess |
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CreateProcess -> ShowS Source # show :: CreateProcess -> String Source # showList :: [CreateProcess] -> ShowS Source #
Eq CreateProcess |
Instance details Defined in System.Process.Common Methods (==) :: CreateProcess -> CreateProcess -> Bool Source # (/=) :: CreateProcess -> CreateProcess -> Bool Source #
ProcessMaker CreateProcess Source # | This is the usual maker argument to `readCreateProcessLazy`.
Instance details Defined in System.Process.Common Methods process :: CreateProcess -> IO (Handle, Handle, Handle, ProcessHandle) Source # showProcessMakerForUser :: CreateProcess -> String Source #
ProcessMaker (CreateProcess, BufferMode, BufferMode) Source # | 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.
Instance details Defined in System.Process.Common Methods process :: (CreateProcess, BufferMode, BufferMode) -> IO (Handle, Handle, Handle, ProcessHandle) Source # showProcessMakerForUser :: (CreateProcess, BufferMode, BufferMode) -> String Source #

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

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 Source #

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

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

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 Source # |
Instance details Methods showsPrec :: Int -> ProcessHandle -> ShowS Source # show :: ProcessHandle -> String Source # showList :: [ProcessHandle] -> ShowS Source #
ListLikeProcessIO String Char Source # | Like `readProcessWithExitCode` that takes a `CreateProcess`.
Instance details Methods forceOutput :: String -> IO String Source # readChunks :: Handle -> IO [String] Source #
ProcessText String Char Source # |
Instance details