~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 (
28
    help_topics,
29
    osutils,
30
    )
1993.4.4 by John Arbash Meinel
cleanup help.py
31
32
33
def help(topic=None, outfile=None):
2070.4.3 by John Arbash Meinel
code and doc cleanup
34
    """Write the help for the specific topic to outfile"""
1993.4.4 by John Arbash Meinel
cleanup help.py
35
    if outfile is None:
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
36
        outfile = sys.stdout
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
37
1993.4.4 by John Arbash Meinel
cleanup help.py
38
    if topic is None:
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
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)
351 by Martin Pool
- Split out help functions into bzrlib.help
44
    else:
2023.1.1 by ghigo
add topics help
45
        help_on_command(topic, outfile=outfile)
351 by Martin Pool
- Split out help functions into bzrlib.help
46
47
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
48
def command_usage(cmd_object):
452 by Martin Pool
- show command usage in help
49
    """Return single-line grammar for command.
50
51
    Only describes arguments, not options.
52
    """
1177 by Martin Pool
- help on command says "usage: bzr help"
53
    s = 'bzr ' + cmd_object.name() + ' '
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
54
    for aname in cmd_object.takes_args:
452 by Martin Pool
- show command usage in help
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
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
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
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
82
def help_on_command(cmdname, outfile=None):
83
    from bzrlib.commands import get_cmd_object
84
351 by Martin Pool
- Split out help functions into bzrlib.help
85
    cmdname = str(cmdname)
86
1963.2.6 by Robey Pointer
pychecker is on crack; go back to using 'is None'.
87
    if outfile is None:
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
88
        outfile = sys.stdout
89
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
90
    cmd_object = get_cmd_object(cmdname)
351 by Martin Pool
- Split out help functions into bzrlib.help
91
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
92
    doc = cmd_object.help()
1963.2.6 by Robey Pointer
pychecker is on crack; go back to using 'is None'.
93
    if doc is None:
351 by Martin Pool
- Split out help functions into bzrlib.help
94
        raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
95
2070.4.3 by John Arbash Meinel
code and doc cleanup
96
    print >>outfile, 'usage:', command_usage(cmd_object)
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
97
98
    if cmd_object.aliases:
99
        print >>outfile, 'aliases:',
100
        print >>outfile, ', '.join(cmd_object.aliases)
101
102
    print >>outfile
103
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
104
    print_command_plugin(cmd_object, outfile, '%s\n\n')
105
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
106
    outfile.write(doc)
675 by Martin Pool
- help formatting fix from ndim
107
    if doc[-1] != '\n':
108
        outfile.write('\n')
1185.33.15 by Martin Pool
[path] bgu in help_on_command (Robert Widhopf-Frank)
109
    help_on_command_options(cmd_object, outfile)
1185.16.43 by Martin Pool
- clean up handling of option objects
110
111
112
def help_on_command_options(cmd, outfile=None):
1857.1.3 by Aaron Bentley
Make option adding depend on Option type
113
    from bzrlib.option import Option, get_optparser
1857.1.2 by Aaron Bentley
Use optparse for generating option help
114
    if outfile is None:
115
        outfile = sys.stdout
1185.16.43 by Martin Pool
- clean up handling of option objects
116
    options = cmd.options()
1857.1.2 by Aaron Bentley
Use optparse for generating option help
117
    outfile.write('\n')
118
    outfile.write(get_optparser(options).format_option_help())
635 by Martin Pool
- manpage generator by Hans Ulrich Niedermann
119
120
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
121
def help_commands(outfile=None):
351 by Martin Pool
- Split out help functions into bzrlib.help
122
    """List all commands"""
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
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"""
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
130
    from bzrlib.commands import (builtin_command_names,
131
                                 plugin_command_names,
132
                                 get_cmd_object)
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
133
    out = []
134
2034.1.3 by Aaron Bentley
Changes from review and tweaks
135
    names = set(builtin_command_names()) # to eliminate duplicates
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
136
    names.update(plugin_command_names())
2034.1.3 by Aaron Bentley
Changes from review and tweaks
137
    commands = ((n, get_cmd_object(n)) for n in names)
138
    shown_commands = [(n, o) for n, o in commands if not o.hidden]
139
    max_name = max(len(n) for n, o in shown_commands)
140
    indent = ' ' * (max_name + 1)
2034.1.1 by Aaron Bentley
Condense command help text
141
    width = osutils.terminal_width() - 1
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
142
2034.1.3 by Aaron Bentley
Changes from review and tweaks
143
    for cmd_name, cmd_object in sorted(shown_commands):
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
144
        plugin_name = cmd_object.plugin_name()
2034.1.1 by Aaron Bentley
Condense command help text
145
        if plugin_name is None:
146
            plugin_name = ''
147
        else:
2034.1.4 by Aaron Bentley
Change angle brackets to square brackets
148
            plugin_name = ' [%s]' % plugin_name
1733.2.5 by Michael Ellerman
Show which plugin (if any) provides a command.
149
1162 by Martin Pool
- change Command infrastructure to use (mostly stateless) objects to
150
        cmd_help = cmd_object.help()
151
        if cmd_help:
152
            firstline = cmd_help.split('\n', 1)[0]
2034.1.1 by Aaron Bentley
Condense command help text
153
        else:
154
            firstline = ''
2034.1.3 by Aaron Bentley
Changes from review and tweaks
155
        helpstring = '%-*s %s%s' % (max_name, cmd_name, firstline, plugin_name)
2034.1.1 by Aaron Bentley
Condense command help text
156
        lines = textwrap.wrap(helpstring, subsequent_indent=indent,
157
                              width=width)
158
        for line in lines:
2070.4.13 by John Arbash Meinel
Switch help_topics to use a Registry.
159
            out.append(line + '\n')
160
    return ''.join(out)
161
162
163
help_topics.topic_registry.register("commands",
164
                                    _help_commands_to_text,
165
                                    "Basic help for all commands")