Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.
Awesome Lists | Featured Topics | Projects
https://github.com/mklement0/shall

A CLI and REPL for invoking shell scripts or commands with multiple POSIX-like shells for portability testing.
https://github.com/mklement0/shall
cli cross-platform posix-sh shell testing unix-cli
Last synced: 23 days ago
JSON representation
A CLI and REPL for invoking shell scripts or commands with multiple POSIX-like shells for portability testing.
Host: GitHub
URL: https://github.com/mklement0/shall
Owner: mklement0
Created: 2014-12-24T04:59:53.000Z (almost 10 years ago)
Default Branch: master
Last Pushed: 2022-12-27T13:52:48.000Z (almost 2 years ago)
Last Synced: 2024-10-05T20:48:07.471Z (about 1 month ago)
Topics: cli, cross-platform, posix-sh, shell, testing, unix-cli
Language: Shell
Homepage:
Size: 90.8 KB
Stars: 43
Watchers: 5
Forks: 3
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md
Awesome Lists containing this project

README

        [![npm version](https://img.shields.io/npm/v/shall.svg)](https://npmjs.com/package/shall) [![license](https://img.shields.io/npm/l/shall.svg)](https://github.com/mklement0/shall/blob/master/LICENSE.md)

**Contents**

- [shall — introduction](#shall-&mdash-introduction)

- [Examples](#examples)

- [Installation](#installation)

  - [Installation from the npm registry](#installation-from-the-npm-registry)

  - [Manual installation](#manual-installation)

- [Usage](#usage)

- [License](#license)

  - [Acknowledgements](#acknowledgements)

  - [npm dependencies](#npm-dependencies)

- [Changelog](#changelog)

# shall — introduction

`shall` is a Unix CLI and REPL for invoking shell scripts or commands with

multiple POSIX-like shells for portability testing.

**`shall`** (for ***sh***ell with ***all*** (POSIX-like) shells) offers a

convenient way of running a given shell script or shell command with a default

set or specifiable set of POSIX-like shells, so as to facilitate testing of

portable (POSIX-compliant, cross-shell) shell code.

By default, the following shells are targeted, if installed: **sh, dash, bash, zsh, ksh**

Additionally, you can use `shall`:

* as a REPL, with `-i`.

* in a script's shebang line.

Each shell's execution is automatically timed to allow performance comparisons.

The syntax is modeled on that of the underlying shells.

See the examples below, concise [usage information](#usage) further below,

or read the [manual](doc/shall.md).

# Examples

```sh

# Echo the name of each executing shell; sample output included.

$ shall -c 'echo "Hello from $0."'

```

![Hello example - sample output](doc/images/example-output-hello.png)

```sh

# Pass a script to all shells via stdin, plus an argument on the command line.

echo 'echo "Passed to $0: $1"' | shall -s one

# Execute script 'foo-script' with argument 'bar' in all shells.

shall foo-script bar

# 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

```

# Installation

**Supported platforms**

* When installing from the [**npm registry**](https://www.npmjs.com): all **Unix-like** platforms supported by [Node.js](http://nodejs.org/) with [**Bash**](http://www.gnu.org/software/bash/) installed.

* When installing **manually**: any **Unix-like** platform with **Bash** installed.

## Installation from the npm registry

^{Note: Even if you don't use Node.js, its package manager, `npm`, works across platforms and is easy to install; try [`curl -L http://git.io/n-install | bash`](https://github.com/mklement0/n-install)}

With [Node.js](http://nodejs.org/) or [io.js](https://iojs.org/) installed, install [the package](https://www.npmjs.com/package/shall) as follows:

    [sudo] npm install shall -g

**Note**:

* Whether you need `sudo` depends on how you installed Node.js / io.js and whether you've [changed permissions later](https://docs.npmjs.com/getting-started/fixing-npm-permissions); if you get an `EACCES` error, try again with `sudo`.

* The `-g` ensures [_global_ installation](https://docs.npmjs.com/getting-started/installing-npm-packages-globally) and is needed to put `shall` in your system's `$PATH`.

## Manual installation

* Download [the CLI](https://raw.githubusercontent.com/mklement0/shall/stable/bin/shall) as `shall`.

* Make it executable with `chmod +x shall`.

* Move it or symlink it to a folder in your `$PATH`, such as `/usr/local/bin` (OSX) or `/usr/bin` (Linux).

# Usage

Find concise usage information below; for complete documentation, read the [manual online](doc/shall.md), or, once installed, run `man shall` (`shall --man` if installed manually).

```nohighlight

$ shall --help

Cross-POSIX-compatible-shell testing:

Run a script file:

    shall [-w ,...] [-q|-Q] [-p ]      [<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

```

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'LICENSE.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

# License

Copyright (c) 2014-2015 Michael Klement, released under the [MIT license](https://spdx.org/licenses/MIT#licenseText).

## Acknowledgements

This project gratefully depends on the following open-source components, according to the terms of their respective licenses.

[npm](https://www.npmjs.com/) dependencies below have optional suffixes denoting the type of dependency; the absence of a suffix denotes a required run-time dependency: `(D)` denotes a development-time-only dependency, `(O)` an optional dependency, and `(P)` a peer dependency.

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the dependencies from 'package.json'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

## npm dependencies

* [doctoc (D)](https://github.com/thlorenz/doctoc)

* [json (D)](https://github.com/trentm/json)

* [marked-man (D)](https://github.com/kapouer/marked-man#readme)

* [replace (D)](https://github.com/harthur/replace)

* [semver (D)](https://github.com/isaacs/node-semver)

* [urchin (D)](https://git.sdf.org/tlevine/urchin)

<!-- DO NOT EDIT THE NEXT CHAPTER and RETAIN THIS COMMENT: The next chapter is updated by `make update-readme/release` with the contents of 'CHANGELOG.md'. ALSO, LEAVE AT LEAST 1 BLANK LINE AFTER THIS COMMENT. -->

# Changelog

Versioning complies with [semantic versioning (semver)](http://semver.org/).

<!-- NOTE: An entry template is automatically added each time `make version` is called. Fill in changes afterwards. -->

* **[v0.2.8](https://github.com/mklement0/shall/compare/v0.2.7...v0.2.8)** (2015-10-23):

  * [doc] `README.md` examples still contained obsolete `-l` switch.

  * [dev] Improved robustness of internal `rreadlink()` function.

* **[v0.2.7](https://github.com/mklement0/shall/compare/v0.2.6...v0.2.7)** (2015-09-20):

  * [dev] Confusing changelog typos fixed.

  * [dev] Removed post-install command that verifies presence of Bash, because

    `npm` always _prints_ the command during installation, which can be confusing.  

* **[v0.2.6](https://github.com/mklement0/shall/compare/v0.2.5...v0.2.6)** (2015-09-19):

  * [doc] `shall` now has a man page (if manually installed, use `shall --man`);

          `shall -h` now just prints concise usage information.

* **[v0.2.5](https://github.com/mklement0/shall/compare/v0.2.4...v0.2.5)** (2015-09-15):

  * [dev] Makefile improvements; various other behind-the-scenes tweaks.

* **[v0.2.4](https://github.com/mklement0/shall/compare/v0.2.3...v0.2.4)** (2015-07-08):

  * [fix] Pass-through option-arguments with embedded spaces are now handled correctly; process substitution replaced with alternative so as to improve FreeBSD compatibility.

  * [doc] Read-me improved, notably: manual-installation instructions added, TOC added.

* **[v0.2.3](https://github.com/mklement0/shall/compare/v0.2.2...v0.2.3)** (2015-06-26):

  * [doc] Read-me: npm badge changed to [shields.io](http://shields.io); license badge added; typo fixed.

  * [dev] To-do added; Makefile updated.

* **v0.2.2** (2015-05-31):

  * [doc] [npm registry badge](https://badge.fury.io) added

* **v0.2.1** (2015-05-27):

  * [fix] Options passed through with -p are no longer ignored on Linux.

  * [fix] Removed extraneous status output.

* **v0.2.0** (2015-05-24):

  * [new] New -p option allows passing additional options through to the shells invoked; e.g.: -p '-e'

  * [deprecated] -l option for specifying shells to target renamed to -w to avoid confusion with shells' native -l version (login shells); -l will continue to work. 

  * [robustness] Exit codes relating to shall's *own* failures changed to: 126 (incorrect arguments) and 127 (unexpected failure), chosen so as to avoid clashes with exit codes produced during normal operation and termination by signal.

* **v0.1.7** (2015-02-11):

  * [doc] improved description in package.json

* **v0.1.6** (2015-02-11):

  * [fix] When using the default target shells, only those actually installed should be targeted.

* **v0.1.5** (2015-02-11):

  * [install] warning added, if bash not found

  * [dev] bash-presence test improved

  * [dev] Makefile improvements

* **v0.1.4** (2015-02-11):

  * [dev] testing no longer requires the CLI to be in the path

  * [dev] bash-presence test added

  * [dev] Makefile improvements

  * [doc] read-me improvements (examples)

* **v0.1.3** (2015-01-28):

  * [doc] read-me typo corrected

  * [dev] Makefile improvements

* **v0.1.2** (2015-01-27):

  * [fix] -q option no longer masks failures

  * [doc] CLI help and read-me updates

  * [dev] Urchin-based tests added

* **v0.1.1** (2014-12-23):

  * [doc] read-me and CLI help fixes

* **v0.1.0** (2014-12-23):

  * Initial release