1
# Copyright (C) 2004, 2005, 2006 Canonical Ltd
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.
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.
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
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.
22
# TODO: `help commands --all` should show hidden commands
33
def help(topic=None, outfile=None):
34
"""Write the help for the specific topic to outfile"""
41
if topic in help_topics.topic_registry:
42
txt = help_topics.topic_registry.get_detail(topic)
45
help_on_command(topic, outfile=outfile)
48
def command_usage(cmd_object):
49
"""Return single-line grammar for command.
51
Only describes arguments, not options.
53
s = 'bzr ' + cmd_object.name() + ' '
54
for aname in cmd_object.takes_args:
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] + '...]'
70
def print_command_plugin(cmd_object, outfile, format):
71
"""Print the plugin that provides a command object, if any.
73
If the cmd_object is provided by a plugin, prints the plugin name to
74
outfile using the provided format string.
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)
82
def help_on_command(cmdname, outfile=None):
83
from bzrlib.commands import get_cmd_object
85
cmdname = str(cmdname)
86
cmd_object = get_cmd_object(cmdname)
88
return help_on_command_object(cmd_object, cmdname, outfile)
91
def help_on_command_object(cmd_object, cmdname, outfile=None):
92
"""Generate help on the cmd_object with a supplied name of cmdname.
94
:param cmd_object: An instance of a Command.
95
:param cmdname: The user supplied name. This might be an alias for example.
96
:param outfile: A stream to write the help to.
101
doc = cmd_object.help()
103
raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
105
print >>outfile, 'usage:', command_usage(cmd_object)
107
if cmd_object.aliases:
108
print >>outfile, 'aliases:',
109
print >>outfile, ', '.join(cmd_object.aliases)
113
print_command_plugin(cmd_object, outfile, '%s\n\n')
118
help_on_command_options(cmd_object, outfile)
119
see_also = cmd_object.get_see_also()
121
outfile.write('\nSee also: ')
122
outfile.write(', '.join(see_also))
126
def help_on_command_options(cmd, outfile=None):
127
from bzrlib.option import Option, get_optparser
130
options = cmd.options()
132
outfile.write(get_optparser(options).format_option_help())
135
def help_commands(outfile=None):
136
"""List all commands"""
139
outfile.write(_help_commands_to_text('commands'))
142
def _help_commands_to_text(topic):
143
"""Generate the help text for the list of commands"""
144
from bzrlib.commands import (builtin_command_names,
145
plugin_command_names,
148
if topic == 'hidden-commands':
152
names = set(builtin_command_names()) # to eliminate duplicates
153
names.update(plugin_command_names())
154
commands = ((n, get_cmd_object(n)) for n in names)
155
shown_commands = [(n, o) for n, o in commands if o.hidden == hidden]
156
max_name = max(len(n) for n, o in shown_commands)
157
indent = ' ' * (max_name + 1)
158
width = osutils.terminal_width() - 1
160
for cmd_name, cmd_object in sorted(shown_commands):
161
plugin_name = cmd_object.plugin_name()
162
if plugin_name is None:
165
plugin_name = ' [%s]' % plugin_name
167
cmd_help = cmd_object.help()
169
firstline = cmd_help.split('\n', 1)[0]
172
helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
173
lines = textwrap.wrap(helpstring, subsequent_indent=indent,
176
out.append(line + '\n')
180
help_topics.topic_registry.register("commands",
181
_help_commands_to_text,
182
"Basic help for all commands")
183
help_topics.topic_registry.register("hidden-commands",
184
_help_commands_to_text,
185
"All hidden commands")
added
removed
bzrlib/help.py
