slap (shell clap) - painless argument parsing and dependency check.
Writing code to parse arguments in a shell scripting language (bash, zsh,
fish etc...) is an extremly verbose, repetitive, error prone, and painful
process.
This program solves that.
You declare your CLI in YAML and pass it to slap's stdin and pass all your
script's arguments to slap as arguments.
slap makes sure that the arguments you pass to it conform to your YAML
description, and if not, it exits with an error code and outputs useful error
messages to stderr.
In other words slap handles the argument parsing logic and validation, your
script only evalutes the code exported by slap and uses the parsed arguments.
Here is an example bash script:
bash
config="path to your YAML config"
eval "$(slap parse bash -- "$@" <"$config")"
The slap-parse subcommand, if the passed arguments conform to the YAML
description, outputs code in the language specified, so you can evaluate it to
have access to the variables containing the parsed arguments.
Relax, slap writes to stdout ONLY if the YAML config is valid and the
arguments passed conform to it, otherwise it doesn't.
This will install you a binary named slap.
bash
cargo install slap-cli
Make sure to add ~/.cargo/bin to your $PATH.
At the moment slap supports bash, zsh, fish, elvish and powershell.
We are planning to support more shells.
If your favourite shell is not supported, make sure to open an issue.
Thanks to clap, slap's underlying engine, automatic completions-script generation is supported. For example in bash:
bash
config="path to your YAML config"
slap bash completions <"$config" >completions.bash
completions.bash now contains a bash script that provides command
autocompletion for the CLI described in your YAML config file.
If your script depends on some programs you can check if they are in $PATH
with the deps subcommand:
bash
slap deps curl jq || exit 1
If curl and jq are found in $PATH the script will continue its execution
and nothing will be printed, otherwise an error will be written to stderr and
slap will exit with a non-zero exit code.
Here are two useful bash scripts:
```bash slap deps curl jq || exit 1
eval "$(slap parse bash _ -- "$@" <<-EOF name: gh-repo-list version: "1.0" about: Outputs JSON containing useful informations about your GitHub repos.
settings: - ArgRequiredElseHelp - ColoredHelp
args: - username: help: your GitHub username required: true - password: help: your GitHub password required: true - iterations: help: the number of iterations to do. 0 means there is no limit long: iterations short: i defaultvalue: "0" EOF )"; [[ -z "${success}" ]] && exit 1
page=1 while :; do data="$(curl -s -X GET \ -u "${usernamevals}:${passwordvals}" \ "https://api.github.com/user/repos?page=${page}&perpage100&type=all")" len="$(printf '%s\n' "${data}" | jq '. | length')" [[ "${iterationsvals}" == "0" && "${len}" == 0 ]] && break printf '%s\n' "${data}" [[ "${page}" == "${iterations_vals}" ]] && break page="$((page + 1))" done ```
```bash slap deps jq git || exit 1
eval "$(slap parse bash _ -- "$@" <<-EOF name: gh-clone-repos version: "1.0" about: Uses 'gh-repo-list' to clone all your GitHub repos.
settings: - ArgRequiredElseHelp - ColoredHelp
args: - username: help: your GitHub username required: true - password: help: your GitHub password required: true - gitoptions: help: "additional Git options (for example: --git-options '--depth 1')" long: git-options takesvalue: true short: o allowhyphenvalues: true EOF )"; [[ -z "${_success}" ]] && exit 1
for repo in $(gh-repo-list "${usernamevals}" "${passwordvals}" \ | jq -r "map(.sshurl) | join(\"\n\")"); do if [[ -n "${gitoptionsoccurs}" ]]; then eval "git clone ${gitoptions_vals} ${repo}" else git clone "${repo}" fi done ```
This YAML config probably contains all the
options you'll ever need.
For additional informations look at clap's
docs.
For powershell, fish, zsh and other
examples look here.
As of v0.14.1, elvish doesn't support eval yet, so you can use slap to
generate elvish code, but you can't yet use the generated code inside an
elvish script.
Luckily there is some work going on for this functionality.
This program is solely made possible by clap, so many thanks to its authors.
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.