Module

Node.ChildProcess

Package
purescript-node-child-process
Repository
purescript-node/purescript-node-child-process

This module contains various types and functions to allow you to spawn and interact with child processes.

It is intended to be imported qualified, as follows:

import Node.ChildProcess (ChildProcess, CHILD_PROCESS)
import Node.ChildProcess as ChildProcess

The Node.js documentation will probably also be useful to read if you want to use this module.

#Handle Source

data Handle :: Type

A handle for inter-process communication (IPC).

#CHILD_PROCESS Source

data CHILD_PROCESS :: Effect

The effect for creating and interacting with child processes.

#ChildProcess Source

newtype ChildProcess

#stdin Source

stdin :: forall eff. ChildProcess -> Writable () (cp :: CHILD_PROCESS | eff)

The standard input stream of a child process. Note that this is only available if the process was spawned with the stdin option set to "pipe".

#stdout Source

stdout :: forall eff. ChildProcess -> Readable () (cp :: CHILD_PROCESS | eff)

The standard output stream of a child process. Note that this is only available if the process was spawned with the stdout option set to "pipe".

#stderr Source

stderr :: forall eff. ChildProcess -> Readable () (cp :: CHILD_PROCESS | eff)

The standard error stream of a child process. Note that this is only available if the process was spawned with the stderr option set to "pipe".

#pid Source

pid :: ChildProcess -> Pid

The process ID of a child process. Note that if the process has already exited, another process may have taken the same ID, so be careful!

#connected Source

connected :: forall eff. ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean

#send Source

send :: forall props eff. Record props -> Handle -> ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean

#disconnect Source

disconnect :: forall eff. ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Unit

#kill Source

kill :: forall eff. Signal -> ChildProcess -> Eff (cp :: CHILD_PROCESS | eff) Boolean

Send a signal to a child process. It's an unfortunate historical decision that this function is called "kill", as sending a signal to a child process won't necessarily kill it.

#Exit Source

data Exit

Specifies how a child process exited; normally (with an exit code), or due to a signal.

Constructors

Instances

#onExit Source

onExit :: forall eff. ChildProcess -> (Exit -> Eff eff Unit) -> Eff eff Unit

#onClose Source

onClose :: forall eff. ChildProcess -> (Exit -> Eff eff Unit) -> Eff eff Unit

#onMessage Source

onMessage :: forall eff. ChildProcess -> (Foreign -> Maybe Handle -> Eff eff Unit) -> Eff eff Unit

#onDisconnect Source

onDisconnect :: forall eff. ChildProcess -> Eff eff Unit -> Eff eff Unit

#onError Source

onError :: forall eff. ChildProcess -> (Error -> Eff eff Unit) -> Eff eff Unit

#spawn Source

spawn :: forall eff. String -> Array String -> SpawnOptions -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess

Spawn a child process. Note that, in the event that a child process could not be spawned (for example, if the executable was not found) this will not throw an error. Instead, the ChildProcess will be created anyway, but it will immediately emit an 'error' event.

#SpawnOptions Source

type SpawnOptions = { cwd :: Maybe String, detached :: Boolean, env :: Maybe (StrMap String), gid :: Maybe Gid, stdio :: Array (Maybe StdIOBehaviour), uid :: Maybe Uid }

#exec Source

exec :: forall eff. String -> ExecOptions -> (ExecResult -> Eff (cp :: CHILD_PROCESS | eff) Unit) -> Eff (cp :: CHILD_PROCESS | eff) Unit

Similar to spawn, except that this variant will:

  • run the given command with the shell,
  • buffer output, and wait until the process has exited before calling the callback.

Note that the child process will be killed if the amount of output exceeds a certain threshold (the default is defined by Node.js).

#execFile Source

execFile :: forall eff. String -> Array String -> ExecOptions -> (ExecResult -> Eff (cp :: CHILD_PROCESS | eff) Unit) -> Eff (cp :: CHILD_PROCESS | eff) Unit

Like exec, except instead of using a shell, it passes the arguments directly to the specified command.

#ExecOptions Source

type ExecOptions = { cwd :: Maybe String, env :: Maybe (StrMap String), gid :: Maybe Gid, killSignal :: Maybe Signal, maxBuffer :: Maybe Int, timeout :: Maybe Number, uid :: Maybe Uid }

#ExecResult Source

type ExecResult = { error :: Maybe Error, stderr :: Buffer, stdout :: Buffer }

#fork Source

fork :: forall eff. String -> Array String -> Eff (cp :: CHILD_PROCESS | eff) ChildProcess

A special case of spawn for creating Node.js child processes. The first argument is the module to be run, and the second is the argv (command line arguments).

#Error Source

type Error = { code :: String, errno :: String, syscall :: String }

An error which occurred inside a child process.

#toStandardError Source

toStandardError :: Error -> Error

Convert a ChildProcess.Error to a standard Error, which can then be thrown inside an Eff or Aff computation (for example).

#StdIOBehaviour Source

data StdIOBehaviour

Behaviour for standard IO streams (eg, standard input, standard output) of a child process.

  • Pipe: creates a pipe between the child and parent process, which can then be accessed as a Stream via the stdin, stdout, or stderr functions.
  • Ignore: ignore this stream. This will cause Node to open /dev/null and connect it to the stream.
  • ShareStream: Connect the supplied stream to the corresponding file descriptor in the child.
  • ShareFD: Connect the supplied file descriptor (which should be open in the parent) to the corresponding file descriptor in the child.

Constructors

#pipe Source

pipe :: Array (Maybe StdIOBehaviour)

Create pipes for each of the three standard IO streams.

#inherit Source

inherit :: Array (Maybe StdIOBehaviour)

Share stdin with stdin, stdout with stdout, and stderr with stderr.

#ignore Source

ignore :: Array (Maybe StdIOBehaviour)

Ignore all streams.

Modules
Node.ChildProcess