NOME
gdcloud topic command-conventions: ajuda complementar para gdcloud command-conventions.
DESCRIÇÃO
O design do comando da CLI gdcloud segue um conjunto comum de princípios e convenções. Este documento as descreve em detalhes.
As convenções são metas, não regras. Para exceções, consulte as informações fornecidas para comandos individuais usando a flag --help.
HIERARQUIA DE COMANDOS
Os comandos da CLI gdcloud são organizados como uma árvore com gdcloud na raiz, grupos de comandos nos nós internos e comandos nos nós de folha. Os comandos de grupo são executáveis, mas apenas para exibir o texto de ajuda.
Todos os grupos e comandos têm uma flag --help que exibe o texto de ajuda como saída padrão. O texto de ajuda é derivado do executável em execução, portanto, está sempre atualizado, mesmo ao alternar entre várias instalações de versões.
LINHA DE COMANDO
Todos os comandos gdcloud seguem o mesmo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Os argumentos de flag e posicionais podem ser misturados, mas, para manter a consistência, os posicionais geralmente são exibidos primeiro, seguidos pelas flags em qualquer ordem.
NOTATION DE USO DO COMANDO
O uso do comando é uma notação abreviada que contém o nome completo do comando, os argumentos posicionais e os argumentos de flag em ordem de classificação de grupo. Os argumentos opcionais estão entre [ ... ]. Por exemplo:
gdcloud foo bar NAME [--format=FORMAT]
Este é o uso do comando gdcloud foo bar com um argumento posicional NAME obrigatório, um argumento posicional EXTRA opcional e um argumento de flag --format opcional.
Argumentos posicionais
Os argumentos posicionais são ordenados e precisam ser especificados na ordem listada no uso do comando e na lista de definições de argumentos do documento de ajuda.
Argumentos de flag
Os nomes das flags são em minúsculas com um prefixo --. As sinalizações com várias palavras usam - (hífen/traço) como separador de palavras.
Seguindo a convenção do UNIX, se uma flag for repetida na linha de comando, apenas a ocorrência mais à direita terá efeito. Nenhum diagnóstico é emitido. Isso facilita a configuração de aliases de comando e scripts de wrapper que fornecem valores de flag padrão, que podem ser facilmente substituídos ao serem especificados na linha de comando do alias ou do script de wrapper.
Sinalizações booleanas
Embora muitas flags booleanas tenham um valor implícito de false, algumas são true por padrão. A presença de --flag define a flag como true ou false, dependendo do valor implícito pelo nome da flag.
Sinalizações de valor
As flags não booleanas têm um valor explícito. O valor pode ser especificado colocando-o como o próximo argumento após a flag --flag value.
Se o valor for um número inteiro, ele precisará ser 0 ou maior. Não são aceitos números inteiros negativos.
Saída
A saída padrão é para informações explícitas solicitadas pelo comando.
Dependendo do contexto, pode haver garantias no formato de saída para oferecer suporte à análise determinística. Alguns comandos retornam recursos, que são listados como saída padrão, geralmente usando um formato de tabela específico do comando ou o formato YAML padrão. Além disso, a flag --format pode ser usada para alterar ou configurar esses formatos de saída padrão. Os valores de --format de saída yaml, json e csv garantem que a conclusão do comando resulte em dados de saída padrão que podem ser analisados usando o respectivo formato. Uma explicação detalhada dos recursos da flag --format pode ser encontrada com o comando gdcloud topic formats. Para comandos que não retornam recursos, a saída é definida na flag --help do comando.
O erro padrão é reservado para diagnósticos. Em geral, o formato dos dados de erro padrão pode mudar de uma versão para outra. Os usuários não podem criar scripts para conteúdo específico ou mesmo para a existência de saída para o erro padrão. O único indicador de erro confiável é o status de saída.
Nenhum comando da CLI gdcloud deve falhar com uma exceção não capturada. No entanto, se a CLI gdcloud falhar, o stack trace será interceptado e gravado no arquivo de registro, e um diagnóstico de falha será gravado no erro padrão.
Status de saída
O status de saída 0 indica sucesso. Qualquer outro status de saída indica um erro. Os diagnósticos específicos do comando explicam a natureza do erro e como corrigi-lo.