agnipau/ slap

(1.3.1) 4 months ago

Rust

Shell

clap

View on GitHub

Need help with slap?

Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

agnipau

129 Stars

0 Forks

Other

61 Commits

12 Opened issues

Description

Painless shell argument parsing and dependency check.

Services available

Need anything else?

Contributors list

No Data

Readme

slap

Name: slap
Brand: slap
SKU: //agnipau/slap
Rating: 2.0725 (129 reviews)

slap (shell

clap

) - painless argument parsing and dependency check.

Why?

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 aims to improve that.

Can't I just use

getopt

or something similiar?

getopt

and similiar tools are not only language-dependent (slap works with a number of shells), but are also just tools to write your own argument parser.
slap is different, in the sense that it puts at your disposal an already written argument parser.
Good luck in writing in bash, powershell, fish or whatever, a full fledged argument parser (using

getopt

if you want) that takes in consideration things like argument order, possible values, subcommands, argument groups, automatic color-enabled help menus, most similiar argument name suggestions etc.

How?

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:

config="path to your YAML config" eval "$(slap parse bash -- "[email protected]"

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.

Installation

If you're an Arch Linux user, you can install slap from the AUR:

# This will install a binary named `slap`.
yay -S slap-cli-bin

If you're a Rust programmer, you can install slap with

cargo

. Make sure to add

~/.cargo/bin

to your

$PATH

# This will install a binary named `slap`.
cargo install slap-cli

You can also download a pre-compiled binary (for

linux

linux-arm

macos

win-msvc

win-gnu

win32-msvc

) from the Releases.

Supported platforms

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.

Completions script generation

Thanks to clap, slap's underlying engine, automatic completions-script generation is supported. For example in bash:

config="path to your YAML config"
slap completions bash completions.bash

completions.bash

now contains a bash script that provides command autocompletion for the CLI described in your YAML config file.

Dependency check

If your script depends on some programs you can check if they are in

$PATH

with the

deps

subcommand:

slap deps curl jq || exit 1

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.

Absolute path of a script

slap includes a

path

subcommand that simplifies getting the absolute path of a script:

# before
abs="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

# with slap
abs="$(slap path -d "${BASH_SOURCE[0]}")"

Both the snippets never dereference symlinks. If you want to dereference symlinks use the

-D

option.

Demo

Example

Here are two useful bash scripts:

slap deps curl jq || exit 1

eval "$(slap parse bash _ -- "[email protected]" <

slap deps jq git || exit 1

eval "$(slap parse bash _ -- "[email protected]" <

Learning material

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.

Elvish

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.

Credits

This program is solely made possible by clap, so many thanks to its authors.

License

^{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.}