← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/help.py

  • Committer: mbp at sourcefrog
  • Date: 2005-03-22 00:37:17 UTC
  • Revision ID: mbp@sourcefrog.net-20050322003717-7b1d4a370c237846
lift out tracefile creation code

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")