Analyse des arguments d’extension

Article
07/08/2024

L’infrastructure d’extension EngExtCpp fournit des méthodes permettant d’analyser les arguments de ligne de commande passés à une extension. Pour tirer parti de ces méthodes, l’extension doit d’abord déclarer le format des arguments de ligne de commande dans la macro EXT_COMMAND.

Pour contourner l’analyse d’argument de ligne de commande effectuée par l’infrastructure et laisser l’extension elle-même analyser les arguments, définissez la description de la ligne de commande et "{{custom}}" utilisez la méthode GetRawArgStr pour obtenir les arguments de ligne de commande pour l’analyse.

Les chaînes de description de ligne de commande sont automatiquement encapsulées lors de l’impression, pour ajuster la largeur de colonne de l’affichage. Toutefois, les caractères de nouvelle ligne peuvent être incorporés dans les chaînes de description , à l’aide de «\n » pour démarrer de nouvelles lignes.

La description de la ligne de commande peut être NULL ou la chaîne vide. Si l’un ou l’autre se produit, il indique que la commande d’extension ne prend aucun argument.

Description de la ligne de commande

La description des arguments de ligne de commande est une séquence qui contient deux types de composants : les directives et les arguments. La description peut éventuellement contenir une de chaque directive et peut contenir jusqu’à 64 arguments.

Directives

Les directives spécifient la façon dont les arguments sont analysés. Ils sont placés entre accolades doubles ('{{' et '}}'). Chaque directive peut éventuellement apparaître zéro ou une fois dans la chaîne qui décrit les arguments.

Les directives suivantes sont disponibles :

custom
Désactive l’analyse effectuée par l’infrastructure d’extension et permet à l’extension d’effectuer son propre analyse.

l:str
Remplace la description longue par défaut des arguments de ligne de commande. L’infrastructure d’extension utilise str pour la description complète de tous les arguments.

opt:str
Remplace les caractères de préfixe par défaut pour les commandes nommées. La valeur par défaut est "/-", permettant à «/ » ou «- » d’être utilisé comme préfixe qui identifie les arguments nommés.

s:str
Remplace la brève description par défaut des arguments de ligne de commande. L’infrastructure d’extension utilise str pour la brève description de tous les arguments.

Voici quelques exemples de directives. La chaîne suivante est utilisée par une commande d’extension qui analyse ses propres arguments. Il fournit également des descriptions courtes et longues à utiliser avec la commande d’extension automatique !help :

{{custom}}{{s:<arg1> <arg2>}}{{l:arg1 - Argument 1\narg2 - Argument 2}}

La chaîne suivante modifie les caractères de préfixe d’option d’argument en «/ » ou «- ». Avec cette directive, les arguments sont spécifiés à l’aide de «+arg » et «:arg » au lieu de «/arg » et «-arg » :

{{opt:+:}}

Arguments

Les arguments peuvent être de deux types : nommés et non nommés. Les arguments non nommés sont lus en position position. Les deux types d’argument ont également un nom complet, utilisé par la commande d’aide.

Les descriptions des arguments sont entourées d’accolades simples ('{' et '}').

Chaque description d’argument a la syntaxe suivante :

{[optname];[type[,flags]];[argname];[argdesc]}

où :

optname
Nom de l’argument. Il s’agit du nom utilisé dans les commandes et dans les méthodes qui extraient les arguments par nom. Ce nom est facultatif. S’il est présent, l’argument devient un « argument nommé » ; elle peut apparaître n’importe où sur la ligne de commande et est référencée par nom. S’il n’est pas présent, l’argument devient un « argument sans nom » ; sa position sur la ligne de commande est importante et elle est référencée par sa position par rapport aux autres arguments non nommés.

type
Type de l’argument. Cela affecte la façon dont l’argument est analysé et comment il est récupéré. Le paramètre de type peut avoir l’une des valeurs suivantes :

b
Type booléen. L’argument est présent ou non présent. Les arguments booléens nommés peuvent être récupérés à l’aide de HasArg.

e[d][s][bits]
Type d’expression. L’argument a une valeur numérique. Les arguments d’expression nommée peuvent être récupérés à l’aide de GetArgU64 et d’arguments d’expression sans nom peuvent être récupérés à l’aide de GetUnnamedArgU64.

d
L’expression est limitée au caractère d’espace suivant dans la chaîne d’argument. S’il n’est pas présent, l’évaluateur d’expression consomme des caractères de la ligne de commande jusqu’à ce qu’il détermine qu’il a atteint la fin de l’expression.

s
La valeur de l’expression est signée. Sinon, la valeur de l’expression n’est pas signée.

bribes
Nombre de bits dans la valeur de l’argument. La valeur maximale des bits est 64.

s
Type de chaîne. La chaîne est limitée au caractère d’espace suivant. Les arguments de chaîne nommée peuvent être récupérés à l’aide de GetArgStr et d’arguments de chaîne non nommés peuvent être récupérés à l’aide de GetUnnamedArgStr.

x
Type de chaîne. L’argument est le reste de la ligne de commande. L’argument est récupéré à l’aide de GetArgStr ou GetUnnamedArgStr, comme avec le type de chaîne s.

flags
Indicateurs d’argument. Ceux-ci déterminent la façon dont l’argument sera traité par l’analyseur. Le paramètre d’indicateurs peut avoir l’une des valeurs suivantes :

d=expr
Valeur par défaut de l’argument. Si l’argument n’est pas présent sur la ligne de commande, l’argument est défini sur expr. La valeur par défaut est une chaîne analysée en fonction du type de l’argument.

Ds
La valeur par défaut ne s’affiche pas dans la description de l’argument fournie par l’aide.

o
Cet argument est facultatif. Il s’agit de la valeur par défaut pour les arguments nommés.

r
L’argument est requis. Il s’agit de la valeur par défaut pour les arguments non nommés.

argname
Nom complet de l’argument. Il s’agit du nom utilisé par la commande d’extension automatique !help et par les arguments de ligne de commande / ? ou - ? . Utilisé lors de l’impression d’un résumé des options de ligne de commande.

argdesc
Description de l’argument. Il s’agit de la description imprimée par l’extension automatique !help et par les arguments de ligne de commande « / ? » ou « - ? ».

Voici quelques exemples de descriptions d’arguments. L’expression suivante définit une commande qui prend un seul argument d’expression facultatif. L’argument doit correspondre à 32 bits. Si l’argument n’est pas présent sur la ligne de commande, la valeur par défaut de 0x100 sera utilisée.

{;e32,o,d=0x100;flags;Flags to control command}

L’expression suivante définit une commande avec un argument booléen facultatif « /v » et un argument de chaîne non nommé requis.

{v;b;;Verbose mode}{;s;name;Name of object}

L’expression suivante définit une commande qui a un argument d’expression nommée facultatif /oname expr et un argument de chaîne nommé facultatif /eol str. Si /eol est présent, sa valeur est définie sur le reste de la ligne de commande et aucun argument supplémentaire n’est analysé.

{oname;e;expr;Address of object}{eol;x;str;Commands to use}

Ligne de commande

Voici une liste de certaines façons dont les arguments sont analysés sur la ligne de commande :

Les valeurs des arguments d’expression nommée et de chaîne suivent le nom sur la ligne de commande. Par exemple, /name expr ou /name str.
Pour les arguments booléens nommés, la valeur est true si le nom apparaît sur la ligne de commande ; false sinon.
Plusieurs options booléennes nommées à caractère unique peuvent être regroupées sur la ligne de commande. Par exemple, « /a /b /c » peut être écrit à l’aide de la notation abrégée « /abc » (sauf s’il existe déjà un argument nommé « abc »).
Si la ligne de commande contient l’argument nommé « ? », par exemple, « / ? » et « - ? », l’analyse d’argument se termine et le texte d’aide de l’extension s’affiche.

Analyse des éléments internes

Plusieurs méthodes sont utilisées par l’analyseur d’arguments pour définir des arguments.

La méthode SetUnnamedArg modifie la valeur d’un argument sans nom. Pour plus de commodité, les méthodes SetUnnamedArgStr et SetUnnamedArgU64 définissent respectivement des arguments de chaîne et d’expression sans nom.

Des méthodes similaires existent pour les arguments nommés. SetArg est utilisé pour modifier la valeur de n’importe quel argument nommé et SetArgStr et SetArgU64 sont utilisés respectivement pour les arguments de chaîne et d’expression nommés.

Partager via