bash args

Bash 引数

これは、オプションや引数を受け入れる bash スクリプトを作成するためのフレームワークです。単純な宣言構文を使用してスクリプトで受け入れられるオプションと引数を定義し、 bash-args を実行します。

• コマンド引数を解析する
• ヘルプページを生成する
• オートコンプリートの処理

使いやすく、邪魔にならず、洗練されたユーザー エクスペリエンスを提供できるように設計されています。

移植性を目指しており、テスト スイートは bash 3.2 以上のすべてのメジャー バージョンに合格します。

目次

• クイックスタート
  • サブコマンド
• スクリプトのメタデータ
• オプションの定義
• オートコンプリート
  • 引数の型
  • カスタム引数の型

クイックスタート

スクリプトでbash-args を使用するには、 init.shファイルをソースするだけです。

eval-command.shスクリプトの例を次に示します。

 #! /usr/bin/env bash
# Summary : My first bash script using bash-args.
#
# Description : This takes a command as argument, and runs it.
#
# Argument : command
#
# Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

. path/to/bash-args/init.sh

# After sourcing the script, you can use the $directory and the $dry_run
# variables to get the values of the options typed (or not) in the command line.
# The other arguments are available as standard bash arguments $1, $2, etc.

command= " cd $directory && $1 "

if [[ $dry_run -eq 1 ]] ; then
    echo " $command "
else
    eval " $command "
fi

オプションを指定してこのコマンドを実行してみましょう。

 $ eval-command.sh --dry-run --directory /home 'echo hello'
cd /home && echo hello

短いオプションを使用でき、グループ化できます。

 $ eval-command.sh -nd /home 'echo hello'
cd /home && echo hello

簡単なコマンドでタブ補完をセットアップします。

 $ eval $(eval-command.sh _register_completion)

ヘルプページが提供されています:

 $ eval-command.sh --help
My first bash script using bash-args.

Usage : eval-command.sh [OPTIONS] [COMMAND]

This takes a command as argument, and runs it.

Options :

  --help | -h
          Show this help.

  --dry-run | -n
          Don't execute, just print.

  --directory | -d [DIRECTORY]
          The directory in which to run the command.

サブコマンド

Bash-args はサブコマンドも管理できます。

• main-script.sh help subcmd1またはmain-script.sh subcmd1 --helpを使用すると、各コマンドのヘルプ ページを利用できます。
• オートコンプリートは、サブコマンド、そのオプション、およびその引数を提案します。

これを実現するには、メイン スクリプトの最後でcmd_run関数を呼び出し、シェル スクリプトをcmd/ディレクトリに追加してサブコマンドを定義します。プロジェクトの構造は次のようになります。

 main-script.sh
cmd/
  - subcmd1.sh
  - subcmd2.sh

サブコマンドを文書化し、そのオプションと引数を定義するには、メイン スクリプトと同様に、各サブコマンドの最初のコメント ブロックにメタデータを書き込みます。

メイン スクリプトで定義されたオプションはすべてのサブコマンドで使用できますが、サブコマンドで定義されたオプションはこの特定のサブコマンドでのみ使用できます。

スクリプトのメタデータ

スクリプトのメタデータは非常に単純な構文に従います。最初のコメント ブロックでは、単語で始まりセミコロンが続く各行が新しいフィールドを定義し、セミコロンに続くすべての値がその値を定義します。次のフィールドの先頭までの次の行が値に追加されます。

bash-argsで使用されるフィールドは次のとおりです。

• 概要 :スクリプトの 1 行の説明。
• 説明 :スクリプトの長い説明。
• バージョン :バージョン文字列。メイン スクリプトにバージョン メタ フィールドがある場合は、その名前とバージョンを出力する--versionオプションを取得します。
• 使用法 :ヘルプ ページのデフォルトの使用法行が気に入らない場合は、ここで上書きできます。
• Argument :オートコンプリートに使用される引数のタイプを定義します。引数の型を参照
• オプション :スクリプトのオプションを定義します。 「オプションの定義」を参照してください。

オプションの定義

オプションは、サンプル スクリプトのように、オプションメタデータで定義されます。

 # Options :
#
# % dry-run
# desc="Don't execute, just print."
# short="n" type="flag" variable="dry_run" value=1 default=0
#
# % directory
# desc="The directory in which to run the command." argument=directory
# short="d" type="option" variable="directory" default="$(pwd)"
#

オプションは%で始まり、その後にその名前が続きます。オプション名には、英数字、 _または-のみを含める必要があります。

次の行は、オプションのパラメータを定義します。スクリプトが実行されると、これは実際には bash コードとして評価されます。定義された変数はオプションのパラメータです。これは、文字列の一般的な引用規則が適用され、 directoryオプションのdefaultパラメータが$(pwd)に設定されている上記の例のように、オプションを動的に定義できることを意味します。

オプションでは、少なくともtypeとvariableパラメータを定義する必要があります。

• type flagまたはoptionのいずれかです。フラグは引数を受け入れませんが、オプションは引数を受け入れます。
• variableスクリプト内でオプションの引数値を使用できる変数名です。

オプションで次の他のパラメータを定義できます。

• desc 、ヘルプ ページで使用されるオプションの説明です。
• short 1 文字で、短いオプションに使用されます。
• argument引数の型です。引数の型を参照
• defaultユーザーが入力したコマンドでオプションが指定されていない場合にオプションが取る値です。
• value 、オプションが指定されたときにオプションが取る値ですが、引数はありません。

オプションで定義された変数は、スクリプト内で定義されることが保証されています。bash -args がオプションの値を見つけられない場合、エラーで終了します。これは、オプションのdefaultを指定しない場合、このオプションを指定せずにメイン スクリプトを実行するとエラーが返されることを意味します。

つまり、オプションを必須にしたくない場合は、その定義でdefaultパラメーターを定義します。

valueパラメーターも同様に機能します。指定しない場合、オプションを使用するには引数が必要です。その場合、オプションは引数なしで使用できます。

フラグ オプションも同様に機能し、引数を取らないため、 defaultパラメータとvalueパラメータの両方を定義する必要があります。

オートコンプリート

Bash-args は、 Bash の補完 API を使用してスクリプトの自動補完を処理できます。コマンドのオートコンプリートを有効にするには、次のコマンドを実行します。

 eval $( my-command.sh _register_completion )

タブ補完は、その時点の単語が-で始まる場合は定義されたオプションを提案し、それ以外の場合はサブコマンドと引数を提案します。

引数の型

bash-args に引数として何を提案するかを指示するには、スクリプト (またはサブコマンド) のArgumentメタデータ、またはオプションのargumentパラメーターで引数の型を指定します。

組み込み引数の型は次のとおりです。

• file はファイルを提案します。
• directory はディレクトリを提案します。

カスタム引数の型

新しい引数の型を作成し、自動補完用に設定するには、 _complete_my_arg_typeという関数を定義します。この関数はinit.shスクリプトで使用できる必要があるため、 .shの前に定義する必要があります. init.sh行。

補完関数は、グローバルなCOMP_REPLIES配列に提案を追加することになっています。便宜上、ポイントで現在の単語をパラメータとして取得しますが、すべての bash 補完スクリプトと同様に、 COMP_LINEおよびCOMP_POINTグローバル変数を使用することもできます。

ファイル引数の型がどのように定義されるかは次のとおりです。

 _complete_file () {

    # $1 is the word being typed that we want to complete.
    for file in " ${1-} " * ; do
        # add each file to the completion candidates.
        COMP_REPLIES+=( " $file " )
    done
}