Análisis de argumentos de extensión

El marco de extensión EngExtCpp proporciona métodos para ayudar a analizar los argumentos de la línea de comandos pasados a una extensión. Para aprovechar estos métodos, la extensión debe declarar primero el formato de los argumentos de la línea de comandos en la macro EXT_COMMAND.

Para omitir el análisis de argumentos de la línea de comandos realizado por el marco y dejar que la propia extensión analice los argumentos, establezca la descripción "{{custom}}" de la línea de comandos en y use el método GetRawArgStr para obtener los argumentos de la línea de comandos para el análisis.

Las cadenas de descripción de la línea de comandos se ajustarán automáticamente cuando se impriman para ajustarse al ancho de columna de la pantalla. Sin embargo, los caracteres de nueva línea se pueden incrustar en las cadenas de descripción ( mediante "\n" ) para iniciar nuevas líneas.

La descripción de la línea de comandos puede ser NULL o la cadena vacía. Si se produce, indica que el comando de extensión no toma ningún argumento.

Descripción de la línea de comandos

La descripción de los argumentos de la línea de comandos es una secuencia que contiene dos tipos de componentes: directivas y argumentos. La descripción puede contener opcionalmente una de cada directiva y puede contener hasta 64 argumentos.

Directivas

Las directivas especifican cómo se analizan los argumentos. Están entre llaves dobles ('{{' y '}}'). Opcionalmente, cada directiva puede aparecer cero o una vez en la cadena que describe los argumentos.

Están disponibles las siguientes directivas:

custom
Desactiva el análisis realizado por el marco de extensión y permite que la extensión realice su propio análisis.

l:str
Invalida la descripción larga predeterminada de los argumentos de la línea de comandos. El marco de extensión usará str para obtener la descripción completa de todos los argumentos.

opt:str
Invalida los caracteres de prefijo predeterminados para los comandos con nombre. El valor predeterminado es "/-", lo que permite usar '/' o '-' como prefijo que identifica argumentos con nombre.

s:str
Invalida la descripción breve predeterminada de los argumentos de la línea de comandos. El marco de extensión usará str para la breve descripción de todos los argumentos.

Estos son algunos ejemplos de directivas. Un comando de extensión usa la siguiente cadena que analiza sus propios argumentos. También proporciona descripciones breves y largas para su uso con el comando automático de extensión !help :

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

La cadena siguiente cambia los caracteres de prefijo de opción de argumento a "/" o "-". Con esta directiva, los argumentos se especificarán mediante '+arg' y ':arg' en lugar de '/arg' y '-arg':

{{opt:+:}}

Argumentos

Los argumentos pueden ser de dos tipos: con nombre y sin nombre. Los argumentos sin nombre se leen de forma posicional. Ambos tipos de argumento también tienen un nombre para mostrar, usado por el comando de ayuda.

Las descripciones de argumentos se incluyen entre llaves simples ('{' y '}').

Cada descripción del argumento tiene la siguiente sintaxis:

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

donde:

optname
El nombre del argumento. Este es el nombre que se usa en los comandos y en los métodos que capturan argumentos por nombre. Este nombre es opcional. Si está presente, el argumento se convierte en un "argumento con nombre"; puede aparecer en cualquier parte de la línea de comandos y se hace referencia por nombre. Si no está presente, el argumento se convierte en un "argumento sin nombre"; su posición en la línea de comandos es importante y se hace referencia a ella por su posición en relación con los otros argumentos sin nombre.

type
Tipo del argumento. Esto afecta a cómo se analiza el argumento y cómo se recupera. El parámetro type puede tener uno de los siguientes valores:

b
Tipo booleano. El argumento está presente o no. Los argumentos booleanos con nombre se pueden recuperar mediante HasArg.

e[d][s][bits]
Tipo de expresión. El argumento tiene un valor numérico. Los argumentos de expresión con nombre se pueden recuperar mediante GetArgU64 y los argumentos de expresión sin nombre se pueden recuperar mediante GetUnnamedArgU64.

d
La expresión se limita al siguiente carácter de espacio de la cadena de argumentos. Si esto no está presente, el evaluador de expresiones consumirá caracteres de la línea de comandos hasta que determine que alcanzó el final de la expresión.

s
El valor de la expresión está firmado. De lo contrario, el valor de la expresión no está firmado.

bits
Número de bits en el valor del argumento. El valor máximo de bits es 64.

s
Tipo de cadena. La cadena está limitada al siguiente carácter de espacio. Los argumentos de cadena con nombre se pueden recuperar mediante GetArgStr y los argumentos de cadena sin nombre se pueden recuperar mediante GetUnnamedArgStr.

x
Tipo de cadena. El argumento es el resto de la línea de comandos. El argumento se recupera mediante GetArgStr o GetUnnamedArgStr, como con el tipo de cadena s.

flags
Marcas de argumento. Estos determinan cómo el analizador tratará el argumento. El parámetro flags puede tener uno de los siguientes valores:

d=expr
Valor predeterminado del argumento. Si el argumento no está presente en la línea de comandos, el argumento se establece en expr. El valor predeterminado es una cadena que se analiza según el tipo del argumento.

Ds
El valor predeterminado no se mostrará en la descripción del argumento proporcionada por la ayuda.

o
El argumento es opcional. Este es el valor predeterminado para los argumentos con nombre.

r
El argumento es obligatorio. Este es el valor predeterminado para los argumentos sin nombre.

argname
Nombre para mostrar del argumento. Este es el nombre usado por el comando automático de extensión !help y por los argumentos de línea de comandos /? o -? automáticos. Se usa al imprimir un resumen de las opciones de la línea de comandos.

argdesc
Descripción del argumento. Esta es la descripción impresa por la extensión de ayuda !help automática y por los argumentos de línea de comandos "/?" o "-?".

Estos son algunos ejemplos de descripciones de argumentos. La expresión siguiente define un comando que toma un único argumento de expresión opcional. El argumento debe caber en 32 bits. Si el argumento no está presente en la línea de comandos, se usará el valor predeterminado de 0x100.

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

La expresión siguiente define un comando con un argumento booleano opcional "/v" y un argumento de cadena sin nombre necesario.

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

La expresión siguiente define un comando que tiene un argumento de expresión con nombre opcional /oname expr y un argumento de cadena con nombre opcional /eol str. Si /eol está presente, su valor se establecerá en el resto de la línea de comandos y no se analizarán argumentos adicionales.

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

Línea de comandos

A continuación se muestra una lista de algunas maneras en que se analizan los argumentos en la línea de comandos:

• Los valores de los argumentos de expresión y cadena con nombre siguen el nombre en la línea de comandos. Por ejemplo, /name expr o /name str.

• Para argumentos booleanos con nombre, el valor es true si el nombre aparece en la línea de comandos; False en caso contrario.

• Se pueden agrupar varias opciones booleanas con un solo carácter en la línea de comandos. Por ejemplo, "/a /b /c" se puede escribir mediante la notación abreviada "/abc" (a menos que ya haya un argumento denominado "abc").

• Si la línea de comandos contiene el argumento con nombre "?" (por ejemplo, "/?" y "-?"), el análisis de argumentos finaliza y se muestra el texto de ayuda de la extensión.

Análisis de elementos internos

El analizador de argumentos usa varios métodos para establecer argumentos.

El método SetUnnamedArg cambiará el valor de un argumento sin nombre. Además, para mayor comodidad, los métodos SetUnnamedArgStr y SetUnnamedArgU64 establecerán argumentos de expresión y cadena sin nombre, respectivamente.

Existen métodos similares para argumentos con nombre. SetArg se usa para cambiar el valor de cualquier argumento con nombre y SetArgStr y SetArgU64 se usan para argumentos de cadena y expresión con nombre, respectivamente.