std/proc

NAME

std/proc - Process execution, environment, and signals.

SYNOPSIS

  from std/proc import Proc, Env, sleep;

  let pid := Proc.pid();
  let home := Env.get("HOME", "");

  let res := Proc.run(
    "perl",
    [ "-e", "print qq<ok\\n>;" ]
  );

  let seen := 0;
  Proc.onsignal( "USR1", function () {
    seen++;
  } );
  Proc.kill( "USR1", Proc.pid() );

  sleep(0.1);

IMPLEMENTATION SUPPORT

This module is supported by zuzu.pl, zuzu-rust, and zuzu-js on Node and Electron. It is not supported by zuzu-js in the browser.

DESCRIPTION

This module provides OS process helpers, environment variable helpers, signal send/receive primitives, process-identification helpers, and process exit.

EXPORTS

Classes

Proc
Static methods:
- pid()
  Parameters: none. Returns: Number. Returns the current process id.
- exit(code?)
  Parameters: code is an optional numeric exit status. Returns: null. Exits the current process.
- run(command, argv?, options?)
  Parameters: command is an executable, argv is an optional array of arguments, and options controls execution. Returns: Dict. Runs one process and returns its result.
  
  Options include stdin, capture_stdout, capture_stderr, and merge_stderr. Also supports env injection, cwd, and timeout.
- run_async(command, argv?, options?)
  Parameters: same as run. Returns: Task. Awaitable version of run resolving to the same result dictionary.
- pipeline(commands, options?)
  Parameters: commands is an array of command specs and options controls execution. Returns: Dict. Runs commands in sequence, piping captured stdout from each step to the next step's stdin.
- pipeline_async(commands, options?)
  Parameters: same as pipeline. Returns: Task. Awaitable version of pipeline resolving to the same result dictionary.
- is_success(result)
  Parameters: result is a process result dictionary. Returns: Boolean. Returns true when the command exited successfully.
- status_text(result)
  Parameters: result is a process result dictionary. Returns: String. Formats the process status for display.
- kill(String signal, Number pid?)
  Parameters: signal is a signal name and pid is an optional process id. Returns: null. Sends a signal to a process.
- onsignal(String signal, Function callback)
  Parameters: signal is a signal name and callback is a handler. Returns: null. Registers a process signal callback.
Env
Static methods:
- get(String name, Any default?)
  Parameters: name is an environment variable name and default is an optional fallback. Returns: String or value. Returns an environment variable value or the fallback.
- set(String name, String value)
  Parameters: name is an environment variable name and value is its new value. Returns: null. Sets an environment variable.
- remove(String name)
  Parameters: name is an environment variable name. Returns: null. Removes an environment variable.

Functions

sleep(seconds)
Parameters: seconds is the delay in seconds. Returns: null. Sleeps for the requested time; fractional seconds are allowed.
sleep_async(seconds)
Parameters: seconds is the delay in seconds. Returns: Task. Returns an awaitable task that completes after the requested delay.

COPYRIGHT AND LICENCE

std/proc is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module