自己文書化関数
:
を使用して、ドキュメントを関数に埋め込むこともできます。
mylib.sh
さまざまな機能を提供するライブラリ script があるとします。ライブラリをソースして ( )、. mylib.sh
その直後に関数を呼び出す ( lib_function1 arg1 arg2
) か、名前空間が乱雑になるのを避けて、関数引数を使用してライブラリを呼び出す( ) ことができますmylib.sh lib_function1 arg1 arg2
。
mylib.sh --help
ヘルプ テキストで関数リストを手動で管理することなく、使用可能な関数とその使用法のリストを入力して取得できると便利だと思いませんか?
#!/ビン/バッシュ
# すべての「パブリック」関数は、このプレフィックスで開始する必要があります
LIB_PREFIX='lib_'
# 「パブリック」ライブラリ関数
lib_function1() {
: この関数は、2 つの引数で複雑なことを行います。
:
: パラメーター:
: ' arg1 - 最初の引数 ($1)'
: ' arg2 - 2 番目の引数'
:
: 結果:
: " それは複雑です"
# 実際の関数コードはここから
}
lib_function2() {
: 関数ドキュメント
# ここに関数コード
}
# ヘルプ機能
- ヘルプ() {
echo MyLib v0.0.1
エコー
echo 使用法: mylib.sh [関数名 [引数]]
エコー
echo 利用可能な機能:
宣言 -f | sed -n -e '/^'$LIB_PREFIX'/,/^}$/{/\(^'$LIB_PREFIX'\)\|\(^[ \t]*:\)/{
s/^\('$LIB_PREFIX'.*\) ()/\n=== \1 ===/;s/^[ \t]*: \?['\''"]\?/ / ;s/['\''"]\?;\?$//;p}}'
}
# メインコード
if [ "${BASH_SOURCE[0]}" = "${0}" ]; それから
# スクリプトはソースではなく実行されました
# 要求された機能を呼び出すか、ヘルプを表示する
if [ "$(type -t - "$1" 2>/dev/null)" = 関数]; それから
「$@」
そうしないと
- ヘルプ
フィ
フィ
コードに関するいくつかのコメント:
- すべての「パブリック」関数には同じプレフィックスがあります。これらのみが、ユーザーによって呼び出され、ヘルプ テキストにリストされることを意図しています。
- 自己文書化機能は前のポイントに依存し、使用
declare -f
可能なすべての関数を列挙し、sed を介してそれらをフィルター処理して、適切なプレフィックスを持つ関数のみを表示します。
- 不要な拡張や空白の削除を防ぐために、ドキュメントを一重引用符で囲むことをお勧めします。テキストでアポストロフィ/引用符を使用する場合も注意が必要です。
- ライブラリ プレフィックスを内部化するコードを書くことができます。つまり、ユーザーは入力するだけで、
mylib.sh function1
内部的に に変換されlib_function1
ます。これは読者に委ねられた演習です。
- ヘルプ機能の名前は「--help」です。これは、ライブラリ呼び出しメカニズムを使用してヘルプ自体を表示する便利な (つまり、遅延) アプローチであり、追加のチェックをコーディングする必要はありません
$1
。同時に、ライブラリをソースすると名前空間が乱雑になります。それが気に入らない場合は、名前を次のように変更するか、lib_help
実際に--help
メイン コードで引数を確認してヘルプ関数を手動で呼び出すことができます。