shell

Note that this module exports the module:shell.$ function as a property shell.$ and as shell directly.

That means that you can use more than one syntax when requiring it (see examples).

Source:
Example
// Recommended syntax
const $ = require('shell');


         OR


// Alternative syntax
const $ = require('shell').$;


         OR


// Orthodox syntax...
const shell = require('shell');

// ...then invoke it with prefix
shell.$(....)

Methods

(static) $(tokens) → {shell.Proc}

Source:

Declare a shell command to be wired and executed. This is the base function to invoke commands in a shell fashion.

Examples
// Execute `ls -l` as bash would do
$('ls', '-l').do();
// Execute `ls -l > ls.out` as bash would do
$('ls', '-l')
  .pipe(1, $.file('ls.out'))
  .do();

// Alternative human friendly syntax
$('ls', '-l')
  .pipe(1, 'ls.out')
  .do();
// Execute `more < ls.out` as bash would do
$('more')
  .pipe(0, $.file('ls.out'))
  .do();

// Alternative human friendly syntax
$('more')
  .pipe(0, 'ls.out')
  .do();
// Execute `more <<HERE_STRING_END ... HERE_STRING_END` as bash would do
$('more')
  .pipe(0, $.here('...'))
  .do();

// Alternative human friendly syntax
$('more')
  .pipe(0, ['...'])
  .do();
// Execute `X=$(ls -l)` as bash would do
const x = {};
$('ls', '-l')
  .pipe(1, $.capture(x))
  .do();

// Alternative human friendly syntax
$('ls', '-l')
  .pipe(1, x)
  .do();
// Execute `rm file >/dev/null 2>&1` as bash would do
$('rm', 'file')
  .pipe([1, 2], $.file('/dev/null'))
  .do();

// Alternative human friendly syntax
$('rm', 'file')
  .pipe([1, 2], null)
  .do();
// Execute
// `cd src && LANG=en ls -l | grep -v node_modules >> files.list 2> /dev/null`
// as bash would do it
$('ls', '-l')
  .dir('src')
  .env({LANG: 'en'})
  .pipe(
    1,
    $('grep', '-v', 'node_modules')
      .pipe(1, '+:files.list')
      .pipe(2, null)
  )
  .do();
Parameters:
Name Type Description
tokens string | Array.<string>

Program and arguments to execute as an array or a list of string arguments
Throws:
SysError
Returns:

A Proc object that provides a fluent API to configure the process wiring

Type
shell.Proc

(static) capture(container) → {object}

Source:
See:
  • Proc.pipe

Declare a redirection to save the output or a process to an object variable.

Note that there's also an alternative human friendly syntax that can be used instead of $.capture(...) (see Proc.pipe).

Example
// Execute `X=$(ls -l)` as bash would do
const x = {};
$('ls', '-l')
  .pipe(1, $.capture(x))
  .do();
Parameters:
Name Type Description
container object

An empty object where the output of the piped file descriptor will be stored as a property.

The names of the properties are out and err for file descriptors 1 and 2, and the file descriptor number for the other.
Throws:
SysError
Returns:

An opaque object to be fed to Proc.pipe

Type
object

(static) file(filepath, modeopt) → {object}

Source:
See:
  • Proc.pipe

Create a redirection to pipe a process to/from a file.

Note that there's also an alternative human friendly syntax that can be used instead of $.capture(...) (see Proc.pipe).

Examples
// Execute `ls -l > ls.out` as bash would do
$('ls', '-l')
  .pipe(1, $.file('ls.out'))
  .do();
// Execute `more < ls.out` as bash would do
$('more')
  .pipe(0, $.file('ls.out'))
  .do();
Parameters:
Name Type Attributes Default Description
filepath string

The path to the file
mode '' | '0' | '+' <optional>
 '0' for stdout/err, '' for the rest

The open mode for the file.

Use '' to open the file with module:io.open.

Use '0' to open the file with module:io.truncate.

Use '+' to open the file with module:io.append.
Throws:
SysError
Returns:

An opaque object to be fed to Proc.pipe

Type
object

(static) here(here_string) → {object}

Source:
See:
  • Proc.pipe

Create a redirection to get a process' input from a here string.

Note that there's also an alternative human friendly syntax that can be used instead of $.capture(...) (see Proc.pipe).

Example
// Execute `more <<HERE_STRING_END ... HERE_STRING_END` as bash would do
$('more')
  .pipe(0, $.here('...'))
  .do();
Parameters:
Name Type Description
here_string string

The contents of the here string
Throws:
SysError
Returns:

An opaque object to be fed to Proc.pipe

Type
object

(static) search_path(command) → {string|null}

Source:

Search PATH environment variable for a certain executable (command)

Parameters:
Name Type Description
command string

Command to look for in PATH
Throws:
SysError
Returns:

The absolute path to the command or null if not found

Type
string | null