☰

将函数注释放在函数头之前时不会打印出来

tag-icon • tag-icon shell-script shell function conventions
将函数注释放在函数头之前时不会打印出来

注释 shell 函数的一个良好且完善的指南是将其放在函数头之前。我试图尽可能地遵循这些准则，但这种约定使得阅读函数的注释变得困难。例如，我无权访问我的函数的注释

#######################################
# init the current directory with the required files to work with latex in Vscode's extension LaTeX workshop
# Arguments:
# $1 -> Main .tex file. Optional. Default to "main.tex"
#######################################
initlatex () {
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/0eeaa62d401659fe1c57602ec8f17608775d5338/_default_preamble.tex > default_preamble.tex
    grep -q "\\input{default_preamble.tex}" ${1:-main.tex} || sed -i '2i\\\input{default_preamble.tex}\n' ${1:-main.tex}
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/Makefile > Makefile
    [[ ! -d .vscode ]] && mkdir --parents --verbose .vscode
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/0eeaa62d401659fe1c57602ec8f17608775d5338/_vscode_makefile.json > .vscode/settings.json
}

直接在终端上使用以下which命令：

❯ which initlatex
initlatex () {
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/0eeaa62d401659fe1c57602ec8f17608775d5338/_default_preamble.tex > default_preamble.tex
    grep -q "\\input{default_preamble.tex}" ${1:-main.tex} || sed -i '2i\\\input{default_preamble.tex}\n' ${1:-main.tex}
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/Makefile > Makefile
    [[ ! -d .vscode ]] && mkdir --parents --verbose --parents --verbose .vscode
    curl https://gist.githubusercontent.com/tapyu/886dc95fc19c4250fb38581ccc58bed8/raw/0eeaa62d401659fe1c57602ec8f17608775d5338/_vscode_makefile.json > .vscode/settings.json
}

是否有另一个命令可以在不破坏此最佳实践的情况下打印出函数的注释？

答案1

一种方法是采用 LISP 程序员使用的方法，然后由 Python 等语言采用，并且不使用注释语法，而是使用文档字符串（文档字符串）。当您使用which/whence/type 时就会看到这一点。在 LISP 中，字符串计算自身，然后被忽略。对于 shell，您需要将其分配给，例如 _doc。

gmt(){
   _doc="Show date in gmt"
   date -u "$@"
}

第二种方法是注意函数接受参数。您可以建立一个约定，如果您使用第一个参数调用该函数，--help它将为您提供帮助。克什93有一个扩展的getopts解析器，可以使生成这些变得容易，例如这个env命令。

答案2

我会将文档放入一个通过严格的编码约定与函数名称相关的变量中。例如，哦，名称完全相同，因为变量和函数位于不同的命名空间中：

initlatex='
#######################################
# init the current directory with the required
# files to work with latex in Vscode'\''s extension LaTeX workshop
# Arguments:
# $1 -> Main .tex file. Optional. Default to "main.tex"
#######################################
'
initlatex () {
    curl ...
}

现在如果我们知道函数的名称，我们就可以获得它的文档：

$ echo "$initlatex"

#######################################
# init the current directory with the required
# files to work with latex in Vscode's extension LaTeX workshop
# Arguments:
# $1 -> Main .tex file. Optional. Default to "main.tex"
#######################################

答案3

我以相同的方式进行编码，并在函数上方添加了详细注释，但我在函数本身中添加了一行：

function dewpoint() { # Calculate dewpoint(C) based on Temperature(C) and Humidity(%)

然后我有一个小脚本llfunctions显示一行信息

dewpoint() Calculate dewpoint(C) based on Temperature(C) and Humidity(%)

llfunctions

#!/usr/bin/env bash
source ~/bin/functions-prt

list=(~/bin/functions-*)
[[ $1 ]] && list=("$@")

for fn in "${list[@]}"; do
    name=$(basename "$fn")
    prt-underline "$name"
    prt ""
    awk '/^function/ { printf "%25s", $2; $1=$2=$3=$4=""; $0=$0; print $0 }' "$fn"
    prt ""
done

答案4

which myfunction（在您似乎正在使用的 zsh 中）向您展示了函数代码的预编译形式的 shell 语法呈现。

您不会在那里找到任何注释，因为它们不是编译代码的一部分（在任何语言中，而不仅仅是 shell）。您看到的代码可能与定义函数的代码不同，您会注意到别名已扩展，缩进将不同，行继续被删除，短格式更改为长格式等。

在这里，您似乎想查看作者编写的实际来源。就像您希望查看文件file.java中 java 函数的源代码file.class而不是file.class.

在 中zsh，对于那些已经在文件中定义的函数，可以通过以下方式查看相应的文件：

view $functions_source[myfunction]

（或您最喜欢的查看器/编辑器）假设该文件仍然存在。您还将受益于语法突出显示和查看器/编辑器的其他好处。

type myfunction还告诉您函数定义是从哪里读取的：

$ type ls _ls
ls is a shell function from /home/chazelas/.zshrc
_ls is a shell function from /usr/share/zsh/functions/Completion/Unix/_ls

相关内容