shall/doc/shall.md

Unix CLI and REPL for invoking shell scripts or commands with multiple POSIX-like shells for portability testing.

<!-- DO NOT EDIT THIS FILE: It is auto-generated by `make update-man` -->

# 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