Analisi degli argomenti dell'estensione

Il framework di estensione EngExtCpp fornisce metodi per facilitare l'analisi degli argomenti della riga di comando passati a un'estensione. Per sfruttare questi metodi, l'estensione deve innanzitutto dichiarare il formato degli argomenti della riga di comando nella macro EXT_COMMAND .

Per ignorare l'analisi dell'argomento della riga di comando eseguita dal framework e consentire all'estensione stessa di analizzare gli argomenti, impostare la descrizione della riga di comando su "{{custom}}" e usare il metodo GetRawArgStr per ottenere gli argomenti della riga di comando per l'analisi.

Le stringhe di descrizione della riga di comando verranno disposte automaticamente quando vengono stampate per adattarsi alla larghezza della colonna della visualizzazione. Tuttavia, i caratteri di nuova riga possono essere incorporati nelle stringhe di descrizione, usando '\n' , per avviare nuove righe.

La descrizione della riga di comando può essere NULL o la stringa vuota. In caso affermativo, indica che il comando di estensione non accetta argomenti.

Descrizione della riga di comando

La descrizione degli argomenti della riga di comando è una sequenza che contiene due tipi di componenti: direttive e argomenti. La descrizione può facoltativamente contenere una di ogni direttiva e può contenere fino a 64 argomenti.

Direttive

Le direttive specificano la modalità di analisi degli argomenti. Sono racchiusi tra parentesi graffe doppie ('{{' e '}}'). Ogni direttiva può essere visualizzata facoltativamente zero o una volta nella stringa che descrive gli argomenti.

Sono disponibili le direttive seguenti:

custom
Disattiva l'analisi eseguita dal framework di estensione e consente all'estensione di eseguire la propria analisi.

l:str
Esegue l'override della descrizione lunga predefinita degli argomenti della riga di comando. Il framework di estensione userà str per la descrizione completa di tutti gli argomenti.

opt:str
Esegue l'override dei caratteri di prefisso predefiniti per i comandi denominati. Il valore predefinito è "/-", consentendo l'uso di '/' o '-' come prefisso che identifica gli argomenti denominati.

s:str
Esegue l'override della descrizione breve predefinita degli argomenti della riga di comando. Il framework di estensione userà str per la breve descrizione di tutti gli argomenti.

Ecco alcuni esempi di direttive. La stringa seguente viene usata da un comando di estensione che analizza i propri argomenti. Fornisce anche descrizioni brevi e lunghe da usare con il comando di estensione !help automatico:

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

La stringa seguente modifica i caratteri di prefisso dell'opzione dell'argomento in '/' o '-'. Con questa direttiva, gli argomenti verranno specificati usando '+arg' e ':arg' anziché '/arg' e '-arg':

{{opt:+:}}

Argomenti

Gli argomenti possono essere di due tipi: denominati e senza nome. Gli argomenti senza nome vengono letti in modo posizionale. Entrambi i tipi di argomento hanno anche un nome visualizzato, usato dal comando della Guida.

Le descrizioni degli argomenti sono racchiuse tra parentesi graffe singole ('{' e '}').

Ogni descrizione dell'argomento ha la sintassi seguente:

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

dove:

optname
Il nome dell’argomento. Questo è il nome usato nei comandi e nei metodi che recuperano argomenti in base al nome. Questo nome è facoltativo. Se è presente, l'argomento diventa un "argomento denominato"; può essere visualizzato ovunque nella riga di comando e viene fatto riferimento in base al nome. Se non è presente, l'argomento diventa un "argomento senza nome"; la posizione nella riga di comando è importante e fa riferimento alla relativa posizione rispetto agli altri argomenti senza nome.

type
Il tipo di argomento. Ciò influisce sulla modalità di analisi dell'argomento e sulla modalità di recupero. Il parametro type può avere uno dei valori seguenti:

b
Tipo booleano. L'argomento è presente o non è presente. Gli argomenti booleani denominati possono essere recuperati usando HasArg.

e[d][s][bits]
Tipo di espressione. L'argomento ha un valore numerico. Gli argomenti di espressione denominata possono essere recuperati usando GetArgU64 e gli argomenti delle espressioni senza nome possono essere recuperati usando GetUnnamedArgU64.

d
L'espressione è limitata al carattere spazio successivo nella stringa dell'argomento. Se non è presente, l'analizzatore di espressioni utilizzerà i caratteri dalla riga di comando fino a quando non determina che ha raggiunto la fine dell'espressione.

s
Il valore dell'espressione è firmato. In caso contrario, il valore dell'espressione è senza segno.

Bit
Numero di bit nel valore dell'argomento. Il valore massimo per i bit è 64.

s
Tipo stringa. La stringa è limitata al carattere di spazio successivo. Gli argomenti stringa denominati possono essere recuperati usando GetArgStr e gli argomenti stringa senza nome possono essere recuperati usando GetUnnamedArgStr.

x
Tipo stringa. L'argomento è il resto della riga di comando. L'argomento viene recuperato usando GetArgStr o GetUnnamedArgStr, come con il tipo stringa s.

flags
Flag di argomento. Determinano il modo in cui l'argomento verrà trattato dal parser. Il parametro flags può avere uno dei valori seguenti:

d=expr
Valore predefinito dell'argomento. Se l'argomento non è presente nella riga di comando, l'argomento viene impostato su expr. Il valore predefinito è una stringa analizzata in base al tipo dell'argomento.

Ds
Il valore predefinito non verrà visualizzato nella descrizione dell'argomento fornita dalla Guida.

o
L'argomento è facoltativo. Si tratta dell'impostazione predefinita per gli argomenti denominati.

r
L'argomento è obbligatorio. Si tratta dell'impostazione predefinita per gli argomenti senza nome.

argname
Nome visualizzato dell'argomento. Si tratta del nome usato dal comando automatico !help extension e dagli argomenti della riga di comando automatici /? o -? . Utilizzato durante la stampa di un riepilogo delle opzioni della riga di comando.

argdesc
Descrizione dell'argomento. Questa è la descrizione stampata dall'estensione !help automatica e dagli argomenti della riga di comando "/?" o "-?".

Ecco alcuni esempi di descrizioni degli argomenti. L'espressione seguente definisce un comando che accetta un singolo argomento di espressione facoltativo. L'argomento deve rientrare in 32 bit. Se l'argomento non è presente nella riga di comando, verrà usato il valore predefinito di 0x100.

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

L'espressione seguente definisce un comando con un argomento booleano facoltativo "/v" e un argomento stringa senza nome obbligatorio.

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

L'espressione seguente definisce un comando con un argomento di espressione denominata facoltativo /oname expr e un argomento stringa denominato facoltativo /eol str. Se /eol è presente, il relativo valore verrà impostato sul resto della riga di comando e non verranno analizzati altri argomenti.

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

Riga di comando

Di seguito è riportato un elenco di alcuni modi in cui gli argomenti vengono analizzati nella riga di comando:

• I valori di espressioni denominate e argomenti stringa seguono il nome nella riga di comando. Ad esempio, /name expr o /name str.

• Per gli argomenti booleani denominati, il valore è true se il nome viene visualizzato nella riga di comando; false in caso contrario.

• È possibile raggruppare più opzioni booleane con un singolo carattere nella riga di comando. Ad esempio, "/a /b /c" può essere scritto usando la notazione abbreviata "/abc" (a meno che non esista già un argomento denominato "abc").

• Se la riga di comando contiene l'argomento denominato "?", ad esempio "/?" e "-?", termina l'analisi dell'argomento e viene visualizzato il testo della Guida per l'estensione.

Analisi dei dati interni

Diversi metodi vengono usati dal parser di argomenti per impostare gli argomenti.

Il metodo SetUnnamedArg modificherà il valore di un argomento senza nome. Inoltre, per praticità, i metodi SetUnnamedArgStr e SetUnnamedArgU64 impostano rispettivamente argomenti stringa ed espressione senza nome.

Esistono metodi simili per gli argomenti denominati. SetArg viene usato per modificare il valore di qualsiasi argomento denominato e SetArgStr e SetArgU64 vengono usati rispettivamente per gli argomenti stringa ed espressione denominati.