NAME
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, consulte la información proporcionada para los comandos individuales mediante 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 se pueden ejecutar, 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
Todos los comandos de gdcloud siguen el mismo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Los argumentos de marca y posicionales se pueden mezclar, 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 por grupo. Los argumentos opcionales se indican 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 del documento de ayuda.
Argumentos de marca
Los nombres de las marcas están en minúsculas y tienen el prefijo --. Las marcas de varias palabras usan - (guion) como separador de palabras.
Siguiendo la convención de UNIX, si una marca se repite en la línea de comandos, solo se tiene en cuenta la aparición más a la derecha. No se emite ningún diagnóstico. De esta forma, es fácil configurar alias de comandos y secuencias de comandos de wrapper que proporcionen valores de marca predeterminados; valores que se pueden sustituir fácilmente especificándolos en la línea de comandos del alias o de la secuencia de comandos de wrapper.
Marcas booleanas
Aunque 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, en función del 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 solicitada por el comando.
En función del contexto, puede haber garantías sobre el formato de salida para admitir el análisis determinista. Algunos comandos devuelven recursos, que se muestran como salida estándar, normalmente con un formato de tabla específico del comando o con 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 yaml, json y csv garantizan que la finalización correcta del comando dé como resultado datos de salida estándar que se puedan analizar con el formato respectivo. Puede consultar una explicación detallada de las funciones de la marca --format con el comando gdcloud topic formats. En el caso de los comandos que no devuelven 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 escribir secuencias de comandos basadas en contenido específico ni en la existencia de salida en el error estándar. El único indicador de error fiable es el estado de salida.
Ningún comando de la CLI gdcloud debe fallar con una excepción no detectada. Sin embargo, si la CLI gdcloud falla, se intercepta el rastreo de la pila y se escribe en el archivo de registro, y se escribe un diagnóstico de fallo en el error estándar.
Estado de salida
El estado de salida 0 indica que la operación se ha realizado correctamente. Cualquier otro estado de salida indica que se ha producido un error. Los diagnósticos específicos de los comandos explicarán la naturaleza del error y cómo corregirlo.