Where is the documentation?

Exports

require('blastoise-shell') returns a single BlastoiseShell: The root shell.

The root shell is a null shell (i.e. its command is null), but it can be piped from to create new shells. The only way to create new shells is to pipe from the root shell.

BlastoiseShell::noThrow

Returns a new instance of BlastoiseShell, piping from this instance.

The new instance has throw behavior disabled. No errors are thrown if there's an error executing a command, if a subprocess exits with a non-zero exit code, if a subprocess is terminated by a signal, or if there's a pipe error.

Instead, the shell returns the error code (e.g.: EACCES), the non-zero subprocess exit code (e.g. 255), or the termination signal name (e.g. SIGTERM).

throw behavior is inheritted by piping.

throw behavior enabled by default on the root shell.

BlastoiseShell::throw

Returns a new instance of BlastoiseShell, piping from this instance.

The new instance has throw behavior enabled. Errors will be thrown if there's an error executing a command, if a subprocess exits with a non-zero exit code, if a subprocess is terminated by a signal, or if there's a pipe error.

throw behavior is inheritted by piping.

throw behavior is enabled by default on the root shell.

It only makes sense to call BlastoiseShell::throw on shells that have throw behavior disabled (usually due to piping from another shell with throw behavior disabled).

BlastoiseShell::exec(cmd, ...args)

Note: Throws an error if this shell instance's subprocess is already started, regardless of throw behavior.

Returns a new instance of BlastoiseShell, piping from this instance. The new instance will run cmd with args arguments when it's started.

cmd must be a command available from the PATH environment variable directory list (e.g.: cat), or a relative path from the script's current working directory to an executable file (e.g. ./my-script.sh).

args are expanded according to the following rules:

• for (let arg of args):
  • If arg is NOT an object, do not expand it (leaves it as-is).
  • for (let [opt, val] of Object.entries(arg)):
    • If val === false, remove arg (arg is elided).
    • If opt is 1 character long, prefix it with a dash (e.g.: f => -f).
    • Otherwise, prefix it with two dashes (e.g.: force => --force).
    • If val === true, expand ${opt} (including prefixes above).
    • If val is an array, for (let v of val):
      • Expand ${opt} ${v} (e.g.: { n: [1, 2, 3] } => -n 1 -n 2 -n 3).
    • Otherwise, expand ${opt} ${val} (e.g.: { depth: 5 } => --depth 5).

Each individual item in args after expansion will be passed exactly to the subprocess as an individual argument.

The subprocess is NOT immediately started. They are lazily started only when BlastoiseShell::then or BlastoiseShell::catch is called.

BlastoiseShell::appendTo(path)

Note: Throws an error if this shell instance's subprocess is already started, regardless of throw behavior.

Pipes this shell instance's subprocess' standard output to the file located under path. The file is appended to, not overwritten.

May fail with errors: EACCES, EISDIR, etc.

If throw behavior is enabled, errors are thrown. Otherwise, error codes are returned.

BlastoiseShell::writeTo(path)

Note: Throws an error if this shell instance's subprocess is already started, regardless of throw behavior.

Pipes this shell instance's subprocess' standard output to the file located under path. The file is truncated and overwritten.

May fail with errors: EACCES, EISDIR, etc.

If throw behavior is enabled, errors are thrown. Otherwise, error codes are returned.