Analisando argumentos de extensão

A estrutura de extensão EngExtCpp fornece métodos para ajudar na análise dos argumentos de linha de comando passados para uma extensão. Para aproveitar esses métodos, a extensão deve primeiro declarar o formato dos argumentos de linha de comando na macro EXT_COMMAND.

Para ignorar a análise de argumento de linha de comando feita pela estrutura e permitir que a própria extensão analise os argumentos, defina a descrição da linha de comando e "{{custom}}" use o método GetRawArgStr para obter os argumentos de linha de comando para análise.

As cadeias de caracteres de descrição da linha de comando serão automaticamente encapsuladas quando impressas, para se ajustarem à largura da coluna da exibição. No entanto, os caracteres de nova linha podem ser incorporados nas cadeias de caracteres de descrição - usando '\n' - para iniciar novas linhas.

A descrição da linha de comando pode ser NULL ou a cadeia de caracteres vazia. Se qualquer um deles ocorrer, isso indica que o comando de extensão não recebe nenhum argumento.

Descrição da linha de comando

A descrição dos argumentos da linha de comando é uma sequência que contém dois tipos de componentes: diretivas e argumentos. A descrição pode conter opcionalmente uma de cada diretiva e pode conter até 64 argumentos.

Directivas

As diretivas especificam como os argumentos são analisados. Eles são cercados por chaves duplas ('{{' e '}}'). Opcionalmente, cada diretiva pode aparecer zero ou uma vez na cadeia de caracteres que descreve os argumentos.

As seguintes diretivas estão disponíveis:

custom
Desativa a análise feita pela estrutura de extensão e permite que a extensão execute sua própria análise.

l:str
Substitui a descrição longa padrão dos argumentos da linha de comando. A estrutura de extensão usará str para a descrição completa de todos os argumentos.

opt:str
Substitui os caracteres de prefixo padrão para comandos nomeados. O valor padrão é "/-", permitindo que '/' ou '-' sejam usados como o prefixo que identifica argumentos nomeados.

s:str
Substitui a breve descrição padrão dos argumentos de linha de comando. A estrutura de extensão usará str para a breve descrição de todos os argumentos.

Aqui estão alguns exemplos de diretivas. A cadeia de caracteres a seguir é usada por um comando de extensão que analisa seus próprios argumentos. Ele também fornece descrições curtas e longas para uso com o comando automático de extensão !help :

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

A cadeia de caracteres a seguir altera os caracteres de prefixo da opção de argumento para '/' ou '-'. Com esta diretiva, os argumentos serão especificados usando '+arg' e ':arg' em vez de '/arg' e '-arg':

{{opt:+:}}

Argumentos

Os argumentos podem ser de dois tipos: nomeados e não nomeados. Argumentos sem nome são lidos posicionalmente. Ambos os tipos de argumento também têm um nome de exibição, usado pelo comando help.

As descrições dos argumentos são colocadas entre chaves simples ('{' e '}').

Cada descrição de argumento tem a seguinte sintaxe:

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

em que:

nome da opção
O nome do argumento. Esse é o nome usado em comandos e métodos que buscam argumentos por nome. Esse nome é opcional. Se estiver presente, o argumento se torna um "argumento nomeado"; Ele pode aparecer em qualquer lugar na linha de comando e é referenciado pelo nome. Se não estiver presente, o argumento se torna um "argumento sem nome"; sua posição na linha de comando é importante e é referenciada por sua posição em relação aos outros argumentos sem nome.

tipo
O tipo do argumento. Isso afeta como o argumento é analisado e como ele é recuperado. O parâmetro type pode ter um dos seguintes valores:

b
Tipo booliano. O argumento está presente ou não está presente. Os argumentos booleanos nomeados podem ser recuperados usando HasArg.

e[d][s][bits]
Tipo de expressão. O argumento tem um valor numérico. Os argumentos de expressão nomeada podem ser recuperados usando GetArgU64 e os argumentos de expressão sem nome podem ser recuperados usando GetUnnamedArgU64.

d
A expressão é limitada ao próximo caractere de espaço na cadeia de caracteres do argumento. Se isso não estiver presente, o avaliador de expressão consumirá caracteres da linha de comando até determinar que atingiu o final da expressão.

s
O valor da expressão é assinado. Caso contrário, o valor da expressão não será assinado.

Bits
O número de bits no valor do argumento. O valor máximo para bits é 64.

s
Tipo de cadeia de caracteres. A cadeia de caracteres é limitada ao próximo caractere de espaço. Os argumentos de cadeia de caracteres nomeados podem ser recuperados usando GetArgStr e os argumentos de cadeia de caracteres sem nome podem ser recuperados usando GetUnnamedArgStr.

x
Tipo de cadeia de caracteres. O argumento é o restante da linha de comando. O argumento é recuperado usando GetArgStr ou GetUnnamedArgStr, assim como acontece com o tipo de cadeia de caracteres s.

sinalizadores
O argumento sinaliza. Eles determinam como o argumento será tratado pelo analisador. O parâmetro flags pode ter um dos seguintes valores:

d=expr
O valor padrão do argumento. Se o argumento não estiver presente na linha de comando, o argumento será definido como expr. O valor padrão é uma cadeia de caracteres que é analisada de acordo com o tipo do argumento.

Ds
O valor padrão não será exibido na descrição do argumento fornecida pela ajuda.

o
O argumento é opcional. Esse é o padrão para argumentos nomeados.

r
O argumento é necessário. Esse é o padrão para argumentos sem nome.

argname
O nome de exibição do argumento. Esse é o nome usado pelo comando automático de extensão !help e pelos argumentos de linha de comando automáticos /? ou -? . Usado ao imprimir um resumo das opções de linha de comando.

argdesc
Uma descrição do argumento. Essa é a descrição impressa pela extensão automática !help e pelos argumentos de linha de comando automáticos "/?" ou "-?".

Aqui estão alguns exemplos de descrições de argumentos. A expressão a seguir define um comando que usa um único argumento de expressão opcional. O argumento deve caber em 32 bits. Se o argumento não estiver presente na linha de comando, o valor padrão de 0x100 será usado.

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

A expressão a seguir define um comando com um argumento booleano opcional "/v" e um argumento de cadeia de caracteres sem nome necessário.

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

A expressão a seguir define um comando que tem um argumento de expressão nomeada opcional /oname expr e um argumento de cadeia de caracteres nomeado opcional /eol str. Se /eol estiver presente, seu valor será definido como o restante da linha de comando e nenhum outro argumento será analisado.

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

Linha de comando

Veja a seguir uma lista de algumas maneiras pelas quais os argumentos são analisados na linha de comando:

• Os valores dos argumentos de expressão nomeada e cadeia de caracteres seguem o nome na linha de comando. Por exemplo, /name expr ou /name str.

• Para argumentos booleanos nomeados, o valor será true se o nome aparecer na linha de comando; false caso contrário.

• Várias opções booleanas nomeadas por caractere único podem ser agrupadas na linha de comando. Por exemplo, "/a /b /c" pode ser escrito usando a notação abreviada "/abc" (a menos que já exista um argumento chamado "abc").

• Se a linha de comando contiver o argumento nomeado "?" - por exemplo, "/?" e "-?" - a análise do argumento será encerrada e o texto de ajuda da extensão será exibido.

Analisando Internos

Vários métodos são usados pelo analisador de argumentos para definir argumentos.

O método SetUnnamedArg alterará o valor de um argumento sem nome. E, por conveniência, os métodos SetUnnamedArgStr e SetUnnamedArgU64 definirão argumentos de cadeia de caracteres e expressão sem nome, respectivamente.

Existem métodos semelhantes para argumentos nomeados. SetArg é usado para alterar o valor de qualquer argumento nomeado e SetArgStr e SetArgU64 são usados para argumentos de cadeia de caracteres e expressão nomeados, respectivamente.