194 lines
8.0 KiB
Python
194 lines
8.0 KiB
Python
# -*- coding: utf-8 -*- #
|
|
# Copyright 2018 Google LLC. All Rights Reserved.
|
|
#
|
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
# you may not use this file except in compliance with the License.
|
|
# You may obtain a copy of the License at
|
|
#
|
|
# http://www.apache.org/licenses/LICENSE-2.0
|
|
#
|
|
# Unless required by applicable law or agreed to in writing, software
|
|
# distributed under the License is distributed on an "AS IS" BASIS,
|
|
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
# See the License for the specific language governing permissions and
|
|
# limitations under the License.
|
|
|
|
"""gcloud command conventions supplementary help."""
|
|
|
|
from __future__ import absolute_import
|
|
from __future__ import division
|
|
from __future__ import unicode_literals
|
|
|
|
from googlecloudsdk.calliope import base
|
|
|
|
|
|
# NOTE: If the name of this topic is modified, please make sure to update all
|
|
# references to it in error messages and other help messages as there are no
|
|
# tests to catch such changes.
|
|
class CommandConventions(base.TopicCommand):
|
|
r"""gcloud command conventions supplementary help.
|
|
|
|
*gcloud* command design follows a common set of principles and conventions.
|
|
This document describes them in detail.
|
|
|
|
Conventions are goals more than rules. Refer to individual command *--help*
|
|
for any exceptions.
|
|
|
|
### Command Hierarchy
|
|
|
|
*gcloud* commands are organized as a tree with *gcloud* at the root, command
|
|
_groups_ in the inner nodes, and _commands_ at the leaf nodes. Each command
|
|
group typically contains a set of CRUD commands (*create*, *describe*, *list*,
|
|
*update*, *delete*) that operate on a resource for a single API. Group
|
|
commands are executable, but only for displaying help.
|
|
|
|
All groups and commands have a *--help* flag that displays a *man*(1) style
|
|
document on the standard output. The display is run through the default pager
|
|
if the calling environment specifies one. Help documents are derived from the
|
|
running executable, so they are always up to date, even when switching
|
|
between multiple release installations.
|
|
|
|
### Command Line
|
|
|
|
Every *gcloud* command line follows the same form:
|
|
|
|
gcloud GROUP GROUP ... COMMAND POSITIONAL ... FLAG ...
|
|
|
|
Flag and positional arguments can be intermixed but for consistency are
|
|
usually displayed positionals first in order, followed by flags in any order.
|
|
|
|
### Command Usage Notation
|
|
|
|
Command usage is a shorthand notation that contains the full command name,
|
|
the positional arguments, and the flag arguments in group sorted order.
|
|
Optional arguments are enclosed in *[ ... ]*. For example:
|
|
|
|
gcloud foo bar NAME [EXTRA] [--format=FORMAT]
|
|
|
|
is the usage for the `gcloud foo bar` command with a required
|
|
NAME positional argument, an optional EXTRA positional argument, and an
|
|
optional *--format* flag argument.
|
|
|
|
Mutually exclusive arguments are separated by *|*; at most one arg in the
|
|
list of mutually exclusive args may be specified:
|
|
|
|
[ --foo | --bar ]
|
|
|
|
This means that either *--foo* or *--bar* may be specified, but not both.
|
|
|
|
Mutually exclusive args may also be _required_, meaning exactly one arg in
|
|
the list must be specified. This is denoted by enclosing the args in
|
|
*( ... )*:
|
|
|
|
( --foo | --bar )
|
|
|
|
Modal argument groups are also supported. If any arg in the group is
|
|
specified, then the modal arguments must also be specified. This is denoted
|
|
by using *:* to separate the modal args on the left from the other args on
|
|
the right:
|
|
|
|
[ --must-a --must-b : --maybe-c --maybe-d ]
|
|
|
|
This means that if *--maybe-c* and/or *--maybe-d* are specified then both
|
|
*--must-a* and *--must-b* must be specified.
|
|
|
|
### Positional Arguments
|
|
|
|
Positional arguments are ordered and must be specified in the order listed
|
|
in the command usage and help document argument definition list.
|
|
|
|
File input arguments usually accept the special name *-* to mean
|
|
_read from the standard input_. This can be used only once per command line.
|
|
|
|
### Flag Arguments
|
|
|
|
Flag names are lower case with a *--* prefix. Multi-word flags use *-*
|
|
(dash) as a word separator. Single character flags are deprecated, rare and
|
|
may not be documented at all.
|
|
|
|
Following UNIX convention, if a flag is repeated on the command line, then
|
|
only the rightmost occurrence takes effect, no diagnostic is emitted. This
|
|
makes it easy to set up command aliases and wrapper scripts that provide
|
|
default flag values; values that can easily be overridden by specifying
|
|
them on the alias or wrapper script command line.
|
|
|
|
### Boolean Flags
|
|
|
|
Boolean flags have an implied value of *false* or *true*. The presence of
|
|
*--foo* sets the flag to *true*. All Boolean flags have a *--no-* prefix
|
|
variant. For example, *--no-foo* sets the Boolean *--foo* flag to *false*.
|
|
Boolean flags are documented using the positive form. This keeps the style
|
|
consistent across all commands, and also makes the meaning of the *--no-*
|
|
variant clear. In the case a Boolean flag has a default value of *true*,
|
|
the *--no-* variant will appear in the command usage and help text
|
|
and like all other *--no-* flags, will set the value of the flag to *false*.
|
|
|
|
### Valued Flags
|
|
|
|
Non-Boolean flags have an explicit value. The value can be specified using
|
|
*=*:
|
|
|
|
--flag=value
|
|
|
|
or by placing the value as the next arg after the flag:
|
|
|
|
--flag value
|
|
|
|
The *=* form must be used if _value_ starts with *-*.
|
|
|
|
The second form requires extra context to determine if *--flag* is
|
|
Boolean and *value* is a positional, or if *--flag* is valued and *value*
|
|
is its value. Because of the visual ambiguity, usage notation and most
|
|
command examples use the first form to make intentions clear. The *=*
|
|
form also has a diagnostic bonus: it is an error to specify a value
|
|
for a Boolean flag.
|
|
|
|
### Complex Flag Values
|
|
|
|
Complex flag values that contain command interpreter special characters may
|
|
be difficult to specify on the command line. The *--flags-file*=_YAML-FILE_
|
|
flag solves this problem by allowing command line flags to be specified in a
|
|
YAML/JSON file. String, numeric, list and dict flag values are specified
|
|
using YAML/JSON notation and quoting rules. See $ gcloud topic flags-file
|
|
for more information.
|
|
|
|
### Output
|
|
|
|
The standard output is for explicit information requested by the command.
|
|
|
|
Depending on the context, there may be guarantees on the output format
|
|
to support deterministic parsing. Certain commands do return resources and
|
|
these resources are listed on standard output usually using either a
|
|
command-specific table format or the default YAML format.
|
|
Moreover, the `--format` flag can be used to change or configure these
|
|
default output formats. *yaml*, *json*, and *csv* output *--format* values
|
|
guarantee that successful command completion results in standard output data
|
|
that can be parsed using the respective format. A detailed explanation of the
|
|
capabilities of the `--format` flag can be found with $ gcloud topic formats.
|
|
In the case of async commands, or commands run with `--async`, the resource
|
|
returned on standard output is an operations resource.
|
|
For commands that do not return resources, the output is defined in the
|
|
command's `--help`.
|
|
|
|
The standard error is reserved for diagnostics. In general, the format of
|
|
standard error data may change from release to release. Users should not
|
|
script against specific content, or even the existence of output to the
|
|
standard error at all. The only reliable error indicator is the _exit status_
|
|
described below.
|
|
|
|
Most standard error messaging is also logged to a file that can be accessed
|
|
by $ gcloud info `--show-log`.
|
|
|
|
No *gcloud* command should crash with an uncaught exception. However, if
|
|
*gcloud* does crash the stack trace is intercepted and written to the log
|
|
file, and a crash diagnostic is written to the standard error.
|
|
|
|
### Exit Status
|
|
|
|
Exit status *0* indicates success. For async commands it indicates that the
|
|
operation started successfully but may not have completed yet.
|
|
|
|
Any other exit status indicates an error. Command-specific diagnostics should
|
|
explain the nature of the error and how to correct it.
|
|
"""
|