NOMBRE
gdcloud topic command-conventions - Ayuda complementaria para gdcloud topic 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, no reglas. Para cualquier excepción, consulta la información proporcionada 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.
COMMAND LINE
Todos los comandos de gcloud siguen el mismo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Los argumentos posicionales y de marcas se pueden mezclar, pero, para mantener la coherencia, los argumentos posicionales suelen mostrarse primero en orden, seguidos de las marcas en cualquier orden.
NOTACIÓN DE USO DE COMANDOS
El uso del comando es una notación abreviada que contiene el nombre completo del comando, los argumentos posicionales y los argumentos de marcas en orden de clasificación por 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 documento de ayuda y uso del comando.
Argumentos de marcas
Los nombres de las marcas están en minúsculas y tienen el prefijo --. Las marcas de varias palabras usan - (guion o guion corto) como separador de palabras.
Según la convención de UNIX, si una marca se repite en la línea de comandos, solo tiene 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 de wrapper que proporcionan valores de marcas predeterminados, valores que se pueden anular fácilmente especificándolos en la línea de comandos del alias o de la secuencia de comandos de 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 que implica el nombre de la marca.
Marcas valoradas
Las marcas no booleanas tienen un valor explícito. El valor se puede especificar colocándolo 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 solicitada por el comando.
Según el contexto, puede haber garantías sobre el formato de salida para admitir el análisis determinístico. Algunos comandos devuelven recursos, y estos se muestran 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 de salida --format de yaml, json y csv garantizan que la finalización correcta del comando genere datos de salida estándar que se pueden analizar con el formato respectivo. Puedes encontrar una explicación detallada de las capacidades de la marca --format con el comando gdcloud topic formats. En el caso de los comandos que no devuelven recursos, el resultado se define en la marca --help del comando.
El error estándar se reserva para el diagnóstico. 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 para contenido específico ni para la existencia de resultados en el error estándar. El único indicador de error confiable es el estado de salida.
Ningún comando de la CLI de gcloud debería fallar con una excepción no detectada. Sin embargo, si la CLI de gdcloud falla, se intercepta el registro 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 que la operación se realizó correctamente. 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.