def _PrintPositionalsAndFlagsSections(self, sections, has_global_flags):
"""Prints the positionals and flags sections."""
visible_positionals = usage_text.FilterOutSuppressed(
self._command.ai.positional_args)
if visible_positionals:
self._Section('POSITIONAL ARGUMENTS', sep=False)
for arg in visible_positionals:
self._out('\n{0}::\n'.format(
usage_text.PositionalDisplayString(
arg, markdown=True).lstrip()))
self._out('\n{arghelp}\n'.format(arghelp=self._Details(arg)))
# List the sections in order.
for heading, _, groups, attrs in sections:
self._PrintFlagSection(heading, groups, attrs)
if has_global_flags:
self._Section('GLOBAL FLAGS', sep=False)
self._out(
'\nRun *$ gcloud help* for a description of flags available to'
'\nall commands.\n')
def _PrintSynopsisSection(self):
"""Prints the command line synopsis section."""
# MARKDOWN_CODE is the default SYNOPSIS font style.
code = base.MARKDOWN_CODE
em = base.MARKDOWN_ITALIC
self._Section('SYNOPSIS')
self._out('{code}{command}{code}'.format(code=code,
command=self._command_name))
# Output the positional args up to the first REMAINDER or '-- *' args. The
# rest will be picked up after the flag args are output. argparse does not
# have an explicit '--' arg intercept, so we use the metavar value as a '--'
# sentinel. Any suppressed args are ingnored by a pre-pass.
positional_args = usage_text.FilterOutSuppressed(
self._command.ai.positional_args)
while positional_args:
arg = positional_args[0]
if arg.nargs == argparse.REMAINDER or arg.metavar.startswith(
'-- '):
break
positional_args.pop(0)
self._out(usage_text.PositionalDisplayString(arg, markdown=True))
if self._subcommands and self._subgroups:
self._out(' ' + em + 'GROUP' + em + ' | ' + em + 'COMMAND' + em)
elif self._subcommands:
self._out(' ' + em + 'COMMAND' + em)
elif self._subgroups:
self._out(' ' + em + 'GROUP' + em)
# Place all flags into a dict. Flags that are in a mutually
# exclusive group are mapped group_id -> [flags]. All other flags
# are mapped dest -> [flag].
global_flags = False
groups = collections.defaultdict(list)
for flag in (self._command.ai.flag_args +
self._command.ai.ancestor_flag_args):
if flag.is_global and not self._is_top_element:
global_flags = True
else:
group_id = self._command.ai.mutex_groups.get(
flag.dest, flag.dest)
groups[group_id].append(flag)
# Partition the non-GLOBAL flag groups dict into categorized sections. A
# group is REQUIRED if any flag in it is required, categorized if any flag
# in it is categorized, otherwise its OTHER. REQUIRED takes precedence
# over categorized.
categorized_groups = {}
for group_id, flags in groups.iteritems():
for f in flags:
if f.required:
category = 'REQUIRED'
elif f.category:
category = f.category
else:
continue
if category not in categorized_groups:
categorized_groups[category] = {}
categorized_groups[category][group_id] = flags
break
# Delete the categorized groups to get OTHER.
for v in categorized_groups.values():
for g in v:
del groups[g]
category = 'OTHER'
if category not in categorized_groups:
categorized_groups[category] = {}
for group_id, flags in groups.iteritems():
categorized_groups[category][group_id] = flags
# Collect the sections in order: REQUIRED, COMMON, OTHER, and categorized.
sections = []
for category in ('REQUIRED', base.COMMONLY_USED_FLAGS, 'OTHER'):
if category in categorized_groups:
sections.append(categorized_groups[category])
del categorized_groups[category]
for _, v in sorted(categorized_groups.iteritems()):
sections.append(v)
# Generate the flag usage string with flags in section order.
for section in sections:
for group in sorted(section.values(),
key=lambda g: g[0].option_strings):
if len(group) == 1:
arg = group[0]
if usage_text.IsSuppressed(arg):
continue
msg = usage_text.FlagDisplayString(arg, markdown=True)
if not msg:
continue
if arg.required:
self._out(' {msg}'.format(msg=msg))
else:
self._out(' [{msg}]'.format(msg=msg))
else:
# Check if the inverted boolean name should be displayed.
inverted = None
if len(group) == 2:
for arg in group:
if getattr(arg, 'show_inverted', False):
inverted = arg
break
if inverted:
# The inverted arg replaces the boolean group which only contains
# the arg and inverted arg.
msg = usage_text.FlagDisplayString(inverted,
markdown=True)
else:
group = usage_text.FilterOutSuppressed(group)
group.sort(key=lambda f: f.option_strings)
msg = ' | '.join(
usage_text.FlagDisplayString(arg, markdown=True)
for arg in group)
if not msg:
continue
self._out(' [{msg}]'.format(msg=msg))
if global_flags:
self._out(' [' + em + 'GLOBAL-FLAG ...' + em + ']')
# positional_args will only be non-empty if we had -- ... or REMAINDER left.
for arg in usage_text.FilterOutSuppressed(positional_args):
self._out(usage_text.PositionalDisplayString(arg, markdown=True))
self._out('\n')
def _PrintSynopsisSection(self, sections, has_global_flags):
"""Prints the command line synopsis section."""
# MARKDOWN_CODE is the default SYNOPSIS font style.
code = base.MARKDOWN_CODE
em = base.MARKDOWN_ITALIC
self._Section('SYNOPSIS')
self._out('{code}{command}{code}'.format(code=code,
command=self._command_name))
# Output the positional args up to the first REMAINDER or '-- *' args. The
# rest will be picked up after the flag args are output. argparse does not
# have an explicit '--' arg intercept, so we use the metavar value as a '--'
# sentinel. Any suppressed args are ingnored by a pre-pass.
positional_args = usage_text.FilterOutSuppressed(
self._command.ai.positional_args)
while positional_args:
arg = positional_args[0]
if arg.nargs == argparse.REMAINDER or arg.metavar.startswith(
'-- '):
break
positional_args.pop(0)
self._out(usage_text.PositionalDisplayString(arg, markdown=True))
if self._subcommands and self._subgroups:
self._out(' ' + em + 'GROUP' + em + ' | ' + em + 'COMMAND' + em)
elif self._subcommands:
self._out(' ' + em + 'COMMAND' + em)
elif self._subgroups:
self._out(' ' + em + 'GROUP' + em)
# Generate the flag usage string with flags in section order.
for _, _, groups, attrs in sections:
for group_id, group in sorted(
groups.iteritems(),
key=lambda x: usage_text.FlagGroupSortKey(x[1])):
flag = group[0]
if len(group) == 1:
show_inverted = getattr(flag, 'show_inverted', None)
if show_inverted:
flag = show_inverted
msg = usage_text.FlagDisplayString(flag, markdown=True)
if not msg:
continue
if flag.required:
self._out(' {msg}'.format(msg=msg))
else:
self._out(' [{msg}]'.format(msg=msg))
else:
group.sort(key=lambda f: f.option_strings)
attr = attrs.get(group_id)
if not attr or not attr.is_mutex:
for flag in group:
self._out(' [{0}]'.format(
usage_text.FlagDisplayString(flag,
markdown=True)))
else:
msg = ' | '.join(
usage_text.FlagDisplayString(flag, markdown=True)
for flag in group)
if not msg:
continue
if attr.is_required:
self._out(' ({msg})'.format(msg=msg))
else:
self._out(' [{msg}]'.format(msg=msg))
if has_global_flags:
self._out(' [' + em + 'GLOBAL-FLAG ...' + em + ']')
# positional_args will only be non-empty if we had -- ... or REMAINDER left.
for arg in usage_text.FilterOutSuppressed(positional_args):
self._out(usage_text.PositionalDisplayString(arg, markdown=True))
self._out('\n')