NAME
gdcloud topic command-conventions: Ayuda complementaria para gdcloud command-conventions.
DESCRIPCIÓN
El diseño de los comandos de la CLI de gdcloud sigue un conjunto común de principios y convenciones. En este documento, se describen en detalle.
Las convenciones son objetivos en lugar de reglas. Para cualquier excepción, consulta la información que se proporciona para los comandos individuales con la marca --help.
JERARQUÍA DE COMANDOS
Los comandos de la CLI de gdcloud se organizan como un árbol con gdcloud en la raíz, grupos de comandos en los nodos internos y comandos en los nodos hoja. Los comandos de grupo son ejecutables, pero solo para mostrar el texto de ayuda.
Todos los grupos y comandos tienen una marca --help que muestra el texto de ayuda como salida estándar. El texto de ayuda se deriva del ejecutable en ejecución, por lo que siempre está actualizado, incluso cuando se cambia entre varias instalaciones de versiones.
LÍNEA DE COMANDOS
Cada comando de gdcloud sigue el mismo formulario
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Se pueden mezclar marcas y argumentos posicionales, pero, por coherencia, los posicionales suelen mostrarse primero en orden, seguidos de las marcas en cualquier orden.
NOTACIÓN DE USO DE COMANDOS
El uso de comandos es una notación abreviada que contiene el nombre completo del comando, los argumentos posicionales y los argumentos de marca en orden de clasificación de grupo. Los argumentos opcionales se incluyen entre [ ... ]. Por ejemplo:
gdcloud foo bar NAME [--format=FORMAT]
Este es el uso del comando gdcloud foo bar con un argumento posicional NAME obligatorio, un argumento posicional EXTRA opcional y un argumento de marca --format opcional.
Argumentos posicionales
Los argumentos posicionales están ordenados y deben especificarse en el orden que se indica en la lista de definición de argumentos del uso del comando y el documento de ayuda.
Argumentos de marca
Los nombres de las marcas están en minúscula con un prefijo --. Las marcas de varias palabras usan - (guion) como separador de palabras.
Siguiendo la convención de UNIX, si se repite una marca en la línea de comandos, solo tendrá efecto la aparición más a la derecha. No se emite ningún diagnóstico. Esto facilita la configuración de alias de comandos y secuencias de comandos wrapper que proporcionan valores de marca predeterminados, valores que se pueden anular fácilmente si se especifican en la línea de comandos del alias o de la secuencia de comandos wrapper.
Marcas booleanas
Si bien muchas marcas booleanas tienen un valor implícito de false, algunas son true de forma predeterminada. La presencia de --flag establece la marca en true o false, según el valor implícito del nombre de la marca.
Marcas con valores
Las marcas no booleanas tienen un valor explícito. El valor se puede especificar colocando el valor como el siguiente argumento después de la marca --flag value.
Si el valor es un número entero, debe ser 0 o superior. No se aceptan números enteros negativos.
Salida
La salida estándar es para la información explícita que solicita el comando.
Según el contexto, es posible que haya garantías sobre el formato de salida para admitir el análisis determinista. Ciertos comandos muestran recursos, y estos recursos se enumeran como salida estándar, por lo general, con un formato de tabla específico del comando o el formato YAML predeterminado. Además, la marca --format se puede usar para cambiar o configurar estos formatos de salida predeterminados. Los valores --format de salida yaml, json y csv garantizan que la finalización correcta del comando genere datos de salida estándar que se puedan analizar con el formato respectivo. Se puede encontrar una explicación detallada de las capacidades de la marca --format con el comando gdcloud topic formats. Para los comandos que no muestran recursos, la salida se define en la marca --help del comando.
El error estándar está reservado para los diagnósticos. En general, el formato de los datos de error estándar puede cambiar de una versión a otra. Los usuarios no deben crear secuencias de comandos en función de contenido específico ni de la existencia de salida al error estándar. El único indicador de error confiable es el estado de salida.
Ningún comando de la CLI de gdcloud debería fallar con una excepción no detectada. Sin embargo, si la CLI de gdcloud falla, se intercepta el seguimiento de pila y se escribe en el archivo de registro, y se escribe un diagnóstico de falla en el error estándar.
Estado de salida
El estado de salida 0 indica éxito. Cualquier otro estado de salida indica un error. Los diagnósticos específicos del comando explicarán la naturaleza del error y cómo corregirlo.