☰

在旨在交互使用的函数中显示使用注释

tag-icon • tag-icon bash function interactive
在旨在交互使用的函数中显示使用注释

我在 my 中定义了许多函数.bashrc，旨在在终端中交互使用。我通常在它们之前添加一条描述其预期用途的评论：

# Usage: foo [bar]
# Foo's a bar into a baz
foo() {
  ...
}

如果浏览源代码，这很好，但最好type在终端中运行以快速提醒该函数的作用。然而，这（可以理解）不包括评论：

$ type foo
foo is a function
foo ()
{
    ...
}

这让我想到“如果这些评论持续存在以便type可以显示出来，那不是很好吗？”本着 Python 的精神文档字符串我想出了这个：

foo() {
  : Usage: foo [bar]
  : "Foo's a bar into a baz"
  ...
}

$ type foo
foo is a function
foo ()
{
    : Usage: foo [bar];
    : "Foo's a bar into a baz";
    ...
}

现在用法已包含在type输出中！当然，正如您所看到的，引用成为一个容易出错的问题，但当它起作用时，它会带来更好的用户体验。

所以我的问题是，这是一个糟糕的主意吗？是否有更好的替代方案（例如函数的man/ info）来为 Bash 函数的用户提供额外的上下文？

理想情况下，我仍然希望使用说明位于函数定义附近，以便查看源代码的人们也能受益，但如果有“正确”的方法来做到这一点，我愿意接受替代方案。

编辑这些都是相当简单的辅助函数，我只是想以交互方式获得一些额外的上下文。当然，对于解析标志的更复杂的脚本，我会添加一个--help选项，但对于这些脚本，向所有内容添加帮助标志会有些麻烦。也许这只是我应该接受的成本，但这种:黑客似乎工作得相当好，并且不会使源代码更难以阅读我们的编辑。

答案1

我不认为只有一种好方法可以做到这一点。

如果用户提供-h或--help作为选项，许多函数、脚本和其他可执行文件都会提供帮助消息：

$ foo() {
[[ "$1" =~ (-h|--help) ]] && { cat <<EOF
Usage: foo [bar]
Foo's a bar into a baz
EOF
return;
}
: ...other stuff...
}

例如：

$ foo -h
Usage: foo [bar]
Foo's a bar into a baz

$ foo --help
Usage: foo [bar]
Foo's a bar into a baz

答案2

我从来没有相当说服自己冒险尝试并使用:命令作为伪注释。特别是，我一直担心“注释”实际上是要评估的参数，并且可能会产生副作用（或者只是破坏事物，例如错误'）。我仍然喜欢这个想法的简单性，但还没有发现这种权衡是合理的。

我对通过标志或类似内容提供使用文本的犹豫--help一直是随之而来的问题。一旦你开始接受标志，你很快就会进入成熟的参数解析，这通常（在 Bash 中）需要相当多的样板文件。

为了部分弥补这一差距，我汇集了小实用程序getopts为了减少这个样板文件而进行包装。它仍然占用几行，所以我不会在其他很小的函数中使用它，但它比直接使用要简洁得多getopts。这是带有标志的示例用法-h（getopts仅支持单字母选项）：

foo() {
  local _usage='foo [-a] [-b] [-f val] [-v val] [args ...]'
  eval "$(parse_opts 'f:v:abh')"
  if (( h )); then
    echo "Usage: $_usage"
    return 0
  fi
  echo "f=$f v=$v a=$a b=$b -- $#: $*"
}

相关内容