slap

slap (shell clap) - 轻松的参数解析和依赖检查。

为什么选择它？

在 shell 脚本语言（如 bash、zsh、fish 等）中编写解析参数的代码是一个极其冗长、重复、容易出错且痛苦的过程。
这个程序旨在改进这一点。

我难道不能只用 getopt 或类似的工具吗？

getopt 和类似的工具不仅依赖于特定语言（slap 与多种 shell 兼容），而且仅仅是用来编写您自己的参数解析器。
slap 与其不同之处在于，它为您提供了已经编写好的参数解析器。
祝您好运，在 bash、powershell、fish 或任何其他语言中编写一个完整的参数解析器（如果您想使用 getopt，当然可以），它会考虑诸如参数顺序、可能的值、子命令、参数组、自动启用的颜色帮助菜单、最相似的参数名称建议等。

它是如何工作的？

您用 YAML 声明您的 CLI 并将其传递给 slap 的 stdin，并将所有脚本参数作为参数传递给 slap。
slap 确保您传递给它的参数符合您的 YAML 描述，如果不一致，它将退出并返回错误代码，同时在 stderr 输出有用的错误信息。
换句话说，slap 处理参数解析逻辑和验证，您的脚本只需评估 slap 导出的代码并使用解析后的参数。
这里是一个 bash 脚本的例子

config="path to your YAML config"
eval "$(slap parse bash -- "$@" <"$config")"

slap-parse 子命令，如果传递的参数符合 YAML 描述，将以指定的语言输出代码，这样您就可以评估它以访问包含解析参数的变量。
放心，slap 仅在 YAML 配置有效且传递的参数符合它时才写入 stdout，否则不会。

安装

如果您是 Arch Linux 用户，您可以从 AUR 安装 slap

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

如果您是 Rust 程序员，可以使用 cargo 安装 slap。请确保将 ~/.cargo/bin 添加到您的 $PATH。

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

您还可以从 发布版 下载预编译的二进制文件（适用于 linux、linux-arm、macos、win-msvc、win-gnu、win32-msvc）。

支持的平台

目前 slap 支持 bash、zsh、fish、elvish 和 powershell。
我们计划支持更多的 shell。
如果您的首选 shell 不受支持，请确保提交一个 issue。

完成脚本生成

感谢 clap，slap 的底层引擎支持自动完成脚本生成。例如，在 bash 中

config="path to your YAML config"
slap completions bash <"$config" >completions.bash

completions.bash 现在包含一个 bash 脚本，它提供了您在 YAML 配置文件中描述的 CLI 的命令自动完成功能。

依赖性检查

如果您的脚本依赖于某些程序，您可以使用 deps 子命令检查它们是否在 $PATH 中。

slap deps curl jq || exit 1

如果 curl 和 jq 在 $PATH 中找到，则脚本将继续执行而不会打印任何内容，否则错误将被写入 stderr，slap 将以非零退出代码退出。

脚本的绝对路径

slap 包含一个 path 子命令，该命令简化了获取脚本绝对路径的过程

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

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

这两个片段都不会解引用符号链接。如果您想解引用符号链接，请使用 -D 选项。

演示

示例

以下有两个有用的 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
    - ColorAuto

global_settings:
    - 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
        default_value: "0"
EOF
)"; [[ -z "${_success}" ]] && exit 1

page=1
while :; do
    data="$(curl -s -X GET \
        -u "${_username_vals}:${_password_vals}" \
    "https://api.github.com/user/repos?page=${page}&per_page100&type=all")"
    len="$(printf '%s\n' "${data}" | jq '. | length')"
    [[ "${_iterations_vals}" == "0" && "${len}" == 0 ]] && break
    printf '%s\n' "${data}"
    [[ "${page}" == "${_iterations_vals}" ]] && break
    page="$((page + 1))"
done

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
    - ColorAuto

global_settings:
    - ColoredHelp

args:
    - username:
        help: your GitHub username
        required: true
    - password:
        help: your GitHub password
        required: true
    - git_options:
        help: "additional Git options (for example: --git-options '--depth 1')"
        long: git-options
        takes_value: true
        short: o
        allow_hyphen_values: true
EOF
)"; [[ -z "${_success}" ]] && exit 1

for repo in $(gh-repo-list "${_username_vals}" "${_password_vals}" \
    | jq -r "map(.ssh_url) | join(\"\n\")"); do
    if [[ -n "${_git_options_occurs}" ]]; then
        eval "git clone ${_git_options_vals} ${repo}"
    else
        git clone "${repo}"
    fi
done

学习材料

这个 YAML 配置 可能包含您可能需要的所有选项。
有关更多信息，请参阅 clap 的文档。

有关 powershell、fish、zsh 和其他示例，请查看 此处。

Elvish

截至 v0.14.1，elvish 还不支持 eval，因此您可以使用 slap 生成 elvish 代码，但您还不能在 elvish 脚本中使用生成的代码。
幸运的是，这个功能正在进行中。