/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/commands.py

  • Committer: Robert Collins
  • Date: 2010-05-06 11:08:10 UTC
  • mto: This revision was merged to the branch mainline in revision 5223.
  • Revision ID: robertc@robertcollins.net-20100506110810-h3j07fh5gmw54s25
Cleaner matcher matching revised unlocking protocol.

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2006 Canonical Ltd
 
1
# Copyright (C) 2005-2010 Canonical Ltd
2
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
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
 
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
 
 
17
 
 
18
 
# TODO: probably should say which arguments are candidates for glob
19
 
# expansion on windows and do that at the command level.
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
20
17
 
21
18
# TODO: Define arguments by objects, rather than just using names.
22
19
# Those objects can specify the expected type of the argument, which
25
22
 
26
23
# TODO: Specific "examples" property on commands for consistent formatting.
27
24
 
28
 
# TODO: "--profile=cum", to change sort order.  Is there any value in leaving
29
 
# the profile output behind so it can be interactively examined?
30
 
 
31
25
import os
32
26
import sys
33
27
 
35
29
lazy_import(globals(), """
36
30
import codecs
37
31
import errno
 
32
import threading
38
33
from warnings import warn
39
34
 
40
35
import bzrlib
41
36
from bzrlib import (
 
37
    cleanup,
 
38
    cmdline,
42
39
    debug,
43
40
    errors,
44
41
    option,
45
42
    osutils,
46
 
    registry,
47
43
    trace,
 
44
    ui,
48
45
    win32utils,
49
46
    )
50
47
""")
51
48
 
 
49
from bzrlib.hooks import HookPoint, Hooks
 
50
# Compatibility - Option used to be in commands.
 
51
from bzrlib.option import Option
 
52
from bzrlib.plugin import disable_plugins, load_plugins
 
53
from bzrlib import registry
52
54
from bzrlib.symbol_versioning import (
53
55
    deprecated_function,
 
56
    deprecated_in,
54
57
    deprecated_method,
55
58
    )
56
 
# Compatibility
57
 
from bzrlib.option import Option
58
 
 
59
 
 
60
 
plugin_cmds = {}
 
59
 
 
60
 
 
61
class CommandInfo(object):
 
62
    """Information about a command."""
 
63
 
 
64
    def __init__(self, aliases):
 
65
        """The list of aliases for the command."""
 
66
        self.aliases = aliases
 
67
 
 
68
    @classmethod
 
69
    def from_command(klass, command):
 
70
        """Factory to construct a CommandInfo from a command."""
 
71
        return klass(command.aliases)
 
72
 
 
73
 
 
74
class CommandRegistry(registry.Registry):
 
75
    """Special registry mapping command names to command classes.
 
76
    
 
77
    :ivar overridden_registry: Look in this registry for commands being
 
78
        overridden by this registry.  This can be used to tell plugin commands
 
79
        about the builtin they're decorating.
 
80
    """
 
81
 
 
82
    def __init__(self):
 
83
        registry.Registry.__init__(self)
 
84
        self.overridden_registry = None
 
85
        # map from aliases to the real command that implements the name
 
86
        self._alias_dict = {}
 
87
 
 
88
    def get(self, command_name):
 
89
        real_name = self._alias_dict.get(command_name, command_name)
 
90
        return registry.Registry.get(self, real_name)
 
91
 
 
92
    @staticmethod
 
93
    def _get_name(command_name):
 
94
        if command_name.startswith("cmd_"):
 
95
            return _unsquish_command_name(command_name)
 
96
        else:
 
97
            return command_name
 
98
 
 
99
    def register(self, cmd, decorate=False):
 
100
        """Utility function to help register a command
 
101
 
 
102
        :param cmd: Command subclass to register
 
103
        :param decorate: If true, allow overriding an existing command
 
104
            of the same name; the old command is returned by this function.
 
105
            Otherwise it is an error to try to override an existing command.
 
106
        """
 
107
        k = cmd.__name__
 
108
        k_unsquished = self._get_name(k)
 
109
        try:
 
110
            previous = self.get(k_unsquished)
 
111
        except KeyError:
 
112
            previous = None
 
113
            if self.overridden_registry:
 
114
                try:
 
115
                    previous = self.overridden_registry.get(k_unsquished)
 
116
                except KeyError:
 
117
                    pass
 
118
        info = CommandInfo.from_command(cmd)
 
119
        try:
 
120
            registry.Registry.register(self, k_unsquished, cmd,
 
121
                                       override_existing=decorate, info=info)
 
122
        except KeyError:
 
123
            trace.warning('Two plugins defined the same command: %r' % k)
 
124
            trace.warning('Not loading the one in %r' %
 
125
                sys.modules[cmd.__module__])
 
126
            trace.warning('Previously this command was registered from %r' %
 
127
                sys.modules[previous.__module__])
 
128
        for a in cmd.aliases:
 
129
            self._alias_dict[a] = k_unsquished
 
130
        return previous
 
131
 
 
132
    def register_lazy(self, command_name, aliases, module_name):
 
133
        """Register a command without loading its module.
 
134
 
 
135
        :param command_name: The primary name of the command.
 
136
        :param aliases: A list of aliases for the command.
 
137
        :module_name: The module that the command lives in.
 
138
        """
 
139
        key = self._get_name(command_name)
 
140
        registry.Registry.register_lazy(self, key, module_name, command_name,
 
141
                                        info=CommandInfo(aliases))
 
142
        for a in aliases:
 
143
            self._alias_dict[a] = key
 
144
 
 
145
 
 
146
plugin_cmds = CommandRegistry()
 
147
builtin_command_registry = CommandRegistry()
 
148
plugin_cmds.overridden_registry = builtin_command_registry
61
149
 
62
150
 
63
151
def register_command(cmd, decorate=False):
64
 
    """Utility function to help register a command
 
152
    """Register a plugin command.
65
153
 
66
 
    :param cmd: Command subclass to register
67
 
    :param decorate: If true, allow overriding an existing command
68
 
        of the same name; the old command is returned by this function.
69
 
        Otherwise it is an error to try to override an existing command.
 
154
    Should generally be avoided in favor of lazy registration. 
70
155
    """
71
156
    global plugin_cmds
72
 
    k = cmd.__name__
73
 
    if k.startswith("cmd_"):
74
 
        k_unsquished = _unsquish_command_name(k)
75
 
    else:
76
 
        k_unsquished = k
77
 
    if k_unsquished not in plugin_cmds:
78
 
        plugin_cmds[k_unsquished] = cmd
79
 
        ## trace.mutter('registered plugin command %s', k_unsquished)
80
 
        if decorate and k_unsquished in builtin_command_names():
81
 
            return _builtin_commands()[k_unsquished]
82
 
    elif decorate:
83
 
        result = plugin_cmds[k_unsquished]
84
 
        plugin_cmds[k_unsquished] = cmd
85
 
        return result
86
 
    else:
87
 
        trace.log_error('Two plugins defined the same command: %r' % k)
88
 
        trace.log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
89
 
        trace.log_error('Previously this command was registered from %r' %
90
 
                        sys.modules[plugin_cmds[k_unsquished].__module__])
 
157
    return plugin_cmds.register(cmd, decorate)
91
158
 
92
159
 
93
160
def _squish_command_name(cmd):
95
162
 
96
163
 
97
164
def _unsquish_command_name(cmd):
98
 
    assert cmd.startswith("cmd_")
99
165
    return cmd[4:].replace('_','-')
100
166
 
101
167
 
 
168
@deprecated_function(deprecated_in((2, 2, 0)))
102
169
def _builtin_commands():
 
170
    """Return a dict of {name: cmd_class} for builtin commands.
 
171
 
 
172
    :deprecated: Use the builtin_command_registry registry instead
 
173
    """
 
174
    # return dict(name: cmd_class)
 
175
    return dict(builtin_command_registry.items())
 
176
 
 
177
 
 
178
def _register_builtin_commands():
 
179
    if builtin_command_registry.keys():
 
180
        # only load once
 
181
        return
103
182
    import bzrlib.builtins
 
183
    for cmd_class in _scan_module_for_commands(bzrlib.builtins).values():
 
184
        builtin_command_registry.register(cmd_class)
 
185
    bzrlib.builtins._register_lazy_builtins()
 
186
 
 
187
 
 
188
def _scan_module_for_commands(module):
104
189
    r = {}
105
 
    builtins = bzrlib.builtins.__dict__
106
 
    for name in builtins:
 
190
    for name, obj in module.__dict__.iteritems():
107
191
        if name.startswith("cmd_"):
108
192
            real_name = _unsquish_command_name(name)
109
 
            r[real_name] = builtins[name]
 
193
            r[real_name] = obj
110
194
    return r
111
 
            
 
195
 
 
196
 
 
197
def _list_bzr_commands(names):
 
198
    """Find commands from bzr's core and plugins.
 
199
    
 
200
    This is not the public interface, just the default hook called by all_command_names.
 
201
    """
 
202
    # to eliminate duplicates
 
203
    names.update(builtin_command_names())
 
204
    names.update(plugin_command_names())
 
205
    return names
 
206
 
 
207
 
 
208
def all_command_names():
 
209
    """Return a set of all command names."""
 
210
    names = set()
 
211
    for hook in Command.hooks['list_commands']:
 
212
        names = hook(names)
 
213
        if names is None:
 
214
            raise AssertionError(
 
215
                'hook %s returned None' % Command.hooks.get_hook_name(hook))
 
216
    return names
 
217
 
112
218
 
113
219
def builtin_command_names():
114
 
    """Return list of builtin command names."""
115
 
    return _builtin_commands().keys()
 
220
    """Return list of builtin command names.
116
221
    
 
222
    Use of all_command_names() is encouraged rather than builtin_command_names
 
223
    and/or plugin_command_names.
 
224
    """
 
225
    return builtin_command_registry.keys()
 
226
 
117
227
 
118
228
def plugin_command_names():
 
229
    """Returns command names from commands registered by plugins."""
119
230
    return plugin_cmds.keys()
120
231
 
121
232
 
122
 
def _get_cmd_dict(plugins_override=True):
123
 
    """Return name->class mapping for all commands."""
124
 
    d = _builtin_commands()
125
 
    if plugins_override:
126
 
        d.update(plugin_cmds)
127
 
    return d
128
 
 
129
 
    
130
 
def get_all_cmds(plugins_override=True):
131
 
    """Return canonical name and class for all registered commands."""
132
 
    for k, v in _get_cmd_dict(plugins_override=plugins_override).iteritems():
133
 
        yield k,v
134
 
 
135
 
 
136
233
def get_cmd_object(cmd_name, plugins_override=True):
137
 
    """Return the canonical name and command class for a command.
 
234
    """Return the command object for a command.
138
235
 
139
236
    plugins_override
140
237
        If true, plugin commands can override builtins.
145
242
        raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
146
243
 
147
244
 
148
 
def _get_cmd_object(cmd_name, plugins_override=True):
149
 
    """Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
 
245
def _get_cmd_object(cmd_name, plugins_override=True, check_missing=True):
 
246
    """Get a command object.
 
247
 
 
248
    :param cmd_name: The name of the command.
 
249
    :param plugins_override: Allow plugins to override builtins.
 
250
    :param check_missing: Look up commands not found in the regular index via
 
251
        the get_missing_command hook.
 
252
    :return: A Command object instance
 
253
    :raises KeyError: If no command is found.
 
254
    """
 
255
    # We want only 'ascii' command names, but the user may have typed
 
256
    # in a Unicode name. In that case, they should just get a
 
257
    # 'command not found' error later.
 
258
    # In the future, we may actually support Unicode command names.
 
259
    cmd = None
 
260
    # Get a command
 
261
    for hook in Command.hooks['get_command']:
 
262
        cmd = hook(cmd, cmd_name)
 
263
        if cmd is not None and not plugins_override and not cmd.plugin_name():
 
264
            # We've found a non-plugin command, don't permit it to be
 
265
            # overridden.
 
266
            break
 
267
    if cmd is None and check_missing:
 
268
        for hook in Command.hooks['get_missing_command']:
 
269
            cmd = hook(cmd_name)
 
270
            if cmd is not None:
 
271
                break
 
272
    if cmd is None:
 
273
        # No command found.
 
274
        raise KeyError
 
275
    # Allow plugins to extend commands
 
276
    for hook in Command.hooks['extend_command']:
 
277
        hook(cmd)
 
278
    return cmd
 
279
 
 
280
 
 
281
def _try_plugin_provider(cmd_name):
 
282
    """Probe for a plugin provider having cmd_name."""
 
283
    try:
 
284
        plugin_metadata, provider = probe_for_provider(cmd_name)
 
285
        raise errors.CommandAvailableInPlugin(cmd_name,
 
286
            plugin_metadata, provider)
 
287
    except errors.NoPluginAvailable:
 
288
        pass
 
289
 
 
290
 
 
291
def probe_for_provider(cmd_name):
 
292
    """Look for a provider for cmd_name.
 
293
 
 
294
    :param cmd_name: The command name.
 
295
    :return: plugin_metadata, provider for getting cmd_name.
 
296
    :raises NoPluginAvailable: When no provider can supply the plugin.
 
297
    """
 
298
    # look for providers that provide this command but aren't installed
 
299
    for provider in command_providers_registry:
 
300
        try:
 
301
            return provider.plugin_for_command(cmd_name), provider
 
302
        except errors.NoPluginAvailable:
 
303
            pass
 
304
    raise errors.NoPluginAvailable(cmd_name)
 
305
 
 
306
 
 
307
def _get_bzr_command(cmd_or_None, cmd_name):
 
308
    """Get a command from bzr's core."""
 
309
    try:
 
310
        cmd_class = builtin_command_registry.get(cmd_name)
 
311
    except KeyError:
 
312
        pass
 
313
    else:
 
314
        return cmd_class()
 
315
    return cmd_or_None
 
316
 
 
317
 
 
318
def _get_external_command(cmd_or_None, cmd_name):
 
319
    """Lookup a command that is a shell script."""
 
320
    # Only do external command lookups when no command is found so far.
 
321
    if cmd_or_None is not None:
 
322
        return cmd_or_None
150
323
    from bzrlib.externalcommand import ExternalCommand
151
 
 
152
 
    # We want only 'ascii' command names, but the user may have typed
153
 
    # in a Unicode name. In that case, they should just get a
154
 
    # 'command not found' error later.
155
 
    # In the future, we may actually support Unicode command names.
156
 
 
157
 
    # first look up this command under the specified name
158
 
    cmds = _get_cmd_dict(plugins_override=plugins_override)
159
 
    try:
160
 
        return cmds[cmd_name]()
161
 
    except KeyError:
162
 
        pass
163
 
 
164
 
    # look for any command which claims this as an alias
165
 
    for real_cmd_name, cmd_class in cmds.iteritems():
166
 
        if cmd_name in cmd_class.aliases:
167
 
            return cmd_class()
168
 
 
169
324
    cmd_obj = ExternalCommand.find_command(cmd_name)
170
325
    if cmd_obj:
171
326
        return cmd_obj
172
327
 
173
 
    # look for plugins that provide this command but aren't installed
174
 
    for provider in command_providers_registry:
175
 
        try:
176
 
            plugin_metadata = provider.plugin_for_command(cmd_name)
177
 
        except errors.NoPluginAvailable:
178
 
            pass
179
 
        else:
180
 
            raise errors.CommandAvailableInPlugin(cmd_name, 
181
 
                                                  plugin_metadata, provider)
182
328
 
183
 
    raise KeyError
 
329
def _get_plugin_command(cmd_or_None, cmd_name):
 
330
    """Get a command from bzr's plugins."""
 
331
    try:
 
332
        return plugin_cmds.get(cmd_name)()
 
333
    except KeyError:
 
334
        pass
 
335
    for key in plugin_cmds.keys():
 
336
        info = plugin_cmds.get_info(key)
 
337
        if cmd_name in info.aliases:
 
338
            return plugin_cmds.get(key)()
 
339
    return cmd_or_None
184
340
 
185
341
 
186
342
class Command(object):
240
396
            sys.stdout is forced to be a binary stream, and line-endings
241
397
            will not mangled.
242
398
 
 
399
    :cvar hooks: An instance of CommandHooks.
243
400
    """
244
401
    aliases = []
245
402
    takes_args = []
247
404
    encoding_type = 'strict'
248
405
 
249
406
    hidden = False
250
 
    
 
407
 
251
408
    def __init__(self):
252
409
        """Construct an instance of this command."""
253
410
        if self.__doc__ == Command.__doc__:
254
411
            warn("No help message set for %r" % self)
255
412
        # List of standard options directly supported
256
413
        self.supported_std_options = []
257
 
 
 
414
        self._setup_run()
 
415
 
 
416
    def add_cleanup(self, cleanup_func, *args, **kwargs):
 
417
        """Register a function to call after self.run returns or raises.
 
418
 
 
419
        Functions will be called in LIFO order.
 
420
        """
 
421
        self._operation.add_cleanup(cleanup_func, *args, **kwargs)
 
422
 
 
423
    def cleanup_now(self):
 
424
        """Execute and empty pending cleanup functions immediately.
 
425
 
 
426
        After cleanup_now all registered cleanups are forgotten.  add_cleanup
 
427
        may be called again after cleanup_now; these cleanups will be called
 
428
        after self.run returns or raises (or when cleanup_now is next called).
 
429
 
 
430
        This is useful for releasing expensive or contentious resources (such
 
431
        as write locks) before doing further work that does not require those
 
432
        resources (such as writing results to self.outf). Note though, that
 
433
        as it releases all resources, this may release locks that the command
 
434
        wants to hold, so use should be done with care.
 
435
        """
 
436
        self._operation.cleanup_now()
 
437
 
 
438
    @deprecated_method(deprecated_in((2, 1, 0)))
258
439
    def _maybe_expand_globs(self, file_list):
259
440
        """Glob expand file_list if the platform does not do that itself.
260
 
        
 
441
 
 
442
        Not used anymore, now that the bzr command-line parser globs on
 
443
        Windows.
 
444
 
261
445
        :return: A possibly empty list of unicode paths.
262
446
 
263
447
        Introduced in bzrlib 0.18.
264
448
        """
265
 
        if not file_list:
266
 
            file_list = []
267
 
        if sys.platform == 'win32':
268
 
            file_list = win32utils.glob_expand(file_list)
269
 
        return list(file_list)
 
449
        return file_list
270
450
 
271
451
    def _usage(self):
272
452
        """Return single-line grammar for this command.
283
463
            elif aname[-1] == '*':
284
464
                aname = '[' + aname[:-1] + '...]'
285
465
            s += aname + ' '
286
 
                
287
 
        assert s[-1] == ' '
288
 
        s = s[:-1]
 
466
        s = s[:-1]      # remove last space
289
467
        return s
290
468
 
291
469
    def get_help_text(self, additional_see_also=None, plain=True,
292
 
                      see_also_as_links=False):
 
470
                      see_also_as_links=False, verbose=True):
293
471
        """Return a text string with help for this command.
294
 
        
 
472
 
295
473
        :param additional_see_also: Additional help topics to be
296
474
            cross-referenced.
297
475
        :param plain: if False, raw help (reStructuredText) is
298
476
            returned instead of plain text.
299
477
        :param see_also_as_links: if True, convert items in 'See also'
300
478
            list to internal links (used by bzr_man rstx generator)
 
479
        :param verbose: if True, display the full help, otherwise
 
480
            leave out the descriptive sections and just display
 
481
            usage help (e.g. Purpose, Usage, Options) with a
 
482
            message explaining how to obtain full help.
301
483
        """
302
484
        doc = self.help()
303
485
        if doc is None:
304
486
            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
305
487
 
306
488
        # Extract the summary (purpose) and sections out from the text
307
 
        purpose,sections = self._get_help_parts(doc)
 
489
        purpose,sections,order = self._get_help_parts(doc)
308
490
 
309
491
        # If a custom usage section was provided, use it
310
492
        if sections.has_key('Usage'):
322
504
        result += '\n'
323
505
 
324
506
        # Add the options
 
507
        #
 
508
        # XXX: optparse implicitly rewraps the help, and not always perfectly,
 
509
        # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
 
510
        # 20090319
325
511
        options = option.get_optparser(self.options()).format_option_help()
 
512
        # XXX: According to the spec, ReST option lists actually don't support 
 
513
        # options like --1.9 so that causes syntax errors (in Sphinx at least).
 
514
        # As that pattern always appears in the commands that break, we trap
 
515
        # on that and then format that block of 'format' options as a literal
 
516
        # block.
 
517
        if not plain and options.find('  --1.9  ') != -1:
 
518
            options = options.replace(' format:\n', ' format::\n\n', 1)
326
519
        if options.startswith('Options:'):
327
520
            result += ':' + options
328
521
        elif options.startswith('options:'):
332
525
            result += options
333
526
        result += '\n'
334
527
 
335
 
        # Add the description, indenting it 2 spaces
336
 
        # to match the indentation of the options
337
 
        if sections.has_key(None):
338
 
            text = sections.pop(None)
339
 
            text = '\n  '.join(text.splitlines())
340
 
            result += ':%s:\n  %s\n\n' % ('Description',text)
 
528
        if verbose:
 
529
            # Add the description, indenting it 2 spaces
 
530
            # to match the indentation of the options
 
531
            if sections.has_key(None):
 
532
                text = sections.pop(None)
 
533
                text = '\n  '.join(text.splitlines())
 
534
                result += ':%s:\n  %s\n\n' % ('Description',text)
341
535
 
342
 
        # Add the custom sections (e.g. Examples). Note that there's no need
343
 
        # to indent these as they must be indented already in the source.
344
 
        if sections:
345
 
            labels = sorted(sections.keys())
346
 
            for label in labels:
347
 
                result += ':%s:\n%s\n\n' % (label,sections[label])
 
536
            # Add the custom sections (e.g. Examples). Note that there's no need
 
537
            # to indent these as they must be indented already in the source.
 
538
            if sections:
 
539
                for label in order:
 
540
                    if sections.has_key(label):
 
541
                        result += ':%s:\n%s\n' % (label,sections[label])
 
542
                result += '\n'
 
543
        else:
 
544
            result += ("See bzr help %s for more details and examples.\n\n"
 
545
                % self.name())
348
546
 
349
547
        # Add the aliases, source (plug-in) and see also links, if any
350
548
        if self.aliases:
363
561
                        # so don't create a real link
364
562
                        see_also_links.append(item)
365
563
                    else:
366
 
                        # Use a reST link for this entry
367
 
                        see_also_links.append("`%s`_" % (item,))
 
564
                        # Use a Sphinx link for this entry
 
565
                        link_text = ":doc:`%s <%s-help>`" % (item, item)
 
566
                        see_also_links.append(link_text)
368
567
                see_also = see_also_links
369
568
            result += ':See also: '
370
569
            result += ', '.join(see_also) + '\n'
371
570
 
372
 
        # If this will be rendered as plan text, convert it
 
571
        # If this will be rendered as plain text, convert it
373
572
        if plain:
374
573
            import bzrlib.help_topics
375
574
            result = bzrlib.help_topics.help_as_plain_text(result)
379
578
    def _get_help_parts(text):
380
579
        """Split help text into a summary and named sections.
381
580
 
382
 
        :return: (summary,sections) where summary is the top line and
 
581
        :return: (summary,sections,order) where summary is the top line and
383
582
            sections is a dictionary of the rest indexed by section name.
 
583
            order is the order the section appear in the text.
384
584
            A section starts with a heading line of the form ":xxx:".
385
585
            Indented text on following lines is the section value.
386
586
            All text found outside a named section is assigned to the
387
587
            default section which is given the key of None.
388
588
        """
389
 
        def save_section(sections, label, section):
 
589
        def save_section(sections, order, label, section):
390
590
            if len(section) > 0:
391
591
                if sections.has_key(label):
392
592
                    sections[label] += '\n' + section
393
593
                else:
 
594
                    order.append(label)
394
595
                    sections[label] = section
395
 
            
 
596
 
396
597
        lines = text.rstrip().splitlines()
397
598
        summary = lines.pop(0)
398
599
        sections = {}
 
600
        order = []
399
601
        label,section = None,''
400
602
        for line in lines:
401
603
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
402
 
                save_section(sections, label, section)
 
604
                save_section(sections, order, label, section)
403
605
                label,section = line[1:-1],''
404
 
            elif label != None and len(line) > 1 and not line[0].isspace():
405
 
                save_section(sections, label, section)
 
606
            elif (label is not None) and len(line) > 1 and not line[0].isspace():
 
607
                save_section(sections, order, label, section)
406
608
                label,section = None,line
407
609
            else:
408
610
                if len(section) > 0:
409
611
                    section += '\n' + line
410
612
                else:
411
613
                    section = line
412
 
        save_section(sections, label, section)
413
 
        return summary, sections
 
614
        save_section(sections, order, label, section)
 
615
        return summary, sections, order
414
616
 
415
617
    def get_help_topic(self):
416
618
        """Return the commands help topic - its name."""
418
620
 
419
621
    def get_see_also(self, additional_terms=None):
420
622
        """Return a list of help topics that are related to this command.
421
 
        
 
623
 
422
624
        The list is derived from the content of the _see_also attribute. Any
423
625
        duplicates are removed and the result is in lexical order.
424
626
        :param additional_terms: Additional help topics to cross-reference.
445
647
 
446
648
    def _setup_outf(self):
447
649
        """Return a file linked to stdout, which has proper encoding."""
448
 
        assert self.encoding_type in ['strict', 'exact', 'replace']
449
 
 
450
 
        # Originally I was using self.stdout, but that looks
451
 
        # *way* too much like sys.stdout
452
 
        if self.encoding_type == 'exact':
453
 
            # force sys.stdout to be binary stream on win32
454
 
            if sys.platform == 'win32':
455
 
                fileno = getattr(sys.stdout, 'fileno', None)
456
 
                if fileno:
457
 
                    import msvcrt
458
 
                    msvcrt.setmode(fileno(), os.O_BINARY)
459
 
            self.outf = sys.stdout
460
 
            return
461
 
 
462
 
        output_encoding = osutils.get_terminal_encoding()
463
 
 
464
 
        self.outf = codecs.getwriter(output_encoding)(sys.stdout,
465
 
                        errors=self.encoding_type)
466
 
        # For whatever reason codecs.getwriter() does not advertise its encoding
467
 
        # it just returns the encoding of the wrapped file, which is completely
468
 
        # bogus. So set the attribute, so we can find the correct encoding later.
469
 
        self.outf.encoding = output_encoding
 
650
        self.outf = ui.ui_factory.make_output_stream(
 
651
            encoding_type=self.encoding_type)
470
652
 
471
653
    def run_argv_aliases(self, argv, alias_argv=None):
472
654
        """Parse the command line and run with extra aliases in alias_argv."""
473
 
        if argv is None:
474
 
            warn("Passing None for [] is deprecated from bzrlib 0.10",
475
 
                 DeprecationWarning, stacklevel=2)
476
 
            argv = []
477
655
        args, opts = parse_args(self, argv, alias_argv)
478
656
 
479
657
        # Process the standard options
480
658
        if 'help' in opts:  # e.g. bzr add --help
481
659
            sys.stdout.write(self.get_help_text())
482
660
            return 0
 
661
        if 'usage' in opts:  # e.g. bzr add --usage
 
662
            sys.stdout.write(self.get_help_text(verbose=False))
 
663
            return 0
483
664
        trace.set_verbosity_level(option._verbosity_level)
484
665
        if 'verbose' in self.supported_std_options:
485
666
            opts['verbose'] = trace.is_verbose()
502
683
        self._setup_outf()
503
684
 
504
685
        return self.run(**all_cmd_args)
505
 
    
 
686
 
 
687
    def _setup_run(self):
 
688
        """Wrap the defined run method on self with a cleanup.
 
689
 
 
690
        This is called by __init__ to make the Command be able to be run
 
691
        by just calling run(), as it could be before cleanups were added.
 
692
 
 
693
        If a different form of cleanups are in use by your Command subclass,
 
694
        you can override this method.
 
695
        """
 
696
        class_run = self.run
 
697
        def run(*args, **kwargs):
 
698
            self._operation = cleanup.OperationWithCleanups(class_run)
 
699
            try:
 
700
                return self._operation.run_simple(*args, **kwargs)
 
701
            finally:
 
702
                del self._operation
 
703
        self.run = run
 
704
 
 
705
    @deprecated_method(deprecated_in((2, 2, 0)))
 
706
    def run_direct(self, *args, **kwargs):
 
707
        """Deprecated thunk from bzrlib 2.1."""
 
708
        return self.run(*args, **kwargs)
 
709
 
506
710
    def run(self):
507
711
        """Actually run the command.
508
712
 
512
716
        Return 0 or None if the command was successful, or a non-zero
513
717
        shell error code if not.  It's OK for this method to allow
514
718
        an exception to raise up.
 
719
 
 
720
        This method is automatically wrapped by Command.__init__ with a 
 
721
        cleanup operation, stored as self._operation. This can be used
 
722
        via self.add_cleanup to perform automatic cleanups at the end of
 
723
        run().
 
724
 
 
725
        The argument for run are assembled by introspection. So for instance,
 
726
        if your command takes an argument files, you would declare::
 
727
 
 
728
            def run(self, files=None):
 
729
                pass
515
730
        """
516
731
        raise NotImplementedError('no implementation of command %r'
517
732
                                  % self.name())
538
753
            return None
539
754
 
540
755
 
 
756
class CommandHooks(Hooks):
 
757
    """Hooks related to Command object creation/enumeration."""
 
758
 
 
759
    def __init__(self):
 
760
        """Create the default hooks.
 
761
 
 
762
        These are all empty initially, because by default nothing should get
 
763
        notified.
 
764
        """
 
765
        Hooks.__init__(self)
 
766
        self.create_hook(HookPoint('extend_command',
 
767
            "Called after creating a command object to allow modifications "
 
768
            "such as adding or removing options, docs etc. Called with the "
 
769
            "new bzrlib.commands.Command object.", (1, 13), None))
 
770
        self.create_hook(HookPoint('get_command',
 
771
            "Called when creating a single command. Called with "
 
772
            "(cmd_or_None, command_name). get_command should either return "
 
773
            "the cmd_or_None parameter, or a replacement Command object that "
 
774
            "should be used for the command. Note that the Command.hooks "
 
775
            "hooks are core infrastructure. Many users will prefer to use "
 
776
            "bzrlib.commands.register_command or plugin_cmds.register_lazy.",
 
777
            (1, 17), None))
 
778
        self.create_hook(HookPoint('get_missing_command',
 
779
            "Called when creating a single command if no command could be "
 
780
            "found. Called with (command_name). get_missing_command should "
 
781
            "either return None, or a Command object to be used for the "
 
782
            "command.", (1, 17), None))
 
783
        self.create_hook(HookPoint('list_commands',
 
784
            "Called when enumerating commands. Called with a set of "
 
785
            "cmd_name strings for all the commands found so far. This set "
 
786
            " is safe to mutate - e.g. to remove a command. "
 
787
            "list_commands should return the updated set of command names.",
 
788
            (1, 17), None))
 
789
 
 
790
Command.hooks = CommandHooks()
 
791
 
 
792
 
541
793
def parse_args(command, argv, alias_argv=None):
542
794
    """Parse command line.
543
 
    
 
795
 
544
796
    Arguments and options are parsed at this level before being passed
545
797
    down to specific command handlers.  This routine knows, from a
546
798
    lookup table, something about the available options, what optargs
595
847
                               % (cmd, argname.upper()))
596
848
            else:
597
849
                argdict[argname] = args.pop(0)
598
 
            
 
850
 
599
851
    if args:
600
852
        raise errors.BzrCommandError("extra argument to command %s: %s"
601
853
                                     % (cmd, args[0]))
609
861
 
610
862
    tracer = trace.Trace(count=1, trace=0)
611
863
    sys.settrace(tracer.globaltrace)
612
 
 
613
 
    ret = the_callable(*args, **kwargs)
614
 
 
615
 
    sys.settrace(None)
616
 
    results = tracer.results()
617
 
    results.write_results(show_missing=1, summary=False,
618
 
                          coverdir=dirname)
 
864
    threading.settrace(tracer.globaltrace)
 
865
 
 
866
    try:
 
867
        return exception_to_return_code(the_callable, *args, **kwargs)
 
868
    finally:
 
869
        sys.settrace(None)
 
870
        results = tracer.results()
 
871
        results.write_results(show_missing=1, summary=False,
 
872
                              coverdir=dirname)
619
873
 
620
874
 
621
875
def apply_profiled(the_callable, *args, **kwargs):
626
880
    try:
627
881
        prof = hotshot.Profile(pfname)
628
882
        try:
629
 
            ret = prof.runcall(the_callable, *args, **kwargs) or 0
 
883
            ret = prof.runcall(exception_to_return_code, the_callable, *args,
 
884
                **kwargs) or 0
630
885
        finally:
631
886
            prof.close()
632
887
        stats = hotshot.stats.load(pfname)
641
896
        os.remove(pfname)
642
897
 
643
898
 
 
899
def exception_to_return_code(the_callable, *args, **kwargs):
 
900
    """UI level helper for profiling and coverage.
 
901
 
 
902
    This transforms exceptions into a return value of 3. As such its only
 
903
    relevant to the UI layer, and should never be called where catching
 
904
    exceptions may be desirable.
 
905
    """
 
906
    try:
 
907
        return the_callable(*args, **kwargs)
 
908
    except (KeyboardInterrupt, Exception), e:
 
909
        # used to handle AssertionError and KeyboardInterrupt
 
910
        # specially here, but hopefully they're handled ok by the logger now
 
911
        exc_info = sys.exc_info()
 
912
        exitcode = trace.report_exception(exc_info, sys.stderr)
 
913
        if os.environ.get('BZR_PDB'):
 
914
            print '**** entering debugger'
 
915
            tb = exc_info[2]
 
916
            import pdb
 
917
            if sys.version_info[:2] < (2, 6):
 
918
                # XXX: we want to do
 
919
                #    pdb.post_mortem(tb)
 
920
                # but because pdb.post_mortem gives bad results for tracebacks
 
921
                # from inside generators, we do it manually.
 
922
                # (http://bugs.python.org/issue4150, fixed in Python 2.6)
 
923
 
 
924
                # Setup pdb on the traceback
 
925
                p = pdb.Pdb()
 
926
                p.reset()
 
927
                p.setup(tb.tb_frame, tb)
 
928
                # Point the debugger at the deepest frame of the stack
 
929
                p.curindex = len(p.stack) - 1
 
930
                p.curframe = p.stack[p.curindex][0]
 
931
                # Start the pdb prompt.
 
932
                p.print_stack_entry(p.stack[p.curindex])
 
933
                p.execRcLines()
 
934
                p.cmdloop()
 
935
            else:
 
936
                pdb.post_mortem(tb)
 
937
        return exitcode
 
938
 
 
939
 
644
940
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
645
941
    from bzrlib.lsprof import profile
646
 
    ret, stats = profile(the_callable, *args, **kwargs)
 
942
    ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
647
943
    stats.sort()
648
944
    if filename is None:
649
945
        stats.pprint()
653
949
    return ret
654
950
 
655
951
 
 
952
@deprecated_function(deprecated_in((2, 2, 0)))
656
953
def shlex_split_unicode(unsplit):
657
 
    import shlex
658
 
    return [u.decode('utf-8') for u in shlex.split(unsplit.encode('utf-8'))]
 
954
    return cmdline.split(unsplit)
659
955
 
660
956
 
661
957
def get_alias(cmd, config=None):
673
969
        config = bzrlib.config.GlobalConfig()
674
970
    alias = config.get_alias(cmd)
675
971
    if (alias):
676
 
        return shlex_split_unicode(alias)
 
972
        return cmdline.split(alias)
677
973
    return None
678
974
 
679
975
 
680
 
def run_bzr(argv):
 
976
def run_bzr(argv, load_plugins=load_plugins, disable_plugins=disable_plugins):
681
977
    """Execute a command.
682
978
 
683
 
    This is similar to main(), but without all the trappings for
684
 
    logging and error handling.  
685
 
    
686
 
    argv
687
 
       The command-line arguments, without the program name from argv[0]
688
 
       These should already be decoded. All library/test code calling
689
 
       run_bzr should be passing valid strings (don't need decoding).
690
 
    
691
 
    Returns a command status or raises an exception.
 
979
    :param argv: The command-line arguments, without the program name from
 
980
        argv[0] These should already be decoded. All library/test code calling
 
981
        run_bzr should be passing valid strings (don't need decoding).
 
982
    :param load_plugins: What function to call when triggering plugin loading.
 
983
        This function should take no arguments and cause all plugins to be
 
984
        loaded.
 
985
    :param disable_plugins: What function to call when disabling plugin
 
986
        loading. This function should take no arguments and cause all plugin
 
987
        loading to be prohibited (so that code paths in your application that
 
988
        know about some plugins possibly being present will fail to import
 
989
        those plugins even if they are installed.)
 
990
    :return: Returns a command exit code or raises an exception.
692
991
 
693
992
    Special master options: these must come before the command because
694
993
    they control how the command is interpreted.
711
1010
 
712
1011
    --coverage
713
1012
        Generate line coverage report in the specified directory.
 
1013
 
 
1014
    --concurrency
 
1015
        Specify the number of processes that can be run concurrently (selftest).
714
1016
    """
 
1017
    trace.mutter("bazaar version: " + bzrlib.__version__)
715
1018
    argv = list(argv)
716
1019
    trace.mutter("bzr arguments: %r", argv)
717
1020
 
741
1044
            opt_no_aliases = True
742
1045
        elif a == '--builtin':
743
1046
            opt_builtin = True
 
1047
        elif a == '--concurrency':
 
1048
            os.environ['BZR_CONCURRENCY'] = argv[i + 1]
 
1049
            i += 1
744
1050
        elif a == '--coverage':
745
1051
            opt_coverage_dir = argv[i + 1]
746
1052
            i += 1
750
1056
            argv_copy.append(a)
751
1057
        i += 1
752
1058
 
 
1059
    debug.set_debug_flags_from_config()
 
1060
 
 
1061
    if not opt_no_plugins:
 
1062
        load_plugins()
 
1063
    else:
 
1064
        disable_plugins()
 
1065
 
753
1066
    argv = argv_copy
754
1067
    if (not argv):
755
 
        from bzrlib.builtins import cmd_help
756
 
        cmd_help().run_argv_aliases([])
 
1068
        get_cmd_object('help').run_argv_aliases([])
757
1069
        return 0
758
1070
 
759
1071
    if argv[0] == '--version':
760
 
        from bzrlib.builtins import cmd_version
761
 
        cmd_version().run_argv_aliases([])
 
1072
        get_cmd_object('version').run_argv_aliases([])
762
1073
        return 0
763
 
        
764
 
    if not opt_no_plugins:
765
 
        from bzrlib.plugin import load_plugins
766
 
        load_plugins()
767
 
    else:
768
 
        from bzrlib.plugin import disable_plugins
769
 
        disable_plugins()
770
1074
 
771
1075
    alias_argv = None
772
1076
 
773
1077
    if not opt_no_aliases:
774
1078
        alias_argv = get_alias(argv[0])
775
1079
        if alias_argv:
776
 
            alias_argv = [a.decode(bzrlib.user_encoding) for a in alias_argv]
 
1080
            user_encoding = osutils.get_user_encoding()
 
1081
            alias_argv = [a.decode(user_encoding) for a in alias_argv]
777
1082
            argv[0] = alias_argv.pop(0)
778
1083
 
779
1084
    cmd = argv.pop(0)
786
1091
    run_argv = [argv, alias_argv]
787
1092
 
788
1093
    try:
 
1094
        # We can be called recursively (tests for example), but we don't want
 
1095
        # the verbosity level to propagate.
 
1096
        saved_verbosity_level = option._verbosity_level
 
1097
        option._verbosity_level = 0
789
1098
        if opt_lsprof:
790
1099
            if opt_coverage_dir:
791
1100
                trace.warning(
802
1111
            ret = run(*run_argv)
803
1112
        return ret or 0
804
1113
    finally:
805
 
        # reset, in case we may do other commands later within the same process
806
 
        option._verbosity_level = 0
 
1114
        # reset, in case we may do other commands later within the same
 
1115
        # process. Commands that want to execute sub-commands must propagate
 
1116
        # --verbose in their own way.
 
1117
        if 'memory' in debug.debug_flags:
 
1118
            trace.debug_memory('Process status after command:', short=False)
 
1119
        option._verbosity_level = saved_verbosity_level
 
1120
 
807
1121
 
808
1122
def display_command(func):
809
1123
    """Decorator that suppresses pipe/interrupt errors."""
825
1139
    return ignore_pipe
826
1140
 
827
1141
 
828
 
def main(argv):
829
 
    import bzrlib.ui
830
 
    from bzrlib.ui.text import TextUIFactory
831
 
    bzrlib.ui.ui_factory = TextUIFactory()
832
 
    try:
833
 
        argv = [a.decode(bzrlib.user_encoding) for a in argv[1:]]
834
 
    except UnicodeDecodeError:
835
 
        raise errors.BzrError(("Parameter '%r' is unsupported by the current "
836
 
                                                            "encoding." % a))
 
1142
def install_bzr_command_hooks():
 
1143
    """Install the hooks to supply bzr's own commands."""
 
1144
    if _list_bzr_commands in Command.hooks["list_commands"]:
 
1145
        return
 
1146
    Command.hooks.install_named_hook("list_commands", _list_bzr_commands,
 
1147
        "bzr commands")
 
1148
    Command.hooks.install_named_hook("get_command", _get_bzr_command,
 
1149
        "bzr commands")
 
1150
    Command.hooks.install_named_hook("get_command", _get_plugin_command,
 
1151
        "bzr plugin commands")
 
1152
    Command.hooks.install_named_hook("get_command", _get_external_command,
 
1153
        "bzr external command lookup")
 
1154
    Command.hooks.install_named_hook("get_missing_command", _try_plugin_provider,
 
1155
        "bzr plugin-provider-db check")
 
1156
 
 
1157
 
 
1158
 
 
1159
def _specified_or_unicode_argv(argv):
 
1160
    # For internal or testing use, argv can be passed.  Otherwise, get it from
 
1161
    # the process arguments in a unicode-safe way.
 
1162
    if argv is None:
 
1163
        return osutils.get_unicode_argv()
 
1164
    else:
 
1165
        new_argv = []
 
1166
        try:
 
1167
            # ensure all arguments are unicode strings
 
1168
            for a in argv[1:]:
 
1169
                if isinstance(a, unicode):
 
1170
                    new_argv.append(a)
 
1171
                else:
 
1172
                    new_argv.append(a.decode('ascii'))
 
1173
        except UnicodeDecodeError:
 
1174
            raise errors.BzrError("argv should be list of unicode strings.")
 
1175
        return new_argv
 
1176
 
 
1177
 
 
1178
def main(argv=None):
 
1179
    """Main entry point of command-line interface.
 
1180
 
 
1181
    Typically `bzrlib.initialize` should be called first.
 
1182
 
 
1183
    :param argv: list of unicode command-line arguments similar to sys.argv.
 
1184
        argv[0] is script name usually, it will be ignored.
 
1185
        Don't pass here sys.argv because this list contains plain strings
 
1186
        and not unicode; pass None instead.
 
1187
 
 
1188
    :return: exit code of bzr command.
 
1189
    """
 
1190
    argv = _specified_or_unicode_argv(argv)
 
1191
    _register_builtin_commands()
837
1192
    ret = run_bzr_catch_errors(argv)
 
1193
    bzrlib.ui.ui_factory.log_transport_activity(
 
1194
        display=('bytes' in debug.debug_flags))
838
1195
    trace.mutter("return code %d", ret)
839
1196
    return ret
840
1197
 
841
1198
 
842
1199
def run_bzr_catch_errors(argv):
843
 
    # Note: The except clause logic below should be kept in sync with the
844
 
    # profile() routine in lsprof.py.
845
 
    try:
846
 
        return run_bzr(argv)
847
 
    except (KeyboardInterrupt, Exception), e:
848
 
        # used to handle AssertionError and KeyboardInterrupt
849
 
        # specially here, but hopefully they're handled ok by the logger now
850
 
        exitcode = trace.report_exception(sys.exc_info(), sys.stderr)
851
 
        if os.environ.get('BZR_PDB'):
852
 
            print '**** entering debugger'
853
 
            import pdb
854
 
            pdb.post_mortem(sys.exc_traceback)
855
 
        return exitcode
 
1200
    """Run a bzr command with parameters as described by argv.
 
1201
 
 
1202
    This function assumed that that UI layer is setup, that symbol deprecations
 
1203
    are already applied, and that unicode decoding has already been performed on argv.
 
1204
    """
 
1205
    # done here so that they're covered for every test run
 
1206
    install_bzr_command_hooks()
 
1207
    return exception_to_return_code(run_bzr, argv)
856
1208
 
857
1209
 
858
1210
def run_bzr_catch_user_errors(argv):
861
1213
    This is used for the test suite, and might be useful for other programs
862
1214
    that want to wrap the commandline interface.
863
1215
    """
 
1216
    # done here so that they're covered for every test run
 
1217
    install_bzr_command_hooks()
864
1218
    try:
865
1219
        return run_bzr(argv)
866
1220
    except Exception, e:
888
1242
        if topic and topic.startswith(self.prefix):
889
1243
            topic = topic[len(self.prefix):]
890
1244
        try:
891
 
            cmd = _get_cmd_object(topic)
 
1245
            cmd = _get_cmd_object(topic, check_missing=False)
892
1246
        except KeyError:
893
1247
            return []
894
1248
        else:
900
1254
 
901
1255
    def plugin_for_command(self, cmd_name):
902
1256
        '''Takes a command and returns the information for that plugin
903
 
        
904
 
        :return: A dictionary with all the available information 
 
1257
 
 
1258
        :return: A dictionary with all the available information
905
1259
        for the requested plugin
906
1260
        '''
907
1261
        raise NotImplementedError
915
1269
            yield provider
916
1270
 
917
1271
command_providers_registry = ProvidersRegistry()
918
 
 
919
 
 
920
 
if __name__ == '__main__':
921
 
    sys.exit(main(sys.argv))