args

Penting

Repo ini telah dipindahkan ke https://github.com/dart-lang/core/tree/main/pkgs/args

Mengurai argumen baris perintah mentah menjadi serangkaian opsi dan nilai.

Pustaka ini mendukung opsi gaya GNU dan POSIX, dan berfungsi di aplikasi sisi server dan sisi klien.

Mendefinisikan pilihan

Pertama buat ArgParser:

 var parser = ArgParser();

Kemudian tentukan serangkaian opsi pada parser tersebut menggunakan addOption() dan addFlag(). Inilah cara minimal untuk membuat opsi bernama "nama":

 parser.addOption('name');

Ketika sebuah opsi hanya dapat disetel atau tidak disetel (sebagai lawan mengambil nilai string), gunakan tanda:

parser. addFlag ( 'name' );

Opsi tandai, secara default, menerima awalan 'tidak-' untuk meniadakan opsi tersebut. Anda dapat menonaktifkan awalan 'tidak-' menggunakan parameter negatable :

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

Catatan: Mulai sekarang, "opsi" mengacu pada opsi reguler dan bendera. Jika perbedaannya penting, kami akan menggunakan "opsi non-bendera".

Opsi dapat memiliki singkatan karakter tunggal opsional, yang ditentukan dengan parameter abbr :

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

Opsi juga dapat memiliki nilai default, yang ditentukan dengan parameter defaultsTo . Nilai default digunakan ketika argumen tidak menentukan opsi.

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

Nilai default untuk opsi non-bendera dapat berupa string apa pun. Untuk flag, harus berupa bool .

Untuk memvalidasi opsi non-bendera, Anda dapat menggunakan parameter allowed untuk memberikan serangkaian nilai yang diizinkan. Saat Anda melakukannya, parser akan memunculkan ArgParserException jika nilai opsi tidak termasuk dalam kumpulan yang diizinkan. Berikut ini contoh menentukan nilai yang diperbolehkan:

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

Anda dapat menggunakan parameter callback untuk mengaitkan fungsi dengan opsi. Nanti, saat penguraian terjadi, fungsi panggilan balik dipanggil dengan nilai opsi:

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

Callback untuk semua opsi dipanggil setiap kali serangkaian argumen diurai. Jika opsi tidak disediakan dalam argumen, panggilan baliknya akan diteruskan dengan nilai default, atau null jika tidak ada nilai default yang ditetapkan.

Jika suatu opsi mandatory tetapi tidak disediakan, objek hasil akan memunculkan [ ArgumentError ] [ArgumentError] saat pengambilan.

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

Mengurai argumen

Setelah Anda menyiapkan ArgParser dengan beberapa opsi dan tanda, Anda dapat menggunakannya dengan memanggil ArgParser.parse() dengan serangkaian argumen:

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

Argumen ini biasanya berasal dari argumen main() . Misalnya:

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

Namun, Anda dapat meneruskan daftar string apa pun. Metode parse() mengembalikan sebuah instance dari ArgResults, sebuah objek mirip peta yang berisi nilai opsi yang diurai.

 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

Secara default, metode parse() mengizinkan tanda dan opsi tambahan untuk diteruskan setelah parameter posisi kecuali -- digunakan untuk menunjukkan bahwa semua parameter selanjutnya akan bersifat posisional. Argumen posisi masuk ke ArgResults.rest.

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

Untuk menghentikan penguraian opsi segera setelah argumen posisi ditemukan, allowTrailingOptions: false saat membuat ArgParser.

Menentukan opsi

Untuk meneruskan opsi dan flag pada baris perintah, gunakan gaya GNU atau POSIX. Pertimbangkan opsi ini:

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

Anda dapat menentukan nilainya pada baris perintah menggunakan salah satu hal berikut:

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

Pertimbangkan bendera ini:

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

Anda dapat menyetelnya ke true menggunakan salah satu cara berikut:

 --name
-n

Anda dapat menyetelnya ke false menggunakan yang berikut ini:

 --no-name

Beberapa singkatan bendera dapat diciutkan menjadi satu argumen. Katakanlah Anda mendefinisikan tanda-tanda ini:

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

Anda dapat menyetel ketiga tanda sekaligus:

 -vfi

Secara default, sebuah opsi hanya memiliki satu nilai, dengan nilai opsi selanjutnya menggantikan nilai sebelumnya; Misalnya:

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

Beberapa nilai dapat diuraikan dengan addMultiOption() . Dengan metode ini, sebuah opsi dapat muncul beberapa kali, dan metode parse() mengembalikan daftar nilai:

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

Secara default, nilai untuk opsi multi-nilai juga dapat dipisahkan dengan koma:

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

Ini dapat dinonaktifkan dengan meneruskan splitCommas: false .

Mendefinisikan perintah

Selain opsi , Anda juga dapat menentukan perintah . Perintah adalah argumen bernama yang memiliki serangkaian opsinya sendiri. Misalnya, pertimbangkan perintah shell ini:

 $ git commit -a

Yang dapat dieksekusi adalah git , perintahnya adalah commit , dan opsi -a adalah opsi yang diteruskan ke perintah. Anda dapat menambahkan perintah menggunakan metode addCommand:

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

Ini mengembalikan ArgParser lain, yang kemudian dapat Anda gunakan untuk menentukan opsi khusus untuk perintah itu. Jika Anda sudah memiliki ArgParser untuk opsi perintah, Anda dapat meneruskannya ke:

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

ArgParser untuk suatu perintah kemudian dapat menentukan opsi atau tanda:

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

Anda dapat menambahkan beberapa perintah ke parser yang sama sehingga pengguna dapat memilih salah satu dari berbagai kemungkinan perintah. Saat mengurai daftar argumen, Anda kemudian dapat menentukan perintah mana yang dimasukkan dan opsi apa yang disediakan untuk perintah tersebut.

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

Opsi untuk suatu perintah harus muncul setelah perintah dalam daftar argumen. Misalnya, berdasarkan parser di atas, "git -a commit" tidak valid. Parser mencoba menemukan perintah paling kanan yang menerima opsi. Misalnya:

 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

Di sini, parser tingkat atas dan perintah "commit" dapat menerima "-a" (yang memang mungkin merupakan antarmuka baris perintah yang buruk). Dalam hal ini, ketika "-a" muncul setelah "commit" , itu diterapkan ke perintah itu. Jika muncul di sebelah kiri "commit" , maka diberikan ke parser tingkat atas.

Mengirimkan Perintah

Jika Anda sedang menulis aplikasi berbasis perintah, Anda dapat menggunakan kelas CommandRunner dan Command untuk membantu menyusunnya. CommandRunner memiliki dukungan bawaan untuk pengiriman ke Perintah berdasarkan argumen baris perintah, serta menangani tanda --help dan argumen yang tidak valid.

Saat menggunakan CommandRunner, ini menggantikan ArgParser.

Dalam contoh berikut kita membangun aplikasi dart bernama dgit yang menggunakan perintah commit dan stash .

CommandRunner mengambil executableName yang digunakan untuk menghasilkan pesan bantuan.

misalnya dgit commit -a

File dgit.dart

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

Ketika baris run(args) di atas dijalankan, ia mem-parsing baris perintah args mencari salah satu perintah ( commit atau stash ).

Jika CommandRunner menemukan perintah yang cocok, maka CommandRunner akan memanggil metode run() yang diganti pada perintah yang cocok (misalnya CommitCommand().run).

Perintah didefinisikan dengan memperluas kelas Command. Misalnya:

 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' ));
  }
}

Argumen CommandRunner

CommandRunner memungkinkan Anda menentukan argumen global serta argumen khusus perintah (dan bahkan argumen khusus sub-perintah).

Argumen Global

Tambahkan argumen langsung ke CommandRunner untuk menentukan argumen global:

Menambahkan argumen global

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

Argumen khusus perintah

Tambahkan argumen ke setiap Perintah untuk menentukan argumen khusus Perintah.

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

SubPerintah

Perintah juga dapat memiliki subperintah, yang ditambahkan dengan perintah addSub. Perintah dengan subperintah tidak dapat menjalankan kodenya sendiri, jadi eksekusi tidak perlu diterapkan. Misalnya:

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

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

Perintah Bantuan Default

CommandRunner secara otomatis menambahkan perintah help yang menampilkan informasi penggunaan perintah, serta dukungan untuk tanda --help untuk semua perintah. Jika ia menemui kesalahan saat mengurai argumen atau memproses perintah, ia akan memunculkan UsageException; metode main() Anda harus menangkapnya dan mencetaknya dengan tepat. Misalnya:

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

Menampilkan penggunaan

Anda dapat secara otomatis membuat teks bantuan yang bagus, cocok untuk digunakan sebagai keluaran --help . Untuk menampilkan informasi penggunaan yang baik, Anda harus memberikan beberapa teks bantuan saat Anda membuat pilihan.

Untuk menentukan teks bantuan untuk keseluruhan opsi, gunakan parameter help: ::

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

Untuk opsi non-bendera, Anda juga dapat memberikan string bantuan untuk parameter:

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

Untuk opsi non-bendera, Anda juga dapat memberikan bantuan mendetail untuk setiap nilai yang diharapkan dengan menggunakan allowedHelp:

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

Untuk menampilkan bantuan, gunakan pengambil penggunaan:

 print (parser.usage);

String yang dihasilkan terlihat seperti ini:

 --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