Skip to content

Latest commit

 

History

History
136 lines (88 loc) · 4.4 KB

shall.md

File metadata and controls

136 lines (88 loc) · 4.4 KB
Raw

shall(1) - cross-shell compatibility testing

SYNOPSIS

Cross-POSIX-compatible-shell testing:

Run a script file:

shall [-w <shellA>,...] [-q|-Q] [-p <opts>]     <script> [<arg>...]

Execute a command string:

shall [-w <shellA>,...] [-q|-Q] [-p <opts>]  -c <cmd>    [<arg0> <arg>...]

Execute commands specified via stdin:

shall [-w <shellA>,...] [-q|-Q] [-p <opts>] [-s           <arg>...]

Start a REPL (run commands interactively):

shall [-w <shellA>,...]  -i

Default shells targeted are sh, and, if installed, dash, bash, zsh, ksh.
Override with -w or environment variable SHELLS, using a comma-separated
list without spaces; e.g., -w bash,ksh,zsh or SHELLS=bash,ksh,zsh.

-q, -Q quiets stdout, stdout + stderr from the script / commands invoked.
-p passes options through to the target shells.

Standard options: --help, --man, --version, --home

DESCRIPTION

shall invokes a shell script or command with multiple POSIX-like shells in
sequence for cross-shell compatibility testing.

Pass a script filename as the first operand, optionally followed by arguments
to pass to the script.
If shall is in your system's path, you can also create executable scripts
based on it by using the following shebang line:

#!/usr/bin/env shall

Use -c to specify a command string instead; note that the first argument
after the command string is assigned to $0(!).

Use -s to read from stdin; -s is optional if no arguments are passed.

Use -i to enter interactive mode: a simple REPL, where one command at a
time is read from the terminal and executed.

By default, the following shells - if installed - are targeted:

sh dash bash zsh ksh

To specify shells explicitly, use either of the following (in order of precedence):

  • Option -w <shellA>,...; e.g., shall -w bash,zsh ...
  • Environment variable SHELLS; e.g.: SHELLS=bash,zsh shall ...

The exit code reflects the number of shells that reported failure; i.e.,
it is 0 if all shells ran the command successfully.

Output is selectively colored, but only when outputting to a terminal.
Note that only shall's own errors are sent to stderr, whereas captured
command/script output (interleaved stdout and stderr) is always reported via
stdout.
When outputting to a terminal and a command/script's invocation fails for a
given shell, the (entire) output captured is printed in red.

Timing information is reported for each shell.

In interactive mode (-i), history is maintained in file ~/.shall_history.

To get the name of the running shell from within your code in any of the
invocation scenarios, use $(ps -o comm= $$)
When using a command string (-c) or stdin input (-s), you can also use $0.

GLOBAL OPTIONS

  • -q, -Q
    Quiet modes:
    -q suppresses stdout output from the command/script invoked.
    -Q suppresses both stdout and stderr.
    Note that per-shell and overall success status information is still
    reported.

  • -p
    Allows you to pass options through to the shells invoked, as a single
    argument; e.g., -p '-e -o noglob'
    Make sure all shells targeted support the specified options; all
    POSIX-like shells should support the same options as the set builtin
    (see http://is.gd/MJPvPr).

STANDARD OPTIONS

All standard options provide information only.

  • -h, --help
    Prints the contents of the synopsis chapter to stdout for quick reference.

  • --man
    Displays this manual page, which is a helpful alternative to using man,
    if the manual page isn't installed.

  • --version
    Prints version information.

  • --home
    Opens this utility's home page in the system's default web browser.

LICENSE

For license information, bug reports, and more, visit this utility's home page
by running shall --home

EXAMPLES

  # Echo the name of each executing shell.
shall -c 'echo "Hello from $0."'

  # Also echo the 1st argument passed.                
echo 'echo "Passed to $0: $1"' | shall -s one

  # Execute a script, passing the -e shell option (abort on errror).
shall -p '-e' someScript

  # Print the type of the 'which' command in bash and zsh.
shall -w bash,zsh -c 'type which'

  # Enter a REPL that evaluates commands in both bash and dash.
SHELLS=bash,dash shall -i