| # -*- coding: utf-8 -*- |
| # Copyright 2011 Google Inc. 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. |
| """Implementation of gsutil help command.""" |
| |
| from __future__ import absolute_import |
| |
| import itertools |
| import os |
| import pkgutil |
| import re |
| from subprocess import PIPE |
| from subprocess import Popen |
| |
| import gslib.addlhelp |
| from gslib.command import Command |
| from gslib.command import OLD_ALIAS_MAP |
| import gslib.commands |
| from gslib.exception import CommandException |
| from gslib.help_provider import HelpProvider |
| from gslib.help_provider import MAX_HELP_NAME_LEN |
| from gslib.util import IsRunningInteractively |
| |
| _SYNOPSIS = """ |
| gsutil help [command or topic] |
| """ |
| |
| _DETAILED_HELP_TEXT = (""" |
| <B>SYNOPSIS</B> |
| """ + _SYNOPSIS + """ |
| |
| |
| <B>DESCRIPTION</B> |
| Running: |
| |
| gsutil help |
| |
| will provide a summary of all commands and additional topics on which |
| help is available. |
| |
| Running: |
| |
| gsutil help command or topic |
| |
| will provide help about the specified command or topic. |
| |
| Running: |
| |
| gsutil help command sub-command |
| |
| will provide help about the specified sub-command. For example, running: |
| |
| gsutil help acl set |
| |
| will provide help about the "set" subcommand of the "acl" command. |
| |
| If you set the PAGER environment variable to the path to a pager program |
| (such as /bin/less on Linux), long help sections will be piped through |
| the specified pager. |
| """) |
| |
| top_level_usage_string = ( |
| 'Usage: gsutil [-D] [-DD] [-h header]... ' |
| '[-m] [-o] [-q] [command [opts...] args...]' |
| ) |
| |
| |
| class HelpCommand(Command): |
| """Implementation of gsutil help command.""" |
| |
| # Command specification. See base class for documentation. |
| command_spec = Command.CreateCommandSpec( |
| 'help', |
| command_name_aliases=['?', 'man'], |
| usage_synopsis=_SYNOPSIS, |
| min_args=0, |
| max_args=2, |
| supported_sub_args='', |
| file_url_ok=True, |
| provider_url_ok=False, |
| urls_start_arg=0, |
| ) |
| # Help specification. See help_provider.py for documentation. |
| help_spec = Command.HelpSpec( |
| help_name='help', |
| help_name_aliases=['?'], |
| help_type='command_help', |
| help_one_line_summary='Get help about commands and topics', |
| help_text=_DETAILED_HELP_TEXT, |
| subcommand_help_text={}, |
| ) |
| |
| def RunCommand(self): |
| """Command entry point for the help command.""" |
| (help_type_map, help_name_map) = self._LoadHelpMaps() |
| output = [] |
| if not self.args: |
| output.append('%s\nAvailable commands:\n' % top_level_usage_string) |
| format_str = ' %-' + str(MAX_HELP_NAME_LEN) + 's%s\n' |
| for help_prov in sorted(help_type_map['command_help'], |
| key=lambda hp: hp.help_spec.help_name): |
| output.append(format_str % ( |
| help_prov.help_spec.help_name, |
| help_prov.help_spec.help_one_line_summary)) |
| output.append('\nAdditional help topics:\n') |
| for help_prov in sorted(help_type_map['additional_help'], |
| key=lambda hp: hp.help_spec.help_name): |
| output.append(format_str % ( |
| help_prov.help_spec.help_name, |
| help_prov.help_spec.help_one_line_summary)) |
| output.append('\nUse gsutil help <command or topic> for detailed help.') |
| else: |
| invalid_subcommand = False |
| arg = self.args[0] |
| if arg not in help_name_map: |
| output.append('No help available for "%s"' % arg) |
| else: |
| help_prov = help_name_map[arg] |
| help_name = None |
| if len(self.args) > 1: # We also have a subcommand argument. |
| subcommand_map = help_prov.help_spec.subcommand_help_text |
| if subcommand_map and self.args[1] in subcommand_map: |
| help_name = arg + ' ' + self.args[1] |
| help_text = subcommand_map[self.args[1]] |
| else: |
| invalid_subcommand = True |
| if not subcommand_map: |
| output.append(( |
| 'The "%s" command has no subcommands. You can ask for the ' |
| 'full help by running:\n\n\tgsutil help %s\n') % |
| (arg, arg)) |
| else: |
| subcommand_examples = [] |
| for subcommand in subcommand_map: |
| subcommand_examples.append( |
| '\tgsutil help %s %s' % (arg, subcommand)) |
| output.append( |
| ('Subcommand "%s" does not exist for command "%s".\n' |
| 'You can either ask for the full help about the command by ' |
| 'running:\n\n\tgsutil help %s\n\n' |
| 'Or you can ask for help about one of the subcommands:\n\n%s' |
| ) % (self.args[1], arg, arg, '\n'.join(subcommand_examples))) |
| if not invalid_subcommand: |
| if not help_name: # No subcommand or invalid subcommand. |
| help_name = help_prov.help_spec.help_name |
| help_text = help_prov.help_spec.help_text |
| |
| output.append('<B>NAME</B>\n') |
| output.append(' %s - %s\n' % ( |
| help_name, help_prov.help_spec.help_one_line_summary)) |
| output.append('\n\n') |
| output.append(help_text.strip('\n')) |
| new_alias = OLD_ALIAS_MAP.get(arg, [None])[0] |
| if new_alias: |
| deprecation_warning = """ |
| The "%s" alias is deprecated, and will eventually be removed completely. |
| Please use the "%s" command instead.""" % (arg, new_alias) |
| |
| output.append('\n\n\n<B>DEPRECATION WARNING</B>\n') |
| output.append(deprecation_warning) |
| self._OutputHelp(''.join(output)) |
| return 0 |
| |
| def _OutputHelp(self, help_str): |
| """Outputs simply formatted string. |
| |
| This function paginates if the string is too long, PAGER is defined, and |
| the output is a tty. |
| |
| Args: |
| help_str: String to format. |
| """ |
| # Replace <B> and </B> with terminal formatting strings if connected to tty. |
| if not IsRunningInteractively(): |
| help_str = re.sub('<B>', '', help_str) |
| help_str = re.sub('</B>', '', help_str) |
| print help_str |
| return |
| help_str = re.sub('<B>', '\033[1m', help_str) |
| help_str = re.sub('</B>', '\033[0;0m', help_str) |
| num_lines = len(help_str.split('\n')) |
| if 'PAGER' in os.environ and num_lines >= gslib.util.GetTermLines(): |
| # Use -r option for less to make bolding work right. |
| pager = os.environ['PAGER'].split(' ') |
| if pager[0].endswith('less'): |
| pager.append('-r') |
| try: |
| Popen(pager, stdin=PIPE).communicate(input=help_str) |
| except OSError, e: |
| raise CommandException('Unable to open pager (%s): %s' % |
| (' '.join(pager), e)) |
| else: |
| print help_str |
| |
| def _LoadHelpMaps(self): |
| """Returns tuple of help type and help name. |
| |
| help type is a dict with key: help type |
| value: list of HelpProviders |
| help name is a dict with key: help command name or alias |
| value: HelpProvider |
| |
| Returns: |
| (help type, help name) |
| """ |
| |
| # Import all gslib.commands submodules. |
| for _, module_name, _ in pkgutil.iter_modules(gslib.commands.__path__): |
| __import__('gslib.commands.%s' % module_name) |
| # Import all gslib.addlhelp submodules. |
| for _, module_name, _ in pkgutil.iter_modules(gslib.addlhelp.__path__): |
| __import__('gslib.addlhelp.%s' % module_name) |
| |
| help_type_map = {} |
| help_name_map = {} |
| for s in gslib.help_provider.ALL_HELP_TYPES: |
| help_type_map[s] = [] |
| # Only include HelpProvider subclasses in the dict. |
| for help_prov in itertools.chain( |
| HelpProvider.__subclasses__(), Command.__subclasses__()): |
| if help_prov is Command: |
| # Skip the Command base class itself; we just want its subclasses, |
| # where the help command text lives (in addition to non-Command |
| # HelpProviders, like naming.py). |
| continue |
| gslib.help_provider.SanityCheck(help_prov, help_name_map) |
| help_name_map[help_prov.help_spec.help_name] = help_prov |
| for help_name_aliases in help_prov.help_spec.help_name_aliases: |
| help_name_map[help_name_aliases] = help_prov |
| help_type_map[help_prov.help_spec.help_type].append(help_prov) |
| return (help_type_map, help_name_map) |
