145 lines
4.7 KiB
Python
145 lines
4.7 KiB
Python
# -*- coding: utf-8 -*- #
|
|
# Copyright 2013 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.
|
|
|
|
"""A calliope command that prints help for another calliope command."""
|
|
|
|
from __future__ import absolute_import
|
|
from __future__ import division
|
|
from __future__ import unicode_literals
|
|
|
|
import argparse
|
|
|
|
from googlecloudsdk.calliope import base
|
|
from googlecloudsdk.command_lib.help_search import search
|
|
from googlecloudsdk.command_lib.help_search import search_util
|
|
from googlecloudsdk.core import log
|
|
|
|
|
|
_DEFAULT_LIMIT = 5
|
|
|
|
|
|
class Help(base.ListCommand):
|
|
"""Search gcloud help text.
|
|
|
|
If a full gcloud command is specified after the ``help'' operand, {command}
|
|
prints a detailed help message for that command.
|
|
|
|
Otherwise, {command} runs a search for all commands with help text matching
|
|
the given argument or arguments. It prints the command name and a summary of
|
|
the help text for any command that it finds as a result.
|
|
|
|
To run a search directly, you can use remainder arguments, following a `--`.
|
|
|
|
By default, command results are displayed in a table that shows the name
|
|
of the command and snippets of the help text that relate to your search terms.
|
|
|
|
By default, search results are sorted from most to least relevant by default,
|
|
using a localized rating based on several heuristics. These heuristics may
|
|
change in future runs of this command.
|
|
|
|
## EXAMPLES
|
|
|
|
To get the help for the command `gcloud projects describe`, run:
|
|
|
|
$ {command} projects describe
|
|
|
|
To search for all commands whose help text contains the word `project`, run:
|
|
|
|
$ {command} -- project
|
|
|
|
To search for commands whose help text contains the word `project` and the
|
|
string `--foo`, run:
|
|
|
|
$ {command} -- project --foo
|
|
|
|
To search and receive more than the default limit of 5 search results, run:
|
|
|
|
$ {command} --limit=20 -- project
|
|
|
|
To search for a term and sort the results by a different characteristic, such
|
|
as command name, run:
|
|
|
|
$ {command} --sort-by=name -- project
|
|
"""
|
|
|
|
category = base.SDK_TOOLS_CATEGORY
|
|
|
|
@staticmethod
|
|
def Args(parser):
|
|
parser.display_info.AddTransforms(search_util.GetTransforms())
|
|
parser.display_info.AddFormat("""
|
|
table[all-box,pager](
|
|
commandpath():label='COMMAND',
|
|
summary():wrap)
|
|
""")
|
|
base.URI_FLAG.RemoveFromParser(parser)
|
|
base.LIMIT_FLAG.SetDefault(parser, _DEFAULT_LIMIT)
|
|
base.SORT_BY_FLAG.SetDefault(parser, '~relevance')
|
|
parser.add_argument(
|
|
'command',
|
|
nargs='*',
|
|
help="""\
|
|
Sequence of names representing a gcloud group or command name.
|
|
|
|
If the arguments provide the name of a gcloud command, the full help
|
|
text of that command will be displayed. Otherwise, all arguments will
|
|
be considered search terms and used to search through all of gcloud's
|
|
help text.
|
|
""")
|
|
|
|
parser.add_argument(
|
|
'search_terms',
|
|
nargs=argparse.REMAINDER,
|
|
help="""\
|
|
Search terms. The command will return a list of gcloud commands that are
|
|
relevant to the searched term. If this argument is provided, the command
|
|
will always return a list of search results rather than displaying help
|
|
text of a single command.
|
|
|
|
For example, to search for commands that relate to the term `project` or
|
|
`folder`, run:
|
|
|
|
$ {command} -- project folder
|
|
""")
|
|
|
|
def Run(self, args):
|
|
if not args.search_terms:
|
|
try:
|
|
# --document=style=help to signal the metrics.Help() 'help' label in
|
|
# actions.RenderDocumentAction().Action().
|
|
self.ExecuteCommandDoNotUse(args.command + ['--document=style=help'])
|
|
return None
|
|
except Exception: # pylint: disable=broad-except
|
|
# In this case, we will treat the arguments as search terms.
|
|
pass
|
|
|
|
results = search.RunSearch(
|
|
args.command + (args.search_terms or []),
|
|
self._cli_power_users_only)
|
|
|
|
self._resources_found = len(results)
|
|
self._resources_displayed = min(len(results), args.limit)
|
|
return results
|
|
|
|
def Epilog(self, resources_were_displayed):
|
|
if not self._resources_found:
|
|
return
|
|
if resources_were_displayed:
|
|
log.status.Print(
|
|
'Listed {} of {} items.'.format(self._resources_displayed,
|
|
self._resources_found))
|
|
else:
|
|
log.status.Print('Listed 0 items.')
|