在旨在交互使用的功能中显示使用注释


11

我在中定义了许多功能.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选项,但是对于这些脚本,向所有内容添加帮助标志会有些麻烦。也许这只是我应该接受的费用,但是这种:破解似乎可以在不使源代码更难以阅读我们的编辑的情况下正常工作。

Answers:


8

我认为没有唯一的好方法可以做到这一点。

如果用户提供-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

是的,我应该提到这一点。这些是简单的函数,我正在努力避免使其过于复杂。对于值得解析标志的命令,我当然会添加一个--help选项。
dimo414 '16

在编程中,一致性是一种优点。另外,这取决于您所说的“复杂”。
John1024 '16

而且,您的方法既聪明又好(并且您的问题已经有了我的+1)。
John1024 '16

1
谢谢; 您的实施--help也是非侵入性的,在这种情况下,我认为这是我的主要标准。我可能最终会使用该:技巧,因为它更直接适合我的用例,但是我感谢您指出,它并不难支持--help,并且大多数用户会期望它。
dimo414 '16

1
+1。我本打算回答“使用getopts”,但是如果没有其他选择的话,这很好用。如果函数还有其他选项,请使用getopts
cas
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.