Analise argumentos CLI com uma especificação

Forneça os elementos e uma especificação compacta que nomeie cada sinalizador booleano ou opção que recebe valor. O analisador converte aliases em nomes canônicos, preserva argumentos posicionais, identifica sinalizadores desconhecidos, aceita opções longas com sinal de igual e encerra a interpretação de opções depois do marcador convencional de dois hífens. Especificações malformadas, argumentos repetidos e opções sem o valor obrigatório geram erros de entrada claros.

Descreva a interface de comando como dados

Comece com os elementos de argumento exatamente como o ambiente de execução os fornece, depois de remover os nomes do executável e do script. Em seguida, defina na especificação cada argumento aceito. Toda entrada possui um nome canônico, um ou mais aliases e um tipo. Use flag para um sinalizador cuja presença signifique verdadeiro, como <code>--verbose</code>. Use option quando a forma precisar ser seguida de um valor, como <code>--output result.json</code>. Os aliases permitem que as formas curta e longa preencham a mesma propriedade canônica; assim, <code>-o</code> e <code>--output</code> podem gerar <code>output</code>. Os nomes canônicos usam letras minúsculas, números e sublinhados, deixando o objeto pronto para consumo sem outra etapa de renomeação. Os aliases devem começar com um ou dois hífens. O analisador rejeita nomes canônicos e aliases duplicados, pois essas colisões tornariam o resultado dependente da ordem da declaração. Defina <code>multiple</code> apenas quando a repetição fizer parte da interface; os valores serão retornados na ordem em que aparecerem.

Entenda a análise dos elementos e a saída

A saída separa três aspectos: valores reconhecidos, elementos posicionais e sinalizadores desconhecidos. Sinalizadores reconhecidos se tornam verdadeiros sob seus nomes canônicos, enquanto as opções armazenam o elemento seguinte. Uma opção longa também pode trazer o valor no mesmo elemento, como em <code>--format=json</code>. A correspondência precisa ser exata; grupos curtos como <code>-abc</code> não são expandidos, a menos que a forma inteira esteja declarada como alias. Todo elemento desconhecido iniciado por hífen é acrescentado a <code>unknown_flags</code>, permitindo que você o rejeite, mostre um aviso ou o encaminhe deliberadamente. Os demais elementos desconhecidos viram valores posicionais. Um <code>--</code> isolado encerra o processamento de opções, e tudo o que vier depois será posicional, mesmo que comece com hífen. Essa saída convencional elimina ambiguidades em nomes como <code>-draft.txt</code>. O analisador não cria padrões nem converte textos em números, pois essas políticas pertencem à aplicação e podem ocultar enganos. A saída é determinística e preserva a ordem dos itens.

Trate valores ausentes e repetições com segurança

Toda entrada do tipo option exige um valor não vazio sempre que um alias aparece. Se o alias for o último elemento, vier antes do marcador de fim das opções ou for seguido por outro elemento com formato de sinalizador, a análise falhará com um erro de entrada que cita o alias responsável. A mesma regra vale para uma forma anexada vazia, como <code>--output=</code>. Esse comportamento rigoroso impede que um sinalizador posterior seja consumido silenciosamente como dado e resolve diretamente uma das falhas mais perigosas da análise de comandos. Um hífen isolado ainda pode ser usado como valor, o que ajuda programas que representam a entrada ou saída padrão por <code>-</code>. Por padrão, repetir o mesmo argumento reconhecido também gera erro. Declare <code>multiple: true</code> quando a repetição for válida, por exemplo para vários caminhos de inclusão ou rótulos; o nome canônico sempre conterá uma lista. Sinalizadores desconhecidos são apenas informados, sem falha, para que você mantenha o controle sobre compatibilidade e encaminhamento.