~bzr-pqm/bzr/bzr.dev

2052.3.2 by John Arbash Meinel
Change Copyright .. by Canonical to Copyright ... Canonical
1
# Copyright (C) 2004, 2005, 2006 Canonical Ltd
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
2
#
351 by Martin Pool
- Split out help functions into bzrlib.help
3
# This program is free software; you can redistribute it and/or modify
4
# it under the terms of the GNU General Public License as published by
5
# the Free Software Foundation; either version 2 of the License, or
6
# (at your option) any later version.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
7
#
351 by Martin Pool
- Split out help functions into bzrlib.help
8
# This program is distributed in the hope that it will be useful,
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
# GNU General Public License for more details.
1887.1.1 by Adeodato Simó
Do not separate paragraphs in the copyright statement with blank lines,
12
#
351 by Martin Pool
- Split out help functions into bzrlib.help
13
# You should have received a copy of the GNU General Public License
14
# along with this program; if not, write to the Free Software
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
17
# TODO: Some way to get a list of external commands (defined by shell
18
# scripts) so that they can be included in the help listing as well.
19
# It should be enough to just list the plugin directory and look for
20
# executable files with reasonable names.
21
22
# TODO: `help commands --all` should show hidden commands
351 by Martin Pool
- Split out help functions into bzrlib.help
23
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
24
import sys
1185.12.55 by Aaron Bentley
did test wrapping for option text
25
import textwrap
2023.1.1 by ghigo
add topics help
26
2070.4.3 by John Arbash Meinel
code and doc cleanup
27
from bzrlib import (
2432.1.3 by Robert Collins
Create a HelpContexts object to do help lookups.
28
    commands as _mod_commands,
2432.1.5 by Robert Collins
Initial stub for topic searching.
29
    errors,
2070.4.3 by John Arbash Meinel
code and doc cleanup
30
    help_topics,
31
    osutils,
2432.1.24 by Robert Collins
Add plugins as a help index.
32
    plugin,
2432.1.31 by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function.
33
    symbol_versioning,
2070.4.3 by John Arbash Meinel
code and doc cleanup
34
    )
1993.4.4 by John Arbash Meinel
cleanup help.py
35
36
37
def help(topic=None, outfile=None):
2070.4.3 by John Arbash Meinel
code and doc cleanup
38
    """Write the help for the specific topic to outfile"""
1993.4.4 by John Arbash Meinel
cleanup help.py
39
    if outfile is None:
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
40
        outfile = sys.stdout
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
41
2432.1.16 by Robert Collins
Correct spelling of Indexs to Indices.
42
    indices = HelpIndices()
43
    topics = indices.search(topic)
2432.1.23 by Robert Collins
Add a list of shadowed terms to "bzr help term".
44
    shadowed_terms = []
45
    for index, topic in topics[1:]:
2432.1.30 by Robert Collins
Fix the ModuleHelpTopic get_help_topic to be tested with closer to real world data and strip the bzrlib.plugins. prefix from the name.
46
        shadowed_terms.append('%s%s' % (index.prefix, topic.get_help_topic()))
2432.1.23 by Robert Collins
Add a list of shadowed terms to "bzr help term".
47
    outfile.write(topics[0][1].get_help_text(shadowed_terms))
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
48
49
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
50
def help_commands(outfile=None):
351 by Martin Pool
- Split out help functions into bzrlib.help
51
    """List all commands"""
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
52
    if outfile is None:
53
        outfile = sys.stdout
54
    outfile.write(_help_commands_to_text('commands'))
55
56
2432.1.31 by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function.
57
@symbol_versioning.deprecated_function(symbol_versioning.zero_sixteen)
58
def command_usage(cmd):
59
    return cmd._usage()
60
61
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
62
def _help_commands_to_text(topic):
63
    """Generate the help text for the list of commands"""
64
    out = []
1551.9.14 by Aaron Bentley
Change topic to hidden-commands
65
    if topic == 'hidden-commands':
1551.9.13 by Aaron Bentley
add "hidden" topic
66
        hidden = True
67
    else:
68
        hidden = False
2432.1.3 by Robert Collins
Create a HelpContexts object to do help lookups.
69
    names = set(_mod_commands.builtin_command_names()) # to eliminate duplicates
70
    names.update(_mod_commands.plugin_command_names())
71
    commands = ((n, _mod_commands.get_cmd_object(n)) for n in names)
1551.9.13 by Aaron Bentley
add "hidden" topic
72
    shown_commands = [(n, o) for n, o in commands if o.hidden == hidden]
2034.1.3 by Aaron Bentley
Changes from review and tweaks
73
    max_name = max(len(n) for n, o in shown_commands)
74
    indent = ' ' * (max_name + 1)
2034.1.1 by Aaron Bentley
Condense command help text
75
    width = osutils.terminal_width() - 1
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
76
2034.1.3 by Aaron Bentley
Changes from review and tweaks
77
    for cmd_name, cmd_object in sorted(shown_commands):
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
78
        plugin_name = cmd_object.plugin_name()
2034.1.1 by Aaron Bentley
Condense command help text
79
        if plugin_name is None:
80
            plugin_name = ''
81
        else:
2034.1.4 by Aaron Bentley
Change angle brackets to square brackets
82
            plugin_name = ' [%s]' % plugin_name
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
83
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
84
        cmd_help = cmd_object.help()
85
        if cmd_help:
86
            firstline = cmd_help.split('\n', 1)[0]
2034.1.1 by Aaron Bentley
Condense command help text
87
        else:
88
            firstline = ''
2034.1.3 by Aaron Bentley
Changes from review and tweaks
89
        helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
2034.1.1 by Aaron Bentley
Condense command help text
90
        lines = textwrap.wrap(helpstring, subsequent_indent=indent,
91
                              width=width)
92
        for line in lines:
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
93
            out.append(line + '\n')
94
    return ''.join(out)
95
96
97
help_topics.topic_registry.register("commands",
98
                                    _help_commands_to_text,
99
                                    "Basic help for all commands")
2432.1.1 by Robert Collins
Add a HelpTopicContext object.
100
help_topics.topic_registry.register("hidden-commands",
1551.9.13 by Aaron Bentley
add "hidden" topic
101
                                    _help_commands_to_text,
102
                                    "All hidden commands")
2432.1.3 by Robert Collins
Create a HelpContexts object to do help lookups.
103
104
2432.1.16 by Robert Collins
Correct spelling of Indexs to Indices.
105
class HelpIndices(object):
2432.1.31 by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function.
106
    """Maintainer of help topics across multiple indices.
2432.1.9 by Robert Collins
Expand HelpContexts documentation.
107
    
2432.1.31 by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function.
108
    It is currently separate to the HelpTopicRegistry because of its ordered
109
    nature, but possibly we should instead structure it as a search within the
110
    registry and add ordering and searching facilities to the registry. The
111
    registry would probably need to be restructured to support that cleanly
112
    which is why this has been implemented in parallel even though it does as a
113
    result permit searching for help in indices which are not discoverable via
2432.1.9 by Robert Collins
Expand HelpContexts documentation.
114
    'help topics'.
2432.1.31 by Robert Collins
Review feedback and put help.command_usage back in as a deprecated function.
115
116
    Each index has a unique prefix string, such as "commands", and contains
117
    help topics which can be listed or searched.
2432.1.9 by Robert Collins
Expand HelpContexts documentation.
118
    """
2432.1.3 by Robert Collins
Create a HelpContexts object to do help lookups.
119
120
    def __init__(self):
121
        self.search_path = [
2432.1.15 by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name.
122
            help_topics.HelpTopicIndex(),
123
            _mod_commands.HelpCommandIndex(),
2432.1.24 by Robert Collins
Add plugins as a help index.
124
            plugin.PluginsHelpIndex(),
2432.1.3 by Robert Collins
Create a HelpContexts object to do help lookups.
125
            ]
2432.1.5 by Robert Collins
Initial stub for topic searching.
126
2432.1.19 by Robert Collins
Ensure each HelpIndex has a unique prefix.
127
    def _check_prefix_uniqueness(self):
128
        """Ensure that the index collection is able to differentiate safely."""
129
        prefixes = {}
130
        for index in self.search_path:
131
            prefixes.setdefault(index.prefix, []).append(index)
132
        for prefix, indices in prefixes.items():
133
            if len(indices) > 1:
134
                raise errors.DuplicateHelpPrefix(prefix)
135
2432.1.5 by Robert Collins
Initial stub for topic searching.
136
    def search(self, topic):
137
        """Search for topic across the help search path.
138
        
139
        :param topic: A string naming the help topic to search for.
2432.1.15 by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name.
140
        :raises: NoHelpTopic if none of the indexs in search_path have topic.
2432.1.7 by Robert Collins
HelpContexts.search now returns the found topics.
141
        :return: A list of HelpTopics which matched 'topic'.
2432.1.5 by Robert Collins
Initial stub for topic searching.
142
        """
2432.1.19 by Robert Collins
Ensure each HelpIndex has a unique prefix.
143
        self._check_prefix_uniqueness()
2432.1.6 by Robert Collins
HelpContexts.search now invokes get_topics on each context.
144
        result = []
2432.1.15 by Robert Collins
Rename Context (in bzrlib.help) to Index, for a clearer name.
145
        for index in self.search_path:
2432.1.20 by Robert Collins
Modify the result of HelpIndices.search to include the index each result was found in.
146
            result.extend([(index, _topic) for _topic in index.get_topics(topic)])
2432.1.6 by Robert Collins
HelpContexts.search now invokes get_topics on each context.
147
        if not result:
148
            raise errors.NoHelpTopic(topic)
2432.1.7 by Robert Collins
HelpContexts.search now returns the found topics.
149
        else:
150
            return result