args

Important

Ce dépôt a été déplacé vers https://github.com/dart-lang/core/tree/main/pkgs/args

Analyse les arguments bruts de la ligne de commande en un ensemble d'options et de valeurs.

Cette bibliothèque prend en charge les options de style GNU et POSIX et fonctionne à la fois dans les applications côté serveur et côté client.

Définir les options

Créez d’abord un ArgParser :

 var parser = ArgParser();

Définissez ensuite un ensemble d'options sur cet analyseur en utilisant addOption() et addFlag(). Voici la manière minimale de créer une option nommée « nom » :

 parser.addOption('name');

Lorsqu'une option ne peut être définie ou désactivée (au lieu de prendre une valeur de chaîne), utilisez un indicateur :

parser. addFlag ( 'name' );

Les options d'indicateur, par défaut, acceptent un préfixe « non » pour annuler l'option. Vous pouvez désactiver le préfixe « no- » en utilisant le paramètre negatable :

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

Remarque : À partir de maintenant, « option » fait référence à la fois aux options standard et aux indicateurs. Dans les cas où la distinction est importante, nous utiliserons « l’option sans drapeau ».

Les options peuvent avoir une abréviation facultative à un seul caractère, spécifiée avec le paramètre abbr :

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

Les options peuvent également avoir une valeur par défaut, spécifiée avec le paramètre defaultsTo . La valeur par défaut est utilisée lorsque les arguments ne spécifient pas l'option.

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

La valeur par défaut des options sans indicateur peut être n'importe quelle chaîne. Pour les drapeaux, ce doit être un bool .

Pour valider une option sans indicateur, vous pouvez utiliser le paramètre allowed pour fournir un ensemble de valeurs autorisé. Lorsque vous le faites, l'analyseur renvoie une ArgParserException si la valeur d'une option ne fait pas partie de l'ensemble autorisé. Voici un exemple de spécification des valeurs autorisées :

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

Vous pouvez utiliser le paramètre callback pour associer une fonction à une option. Plus tard, lors de l'analyse, la fonction de rappel est invoquée avec la valeur de l'option :

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

Les rappels pour toutes les options sont appelés chaque fois qu'un ensemble d'arguments est analysé. Si une option n'est pas fournie dans les arguments, son rappel reçoit la valeur par défaut, ou null si aucune valeur par défaut n'est définie.

Si une option est mandatory mais non fournie, l'objet de résultats renvoie un [ ArgumentError ][ArgumentError] lors de la récupération.

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

Analyser les arguments

Une fois que vous avez configuré un ArgParser avec quelques options et indicateurs, vous l'utilisez en appelant ArgParser.parse() avec un ensemble d'arguments :

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

Ces arguments proviennent généralement des arguments de main() . Par exemple:

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

Cependant, vous pouvez transmettre n’importe quelle liste de chaînes. La méthode parse() renvoie une instance de ArgResults, un objet de type carte qui contient les valeurs des options analysées.

 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

Par défaut, la méthode parse() permet de transmettre des indicateurs et des options supplémentaires après les paramètres de position, à moins que -- soit utilisé pour indiquer que tous les autres paramètres seront de position. Les arguments de position vont dans ArgResults.rest.

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

Pour arrêter l'analyse des options dès qu'un argument de position est trouvé, allowTrailingOptions: false lors de la création d'ArgParser.

Spécification des options

Pour transmettre réellement des options et des indicateurs sur la ligne de commande, utilisez le style GNU ou POSIX. Considérez cette option :

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

Vous pouvez spécifier sa valeur sur la ligne de commande en utilisant l'un des éléments suivants :

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

Considérez ce drapeau :

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

Vous pouvez le définir sur true en utilisant l'une des méthodes suivantes :

 --name
-n

Vous pouvez le définir sur false en utilisant ce qui suit :

 --no-name

Plusieurs abréviations de drapeaux peuvent être regroupées en un seul argument. Supposons que vous définissiez ces indicateurs :

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

Vous pouvez définir les trois indicateurs à la fois :

 -vfi

Par défaut, une option n’a qu’une seule valeur, les valeurs d’option ultérieures remplaçant les précédentes ; Par exemple:

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

Plusieurs valeurs peuvent être analysées avec addMultiOption() . Avec cette méthode, une option peut apparaître plusieurs fois et la méthode parse() renvoie une liste de valeurs :

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

Par défaut, les valeurs d'une option à valeurs multiples peuvent également être séparées par des virgules :

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

Cela peut être désactivé en passant splitCommas: false .

Définir des commandes

En plus des options , vous pouvez également définir des commandes . Une commande est un argument nommé qui possède son propre ensemble d’options. Par exemple, considérons cette commande shell :

 $ git commit -a

L'exécutable est git , la commande est commit et l'option -a est une option passée à la commande. Vous pouvez ajouter une commande à l'aide de la méthode addCommand :

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

Il renvoie un autre ArgParser, que vous pouvez ensuite utiliser pour définir des options spécifiques à cette commande. Si vous disposez déjà d'un ArgParser pour les options de la commande, vous pouvez le transmettre :

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

L'ArgParser d'une commande peut alors définir des options ou des indicateurs :

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

Vous pouvez ajouter plusieurs commandes au même analyseur afin qu'un utilisateur puisse en sélectionner une parmi une gamme de commandes possibles. Lors de l'analyse d'une liste d'arguments, vous pouvez alors déterminer quelle commande a été saisie et quelles options ont été fournies pour celle-ci.

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

Les options d'une commande doivent apparaître après la commande dans la liste des arguments. Par exemple, étant donné l'analyseur ci-dessus, "git -a commit" n'est pas valide. L'analyseur essaie de trouver la commande la plus à droite qui accepte une option. Par exemple:

 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

Ici, l'analyseur de niveau supérieur et la commande "commit" peuvent accepter un "-a" (qui est probablement une mauvaise interface de ligne de commande, certes). Dans ce cas, lorsque "-a" apparaît après "commit" , il est appliqué à cette commande. S'il apparaît à gauche de "commit" , il est transmis à l'analyseur de niveau supérieur.

Envoi des commandes

Si vous écrivez une application basée sur des commandes, vous pouvez utiliser les classes CommandRunner et Command pour vous aider à la structurer. CommandRunner prend en charge la répartition vers les commandes en fonction des arguments de ligne de commande, ainsi que la gestion des indicateurs --help et des arguments non valides.

Lors de l'utilisation du CommandRunner, il remplace ArgParser.

Dans l'exemple suivant, nous construisons une application Dart appelée dgit qui prend les commandes commit et stash .

Le CommandRunner prend un executableName qui est utilisé pour générer le message d'aide.

par exemple, dgit commit -a

Fichier dgit.dart

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

Lorsque la ligne run(args) ci-dessus s'exécute, elle analyse les arguments de la ligne de commande à la recherche de l'une des commandes ( commit ou stash ).

Si le CommandRunner trouve une commande correspondante, alors le CommandRunner appelle la méthode run() remplacée sur la commande correspondante (par exemple CommitCommand().run).

Les commandes sont définies en étendant la classe Command. Par exemple:

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

Arguments de CommandRunner

Le CommandRunner vous permet de spécifier à la fois des arguments globaux ainsi que des arguments spécifiques à la commande (et même des arguments spécifiques aux sous-commandes).

Arguments mondiaux

Ajoutez des arguments directement au CommandRunner pour spécifier des arguments globaux :

Ajout d'arguments globaux

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

Arguments spécifiques à la commande

Ajoutez des arguments à chaque commande pour spécifier des arguments spécifiques à la commande.

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

Sous-commandes

Les commandes peuvent également avoir des sous-commandes, qui sont ajoutées avec addSubcommand. Une commande avec des sous-commandes ne peut pas exécuter son propre code, donc run n'a pas besoin d'être implémenté. Par exemple:

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

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

Commande d'aide par défaut

CommandRunner ajoute automatiquement une commande help qui affiche les informations d'utilisation des commandes, ainsi que la prise en charge de l'indicateur --help pour toutes les commandes. S'il rencontre une erreur lors de l'analyse des arguments ou du traitement d'une commande, il lève une UsageException ; votre méthode main() doit les récupérer et les imprimer de manière appropriée. Par exemple:

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

Affichage de l'utilisation

Vous pouvez générer automatiquement un joli texte d'aide, pouvant être utilisé comme sortie de --help . Pour afficher de bonnes informations d'utilisation, vous devez fournir un texte d'aide lorsque vous créez vos options.

Pour définir le texte d'aide pour une option entière, utilisez le paramètre help: : :

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

Pour les options sans indicateur, vous pouvez également fournir une chaîne d'aide pour le paramètre :

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

Pour les options sans indicateur, vous pouvez également fournir une aide détaillée pour chaque valeur attendue en utilisant le paramètre allowedHelp: :

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

Pour afficher l'aide, utilisez le getter d'utilisation :

 print (parser.usage);

La chaîne résultante ressemble à ceci :

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