Analizzi gli argomenti CLI mediante una specifica

Fornisca gli elementi e una specifica compatta che definisca ogni flag booleano e ogni opzione che richiede un valore. L’analizzatore associa gli alias ai nomi canonici, conserva gli argomenti posizionali, identifica i flag sconosciuti, accetta le opzioni lunghe con il segno di uguale e interrompe l’interpretazione dopo il separatore convenzionale con due trattini. Specifiche errate, argomenti ripetuti e opzioni prive del valore obbligatorio generano errori di input chiari.

Descriva l’interfaccia a riga di comando come dati

Parta dagli elementi esattamente come vengono forniti dall’ambiente di esecuzione, dopo aver escluso i nomi dell’eseguibile e dello script. Definisca quindi ogni argomento accettato nella specifica. Ciascuna voce contiene un nome canonico, uno o più alias e un tipo. Usi flag per un interruttore la cui presenza indica vero, per esempio <code>--verbose</code>. Usi option quando la forma deve essere seguita da un valore, come <code>--output result.json</code>. Gli alias consentono alle forme breve e lunga di valorizzare la stessa proprietà: <code>-o</code> e <code>--output</code> possono quindi produrre <code>output</code>. I nomi canonici contengono lettere minuscole, cifre e trattini bassi, così l’oggetto restituito è utilizzabile senza un’ulteriore rinomina. Gli alias devono iniziare con uno o due trattini. L’analizzatore rifiuta nomi canonici e alias duplicati, perché tali collisioni renderebbero il risultato dipendente dall’ordine delle dichiarazioni. Imposti <code>multiple</code> solo quando l’interfaccia prevede la ripetizione; i valori vengono allora restituiti nell’ordine di incontro.

Comprenda l’analisi degli elementi e l’output

L’output separa valori riconosciuti, elementi posizionali e flag sconosciuti. I flag riconosciuti diventano veri sotto il rispettivo nome canonico, mentre le opzioni memorizzano l’elemento successivo. Un’opzione lunga può anche includere il valore nello stesso elemento, come <code>--format=json</code>. La corrispondenza è esatta: i gruppi brevi come <code>-abc</code> non vengono espansi, a meno che l’intera forma sia dichiarata come alias. Ogni elemento sconosciuto che inizia con un trattino viene aggiunto a <code>unknown_flags</code>, permettendoLe di rifiutarlo, mostrare un avviso o inoltrarlo intenzionalmente. Gli altri elementi sconosciuti diventano valori posizionali. Un <code>--</code> isolato termina l’elaborazione delle opzioni e ogni elemento successivo diventa posizionale, anche se inizia con un trattino. Questa convenzione rende inequivocabili nomi come <code>-draft.txt</code>. L’analizzatore non crea valori predefiniti e non converte stringhe in numeri, poiché tali criteri spettano all’applicazione e potrebbero nascondere errori. Il risultato è deterministico e conserva l’ordine.

Gestisca con sicurezza valori mancanti e ripetizioni

Ogni voce di tipo option richiede un valore non vuoto ogni volta che compare uno dei suoi alias. Se l’alias è l’ultimo elemento, precede il marcatore di fine opzioni oppure è seguito da un altro elemento che assomiglia a un flag, l’analisi termina con un errore di input che nomina l’alias responsabile. La stessa regola vale per una forma allegata vuota come <code>--output=</code>. Questo comportamento rigoroso impedisce che un flag successivo venga consumato silenziosamente come dato e affronta direttamente uno degli errori più dannosi nell’analisi dei comandi. Un trattino isolato può comunque essere usato come valore, utile per i programmi che rappresentano l’input o l’output standard con <code>-</code>. Per impostazione predefinita, anche la ripetizione di un argomento riconosciuto causa un errore. Dichiari <code>multiple: true</code> quando la ripetizione è valida, per esempio per più percorsi di inclusione o etichette; il nome canonico conterrà sempre un elenco. I flag sconosciuti vengono segnalati senza causare un errore, lasciando a Lei la gestione della compatibilità e dell’inoltro.