/brz/remove-bazaar

To get this branch, use:
bzr branch http://gegoxaren.bato24.eu/bzr/brz/remove-bazaar

« back to all changes in this revision

Viewing changes to bzrlib/help.py

Merge from bzr.dev, resolving conflicts.

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/help.py
1
 
# Copyright (C) 2004, 2005 by Canonical Ltd
2
 
 
 
1
# Copyright (C) 2004, 2005, 2006 Canonical Ltd
 
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
 
 
7
#
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
12
 
 
 
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
 
global_help = \
18
 
"""Bazaar-NG -- a free distributed version-control tool
19
 
http://bazaar-ng.org/
20
 
 
21
 
WARNING: This is an unstable development version.
22
 
         Please keep backups.
23
 
 
24
 
Basic commands:
25
 
 
26
 
  bzr init      makes this branch versioned
27
 
  bzr branch    make a copy of another branch
28
 
 
29
 
  bzr add       make files or directories versioned
30
 
  bzr ignore    ignore a file or pattern
31
 
  bzr mv        move or rename a versioned file
32
 
 
33
 
  bzr status    summarize changes in working copy
34
 
  bzr diff      show detailed diffs
35
 
 
36
 
  bzr merge     pull in changes from another branch
37
 
  bzr commit    
38
 
 
39
 
  bzr log       show history of changes
40
 
  bzr check     validate storage
41
 
 
42
 
Use e.g. 'bzr help init' for more details, or 'bzr help commands' for
43
 
all commands.
44
 
"""
45
 
 
 
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
46
23
 
47
24
import sys
48
 
 
49
 
 
50
 
def help(topic=None, outfile = None):
51
 
    if outfile == None:
 
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:
52
36
        outfile = sys.stdout
53
 
    if topic == None:
54
 
        outfile.write(global_help)
55
 
    elif topic == 'commands':
56
 
        help_commands(outfile = outfile)
 
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)
57
44
    else:
58
 
        help_on_command(topic, outfile = outfile)
59
 
 
60
 
 
61
 
def command_usage(cmdname, cmdclass):
 
45
        help_on_command(topic, outfile=outfile)
 
46
 
 
47
 
 
48
def command_usage(cmd_object):
62
49
    """Return single-line grammar for command.
63
50
 
64
51
    Only describes arguments, not options.
65
52
    """
66
 
    s = cmdname + ' '
67
 
    for aname in cmdclass.takes_args:
 
53
    s = 'bzr ' + cmd_object.name() + ' '
 
54
    for aname in cmd_object.takes_args:
68
55
        aname = aname.upper()
69
56
        if aname[-1] in ['$', '+']:
70
57
            aname = aname[:-1] + '...'
80
67
    return s
81
68
 
82
69
 
83
 
def help_on_command(cmdname, outfile = None):
 
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
 
84
85
    cmdname = str(cmdname)
85
86
 
86
 
    if outfile == None:
 
87
    if outfile is None:
87
88
        outfile = sys.stdout
88
89
 
89
 
    from inspect import getdoc
90
 
    import commands
91
 
    topic, cmdclass = commands.get_cmd_class(cmdname)
 
90
    cmd_object = get_cmd_object(cmdname)
92
91
 
93
 
    doc = getdoc(cmdclass)
94
 
    if doc == None:
 
92
    doc = cmd_object.help()
 
93
    if doc is None:
95
94
        raise NotImplementedError("sorry, no detailed help yet for %r" % cmdname)
96
95
 
97
 
    outfile.write('usage: ' + command_usage(topic, cmdclass) + '\n')
98
 
 
99
 
    if cmdclass.aliases:
100
 
        outfile.write('aliases: ' + ', '.join(cmdclass.aliases) + '\n')
101
 
    
 
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
 
102
106
    outfile.write(doc)
103
107
    if doc[-1] != '\n':
104
108
        outfile.write('\n')
105
 
    
106
 
    help_on_option(cmdclass.takes_options, outfile = None)
107
 
 
108
 
 
109
 
def help_on_option(options, outfile = None):
110
 
    import commands
111
 
    
112
 
    if not options:
113
 
        return
114
 
    
115
 
    if outfile == None:
 
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:
116
115
        outfile = sys.stdout
117
 
 
118
 
    outfile.write('\noptions:\n')
119
 
    for on in options:
120
 
        l = '    --' + on
121
 
        for shortname, longname in commands.SHORT_OPTIONS.items():
122
 
            if longname == on:
123
 
                l += ', -' + shortname
124
 
                break
125
 
        outfile.write(l + '\n')
126
 
 
127
 
 
128
 
def help_commands(outfile = None):
 
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):
129
122
    """List all commands"""
130
 
    import inspect
131
 
    import commands
132
 
 
133
 
    if outfile == None:
 
123
    if outfile is None:
134
124
        outfile = sys.stdout
135
 
    
136
 
    accu = []
137
 
    for cmdname, cmdclass in commands.get_all_cmds():
138
 
        accu.append((cmdname, cmdclass))
139
 
    accu.sort()
140
 
    for cmdname, cmdclass in accu:
141
 
        if cmdclass.hidden:
142
 
            continue
143
 
        outfile.write(command_usage(cmdname, cmdclass) + '\n')
144
 
        help = inspect.getdoc(cmdclass)
145
 
        if help:
146
 
            outfile.write("    " + help.split('\n', 1)[0] + '\n')
147
 
 
148
 
            
149
 
 
 
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")