← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help.py

Partial updates for API changes in trunk.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help.py
 
1
# Copyright (C) 2004, 2005, 2006 Canonical Ltd
 
2
#
 
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.
 
7
#
 
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.
 
12
#
 
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
 
 
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
 
23
 
 
24
import sys
 
25
import textwrap
 
26
 
 
27
from bzrlib import (
 
28
    help_topics,
 
29
    osutils,
 
30
    )
 
31
 
 
32
 
 
33
def help(topic=None, outfile=None):
 
34
    """Write the help for the specific topic to outfile"""
 
35
    if outfile is None:
 
36
        outfile = sys.stdout
 
37
 
 
38
    if topic is None:
 
39
        topic = 'basic'
 
40
 
 
41
    if topic in help_topics.topic_registry:
 
42
        txt = help_topics.topic_registry.get_detail(topic)
 
43
        outfile.write(txt)
 
44
    else:
 
45
        help_on_command(topic, outfile=outfile)
 
46
 
 
47
 
 
48
def command_usage(cmd_object):
 
49
    """Return single-line grammar for command.
 
50
 
 
51
    Only describes arguments, not options.
 
52
    """
 
53
    s = 'bzr ' + cmd_object.name() + ' '
 
54
    for aname in cmd_object.takes_args:
 
55
        aname = aname.upper()
 
56
        if aname[-1] in ['$', '+']:
 
57
            aname = aname[:-1] + '...'
 
58
        elif aname[-1] == '?':
 
59
            aname = '[' + aname[:-1] + ']'
 
60
        elif aname[-1] == '*':
 
61
            aname = '[' + aname[:-1] + '...]'
 
62
        s += aname + ' '
 
63
            
 
64
    assert s[-1] == ' '
 
65
    s = s[:-1]
 
66
    
 
67
    return s
 
68
 
 
69
 
 
70
def print_command_plugin(cmd_object, outfile, format):
 
71
    """Print the plugin that provides a command object, if any.
 
72
 
 
73
    If the cmd_object is provided by a plugin, prints the plugin name to
 
74
    outfile using the provided format string.
 
75
    """
 
76
    plugin_name = cmd_object.plugin_name()
 
77
    if plugin_name is not None:
 
78
        out_str = '(From plugin "%s")' % plugin_name
 
79
        outfile.write(format % out_str)
 
80
 
 
81
 
 
82
def help_on_command(cmdname, outfile=None):
 
83
    from bzrlib.commands import get_cmd_object
 
84
 
 
85
    cmdname = str(cmdname)
 
86
 
 
87
    if outfile is None:
 
88
        outfile = sys.stdout
 
89
 
 
90
    cmd_object = get_cmd_object(cmdname)
 
91
 
 
92
    doc = cmd_object.help()
 
93
    if doc is None:
 
94
        raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
 
95
 
 
96
    print >>outfile, 'usage:', command_usage(cmd_object)
 
97
 
 
98
    if cmd_object.aliases:
 
99
        print >>outfile, 'aliases:',
 
100
        print >>outfile, ', '.join(cmd_object.aliases)
 
101
 
 
102
    print >>outfile
 
103
 
 
104
    print_command_plugin(cmd_object, outfile, '%s\n\n')
 
105
 
 
106
    outfile.write(doc)
 
107
    if doc[-1] != '\n':
 
108
        outfile.write('\n')
 
109
    help_on_command_options(cmd_object, outfile)
 
110
 
 
111
 
 
112
def help_on_command_options(cmd, outfile=None):
 
113
    from bzrlib.option import Option, get_optparser
 
114
    if outfile is None:
 
115
        outfile = sys.stdout
 
116
    options = cmd.options()
 
117
    outfile.write('\n')
 
118
    outfile.write(get_optparser(options).format_option_help())
 
119
 
 
120
 
 
121
def help_commands(outfile=None):
 
122
    """List all commands"""
 
123
    if outfile is None:
 
124
        outfile = sys.stdout
 
125
    outfile.write(_help_commands_to_text('commands'))
 
126
 
 
127
 
 
128
def _help_commands_to_text(topic):
 
129
    """Generate the help text for the list of commands"""
 
130
    from bzrlib.commands import (builtin_command_names,
 
131
                                 plugin_command_names,
 
132
                                 get_cmd_object)
 
133
    out = []
 
134
    if topic == 'hidden-commands':
 
135
        hidden = True
 
136
    else:
 
137
        hidden = False
 
138
    names = set(builtin_command_names()) # to eliminate duplicates
 
139
    names.update(plugin_command_names())
 
140
    commands = ((n, get_cmd_object(n)) for n in names)
 
141
    shown_commands = [(n, o) for n, o in commands if o.hidden == hidden]
 
142
    max_name = max(len(n) for n, o in shown_commands)
 
143
    indent = ' ' * (max_name + 1)
 
144
    width = osutils.terminal_width() - 1
 
145
 
 
146
    for cmd_name, cmd_object in sorted(shown_commands):
 
147
        plugin_name = cmd_object.plugin_name()
 
148
        if plugin_name is None:
 
149
            plugin_name = ''
 
150
        else:
 
151
            plugin_name = ' [%s]' % plugin_name
 
152
 
 
153
        cmd_help = cmd_object.help()
 
154
        if cmd_help:
 
155
            firstline = cmd_help.split('\n', 1)[0]
 
156
        else:
 
157
            firstline = ''
 
158
        helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
 
159
        lines = textwrap.wrap(helpstring, subsequent_indent=indent,
 
160
                              width=width)
 
161
        for line in lines:
 
162
            out.append(line + '\n')
 
163
    return ''.join(out)
 
164
 
 
165
 
 
166
help_topics.topic_registry.register("commands",
 
167
                                    _help_commands_to_text,
 
168
                                    "Basic help for all commands")
 
169
help_topics.topic_registry.register("hidden-commands", 
 
170
                                    _help_commands_to_text,
 
171
                                    "All hidden commands")