Safe Haskell	Safe-Inferred
Language	Haskell2010

Effectful.Process

Contents

Effect
- Handlers
Running sub-processes
- Simpler functions for common tasks
- Related utilities
Process completion
Interprocess communication

Description

Lifted System.Process.

Synopsis

data Process :: Effect
runProcess :: IOE :> es => Eff (Process ': es) a -> Eff es a
createProcess :: Process :> es => CreateProcess -> Eff es (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
createProcess_ :: Process :> es => String -> CreateProcess -> Eff es (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle)
shell :: String -> CreateProcess
proc :: FilePath -> [String] -> CreateProcess
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
}
data CmdSpec
- = ShellCommand String
- | RawCommand FilePath [String]
data StdStream
- = Inherit
- | UseHandle Handle
- | CreatePipe
- | NoStream
data ProcessHandle
callProcess :: Process :> es => FilePath -> [String] -> Eff es ()
callCommand :: Process :> es => String -> Eff es ()
spawnProcess :: Process :> es => FilePath -> [String] -> Eff es ProcessHandle
spawnCommand :: Process :> es => String -> Eff es ProcessHandle
readCreateProcess :: Process :> es => CreateProcess -> String -> Eff es String
readProcess :: Process :> es => FilePath -> [String] -> String -> Eff es String
readCreateProcessWithExitCode :: Process :> es => CreateProcess -> String -> Eff es (ExitCode, String, String)
readProcessWithExitCode :: Process :> es => FilePath -> [String] -> String -> Eff es (ExitCode, String, String)
withCreateProcess :: Process :> es => CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> Eff es a) -> Eff es a
cleanupProcess :: Process :> es => (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -> Eff es ()
showCommandForUser :: FilePath -> [String] -> String
type Pid = CPid
getPid :: Process :> es => ProcessHandle -> Eff es (Maybe Pid)
getCurrentPid :: Process :> es => Eff es Pid
waitForProcess :: Process :> es => ProcessHandle -> Eff es ExitCode
getProcessExitCode :: Process :> es => ProcessHandle -> Eff es (Maybe ExitCode)
terminateProcess :: Process :> es => ProcessHandle -> Eff es ()
interruptProcessGroupOf :: Process :> es => ProcessHandle -> Eff es ()
createPipe :: Process :> es => Eff es (Handle, Handle)
createPipeFd :: Process :> es => Eff es (FD, FD)

Effect

data Process :: Effect Source #

An effect for running child processes using the process library.

Instances

Instances details

type DispatchOf Process Source #
Instance details Defined in Effectful.Process type DispatchOf Process = 'Static 'WithSideEffects
data StaticRep Process Source #
Instance details Defined in Effectful.Process data StaticRep Process = Process

Handlers

runProcess :: IOE :> es => Eff (Process ': es) a -> Eff es a Source #

Running sub-processes

createProcess :: Process :> es => CreateProcess -> Eff es (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #

Lifted createProcess.

createProcess_ :: Process :> es => String -> CreateProcess -> Eff es (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) Source #

Lifted createProcess_.

shell :: String -> CreateProcess #

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

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.

data CreateProcess #

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
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 an 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
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: 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; 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; 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; 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 # show :: CreateProcess -> String # showList :: [CreateProcess] -> ShowS #
Eq CreateProcess
Instance details Defined in System.Process.Common Methods (==) :: CreateProcess -> CreateProcess -> Bool # (/=) :: CreateProcess -> CreateProcess -> Bool #

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

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 #
Show CmdSpec
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> CmdSpec -> ShowS # show :: CmdSpec -> String # showList :: [CmdSpec] -> ShowS #
Eq CmdSpec
Instance details Defined in System.Process.Common Methods (==) :: CmdSpec -> CmdSpec -> Bool # (/=) :: CmdSpec -> CmdSpec -> Bool #

data StdStream #

Constructors

Inherit	Inherit Handle from parent
UseHandle Handle	Use the supplied Handle
CreatePipe	Create a new pipe. The returned `Handle` will use the default encoding and newline translation mode (just like `Handle`s created by `openFile`).
NoStream	Close the stream's file descriptor without passing a Handle. On POSIX systems this may lead to strange behavior in the child process because attempting to read or write after the file has been closed throws an error. This should only be used with child processes that don't use the file descriptor at all. If you wish to ignore the child process's output you should either create a pipe and drain it manually or pass a `Handle` that writes to `/dev/null`.

Instances

Instances details

Show StdStream
Instance details Defined in System.Process.Common Methods showsPrec :: Int -> StdStream -> ShowS # show :: StdStream -> String # showList :: [StdStream] -> ShowS #
Eq StdStream
Instance details Defined in System.Process.Common Methods (==) :: StdStream -> StdStream -> Bool # (/=) :: StdStream -> StdStream -> Bool #

data ProcessHandle #

A handle to a process, which can be used to wait for termination of the process using waitForProcess.

None of the process-creation functions in this library wait for termination: they all return a ProcessHandle which may be used to wait for the process later.

On Windows a second wait method can be used to block for event completion. This requires two handles. A process job handle and a events handle to monitor.

Simpler functions for common tasks

callProcess :: Process :> es => FilePath -> [String] -> Eff es () Source #

Lifted callProcess.

callCommand :: Process :> es => String -> Eff es () Source #

Lifted callCommand.

spawnProcess :: Process :> es => FilePath -> [String] -> Eff es ProcessHandle Source #

Lifted spawnProcess.

spawnCommand :: Process :> es => String -> Eff es ProcessHandle Source #

Lifted spawnCommand.

readCreateProcess :: Process :> es => CreateProcess -> String -> Eff es String Source #

Lifted readCreateProcess.

readProcess :: Process :> es => FilePath -> [String] -> String -> Eff es String Source #

Lifted readProcess.

readCreateProcessWithExitCode :: Process :> es => CreateProcess -> String -> Eff es (ExitCode, String, String) Source #

Lifted readCreateProcessWithExitCode.

readProcessWithExitCode :: Process :> es => FilePath -> [String] -> String -> Eff es (ExitCode, String, String) Source #

Lifted readProcessWithExitCode.

withCreateProcess :: Process :> es => CreateProcess -> (Maybe Handle -> Maybe Handle -> Maybe Handle -> ProcessHandle -> Eff es a) -> Eff es a Source #

Lifted withCreateProcess.

cleanupProcess :: Process :> es => (Maybe Handle, Maybe Handle, Maybe Handle, ProcessHandle) -> Eff es () Source #

Lifted cleanupProcess.

Related utilities

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).

type Pid = CPid #

The platform specific type for a process identifier.

This is always an integral type. Width and signedness are platform specific.

Since: process-1.6.3.0

getPid :: Process :> es => ProcessHandle -> Eff es (Maybe Pid) Source #

Lifted getPid.

getCurrentPid :: Process :> es => Eff es Pid Source #

Lifted getCurrentPid.