记录 shell 脚本的参数答案

【问题标题】：documenting shell scripts' parameters记录 shell 脚本的参数
【发布时间】：2010-10-15 19:48:06
【问题描述】：

有记录 shell 脚本参数的约定吗？

例如：

#!/usr/bin/env bash

# <description>
#
# Usage:
#  $ ./myScript param1 [param2]
# * param1: <description>
# * param2: <description>

我不喜欢这个特定模板的一些地方：

脚本的文件名 (myScript) 出现在文件本身中
参数描述看起来很奇怪
$ 之前的前导空格在视觉上很有用，但可能会导致带有块 cmets 的语言混淆，导致一些验证工具抱怨缩进混合/不一致（例如，此块中的空格、代码制表符 - 前提是喜欢选项卡，当然）

有没有这方面的指导方针？

【问题讨论】：

man 用于格式化和参数文档示例的页面：unix.stackexchange.com/questions/6891/…

标签： linux unix shell

【解决方案1】：

传统上，您在 usage() 函数中记录您的论点：

#!/bin/bash

programname=$0

function usage {
    echo "usage: $programname [-abch] [-f infile] [-o outfile]"
    echo "  -a      turn on feature a"
    echo "  -b      turn on feature b"
    echo "  -c      turn on feature c"
    echo "  -h      display help"
    echo "  -f infile   specify input file infile"
    echo "  -o outfile  specify output file outfile"
    exit 1
}

usage

【讨论】：

感谢大家的回复。尽管它们都是相当特定于 Bash 的，但它们仍然很有用。我将不得不考虑如何最好地在 Python、Perl、Ruby 等中实现这一点（作为一种常见模式）。
考虑到这一点，代码内文档也是必需的，因为它的用途略有不同。因此，我将采用自动使用信息，但仍然希望对原始问题提供一些建议。
我有一个问题。为什么要在这里使用退出代码 1？
@LRDPRDX 因为如果你是打印使用，你很可能没有完成程序的功能，所以你返回失败。一个很好的例子是，如果不提供任何参数会导致脚本调用用法，而另一个名为该脚本的脚本打算提供参数，但由于错误而没有这样做，那么该脚本最好与调用脚本进行通信什么都没做。
@DuncanXSimpson 如果 arguments-supplier 程序打算在某个时候打印使用情况怎么办？最好只在处理过的意外情况而不是在完全预期的情况下寻求帮助时致电exit 1。我想说打印自我使用是程序功能的一部分。另外，我希望使用函数只打印使用情况，而不是终止程序，因此应该在 usage 之外调用 exit。

【解决方案2】：

我会推荐使用heredoc：

usage () {
    cat <<HELP_USAGE

    $0  [-a] -f <file>

   -a  All the instances.
   -f  File to write all the log lines
HELP_USAGE
}

代替：

echo "$0  [-a] -f <file>"
echo
echo "-a  All the instances."
echo "-f  File to write all the log lines."

我认为它比所有这些 echo 行更干净。

【讨论】：

我认为这个解决方案是所有答案中最漂亮的。谢谢
我避免使用heredoc只是因为它破坏了缩进。

【解决方案3】：

我通常将我的用法包装在函数中，这样我就可以从 -h 参数等中调用它。

#!/bin/bash
usage() {
    cat <<EOM
    Usage:
    $(basename $0) Explain options here

EOM
    exit 0
}

[ -z $1 ] && { usage; }

【讨论】：

我通过缩进脚本为您修复了此处的文档。我不明白 [ -x $1 ] （如果第一个参数不是可执行文件的路径，产生用法？）；调用周围的大括号和分号也是多余的。
Doh，没注意到 x；将其更改为想要的 z。
我猜大括号是习惯，所以我可以根据检查在检查中包含错误消息。感谢缩进代码技巧！
你需要引用$1，因为它可能包含空格，而[ 只是一个常规程序，它以-z 作为第一个参数，] 最后一个参数。如果$1 包含"x -o 1 -eq 1"，它将始终显示使用信息。

【解决方案4】：

执行此操作的Vim bash IDE：

#!/bin/bash
#===============================================================================
#
#          FILE:  test.sh
#
#         USAGE:  ./test.sh
#
#   DESCRIPTION:
#
#       OPTIONS:  ---
#  REQUIREMENTS:  ---
#          BUGS:  ---
#         NOTES:  ---
#        AUTHOR:  Joe Brockmeier, jzb@zonker.net
#       COMPANY:  Dissociated Press
#       VERSION:  1.0
#       CREATED:  05/25/2007 10:31:01 PM MDT
#      REVISION:  ---
#===============================================================================

【讨论】：

呃，好像是COBOL程序的识别部分。颤抖。
这看起来很有趣 - 会考虑的，谢谢！（尽管多行 cmets 的问题 - 就像在 heredoc 中一样 - 仍然存在。）
我总是对这个 meta-cmets 使用“#:”，这样我就可以将它们与实现 cmets 分开。

【解决方案5】：

我建议让您的脚本自动打印使用情况（如果它不应该在没有参数的情况下运行）：

#!/usr/bin/env bash

if [ $# == 0 ]; then
    echo "Usage: $0 param1 [param2]"
    echo "* param1: <description>"
    echo "* param2: <description>"
fi

【讨论】：

您可以使用$# 作为参数计数的快捷方式。

【解决方案6】：

我宁愿写：

Usage: `basename $0` [option1]|[option2] param1
  Options:
   - option1:  .....
   - option2:  .....
  Parameters:
   - param1:   .....

尝试查看标准 UNIX 实用程序的帮助格式（例如 ls --help）

【讨论】：