Analice argumentos CLI mediante una especificación

Proporcione los elementos y una especificación compacta que defina cada indicador booleano y cada opción con valor. El analizador resuelve alias en nombres canónicos, conserva argumentos posicionales, identifica indicadores desconocidos, admite opciones largas con signo igual y deja de interpretar opciones tras el separador convencional de doble guion. Las especificaciones incorrectas, los argumentos duplicados y las opciones que carecen de un valor obligatorio producen errores de entrada claros.

Describa la interfaz de comandos como datos

Comience con los elementos tal como los entrega el entorno de ejecución, tras retirar el nombre del ejecutable y el del script. Después, defina cada argumento aceptado en la especificación. Cada entrada contiene un nombre canónico, uno o varios alias y un tipo. Use flag para un indicador cuya presencia signifique verdadero, como <code>--verbose</code>. Use option cuando deba seguirle un valor, como <code>--output result.json</code>. Los alias permiten que las formas corta y larga alimenten la misma propiedad: <code>-o</code> y <code>--output</code> pueden generar <code>output</code>. Los nombres canónicos utilizan letras minúsculas, dígitos y guiones bajos, de modo que el objeto devuelto pueda consumirse sin otro proceso de renombrado. Los alias deben comenzar con uno o dos guiones. El analizador rechaza nombres canónicos y alias duplicados porque esas colisiones harían que el resultado dependiera del orden de declaración. Active <code>multiple</code> solo cuando la interfaz permita repetir el argumento; los valores se devolverán entonces según el orden de aparición.

Comprenda el análisis y el resultado

El resultado separa tres elementos: valores reconocidos, elementos posicionales e indicadores desconocidos. Los indicadores reconocidos se convierten en verdadero bajo su nombre canónico, mientras que las opciones guardan el elemento siguiente. Una opción larga también puede incorporar su valor, por ejemplo <code>--format=json</code>. La coincidencia es exacta; combinaciones cortas como <code>-abc</code> no se descomponen salvo que esa forma completa figure como alias. Todo elemento no reconocido que empiece por guion se añade a <code>unknown_flags</code>, para que usted pueda rechazarlo, mostrar una advertencia o reenviarlo deliberadamente. Los demás elementos no reconocidos se consideran posicionales. Un <code>--</code> independiente termina el análisis de opciones y convierte todos los elementos posteriores en posicionales, aunque comiencen por guion. Este escape convencional elimina la ambigüedad de archivos como <code>-draft.txt</code>. El analizador no inventa valores predeterminados ni convierte cadenas en números, pues esas políticas pertenecen a la aplicación y podrían ocultar errores. El resultado es determinista y conserva el orden.

Gestione valores ausentes y repeticiones con seguridad

Toda entrada de tipo option exige un valor no vacío cada vez que aparece uno de sus alias. Si el alias es el último elemento, precede al separador de fin de opciones o va seguido de otro elemento con forma de indicador, el análisis falla con un error de entrada que identifica el alias problemático. La misma regla se aplica a una forma adjunta vacía como <code>--output=</code>. Esta conducta estricta evita consumir por accidente el siguiente indicador como si fuera un dato y trata directamente uno de los fallos más perjudiciales del análisis de comandos. Un guion aislado sí puede utilizarse como valor, algo útil cuando un programa representa la entrada o salida estándar mediante <code>-</code>. De forma predeterminada, repetir un argumento reconocido también produce un error. Declare <code>multiple: true</code> cuando la repetición sea válida, como sucede con varias rutas de inclusión o etiquetas; el nombre canónico contendrá siempre una lista. Los indicadores desconocidos se notifican sin provocar el fallo, por lo que usted conserva el control de compatibilidad y reenvío.