docopts 0.6.1-fix2

SYNOPSIS

docopts [options] -h msg : [argv…]

DESCRIPTION

docopts 解析命令行参数向量 argv，根据 docopt 字符串 msg，并将结果作为Bash源代码片段输出到标准输出。将此片段作为参数传递给 eval(1) 即可满足大多数脚本的CLI需求。

如果 argv 与在 msg 中定义的使用模式之一匹配，docopts 会生成代码以将解析后的参数存储为 Bash 变量。由于大多数命令行参数名称不是有效的 Bash 标识符，因此需要进行一些名称变形。

• <Angle_Brackets>: Angle_Brackets

• UPPER-CASE: UPPER_CASE

• --Long-Option: Long_Option

• -S: S

如果某个参数名称无法变形为有效的 Bash 标识符，或者两个参数名称映射到相同的变量名称，docopt 将以错误状态退出，并且您真的需要重新考虑您的 CLI。-- 和 - 命令将不会被存储。

或者，您可以使用带有 -A <name> 选项的 docopts，它将解析后的参数存储为名为 <name> 的 Bash 4 关联数组的字段。然而，由于 Bash 不原生支持嵌套数组，它们通过以下访问语法来模拟可重复参数

${args[ARG,#]} # the number of arguments to ARG
${args[ARG,0]} # the first argument to ARG
${args[ARG,1]} # the second argument to ARG, etc.

参数存储如下

• 非重复、无值的参数：如果找到则为 true，如果没有找到则为 false

• 可重复、无值的参数：在 argv 中的实例计数

• 非重复、有值的参数：如果找到则作为字符串的值，如果没有找到则为空字符串

• 可重复、有值的参数：解析值的 Bash 数组

除非提供 --no-help 选项，否则 docopts 会特别处理 --help 和 --version 选项及其可能的别名，生成代码以将相关消息打印到标准输出，并在解析 argv 时遇到任一选项时成功终止。然而请注意，这也需要在 msg 中列出相关选项，并且在 --version 的情况下，需要使用 --version 选项调用 docopts。

如果 argv 与 msg 中的任何使用模式都不匹配，docopts 将生成代码以退出程序并打印状态 64（在 sysexits(3) 中的 EX_USAGE）的诊断错误消息。

选项

-h <msg>, --help=<msg>

docopt 格式的帮助信息。如果指定了 -，则从标准输入读取帮助信息。如果没有指定参数，则打印 docopts 的帮助信息并退出。

-V <msg>, --version=<msg>

版本信息。如果指定了 -，则从标准输入读取版本信息。如果也读取了帮助信息，则首先读取它。如果没有指定参数，则打印 docopts 的版本信息并退出。

-O, --options-first

不允许选项和位置参数混用：从第一个不以破折号开始的参数开始，所有参数都将被视为位置参数。

-H, --no-help

不特别处理 –help 和 –version。

-A <name>

将参数作为名为 <name> 的 Bash 4.x 关联数组导出。

-s <str>, --separator=<str>

用于在标准输入同时提供帮助信息和版本信息时，将两者分开的字符串。[默认值: —-]

示例

从标准输入读取帮助和版本信息

eval "$(docopts -V - -h - : "$@" <<EOF
Usage: rock [options] <argv>...

      --verbose  Generate verbose messages.
      --help     Show help options.
      --version  Print program version.
----
rock 0.1.0
Copyright (C) 200X Thomas Light
License RIT (Robot Institute of Technology)
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
EOF
)"

if $verbose ; then
    echo "Hello, world!"
fi

从脚本注释中解析帮助和版本信息，并将其作为命令行参数传递

#? rock 0.1.0
#? Copyright (C) 200X Thomas Light
#? License RIT (Robot Institute of Technology)
#? This is free software: you are free to change and redistribute it.
#? There is NO WARRANTY, to the extent permitted by law.

##? Usage: rock [options] <argv>...
##?
##?       --help     Show help options.
##?       --version  Print program version.

help=$(grep "^##?" "$0" | cut -c 5-)
version=$(grep "^#?"  "$0" | cut -c 4-)
eval "$(docopts -h "$help" -V "$version" : "$@")"

for arg in "${argv[@]}"; do
    echo "$arg"
done

使用关联数组

eval "$(docopts -A args -h "$help" : "$@")"

if ${args[subcommand]} ; then
    echo "subcommand was given"
fi

if [ -n "${args[--long-option-with-argument]}" ] ; then
    echo "${args[--long-option-with-argument]}"
else
    echo "--long-option-with-argument was not given"
fi

i=0
while [[ $i -lt ${args[<argument-with-multiple-values>,#]} ]] ; do
    echo "${args[<argument-with-multiple-values>,$i]}"
    i=$[$i+1]
done

版本控制

docopts 的版本号始终与其构建时使用的 docopt Python 引用实现 版本相匹配。由于 docopt 遵循 语义版本控制，docopts 应该能够与任何与它共享主版本号的 docopt 发布版一起工作；然而，由于 docopts 和 docopt 目前都处于主版本号 0，因此 docopts 只能依赖于与它具有完全相同版本号的 docopt 安装。