def _PrintArgDefinition(self, arg, depth=0):
"""Prints a positional or flag arg definition list item at depth."""
self._out(u'\n{usage}{depth}\n'.format(
usage=usage_text.GetArgUsage(arg, definition=True, markdown=True),
depth=':' * (depth + 2)))
if arg.is_required and depth:
modal = (' This {arg_type} must be specified if any of the other '
'arguments in this group are specified.').format(
arg_type=self._ArgTypeName(arg))
else:
modal = ''
self._out(u'\n{details}{modal}\n'.format(details=self.GetArgDetails(arg),
modal=modal))
def _PrintArgDefinition(self, arg, depth=0, single=False):
"""Prints a positional or flag arg definition list item at depth."""
usage = usage_text.GetArgUsage(arg, definition=True, markdown=True)
if not usage:
return
self._out('\n{usage}{depth}\n'.format(usage=usage,
depth=':' *
(depth + _HANGING_OFFSET)))
if arg.is_required and depth and not single:
modal = ('\nThis {arg_type} must be specified if any of the other '
'arguments in this group are specified.').format(
arg_type=self._ArgTypeName(arg))
else:
modal = ''
self._out('\n{details}{modal}\n'.format(details=self.GetArgDetails(
arg, depth=depth),
modal=modal))
def PrintSynopsisSection(self, disable_header=False):
"""Prints the command line synopsis section.
Args:
disable_header: Disable printing the section header if True.
"""
if self._is_topic:
return
self._SetArgSections()
# MARKDOWN_CODE is the default SYNOPSIS font style.
code = base.MARKDOWN_CODE
em = base.MARKDOWN_ITALIC
if not disable_header:
self.PrintSectionHeader('SYNOPSIS')
self._out('{code}{command}{code}'.format(code=code,
command=self._command_name))
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 arg usage string with flags in section order.
remainder_usage = []
for section in self._arg_sections:
self._out(' ')
self._out(
usage_text.GetArgUsage(section.args,
markdown=True,
top=True,
remainder_usage=remainder_usage))
if self._global_flags:
self._out(' [' + em + self._top.upper() + '_WIDE_FLAG ...' + em +
']')
if remainder_usage:
self._out(' ')
self._out(' '.join(remainder_usage))
self._out('\n')
def validate_specified_args(self, ai, specified_args, top=True):
"""Validate specified args against the arg group constraints.
Each group may be mutually exclusive and/or required. Each argument may be
required.
Args:
ai: ArgumentInterceptor, The argument interceptor containing the
ai.arguments argument group.
specified_args: set, The dests of the specified args.
top: bool, True if ai.arguments is the top level group.
Raises:
ModalGroupError: If modal arg not specified.
OptionalMutexError: On optional mutex group conflict.
RequiredError: If required arg not specified.
RequiredMutexError: On required mutex group conflict.
Returns:
True if the subgroup was specified.
"""
also_optional = [] # The optional args in group that were not specified.
have_optional = [] # The specified optional (not required) args.
have_required = [] # The specified required args.
need_required = [] # The required args in group that must be specified.
for arg in sorted(ai.arguments, key=usage_text.GetArgSortKey):
if arg.is_group:
arg_was_specified = self.validate_specified_args(arg, specified_args,
top=False)
else:
arg_was_specified = arg.dest in specified_args
if arg_was_specified:
if arg.is_required:
have_required.append(arg)
else:
have_optional.append(arg)
elif arg.is_required:
if not isinstance(arg, DynamicPositionalAction):
need_required.append(arg)
else:
also_optional.append(arg)
if need_required:
if top or have_required and not (have_optional or also_optional):
ai = parser_arguments.ArgumentInterceptor(self, arguments=need_required)
self._Error(parser_errors.RequiredError(
parser=self,
argument=usage_text.GetArgUsage(
ai, value=False, hidden=True, top=top)))
if have_optional or have_required:
have_ai = parser_arguments.ArgumentInterceptor(
self, arguments=have_optional + have_required)
need_ai = parser_arguments.ArgumentInterceptor(
self, arguments=need_required)
self._Error(parser_errors.ModalGroupError(
parser=self,
argument=usage_text.GetArgUsage(
have_ai, value=False, hidden=True, top=top),
conflict=usage_text.GetArgUsage(
need_ai, value=False, hidden=True, top=top)))
# Multiple args with the same dest are counted as 1 arg.
count = (len(self.GetDestinations(have_required)) +
len(self.GetDestinations(have_optional)))
if ai.is_mutex:
conflict = usage_text.GetArgUsage(ai, value=False, hidden=True, top=top)
if ai.is_required:
if count != 1:
if count:
argument = usage_text.GetArgUsage(
sorted(have_required + have_optional,
key=usage_text.GetArgSortKey)[0],
value=False, hidden=True, top=top)
else:
argument = None
self._Error(parser_errors.RequiredMutexError(
parser=self, argument=argument, conflict=conflict))
elif count > 1:
argument = usage_text.GetArgUsage(
sorted(have_required + have_optional,
key=usage_text.GetArgSortKey)[0],
value=False, hidden=True, top=top)
self._Error(parser_errors.OptionalMutexError(
parser=self, argument=argument, conflict=conflict))
return bool(count)
