NOME
gdcloud topic command-conventions - Supplementary help for gdcloud command-conventions.
DESCRIÇÃO
A conceção do comando da CLI gdcloud segue um conjunto comum de princípios e convenções. Este documento descreve-as detalhadamente.
As convenções são objetivos e não regras. Para quaisquer exceções, consulte as informações fornecidas para comandos individuais através da flag --help.
HIERARQUIA DE COMANDOS
Os comandos da CLI gdcloud estão organizados como uma árvore com gdcloud na raiz, grupos de comandos nos nós internos e comandos nos nós folha. Os comandos de grupo são executáveis, mas apenas para apresentar o texto de ajuda.
Todos os grupos e comandos têm uma flag --help que apresenta o texto de ajuda como saída padrão. O texto de ajuda é derivado do ficheiro executável em execução, pelo que está sempre atualizado, mesmo quando alterna entre várias instalações de lançamentos.
LINHA DE COMANDOS
Todos os comandos gdcloud seguem o mesmo formato
gdcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
Os argumentos de posição e de indicação podem ser misturados, mas, para consistência, os argumentos de posição são normalmente apresentados primeiro por ordem, seguidos dos argumentos de indicação em qualquer ordem.
NOTIFICAÇÃO DE UTILIZAÇÃO DE COMANDOS
A utilização de comandos é uma notação abreviada que contém o nome completo do comando, os argumentos posicionais e os argumentos de flags por ordem de grupo. Os argumentos opcionais estão entre [ ... ]. Por exemplo
gdcloud foo bar NAME [--format=FORMAT]
Esta é a utilização do comando gdcloud foo bar com um argumento posicional NAME obrigatório, um argumento posicional EXTRA opcional e um argumento de sinalização --format opcional.
Argumentos posicionais
Os argumentos posicionais estão ordenados e têm de ser especificados pela ordem indicada na utilização do comando e na lista de definição de argumentos do documento de ajuda.
Argumentos de sinalização
Os nomes das flags estão em minúsculas com um prefixo --. As flags com várias palavras usam - (hífen) como separador de palavras.
Seguindo a convenção UNIX, se uma flag for repetida na linha de comandos, apenas a ocorrência mais à direita entra em vigor. Não é emitido nenhum diagnóstico. Isto facilita a configuração de alias de comandos e scripts de wrapper que fornecem valores de flags predefinidos; valores que podem ser facilmente substituídos especificando-os na linha de comandos 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 predefinição. A presença de --flag define a flag como true ou false, consoante o valor implícito no nome da flag.
Sinalizações valiosas
As flags não booleanas têm um valor explícito. Pode especificar o valor colocando-o como o argumento seguinte após a flag --flag value.
Se o valor for um número inteiro, tem de ser 0 ou superior. Não são aceites números inteiros negativos.
Resultado
O resultado padrão destina-se a informações explícitas pedidas pelo comando.
Consoante o contexto, podem existir garantias no formato de saída para suportar a análise determinística. Determinados comandos devolvem recursos, e estes recursos são apresentados como saída padrão, normalmente, através de um formato de tabela específico do comando ou do formato YAML predefinido. Além disso, a flag --format pode ser usada para alterar ou configurar estes formatos de saída predefinidos. Os valores de saída --format de yaml, json e csv garantem que a conclusão bem-sucedida do comando resulta em dados de saída padrão que podem ser analisados usando o formato respetivo. Pode encontrar uma explicação detalhada das capacidades da flag --format com o comando gdcloud topic formats. Para comandos que não devolvem recursos, o resultado é definido no sinalizador --help do comando.
O erro padrão está reservado para diagnósticos. Em geral, o formato dos dados de erro padrão pode mudar de versão para versão. Os utilizadores não podem criar scripts contra conteúdo específico nem contra a existência de resultados no erro padrão. O único indicador de erro fiável é o estado 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 rastreio da pilha é intercetado e escrito no ficheiro de registo, e é escrito um diagnóstico de falha no erro padrão.
Estado de saída
O estado de saída 0 indica êxito. Qualquer outro estado de saída indica um erro. Os diagnósticos específicos de comandos explicam a natureza do erro e como corrigi-lo.