"Standardized" docstring/self-documentation 个脚本,共 bash 个脚本
"Standardized" docstring/self-documentation of bash scripts
背景
例如,Python 脚本可以通过 docstrings
具有多个“级别”的文档。它的巧妙之处在于,它们可以在每个函数级别、每个方法级别、每个 class 级别以及最重要的(在我的问题的上下文中)定义:每个文件级别。例如,文件的顶部可能如下所示:
#!/usr/bin/env python
"""
@brief A script that does cool stuff.
"""
What's especially useful about this feature is that it's easy to extract and print at run-time.
问题
做bash scripts support such a feature? i.e. is there a "standardized" approach to generating a file-level set of documentation (i.e. human-readable description of the purpose of the script, usage
syntax等;这样其他脚本就可以轻松地自动 parse/extract 此信息? 我的目标是创建几个自我记录的调试脚本,如果已经有 standard/de-facto-best 方法来做到这一点,我想避免重新发明轮子。
bash 的文档字符串没有标准。不过有手册页总是很好(例如 https://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/), or info pages (https://unix.stackexchange.com/questions/164443/how-to-create-info-documentation)。
Google 的 Shell Style Guide 的 "File Header" 部分是将 'docstring' 添加到 bash 脚本的一种方法。
基本上,答案是使用 #
,而不是像 Python.
这样的引号
你可以很容易地为 Bash 做到这一点,如果你需要确保与 POSIX 仅与 /bin/sh 之类的 shell 或主要是像 Alpine 这样的 busybox 系统的兼容性,那就有点棘手了。
Linux 文档项目有一些很好的例子。
http://tldp.org/LDP/abs/html/here-docs.html
Yet another twist of this nifty trick makes "self-documenting" scripts
possible.
Example 19-12. A self-documenting script
#!/bin/bash
# self-document.sh: self-documenting script
# Modification of "colm.sh".
DOC_REQUEST=70
if [ "" = "-h" -o "" = "--help" ] # Request help.
then
echo; echo "Usage: [=10=] [directory-name]"; echo
sed --silent -e '/DOCUMENTATIONXX$/,/^DOCUMENTATIONXX$/p' "[=10=]" |
sed -e '/DOCUMENTATIONXX$/d'; exit $DOC_REQUEST; fi
: <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.
DOCUMENTATIONXX
if [ -z "" -o ! -r "" ]
then
directory=.
else
directory=""
fi
echo "Listing of "$directory":"; echo
(printf "PERMISSIONS LINKS OWNER GROUP SIZE MONTH DAY HH:MM PROG-NAME\n" \
; ls -l "$directory" | sed 1d) | column -t
exit 0
Using a cat script is an alternate way of accomplishing this.
DOC_REQUEST=70
if [ "" = "-h" -o "" = "--help" ] # Request help.
then # Use a "cat script" . . .
cat <<DOCUMENTATIONXX
List the statistics of a specified directory in tabular format.
---------------------------------------------------------------
The command-line parameter gives the directory to be listed.
If no directory specified or directory specified cannot be read,
then list the current working directory.
DOCUMENTATIONXX
exit $DOC_REQUEST
fi
使用函数处理文档和错误消息的稍微更优雅的示例。
#!/bin/sh
usage() {
cat << EOF
Usage:
[=12=] [-u [username]] [-p]
Options:
-u <username> : Optionally specify the new username to set password for.
-p : Prompt for a new password.
EOF
}
die() {
echo
echo ", so giving up. Sorry."
echo
exit 2
}
if [ -z "$USER" ] ; then
die "Could not identify the existing user"
fi
if $PSET ; then
passwd $USER || die "Busybox didn't like your password"
fi
https://github.com/jyellick/mficli/blob/master/util/changecreds.sh
背景
例如,Python 脚本可以通过 docstrings
具有多个“级别”的文档。它的巧妙之处在于,它们可以在每个函数级别、每个方法级别、每个 class 级别以及最重要的(在我的问题的上下文中)定义:每个文件级别。例如,文件的顶部可能如下所示:
#!/usr/bin/env python
"""
@brief A script that does cool stuff.
"""
What's especially useful about this feature is that it's easy to extract and print at run-time.
问题
做bash scripts support such a feature? i.e. is there a "standardized" approach to generating a file-level set of documentation (i.e. human-readable description of the purpose of the script, usage
syntax等;这样其他脚本就可以轻松地自动 parse/extract 此信息? 我的目标是创建几个自我记录的调试脚本,如果已经有 standard/de-facto-best 方法来做到这一点,我想避免重新发明轮子。
bash 的文档字符串没有标准。不过有手册页总是很好(例如 https://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/), or info pages (https://unix.stackexchange.com/questions/164443/how-to-create-info-documentation)。
Google 的 Shell Style Guide 的 "File Header" 部分是将 'docstring' 添加到 bash 脚本的一种方法。
基本上,答案是使用 #
,而不是像 Python.
你可以很容易地为 Bash 做到这一点,如果你需要确保与 POSIX 仅与 /bin/sh 之类的 shell 或主要是像 Alpine 这样的 busybox 系统的兼容性,那就有点棘手了。
Linux 文档项目有一些很好的例子。
http://tldp.org/LDP/abs/html/here-docs.html
Yet another twist of this nifty trick makes "self-documenting" scripts possible.
Example 19-12. A self-documenting script
#!/bin/bash # self-document.sh: self-documenting script # Modification of "colm.sh". DOC_REQUEST=70 if [ "" = "-h" -o "" = "--help" ] # Request help. then echo; echo "Usage: [=10=] [directory-name]"; echo sed --silent -e '/DOCUMENTATIONXX$/,/^DOCUMENTATIONXX$/p' "[=10=]" | sed -e '/DOCUMENTATIONXX$/d'; exit $DOC_REQUEST; fi : <<DOCUMENTATIONXX List the statistics of a specified directory in tabular format. --------------------------------------------------------------- The command-line parameter gives the directory to be listed. If no directory specified or directory specified cannot be read, then list the current working directory. DOCUMENTATIONXX if [ -z "" -o ! -r "" ] then directory=. else directory="" fi echo "Listing of "$directory":"; echo (printf "PERMISSIONS LINKS OWNER GROUP SIZE MONTH DAY HH:MM PROG-NAME\n" \ ; ls -l "$directory" | sed 1d) | column -t exit 0
Using a cat script is an alternate way of accomplishing this.
DOC_REQUEST=70 if [ "" = "-h" -o "" = "--help" ] # Request help. then # Use a "cat script" . . . cat <<DOCUMENTATIONXX List the statistics of a specified directory in tabular format. --------------------------------------------------------------- The command-line parameter gives the directory to be listed. If no directory specified or directory specified cannot be read, then list the current working directory. DOCUMENTATIONXX exit $DOC_REQUEST fi
使用函数处理文档和错误消息的稍微更优雅的示例。
#!/bin/sh
usage() {
cat << EOF
Usage:
[=12=] [-u [username]] [-p]
Options:
-u <username> : Optionally specify the new username to set password for.
-p : Prompt for a new password.
EOF
}
die() {
echo
echo ", so giving up. Sorry."
echo
exit 2
}
if [ -z "$USER" ] ; then
die "Could not identify the existing user"
fi
if $PSET ; then
passwd $USER || die "Busybox didn't like your password"
fi
https://github.com/jyellick/mficli/blob/master/util/changecreds.sh