args

重要

このリポジトリは https://github.com/dart-lang/core/tree/main/pkgs/args に移動しました

生のコマンドライン引数をオプションと値のセットに解析します。

このライブラリは GNU および POSIX スタイルのオプションをサポートしており、サーバー側とクライアント側の両方のアプリで動作します。

オプションの定義

まず ArgParser を作成します。

 var parser = ArgParser();

次に、addOption() と addFlag() を使用して、そのパーサーでオプションのセットを定義します。 「name」という名前のオプションを作成する最小限の方法は次のとおりです。

 parser.addOption('name');

オプションが (文字列値を取得するのではなく) 設定または設定解除のみできる場合は、フラグを使用します。

parser. addFlag ( 'name' );

フラグ オプションは、デフォルトで、オプションを無効にする「no-」プレフィックスを受け入れます。 negatableパラメーターを使用して、「no-」プレフィックスを無効にできます。

parser. addFlag ( 'name' , negatable : false );

注:これ以降、「オプション」は通常のオプションとフラグの両方を指します。区別が重要な場合には、「非フラグ オプション」を使用します。

オプションには、 abbrパラメーターで指定されたオプションの 1 文字の省略形を含めることができます。

parser. addOption ( 'mode' , abbr : 'm' );
parser. addFlag ( 'verbose' , abbr : 'v' );

オプションには、 defaultsToパラメーターで指定されたデフォルト値を設定することもできます。引数でオプションが指定されていない場合は、デフォルト値が使用されます。

parser. addOption ( 'mode' , defaultsTo : 'debug' );
parser. addFlag ( 'verbose' , defaultsTo : false );

非フラグ オプションのデフォルト値は、任意の文字列にすることができます。フラグの場合はboolでなければなりません。

非フラグ オプションを検証するには、 allowedパラメータを使用して、許可される値のセットを指定できます。これを行うと、オプションの値が許可されたセットにない場合、パーサーはArgParserExceptionをスローします。許可される値を指定する例を次に示します。

parser. addOption ( 'mode' , allowed : [ 'debug' , 'release' ]);

callbackパラメーターを使用して、関数をオプションに関連付けることができます。その後、解析が行われるときに、オプションの値を使用してコールバック関数が呼び出されます。

parser. addOption ( 'mode' , callback : (mode) => print ( 'Got mode $ mode ' ));
parser. addFlag ( 'verbose' , callback : (verbose) {
  if (verbose) print ( 'Verbose' );
});

すべてのオプションのコールバックは、引数のセットが解析されるたびに呼び出されます。引数にオプションが指定されていない場合、そのコールバックにはデフォルト値が渡され、デフォルト値が設定されていない場合はnullれます。

オプションがmandatoryあるにもかかわらず指定されていない場合、結果オブジェクトは取得時に [ ArgumentError ][ArgumentError] をスローします。

parser. addOption ( 'mode' , mandatory : true );

引数の解析

いくつかのオプションとフラグを使用して ArgParser を設定したら、一連の引数を指定して ArgParser.parse() を呼び出してそれを使用します。

 var results = parser. parse ([ 'some' , 'command' , 'line' , 'args' ]);

これらの引数は通常、 main()の引数から取得されます。例えば：

 main(List<String> args) {
  // ...
  var results = parser.parse(args);
}

ただし、任意の文字列リストを渡すことができます。 parse()メソッドは、解析されたオプションの値を含むマップのようなオブジェクトである ArgResults のインスタンスを返します。

 var parser = ArgParser ();
parser. addOption ( 'mode' );
parser. addFlag ( 'verbose' , defaultsTo : true );
var results = parser. parse ([ '--mode' , 'debug' , 'something' , 'else' ]);

print (results. option ( 'mode' )); // debug
print (results. flag ( 'verbose' )); // true

デフォルトでは、 --を使用して以降のパラメータがすべて位置パラメータであることを示す場合を除き、 parse()メソッドでは位置パラメータの後に追加のフラグとオプションを渡すことができます。位置引数は ArgResults.rest に入ります。

 print (results.rest); // ['something', 'else']

位置引数が見つかったらすぐにオプションの解析を停止するには、ArgParser の作成時にallowTrailingOptions: false 。

オプションの指定

実際にコマンドラインでオプションとフラグを渡すには、GNU または POSIX スタイルを使用します。次のオプションを検討してください。

parser. addOption ( 'name' , abbr : 'n' );

次のいずれかを使用して、コマンドラインでその値を指定できます。

 --name=somevalue
--name somevalue
-nsomevalue
-n somevalue

次のフラグを考えてみましょう。

parser. addFlag ( 'name' , abbr : 'n' );

次のいずれかを使用して true に設定できます。

 --name
-n

以下を使用して false に設定できます。

 --no-name

複数のフラグの省略形を 1 つの引数にまとめることができます。これらのフラグを定義するとします。

parser
  .. addFlag ( 'verbose' , abbr : 'v' )
  .. addFlag ( 'french' , abbr : 'f' )
  .. addFlag ( 'iambic-pentameter' , abbr : 'i' );

3 つのフラグをすべて一度に設定できます。

 -vfi

デフォルトでは、オプションには 1 つの値のみがあり、後のオプションの値が前のオプションの値をオーバーライドします。例えば：

 var parser = ArgParser ();
parser. addOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on' , '--mode' , 'off' ]);
print (results. option ( 'mode' )); // prints 'off'

複数の値はaddMultiOption()で解析できます。このメソッドでは、オプションが複数回出現する可能性があり、 parse()メソッドは値のリストを返します。

 var parser = ArgParser ();
parser. addMultiOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on' , '--mode' , 'off' ]);
print (results. multiOption ( 'mode' )); // prints '[on, off]'

デフォルトでは、複数値のオプションの値をカンマで区切ることもできます。

 var parser = ArgParser ();
parser. addMultiOption ( 'mode' );
var results = parser. parse ([ '--mode' , 'on,off' ]);
print (results. multiOption ( 'mode' )); // prints '[on, off]'

これは、 splitCommas: false渡すことで無効にできます。

コマンドの定義

オプションに加えて、コマンドも定義できます。コマンドは、独自のオプション セットを持つ名前付き引数です。たとえば、次のシェル コマンドについて考えてみましょう。

 $ git commit -a

実行可能ファイルはgit 、コマンドはcommit 、および-aオプションはコマンドに渡されるオプションです。 addCommand メソッドを使用してコマンドを追加できます。

 var parser = ArgParser ();
var command = parser. addCommand ( 'commit' );

これは別の ArgParser を返します。これを使用して、そのコマンドに固有のオプションを定義できます。コマンドのオプション用の ArgParser がすでにある場合は、それを次のように渡すことができます。

 var parser = ArgParser ();
var command = ArgParser ();
parser. addCommand ( 'commit' , command);

コマンドの ArgParser はオプションまたはフラグを定義できます。

command. addFlag ( 'all' , abbr : 'a' );

同じパーサーに複数のコマンドを追加して、ユーザーが可能なコマンドの範囲から 1 つを選択できるようにすることができます。引数リストを解析すると、入力されたコマンドとそのコマンドにどのようなオプションが提供されたかを判断できます。

 var results = parser. parse ([ 'commit' , '-a' ]);
print (results.command.name);   // "commit"
print (results.command[ 'all' ]); // true

コマンドのオプションは、引数リスト内のコマンドの後に指定する必要があります。たとえば、上記のパーサーの場合、 "git -a commit"無効です。パーサーは、オプションを受け入れる右端のコマンドを見つけようとします。例えば：

 var parser = ArgParser ();
parser. addFlag ( 'all' , abbr : 'a' );
var command = parser. addCommand ( 'commit' );
command. addFlag ( 'all' , abbr : 'a' );

var results = parser. parse ([ 'commit' , '-a' ]);
print (results.command[ 'all' ]); // true

ここで、トップレベルのパーサーと"commit"コマンドは両方とも"-a"を受け入れることができます（これは、確かに、おそらく悪いコマンドラインインターフェイスです）。その場合、 "commit"の後に"-a"が現れると、そのコマンドに適用されます。 "commit"の左側に表示される場合は、最上位のパーサーに渡されます。

コマンドのディスパッチ

コマンドベースのアプリケーションを作成している場合は、CommandRunner クラスと Command クラスを使用してアプリケーションを構造化できます。 CommandRunner には、コマンドライン引数に基づいてコマンドをディスパッチする機能と、 --helpフラグと無効な引数を処理する機能が組み込まれています。

CommandRunner を使用する場合、ArgParser が置き換えられます。

次の例では、コマンドcommitおよびstash受け取るdgitという名前の dart アプリケーションを構築します。

CommandRunner は、ヘルプ メッセージの生成に使用されるexecutableNameを受け取ります。

例: dgit commit -a

ファイルdgit.dart

 void main ( List < String > args) {
  var runner = CommandRunner ( "dgit" , "A dart implementation of distributed version control." )
    .. addCommand ( CommitCommand ())
    .. addCommand ( StashCommand ())
    .. run (args);
}

上記のrun(args)行が実行されると、コマンド ライン引数が解析され、コマンド ( commitまたはstash ) の 1 つが検索されます。

CommandRunner が一致するコマンドを見つけた場合、CommandRunner は一致するコマンドでオーバーライドされたrun()メソッドを呼び出します (例: CommitCommand().run)。

コマンドは、Command クラスを拡張して定義されます。例えば：

 class CommitCommand extends Command {
  // The [name] and [description] properties must be defined by every
  // subclass.
  final name = "commit" ;
  final description = "Record changes to the repository." ;

  CommitCommand () {
    // we can add command specific arguments here.
    // [argParser] is automatically created by the parent class.
    argParser. addFlag ( 'all' , abbr : 'a' );
  }

  // [run] may also return a Future.
  void run () {
    // [argResults] is set before [run()] is called and contains the flags/options
    // passed to this command.
    print (argResults. flag ( 'all' ));
  }
}

CommandRunner の引数

CommandRunner を使用すると、グローバル引数とコマンド固有の引数 (さらにはサブコマンド固有の引数) の両方を指定できます。

グローバル引数

CommandRunner に引数を直接追加して、グローバル引数を指定します。

グローバル引数の追加

 var runner = CommandRunner ( 'dgit' ,  "A dart implementation of distributed version control." );
// add global flag
runner.argParser. addFlag ( 'verbose' , abbr : 'v' , help : 'increase logging' );

コマンド固有の引数

各コマンドに引数を追加して、コマンド固有の引数を指定します。

  CommitCommand () {
    // we can add command specific arguments here.
    // [argParser] is automatically created by the parent class.
    argParser. addFlag ( 'all' , abbr : 'a' );
  }

サブコマンド

コマンドにはサブコマンドを含めることもでき、サブコマンドは addSubcommand で追加されます。サブコマンドを含むコマンドは独自のコードを実行できないため、run を実装する必要はありません。例えば：

 class StashCommand extends Command {
  final String name = "stash" ;
  final String description = "Stash changes in the working directory." ;

  StashCommand () {
    addSubcommand ( StashSaveCommand ());
    addSubcommand ( StashListCommand ());
  }
}

デフォルトのヘルプコマンド

CommandRunner は、コマンドの使用法情報を表示するhelpコマンドを自動的に追加するだけでなく、すべてのコマンドの--helpフラグのサポートも追加します。引数の解析またはコマンドの処理中にエラーが発生した場合は、UsageException がスローされます。 main()メソッドはこれらをキャッチし、適切に出力する必要があります。例えば：

runner. run (arguments). catchError ((error) {
  if (error is ! UsageException ) throw error;
  print (error);
  exit ( 64 ); // Exit code 64 indicates a usage error.
});

使用状況の表示

--helpの出力として使用するのに適した、優れたヘルプ テキストを自動的に生成できます。適切な使用法情報を表示するには、オプションを作成するときにヘルプ テキストを提供する必要があります。

オプション全体のヘルプ テキストを定義するには、 help:パラメーターを使用します。

parser. addOption ( 'mode' , help : 'The compiler configuration' ,
    allowed : [ 'debug' , 'release' ]);
parser. addFlag ( 'verbose' , help : 'Show additional diagnostic info' );

フラグ以外のオプションの場合は、パラメーターのヘルプ文字列を指定することもできます。

parser. addOption ( 'out' , help : 'The output path' , valueHelp : 'path' ,
    allowed : [ 'debug' , 'release' ]);

非フラグ オプションの場合は、 allowedHelp:パラメーターを使用して、期待される値ごとに詳細なヘルプを提供することもできます。

parser. addOption ( 'arch' , help : 'The architecture to compile for' ,
    allowedHelp : {
      'ia32' : 'Intel x86' ,
      'arm' : 'ARM Holding 32-bit chip'
    });

ヘルプを表示するには、使用法ゲッターを使用します。

 print (parser.usage);

結果の文字列は次のようになります。

 --mode            The compiler configuration
                  [debug, release]

--out=<path>      The output path
--[no-]verbose    Show additional diagnostic info
--arch            The architecture to compile for
      [arm]       ARM Holding 32-bit chip
      [ia32]      Intel x86