~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/commands.py

  • Committer: Andrew Bennetts
  • Date: 2010-10-08 08:15:14 UTC
  • mto: This revision was merged to the branch mainline in revision 5498.
  • Revision ID: andrew.bennetts@canonical.com-20101008081514-dviqzrdfwyzsqbz2
Split NEWS into per-release doc/en/release-notes/bzr-*.txt

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2004, 2005 by Canonical Ltd
2
 
 
 
1
# Copyright (C) 2005-2010 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
 
# 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.
20
 
 
21
 
# TODO: Help messages for options.
 
15
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
16
 
22
17
 
23
18
# TODO: Define arguments by objects, rather than just using names.
24
19
# Those objects can specify the expected type of the argument, which
25
 
# would help with validation and shell completion.
26
 
 
27
 
# TODO: "--profile=cum", to change sort order.  Is there any value in leaving
28
 
# the profile output behind so it can be interactively examined?
29
 
 
 
20
# would help with validation and shell completion.  They could also provide
 
21
# help/explanation for that argument in a structured way.
 
22
 
 
23
# TODO: Specific "examples" property on commands for consistent formatting.
 
24
 
 
25
import os
30
26
import sys
31
 
import os
 
27
 
 
28
from bzrlib.lazy_import import lazy_import
 
29
lazy_import(globals(), """
 
30
import codecs
 
31
import errno
 
32
import threading
32
33
from warnings import warn
33
 
from inspect import getdoc
34
34
 
35
35
import bzrlib
36
 
import bzrlib.trace
37
 
from bzrlib.trace import mutter, note, log_error, warning
38
 
from bzrlib.errors import BzrError, BzrCheckError, BzrCommandError, NotBranchError
39
 
from bzrlib.revisionspec import RevisionSpec
40
 
from bzrlib import BZRDIR
 
36
from bzrlib import (
 
37
    cleanup,
 
38
    cmdline,
 
39
    debug,
 
40
    errors,
 
41
    option,
 
42
    osutils,
 
43
    trace,
 
44
    ui,
 
45
    win32utils,
 
46
    )
 
47
""")
 
48
 
 
49
from bzrlib.hooks import HookPoint, Hooks
 
50
# Compatibility - Option used to be in commands.
41
51
from bzrlib.option import Option
42
 
 
43
 
plugin_cmds = {}
44
 
 
45
 
 
46
 
def register_command(cmd):
47
 
    "Utility function to help register a command"
 
52
from bzrlib.plugin import disable_plugins, load_plugins
 
53
from bzrlib import registry
 
54
from bzrlib.symbol_versioning import (
 
55
    deprecated_function,
 
56
    deprecated_in,
 
57
    deprecated_method,
 
58
    )
 
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
 
149
 
 
150
 
 
151
def register_command(cmd, decorate=False):
 
152
    """Register a plugin command.
 
153
 
 
154
    Should generally be avoided in favor of lazy registration. 
 
155
    """
48
156
    global plugin_cmds
49
 
    k = cmd.__name__
50
 
    if k.startswith("cmd_"):
51
 
        k_unsquished = _unsquish_command_name(k)
52
 
    else:
53
 
        k_unsquished = k
54
 
    if not plugin_cmds.has_key(k_unsquished):
55
 
        plugin_cmds[k_unsquished] = cmd
56
 
        mutter('registered plugin command %s', k_unsquished)      
57
 
    else:
58
 
        log_error('Two plugins defined the same command: %r' % k)
59
 
        log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
 
157
    return plugin_cmds.register(cmd, decorate)
60
158
 
61
159
 
62
160
def _squish_command_name(cmd):
64
162
 
65
163
 
66
164
def _unsquish_command_name(cmd):
67
 
    assert cmd.startswith("cmd_")
68
165
    return cmd[4:].replace('_','-')
69
166
 
70
167
 
 
168
@deprecated_function(deprecated_in((2, 2, 0)))
71
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
72
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):
73
189
    r = {}
74
 
    builtins = bzrlib.builtins.__dict__
75
 
    for name in builtins:
 
190
    for name, obj in module.__dict__.iteritems():
76
191
        if name.startswith("cmd_"):
77
 
            real_name = _unsquish_command_name(name)        
78
 
            r[real_name] = builtins[name]
 
192
            real_name = _unsquish_command_name(name)
 
193
            r[real_name] = obj
79
194
    return r
80
195
 
81
 
            
 
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
 
82
218
 
83
219
def builtin_command_names():
84
 
    """Return list of builtin command names."""
85
 
    return _builtin_commands().keys()
 
220
    """Return list of builtin command names.
86
221
    
 
222
    Use of all_command_names() is encouraged rather than builtin_command_names
 
223
    and/or plugin_command_names.
 
224
    """
 
225
    _register_builtin_commands()
 
226
    return builtin_command_registry.keys()
 
227
 
87
228
 
88
229
def plugin_command_names():
 
230
    """Returns command names from commands registered by plugins."""
89
231
    return plugin_cmds.keys()
90
232
 
91
233
 
92
 
def _get_cmd_dict(plugins_override=True):
93
 
    """Return name->class mapping for all commands."""
94
 
    d = _builtin_commands()
95
 
    if plugins_override:
96
 
        d.update(plugin_cmds)
97
 
    return d
98
 
 
99
 
    
100
 
def get_all_cmds(plugins_override=True):
101
 
    """Return canonical name and class for all registered commands."""
102
 
    for k, v in _get_cmd_dict(plugins_override=plugins_override).iteritems():
103
 
        yield k,v
104
 
 
105
 
 
106
234
def get_cmd_object(cmd_name, plugins_override=True):
107
 
    """Return the canonical name and command class for a command.
 
235
    """Return the command object for a command.
108
236
 
109
237
    plugins_override
110
238
        If true, plugin commands can override builtins.
111
239
    """
 
240
    try:
 
241
        return _get_cmd_object(cmd_name, plugins_override)
 
242
    except KeyError:
 
243
        raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
 
244
 
 
245
 
 
246
def _get_cmd_object(cmd_name, plugins_override=True, check_missing=True):
 
247
    """Get a command object.
 
248
 
 
249
    :param cmd_name: The name of the command.
 
250
    :param plugins_override: Allow plugins to override builtins.
 
251
    :param check_missing: Look up commands not found in the regular index via
 
252
        the get_missing_command hook.
 
253
    :return: A Command object instance
 
254
    :raises KeyError: If no command is found.
 
255
    """
 
256
    # We want only 'ascii' command names, but the user may have typed
 
257
    # in a Unicode name. In that case, they should just get a
 
258
    # 'command not found' error later.
 
259
    # In the future, we may actually support Unicode command names.
 
260
    cmd = None
 
261
    # Get a command
 
262
    for hook in Command.hooks['get_command']:
 
263
        cmd = hook(cmd, cmd_name)
 
264
        if cmd is not None and not plugins_override and not cmd.plugin_name():
 
265
            # We've found a non-plugin command, don't permit it to be
 
266
            # overridden.
 
267
            break
 
268
    if cmd is None and check_missing:
 
269
        for hook in Command.hooks['get_missing_command']:
 
270
            cmd = hook(cmd_name)
 
271
            if cmd is not None:
 
272
                break
 
273
    if cmd is None:
 
274
        # No command found.
 
275
        raise KeyError
 
276
    # Allow plugins to extend commands
 
277
    for hook in Command.hooks['extend_command']:
 
278
        hook(cmd)
 
279
    return cmd
 
280
 
 
281
 
 
282
def _try_plugin_provider(cmd_name):
 
283
    """Probe for a plugin provider having cmd_name."""
 
284
    try:
 
285
        plugin_metadata, provider = probe_for_provider(cmd_name)
 
286
        raise errors.CommandAvailableInPlugin(cmd_name,
 
287
            plugin_metadata, provider)
 
288
    except errors.NoPluginAvailable:
 
289
        pass
 
290
 
 
291
 
 
292
def probe_for_provider(cmd_name):
 
293
    """Look for a provider for cmd_name.
 
294
 
 
295
    :param cmd_name: The command name.
 
296
    :return: plugin_metadata, provider for getting cmd_name.
 
297
    :raises NoPluginAvailable: When no provider can supply the plugin.
 
298
    """
 
299
    # look for providers that provide this command but aren't installed
 
300
    for provider in command_providers_registry:
 
301
        try:
 
302
            return provider.plugin_for_command(cmd_name), provider
 
303
        except errors.NoPluginAvailable:
 
304
            pass
 
305
    raise errors.NoPluginAvailable(cmd_name)
 
306
 
 
307
 
 
308
def _get_bzr_command(cmd_or_None, cmd_name):
 
309
    """Get a command from bzr's core."""
 
310
    try:
 
311
        cmd_class = builtin_command_registry.get(cmd_name)
 
312
    except KeyError:
 
313
        pass
 
314
    else:
 
315
        return cmd_class()
 
316
    return cmd_or_None
 
317
 
 
318
 
 
319
def _get_external_command(cmd_or_None, cmd_name):
 
320
    """Lookup a command that is a shell script."""
 
321
    # Only do external command lookups when no command is found so far.
 
322
    if cmd_or_None is not None:
 
323
        return cmd_or_None
112
324
    from bzrlib.externalcommand import ExternalCommand
113
 
 
114
 
    cmd_name = str(cmd_name)            # not unicode
115
 
 
116
 
    # first look up this command under the specified name
117
 
    cmds = _get_cmd_dict(plugins_override=plugins_override)
118
 
    try:
119
 
        return cmds[cmd_name]()
120
 
    except KeyError:
121
 
        pass
122
 
 
123
 
    # look for any command which claims this as an alias
124
 
    for real_cmd_name, cmd_class in cmds.iteritems():
125
 
        if cmd_name in cmd_class.aliases:
126
 
            return cmd_class()
127
 
 
128
325
    cmd_obj = ExternalCommand.find_command(cmd_name)
129
326
    if cmd_obj:
130
327
        return cmd_obj
131
328
 
132
 
    raise BzrCommandError("unknown command %r" % cmd_name)
 
329
 
 
330
def _get_plugin_command(cmd_or_None, cmd_name):
 
331
    """Get a command from bzr's plugins."""
 
332
    try:
 
333
        return plugin_cmds.get(cmd_name)()
 
334
    except KeyError:
 
335
        pass
 
336
    for key in plugin_cmds.keys():
 
337
        info = plugin_cmds.get_info(key)
 
338
        if cmd_name in info.aliases:
 
339
            return plugin_cmds.get(key)()
 
340
    return cmd_or_None
133
341
 
134
342
 
135
343
class Command(object):
157
365
        List of argument forms, marked with whether they are optional,
158
366
        repeated, etc.
159
367
 
 
368
                Examples:
 
369
 
 
370
                ['to_location', 'from_branch?', 'file*']
 
371
 
 
372
                'to_location' is required
 
373
                'from_branch' is optional
 
374
                'file' can be specified 0 or more times
 
375
 
160
376
    takes_options
161
377
        List of options that may be given for this command.  These can
162
378
        be either strings, referring to globally-defined options,
165
381
    hidden
166
382
        If true, this command isn't advertised.  This is typically
167
383
        for commands intended for expert users.
 
384
 
 
385
    encoding_type
 
386
        Command objects will get a 'outf' attribute, which has been
 
387
        setup to properly handle encoding of unicode strings.
 
388
        encoding_type determines what will happen when characters cannot
 
389
        be encoded
 
390
            strict - abort if we cannot decode
 
391
            replace - put in a bogus character (typically '?')
 
392
            exact - do not encode sys.stdout
 
393
 
 
394
            NOTE: by default on Windows, sys.stdout is opened as a text
 
395
            stream, therefore LF line-endings are converted to CRLF.
 
396
            When a command uses encoding_type = 'exact', then
 
397
            sys.stdout is forced to be a binary stream, and line-endings
 
398
            will not mangled.
 
399
 
 
400
    :cvar hooks: An instance of CommandHooks.
 
401
    :ivar __doc__: The help shown by 'bzr help command' for this command.
 
402
        This is set by assigning explicitly to __doc__ so that -OO can
 
403
        be used::
 
404
 
 
405
        class Foo(Command):
 
406
            __doc__ = "My help goes here"
168
407
    """
169
408
    aliases = []
170
409
    takes_args = []
171
410
    takes_options = []
 
411
    encoding_type = 'strict'
172
412
 
173
413
    hidden = False
174
 
    
 
414
 
175
415
    def __init__(self):
176
416
        """Construct an instance of this command."""
177
 
        if self.__doc__ == Command.__doc__:
178
 
            warn("No help message set for %r" % self)
 
417
        # List of standard options directly supported
 
418
        self.supported_std_options = []
 
419
        self._setup_run()
 
420
 
 
421
    def add_cleanup(self, cleanup_func, *args, **kwargs):
 
422
        """Register a function to call after self.run returns or raises.
 
423
 
 
424
        Functions will be called in LIFO order.
 
425
        """
 
426
        self._operation.add_cleanup(cleanup_func, *args, **kwargs)
 
427
 
 
428
    def cleanup_now(self):
 
429
        """Execute and empty pending cleanup functions immediately.
 
430
 
 
431
        After cleanup_now all registered cleanups are forgotten.  add_cleanup
 
432
        may be called again after cleanup_now; these cleanups will be called
 
433
        after self.run returns or raises (or when cleanup_now is next called).
 
434
 
 
435
        This is useful for releasing expensive or contentious resources (such
 
436
        as write locks) before doing further work that does not require those
 
437
        resources (such as writing results to self.outf). Note though, that
 
438
        as it releases all resources, this may release locks that the command
 
439
        wants to hold, so use should be done with care.
 
440
        """
 
441
        self._operation.cleanup_now()
 
442
 
 
443
    @deprecated_method(deprecated_in((2, 1, 0)))
 
444
    def _maybe_expand_globs(self, file_list):
 
445
        """Glob expand file_list if the platform does not do that itself.
 
446
 
 
447
        Not used anymore, now that the bzr command-line parser globs on
 
448
        Windows.
 
449
 
 
450
        :return: A possibly empty list of unicode paths.
 
451
 
 
452
        Introduced in bzrlib 0.18.
 
453
        """
 
454
        return file_list
 
455
 
 
456
    def _usage(self):
 
457
        """Return single-line grammar for this command.
 
458
 
 
459
        Only describes arguments, not options.
 
460
        """
 
461
        s = 'bzr ' + self.name() + ' '
 
462
        for aname in self.takes_args:
 
463
            aname = aname.upper()
 
464
            if aname[-1] in ['$', '+']:
 
465
                aname = aname[:-1] + '...'
 
466
            elif aname[-1] == '?':
 
467
                aname = '[' + aname[:-1] + ']'
 
468
            elif aname[-1] == '*':
 
469
                aname = '[' + aname[:-1] + '...]'
 
470
            s += aname + ' '
 
471
        s = s[:-1]      # remove last space
 
472
        return s
 
473
 
 
474
    def get_help_text(self, additional_see_also=None, plain=True,
 
475
                      see_also_as_links=False, verbose=True):
 
476
        """Return a text string with help for this command.
 
477
 
 
478
        :param additional_see_also: Additional help topics to be
 
479
            cross-referenced.
 
480
        :param plain: if False, raw help (reStructuredText) is
 
481
            returned instead of plain text.
 
482
        :param see_also_as_links: if True, convert items in 'See also'
 
483
            list to internal links (used by bzr_man rstx generator)
 
484
        :param verbose: if True, display the full help, otherwise
 
485
            leave out the descriptive sections and just display
 
486
            usage help (e.g. Purpose, Usage, Options) with a
 
487
            message explaining how to obtain full help.
 
488
        """
 
489
        doc = self.help()
 
490
        if not doc:
 
491
            doc = "No help for this command."
 
492
 
 
493
        # Extract the summary (purpose) and sections out from the text
 
494
        purpose,sections,order = self._get_help_parts(doc)
 
495
 
 
496
        # If a custom usage section was provided, use it
 
497
        if sections.has_key('Usage'):
 
498
            usage = sections.pop('Usage')
 
499
        else:
 
500
            usage = self._usage()
 
501
 
 
502
        # The header is the purpose and usage
 
503
        result = ""
 
504
        result += ':Purpose: %s\n' % purpose
 
505
        if usage.find('\n') >= 0:
 
506
            result += ':Usage:\n%s\n' % usage
 
507
        else:
 
508
            result += ':Usage:   %s\n' % usage
 
509
        result += '\n'
 
510
 
 
511
        # Add the options
 
512
        #
 
513
        # XXX: optparse implicitly rewraps the help, and not always perfectly,
 
514
        # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
 
515
        # 20090319
 
516
        options = option.get_optparser(self.options()).format_option_help()
 
517
        # XXX: According to the spec, ReST option lists actually don't support 
 
518
        # options like --1.9 so that causes syntax errors (in Sphinx at least).
 
519
        # As that pattern always appears in the commands that break, we trap
 
520
        # on that and then format that block of 'format' options as a literal
 
521
        # block.
 
522
        if not plain and options.find('  --1.9  ') != -1:
 
523
            options = options.replace(' format:\n', ' format::\n\n', 1)
 
524
        if options.startswith('Options:'):
 
525
            result += ':' + options
 
526
        elif options.startswith('options:'):
 
527
            # Python 2.4 version of optparse
 
528
            result += ':Options:' + options[len('options:'):]
 
529
        else:
 
530
            result += options
 
531
        result += '\n'
 
532
 
 
533
        if verbose:
 
534
            # Add the description, indenting it 2 spaces
 
535
            # to match the indentation of the options
 
536
            if sections.has_key(None):
 
537
                text = sections.pop(None)
 
538
                text = '\n  '.join(text.splitlines())
 
539
                result += ':%s:\n  %s\n\n' % ('Description',text)
 
540
 
 
541
            # Add the custom sections (e.g. Examples). Note that there's no need
 
542
            # to indent these as they must be indented already in the source.
 
543
            if sections:
 
544
                for label in order:
 
545
                    if sections.has_key(label):
 
546
                        result += ':%s:\n%s\n' % (label,sections[label])
 
547
                result += '\n'
 
548
        else:
 
549
            result += ("See bzr help %s for more details and examples.\n\n"
 
550
                % self.name())
 
551
 
 
552
        # Add the aliases, source (plug-in) and see also links, if any
 
553
        if self.aliases:
 
554
            result += ':Aliases:  '
 
555
            result += ', '.join(self.aliases) + '\n'
 
556
        plugin_name = self.plugin_name()
 
557
        if plugin_name is not None:
 
558
            result += ':From:     plugin "%s"\n' % plugin_name
 
559
        see_also = self.get_see_also(additional_see_also)
 
560
        if see_also:
 
561
            if not plain and see_also_as_links:
 
562
                see_also_links = []
 
563
                for item in see_also:
 
564
                    if item == 'topics':
 
565
                        # topics doesn't have an independent section
 
566
                        # so don't create a real link
 
567
                        see_also_links.append(item)
 
568
                    else:
 
569
                        # Use a Sphinx link for this entry
 
570
                        link_text = ":doc:`%s <%s-help>`" % (item, item)
 
571
                        see_also_links.append(link_text)
 
572
                see_also = see_also_links
 
573
            result += ':See also: '
 
574
            result += ', '.join(see_also) + '\n'
 
575
 
 
576
        # If this will be rendered as plain text, convert it
 
577
        if plain:
 
578
            import bzrlib.help_topics
 
579
            result = bzrlib.help_topics.help_as_plain_text(result)
 
580
        return result
 
581
 
 
582
    @staticmethod
 
583
    def _get_help_parts(text):
 
584
        """Split help text into a summary and named sections.
 
585
 
 
586
        :return: (summary,sections,order) where summary is the top line and
 
587
            sections is a dictionary of the rest indexed by section name.
 
588
            order is the order the section appear in the text.
 
589
            A section starts with a heading line of the form ":xxx:".
 
590
            Indented text on following lines is the section value.
 
591
            All text found outside a named section is assigned to the
 
592
            default section which is given the key of None.
 
593
        """
 
594
        def save_section(sections, order, label, section):
 
595
            if len(section) > 0:
 
596
                if sections.has_key(label):
 
597
                    sections[label] += '\n' + section
 
598
                else:
 
599
                    order.append(label)
 
600
                    sections[label] = section
 
601
 
 
602
        lines = text.rstrip().splitlines()
 
603
        summary = lines.pop(0)
 
604
        sections = {}
 
605
        order = []
 
606
        label,section = None,''
 
607
        for line in lines:
 
608
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
 
609
                save_section(sections, order, label, section)
 
610
                label,section = line[1:-1],''
 
611
            elif (label is not None) and len(line) > 1 and not line[0].isspace():
 
612
                save_section(sections, order, label, section)
 
613
                label,section = None,line
 
614
            else:
 
615
                if len(section) > 0:
 
616
                    section += '\n' + line
 
617
                else:
 
618
                    section = line
 
619
        save_section(sections, order, label, section)
 
620
        return summary, sections, order
 
621
 
 
622
    def get_help_topic(self):
 
623
        """Return the commands help topic - its name."""
 
624
        return self.name()
 
625
 
 
626
    def get_see_also(self, additional_terms=None):
 
627
        """Return a list of help topics that are related to this command.
 
628
 
 
629
        The list is derived from the content of the _see_also attribute. Any
 
630
        duplicates are removed and the result is in lexical order.
 
631
        :param additional_terms: Additional help topics to cross-reference.
 
632
        :return: A list of help topics.
 
633
        """
 
634
        see_also = set(getattr(self, '_see_also', []))
 
635
        if additional_terms:
 
636
            see_also.update(additional_terms)
 
637
        return sorted(see_also)
179
638
 
180
639
    def options(self):
181
640
        """Return dict of valid options for this command.
182
641
 
183
642
        Maps from long option name to option object."""
184
 
        r = dict()
185
 
        r['help'] = Option.OPTIONS['help']
 
643
        r = Option.STD_OPTIONS.copy()
 
644
        std_names = r.keys()
186
645
        for o in self.takes_options:
187
 
            if not isinstance(o, Option):
188
 
                o = Option.OPTIONS[o]
 
646
            if isinstance(o, basestring):
 
647
                o = option.Option.OPTIONS[o]
189
648
            r[o.name] = o
 
649
            if o.name in std_names:
 
650
                self.supported_std_options.append(o.name)
190
651
        return r
191
652
 
192
 
    def run_argv(self, argv):
193
 
        """Parse command line and run."""
194
 
        args, opts = parse_args(self, argv)
 
653
    def _setup_outf(self):
 
654
        """Return a file linked to stdout, which has proper encoding."""
 
655
        self.outf = ui.ui_factory.make_output_stream(
 
656
            encoding_type=self.encoding_type)
 
657
 
 
658
    def run_argv_aliases(self, argv, alias_argv=None):
 
659
        """Parse the command line and run with extra aliases in alias_argv."""
 
660
        args, opts = parse_args(self, argv, alias_argv)
 
661
 
 
662
        # Process the standard options
195
663
        if 'help' in opts:  # e.g. bzr add --help
196
 
            from bzrlib.help import help_on_command
197
 
            help_on_command(self.name())
198
 
            return 0
199
 
        # XXX: This should be handled by the parser
200
 
        allowed_names = self.options().keys()
201
 
        for oname in opts:
202
 
            if oname not in allowed_names:
203
 
                raise BzrCommandError("option '--%s' is not allowed for command %r"
204
 
                                      % (oname, self.name()))
 
664
            sys.stdout.write(self.get_help_text())
 
665
            return 0
 
666
        if 'usage' in opts:  # e.g. bzr add --usage
 
667
            sys.stdout.write(self.get_help_text(verbose=False))
 
668
            return 0
 
669
        trace.set_verbosity_level(option._verbosity_level)
 
670
        if 'verbose' in self.supported_std_options:
 
671
            opts['verbose'] = trace.is_verbose()
 
672
        elif opts.has_key('verbose'):
 
673
            del opts['verbose']
 
674
        if 'quiet' in self.supported_std_options:
 
675
            opts['quiet'] = trace.is_quiet()
 
676
        elif opts.has_key('quiet'):
 
677
            del opts['quiet']
 
678
 
205
679
        # mix arguments and options into one dictionary
206
680
        cmdargs = _match_argform(self.name(), self.takes_args, args)
207
681
        cmdopts = {}
211
685
        all_cmd_args = cmdargs.copy()
212
686
        all_cmd_args.update(cmdopts)
213
687
 
 
688
        self._setup_outf()
 
689
 
214
690
        return self.run(**all_cmd_args)
215
691
 
216
 
    
 
692
    def _setup_run(self):
 
693
        """Wrap the defined run method on self with a cleanup.
 
694
 
 
695
        This is called by __init__ to make the Command be able to be run
 
696
        by just calling run(), as it could be before cleanups were added.
 
697
 
 
698
        If a different form of cleanups are in use by your Command subclass,
 
699
        you can override this method.
 
700
        """
 
701
        class_run = self.run
 
702
        def run(*args, **kwargs):
 
703
            self._operation = cleanup.OperationWithCleanups(class_run)
 
704
            try:
 
705
                return self._operation.run_simple(*args, **kwargs)
 
706
            finally:
 
707
                del self._operation
 
708
        self.run = run
 
709
 
 
710
    @deprecated_method(deprecated_in((2, 2, 0)))
 
711
    def run_direct(self, *args, **kwargs):
 
712
        """Deprecated thunk from bzrlib 2.1."""
 
713
        return self.run(*args, **kwargs)
 
714
 
217
715
    def run(self):
218
716
        """Actually run the command.
219
717
 
223
721
        Return 0 or None if the command was successful, or a non-zero
224
722
        shell error code if not.  It's OK for this method to allow
225
723
        an exception to raise up.
 
724
 
 
725
        This method is automatically wrapped by Command.__init__ with a 
 
726
        cleanup operation, stored as self._operation. This can be used
 
727
        via self.add_cleanup to perform automatic cleanups at the end of
 
728
        run().
 
729
 
 
730
        The argument for run are assembled by introspection. So for instance,
 
731
        if your command takes an argument files, you would declare::
 
732
 
 
733
            def run(self, files=None):
 
734
                pass
226
735
        """
227
 
        raise NotImplementedError()
228
 
 
 
736
        raise NotImplementedError('no implementation of command %r'
 
737
                                  % self.name())
229
738
 
230
739
    def help(self):
231
740
        """Return help message for this class."""
 
741
        from inspect import getdoc
232
742
        if self.__doc__ is Command.__doc__:
233
743
            return None
234
744
        return getdoc(self)
236
746
    def name(self):
237
747
        return _unsquish_command_name(self.__class__.__name__)
238
748
 
 
749
    def plugin_name(self):
 
750
        """Get the name of the plugin that provides this command.
239
751
 
240
 
def parse_spec(spec):
241
 
    """
242
 
    >>> parse_spec(None)
243
 
    [None, None]
244
 
    >>> parse_spec("./")
245
 
    ['./', None]
246
 
    >>> parse_spec("../@")
247
 
    ['..', -1]
248
 
    >>> parse_spec("../f/@35")
249
 
    ['../f', 35]
250
 
    >>> parse_spec('./@revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67')
251
 
    ['.', 'revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67']
252
 
    """
253
 
    if spec is None:
254
 
        return [None, None]
255
 
    if '/@' in spec:
256
 
        parsed = spec.split('/@')
257
 
        assert len(parsed) == 2
258
 
        if parsed[1] == "":
259
 
            parsed[1] = -1
 
752
        :return: The name of the plugin or None if the command is builtin.
 
753
        """
 
754
        mod_parts = self.__module__.split('.')
 
755
        if len(mod_parts) >= 3 and mod_parts[1] == 'plugins':
 
756
            return mod_parts[2]
260
757
        else:
261
 
            try:
262
 
                parsed[1] = int(parsed[1])
263
 
            except ValueError:
264
 
                pass # We can allow stuff like ./@revid:blahblahblah
265
 
            else:
266
 
                assert parsed[1] >=0
267
 
    else:
268
 
        parsed = [spec, None]
269
 
    return parsed
270
 
 
271
 
def parse_args(command, argv):
 
758
            return None
 
759
 
 
760
 
 
761
class CommandHooks(Hooks):
 
762
    """Hooks related to Command object creation/enumeration."""
 
763
 
 
764
    def __init__(self):
 
765
        """Create the default hooks.
 
766
 
 
767
        These are all empty initially, because by default nothing should get
 
768
        notified.
 
769
        """
 
770
        Hooks.__init__(self)
 
771
        self.create_hook(HookPoint('extend_command',
 
772
            "Called after creating a command object to allow modifications "
 
773
            "such as adding or removing options, docs etc. Called with the "
 
774
            "new bzrlib.commands.Command object.", (1, 13), None))
 
775
        self.create_hook(HookPoint('get_command',
 
776
            "Called when creating a single command. Called with "
 
777
            "(cmd_or_None, command_name). get_command should either return "
 
778
            "the cmd_or_None parameter, or a replacement Command object that "
 
779
            "should be used for the command. Note that the Command.hooks "
 
780
            "hooks are core infrastructure. Many users will prefer to use "
 
781
            "bzrlib.commands.register_command or plugin_cmds.register_lazy.",
 
782
            (1, 17), None))
 
783
        self.create_hook(HookPoint('get_missing_command',
 
784
            "Called when creating a single command if no command could be "
 
785
            "found. Called with (command_name). get_missing_command should "
 
786
            "either return None, or a Command object to be used for the "
 
787
            "command.", (1, 17), None))
 
788
        self.create_hook(HookPoint('list_commands',
 
789
            "Called when enumerating commands. Called with a set of "
 
790
            "cmd_name strings for all the commands found so far. This set "
 
791
            " is safe to mutate - e.g. to remove a command. "
 
792
            "list_commands should return the updated set of command names.",
 
793
            (1, 17), None))
 
794
 
 
795
Command.hooks = CommandHooks()
 
796
 
 
797
 
 
798
def parse_args(command, argv, alias_argv=None):
272
799
    """Parse command line.
273
 
    
 
800
 
274
801
    Arguments and options are parsed at this level before being passed
275
802
    down to specific command handlers.  This routine knows, from a
276
803
    lookup table, something about the available options, what optargs
277
804
    they take, and which commands will accept them.
278
805
    """
279
 
    # TODO: chop up this beast; make it a method of the Command
280
 
    args = []
281
 
    opts = {}
282
 
 
283
 
    cmd_options = command.options()
284
 
    argsover = False
285
 
    while argv:
286
 
        a = argv.pop(0)
287
 
        if argsover:
288
 
            args.append(a)
289
 
            continue
290
 
        elif a == '--':
291
 
            # We've received a standalone -- No more flags
292
 
            argsover = True
293
 
            continue
294
 
        if a[0] == '-':
295
 
            # option names must not be unicode
296
 
            a = str(a)
297
 
            optarg = None
298
 
            if a[1] == '-':
299
 
                mutter("  got option %r" % a)
300
 
                if '=' in a:
301
 
                    optname, optarg = a[2:].split('=', 1)
302
 
                else:
303
 
                    optname = a[2:]
304
 
                if optname not in cmd_options:
305
 
                    raise BzrCommandError('unknown long option %r for command %s' 
306
 
                            % (a, command.name))
307
 
            else:
308
 
                shortopt = a[1:]
309
 
                if shortopt in Option.SHORT_OPTIONS:
310
 
                    # Multi-character options must have a space to delimit
311
 
                    # their value
312
 
                    # ^^^ what does this mean? mbp 20051014
313
 
                    optname = Option.SHORT_OPTIONS[shortopt].name
314
 
                else:
315
 
                    # Single character short options, can be chained,
316
 
                    # and have their value appended to their name
317
 
                    shortopt = a[1:2]
318
 
                    if shortopt not in Option.SHORT_OPTIONS:
319
 
                        # We didn't find the multi-character name, and we
320
 
                        # didn't find the single char name
321
 
                        raise BzrError('unknown short option %r' % a)
322
 
                    optname = Option.SHORT_OPTIONS[shortopt].name
323
 
 
324
 
                    if a[2:]:
325
 
                        # There are extra things on this option
326
 
                        # see if it is the value, or if it is another
327
 
                        # short option
328
 
                        optargfn = Option.OPTIONS[optname].type
329
 
                        if optargfn is None:
330
 
                            # This option does not take an argument, so the
331
 
                            # next entry is another short option, pack it back
332
 
                            # into the list
333
 
                            argv.insert(0, '-' + a[2:])
334
 
                        else:
335
 
                            # This option takes an argument, so pack it
336
 
                            # into the array
337
 
                            optarg = a[2:]
338
 
            
339
 
            if optname in opts:
340
 
                # XXX: Do we ever want to support this, e.g. for -r?
341
 
                raise BzrError('repeated option %r' % a)
342
 
                
343
 
            option_obj = cmd_options[optname]
344
 
            optargfn = option_obj.type
345
 
            if optargfn:
346
 
                if optarg == None:
347
 
                    if not argv:
348
 
                        raise BzrError('option %r needs an argument' % a)
349
 
                    else:
350
 
                        optarg = argv.pop(0)
351
 
                opts[optname] = optargfn(optarg)
352
 
            else:
353
 
                if optarg != None:
354
 
                    raise BzrError('option %r takes no argument' % optname)
355
 
                opts[optname] = True
356
 
        else:
357
 
            args.append(a)
 
806
    # TODO: make it a method of the Command?
 
807
    parser = option.get_optparser(command.options())
 
808
    if alias_argv is not None:
 
809
        args = alias_argv + argv
 
810
    else:
 
811
        args = argv
 
812
 
 
813
    options, args = parser.parse_args(args)
 
814
    opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
 
815
                 v is not option.OptionParser.DEFAULT_VALUE])
358
816
    return args, opts
359
817
 
360
818
 
375
833
                argdict[argname + '_list'] = None
376
834
        elif ap[-1] == '+':
377
835
            if not args:
378
 
                raise BzrCommandError("command %r needs one or more %s"
379
 
                        % (cmd, argname.upper()))
 
836
                raise errors.BzrCommandError("command %r needs one or more %s"
 
837
                                             % (cmd, argname.upper()))
380
838
            else:
381
839
                argdict[argname + '_list'] = args[:]
382
840
                args = []
383
841
        elif ap[-1] == '$': # all but one
384
842
            if len(args) < 2:
385
 
                raise BzrCommandError("command %r needs one or more %s"
386
 
                        % (cmd, argname.upper()))
 
843
                raise errors.BzrCommandError("command %r needs one or more %s"
 
844
                                             % (cmd, argname.upper()))
387
845
            argdict[argname + '_list'] = args[:-1]
388
 
            args[:-1] = []                
 
846
            args[:-1] = []
389
847
        else:
390
848
            # just a plain arg
391
849
            argname = ap
392
850
            if not args:
393
 
                raise BzrCommandError("command %r requires argument %s"
394
 
                        % (cmd, argname.upper()))
 
851
                raise errors.BzrCommandError("command %r requires argument %s"
 
852
                               % (cmd, argname.upper()))
395
853
            else:
396
854
                argdict[argname] = args.pop(0)
397
 
            
 
855
 
398
856
    if args:
399
 
        raise BzrCommandError("extra argument to command %s: %s"
400
 
                              % (cmd, args[0]))
 
857
        raise errors.BzrCommandError("extra argument to command %s: %s"
 
858
                                     % (cmd, args[0]))
401
859
 
402
860
    return argdict
403
861
 
 
862
def apply_coveraged(dirname, the_callable, *args, **kwargs):
 
863
    # Cannot use "import trace", as that would import bzrlib.trace instead of
 
864
    # the standard library's trace.
 
865
    trace = __import__('trace')
 
866
 
 
867
    tracer = trace.Trace(count=1, trace=0)
 
868
    sys.settrace(tracer.globaltrace)
 
869
    threading.settrace(tracer.globaltrace)
 
870
 
 
871
    try:
 
872
        return exception_to_return_code(the_callable, *args, **kwargs)
 
873
    finally:
 
874
        sys.settrace(None)
 
875
        results = tracer.results()
 
876
        results.write_results(show_missing=1, summary=False,
 
877
                              coverdir=dirname)
404
878
 
405
879
 
406
880
def apply_profiled(the_callable, *args, **kwargs):
411
885
    try:
412
886
        prof = hotshot.Profile(pfname)
413
887
        try:
414
 
            ret = prof.runcall(the_callable, *args, **kwargs) or 0
 
888
            ret = prof.runcall(exception_to_return_code, the_callable, *args,
 
889
                **kwargs) or 0
415
890
        finally:
416
891
            prof.close()
417
892
        stats = hotshot.stats.load(pfname)
426
901
        os.remove(pfname)
427
902
 
428
903
 
429
 
def run_bzr(argv):
 
904
def exception_to_return_code(the_callable, *args, **kwargs):
 
905
    """UI level helper for profiling and coverage.
 
906
 
 
907
    This transforms exceptions into a return value of 3. As such its only
 
908
    relevant to the UI layer, and should never be called where catching
 
909
    exceptions may be desirable.
 
910
    """
 
911
    try:
 
912
        return the_callable(*args, **kwargs)
 
913
    except (KeyboardInterrupt, Exception), e:
 
914
        # used to handle AssertionError and KeyboardInterrupt
 
915
        # specially here, but hopefully they're handled ok by the logger now
 
916
        exc_info = sys.exc_info()
 
917
        exitcode = trace.report_exception(exc_info, sys.stderr)
 
918
        if os.environ.get('BZR_PDB'):
 
919
            print '**** entering debugger'
 
920
            tb = exc_info[2]
 
921
            import pdb
 
922
            if sys.version_info[:2] < (2, 6):
 
923
                # XXX: we want to do
 
924
                #    pdb.post_mortem(tb)
 
925
                # but because pdb.post_mortem gives bad results for tracebacks
 
926
                # from inside generators, we do it manually.
 
927
                # (http://bugs.python.org/issue4150, fixed in Python 2.6)
 
928
 
 
929
                # Setup pdb on the traceback
 
930
                p = pdb.Pdb()
 
931
                p.reset()
 
932
                p.setup(tb.tb_frame, tb)
 
933
                # Point the debugger at the deepest frame of the stack
 
934
                p.curindex = len(p.stack) - 1
 
935
                p.curframe = p.stack[p.curindex][0]
 
936
                # Start the pdb prompt.
 
937
                p.print_stack_entry(p.stack[p.curindex])
 
938
                p.execRcLines()
 
939
                p.cmdloop()
 
940
            else:
 
941
                pdb.post_mortem(tb)
 
942
        return exitcode
 
943
 
 
944
 
 
945
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
 
946
    from bzrlib.lsprof import profile
 
947
    ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
 
948
    stats.sort()
 
949
    if filename is None:
 
950
        stats.pprint()
 
951
    else:
 
952
        stats.save(filename)
 
953
        trace.note('Profile data written to "%s".', filename)
 
954
    return ret
 
955
 
 
956
 
 
957
@deprecated_function(deprecated_in((2, 2, 0)))
 
958
def shlex_split_unicode(unsplit):
 
959
    return cmdline.split(unsplit)
 
960
 
 
961
 
 
962
def get_alias(cmd, config=None):
 
963
    """Return an expanded alias, or None if no alias exists.
 
964
 
 
965
    cmd
 
966
        Command to be checked for an alias.
 
967
    config
 
968
        Used to specify an alternative config to use,
 
969
        which is especially useful for testing.
 
970
        If it is unspecified, the global config will be used.
 
971
    """
 
972
    if config is None:
 
973
        import bzrlib.config
 
974
        config = bzrlib.config.GlobalConfig()
 
975
    alias = config.get_alias(cmd)
 
976
    if (alias):
 
977
        return cmdline.split(alias)
 
978
    return None
 
979
 
 
980
 
 
981
def run_bzr(argv, load_plugins=load_plugins, disable_plugins=disable_plugins):
430
982
    """Execute a command.
431
983
 
432
 
    This is similar to main(), but without all the trappings for
433
 
    logging and error handling.  
434
 
    
435
 
    argv
436
 
       The command-line arguments, without the program name from argv[0]
437
 
    
438
 
    Returns a command status or raises an exception.
 
984
    :param argv: The command-line arguments, without the program name from
 
985
        argv[0] These should already be decoded. All library/test code calling
 
986
        run_bzr should be passing valid strings (don't need decoding).
 
987
    :param load_plugins: What function to call when triggering plugin loading.
 
988
        This function should take no arguments and cause all plugins to be
 
989
        loaded.
 
990
    :param disable_plugins: What function to call when disabling plugin
 
991
        loading. This function should take no arguments and cause all plugin
 
992
        loading to be prohibited (so that code paths in your application that
 
993
        know about some plugins possibly being present will fail to import
 
994
        those plugins even if they are installed.)
 
995
    :return: Returns a command exit code or raises an exception.
439
996
 
440
997
    Special master options: these must come before the command because
441
998
    they control how the command is interpreted.
443
1000
    --no-plugins
444
1001
        Do not load plugin modules at all
445
1002
 
 
1003
    --no-aliases
 
1004
        Do not allow aliases
 
1005
 
446
1006
    --builtin
447
1007
        Only use builtin commands.  (Plugins are still allowed to change
448
1008
        other behaviour.)
449
1009
 
450
1010
    --profile
451
 
        Run under the Python profiler.
 
1011
        Run under the Python hotshot profiler.
 
1012
 
 
1013
    --lsprof
 
1014
        Run under the Python lsprof profiler.
 
1015
 
 
1016
    --coverage
 
1017
        Generate line coverage report in the specified directory.
 
1018
 
 
1019
    --concurrency
 
1020
        Specify the number of processes that can be run concurrently (selftest).
452
1021
    """
453
 
    # Load all of the transport methods
454
 
    import bzrlib.transport.local, bzrlib.transport.http
455
 
    
456
 
    argv = [a.decode(bzrlib.user_encoding) for a in argv]
 
1022
    trace.mutter("bazaar version: " + bzrlib.__version__)
 
1023
    argv = list(argv)
 
1024
    trace.mutter("bzr arguments: %r", argv)
457
1025
 
458
 
    opt_profile = opt_no_plugins = opt_builtin = False
 
1026
    opt_lsprof = opt_profile = opt_no_plugins = opt_builtin =  \
 
1027
                opt_no_aliases = False
 
1028
    opt_lsprof_file = opt_coverage_dir = None
459
1029
 
460
1030
    # --no-plugins is handled specially at a very early stage. We need
461
1031
    # to load plugins before doing other command parsing so that they
462
1032
    # can override commands, but this needs to happen first.
463
1033
 
464
 
    for a in argv:
 
1034
    argv_copy = []
 
1035
    i = 0
 
1036
    while i < len(argv):
 
1037
        a = argv[i]
465
1038
        if a == '--profile':
466
1039
            opt_profile = True
 
1040
        elif a == '--lsprof':
 
1041
            opt_lsprof = True
 
1042
        elif a == '--lsprof-file':
 
1043
            opt_lsprof = True
 
1044
            opt_lsprof_file = argv[i + 1]
 
1045
            i += 1
467
1046
        elif a == '--no-plugins':
468
1047
            opt_no_plugins = True
 
1048
        elif a == '--no-aliases':
 
1049
            opt_no_aliases = True
469
1050
        elif a == '--builtin':
470
1051
            opt_builtin = True
471
 
        else:
472
 
            break
473
 
        argv.remove(a)
474
 
 
475
 
    if (not argv) or (argv[0] == '--help'):
476
 
        from bzrlib.help import help
477
 
        if len(argv) > 1:
478
 
            help(argv[1])
479
 
        else:
480
 
            help()
481
 
        return 0
482
 
 
483
 
    if argv[0] == '--version':
484
 
        from bzrlib.builtins import show_version
485
 
        show_version()
486
 
        return 0
487
 
        
 
1052
        elif a == '--concurrency':
 
1053
            os.environ['BZR_CONCURRENCY'] = argv[i + 1]
 
1054
            i += 1
 
1055
        elif a == '--coverage':
 
1056
            opt_coverage_dir = argv[i + 1]
 
1057
            i += 1
 
1058
        elif a == '--profile-imports':
 
1059
            pass # already handled in startup script Bug #588277
 
1060
        elif a.startswith('-D'):
 
1061
            debug.debug_flags.add(a[2:])
 
1062
        else:
 
1063
            argv_copy.append(a)
 
1064
        i += 1
 
1065
 
 
1066
    debug.set_debug_flags_from_config()
 
1067
 
488
1068
    if not opt_no_plugins:
489
 
        from bzrlib.plugin import load_plugins
490
1069
        load_plugins()
491
 
 
492
 
    cmd = str(argv.pop(0))
493
 
 
 
1070
    else:
 
1071
        disable_plugins()
 
1072
 
 
1073
    argv = argv_copy
 
1074
    if (not argv):
 
1075
        get_cmd_object('help').run_argv_aliases([])
 
1076
        return 0
 
1077
 
 
1078
    if argv[0] == '--version':
 
1079
        get_cmd_object('version').run_argv_aliases([])
 
1080
        return 0
 
1081
 
 
1082
    alias_argv = None
 
1083
 
 
1084
    if not opt_no_aliases:
 
1085
        alias_argv = get_alias(argv[0])
 
1086
        if alias_argv:
 
1087
            argv[0] = alias_argv.pop(0)
 
1088
 
 
1089
    cmd = argv.pop(0)
494
1090
    cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
495
 
 
496
 
    if opt_profile:
497
 
        ret = apply_profiled(cmd_obj.run_argv, argv)
 
1091
    run = cmd_obj.run_argv_aliases
 
1092
    run_argv = [argv, alias_argv]
 
1093
 
 
1094
    try:
 
1095
        # We can be called recursively (tests for example), but we don't want
 
1096
        # the verbosity level to propagate.
 
1097
        saved_verbosity_level = option._verbosity_level
 
1098
        option._verbosity_level = 0
 
1099
        if opt_lsprof:
 
1100
            if opt_coverage_dir:
 
1101
                trace.warning(
 
1102
                    '--coverage ignored, because --lsprof is in use.')
 
1103
            ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
 
1104
        elif opt_profile:
 
1105
            if opt_coverage_dir:
 
1106
                trace.warning(
 
1107
                    '--coverage ignored, because --profile is in use.')
 
1108
            ret = apply_profiled(run, *run_argv)
 
1109
        elif opt_coverage_dir:
 
1110
            ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
 
1111
        else:
 
1112
            ret = run(*run_argv)
 
1113
        return ret or 0
 
1114
    finally:
 
1115
        # reset, in case we may do other commands later within the same
 
1116
        # process. Commands that want to execute sub-commands must propagate
 
1117
        # --verbose in their own way.
 
1118
        if 'memory' in debug.debug_flags:
 
1119
            trace.debug_memory('Process status after command:', short=False)
 
1120
        option._verbosity_level = saved_verbosity_level
 
1121
 
 
1122
 
 
1123
def display_command(func):
 
1124
    """Decorator that suppresses pipe/interrupt errors."""
 
1125
    def ignore_pipe(*args, **kwargs):
 
1126
        try:
 
1127
            result = func(*args, **kwargs)
 
1128
            sys.stdout.flush()
 
1129
            return result
 
1130
        except IOError, e:
 
1131
            if getattr(e, 'errno', None) is None:
 
1132
                raise
 
1133
            if e.errno != errno.EPIPE:
 
1134
                # Win32 raises IOError with errno=0 on a broken pipe
 
1135
                if sys.platform != 'win32' or (e.errno not in (0, errno.EINVAL)):
 
1136
                    raise
 
1137
            pass
 
1138
        except KeyboardInterrupt:
 
1139
            pass
 
1140
    return ignore_pipe
 
1141
 
 
1142
 
 
1143
def install_bzr_command_hooks():
 
1144
    """Install the hooks to supply bzr's own commands."""
 
1145
    if _list_bzr_commands in Command.hooks["list_commands"]:
 
1146
        return
 
1147
    Command.hooks.install_named_hook("list_commands", _list_bzr_commands,
 
1148
        "bzr commands")
 
1149
    Command.hooks.install_named_hook("get_command", _get_bzr_command,
 
1150
        "bzr commands")
 
1151
    Command.hooks.install_named_hook("get_command", _get_plugin_command,
 
1152
        "bzr plugin commands")
 
1153
    Command.hooks.install_named_hook("get_command", _get_external_command,
 
1154
        "bzr external command lookup")
 
1155
    Command.hooks.install_named_hook("get_missing_command", _try_plugin_provider,
 
1156
        "bzr plugin-provider-db check")
 
1157
 
 
1158
 
 
1159
 
 
1160
def _specified_or_unicode_argv(argv):
 
1161
    # For internal or testing use, argv can be passed.  Otherwise, get it from
 
1162
    # the process arguments in a unicode-safe way.
 
1163
    if argv is None:
 
1164
        return osutils.get_unicode_argv()
498
1165
    else:
499
 
        ret = cmd_obj.run_argv(argv)
500
 
    return ret or 0
501
 
 
502
 
 
503
 
def main(argv):
504
 
    import bzrlib.ui
505
 
    bzrlib.trace.log_startup(argv)
506
 
    bzrlib.ui.ui_factory = bzrlib.ui.TextUIFactory()
507
 
 
508
 
    return run_bzr_catch_errors(argv[1:])
 
1166
        new_argv = []
 
1167
        try:
 
1168
            # ensure all arguments are unicode strings
 
1169
            for a in argv[1:]:
 
1170
                if isinstance(a, unicode):
 
1171
                    new_argv.append(a)
 
1172
                else:
 
1173
                    new_argv.append(a.decode('ascii'))
 
1174
        except UnicodeDecodeError:
 
1175
            raise errors.BzrError("argv should be list of unicode strings.")
 
1176
        return new_argv
 
1177
 
 
1178
 
 
1179
def main(argv=None):
 
1180
    """Main entry point of command-line interface.
 
1181
 
 
1182
    Typically `bzrlib.initialize` should be called first.
 
1183
 
 
1184
    :param argv: list of unicode command-line arguments similar to sys.argv.
 
1185
        argv[0] is script name usually, it will be ignored.
 
1186
        Don't pass here sys.argv because this list contains plain strings
 
1187
        and not unicode; pass None instead.
 
1188
 
 
1189
    :return: exit code of bzr command.
 
1190
    """
 
1191
    argv = _specified_or_unicode_argv(argv)
 
1192
    _register_builtin_commands()
 
1193
    ret = run_bzr_catch_errors(argv)
 
1194
    bzrlib.ui.ui_factory.log_transport_activity(
 
1195
        display=('bytes' in debug.debug_flags))
 
1196
    trace.mutter("return code %d", ret)
 
1197
    return ret
509
1198
 
510
1199
 
511
1200
def run_bzr_catch_errors(argv):
 
1201
    """Run a bzr command with parameters as described by argv.
 
1202
 
 
1203
    This function assumed that that UI layer is setup, that symbol deprecations
 
1204
    are already applied, and that unicode decoding has already been performed on argv.
 
1205
    """
 
1206
    # done here so that they're covered for every test run
 
1207
    install_bzr_command_hooks()
 
1208
    return exception_to_return_code(run_bzr, argv)
 
1209
 
 
1210
 
 
1211
def run_bzr_catch_user_errors(argv):
 
1212
    """Run bzr and report user errors, but let internal errors propagate.
 
1213
 
 
1214
    This is used for the test suite, and might be useful for other programs
 
1215
    that want to wrap the commandline interface.
 
1216
    """
 
1217
    # done here so that they're covered for every test run
 
1218
    install_bzr_command_hooks()
512
1219
    try:
513
 
        try:
514
 
            return run_bzr(argv)
515
 
        finally:
516
 
            # do this here inside the exception wrappers to catch EPIPE
517
 
            sys.stdout.flush()
518
 
    except BzrCommandError, e:
519
 
        # command line syntax error, etc
520
 
        log_error(str(e))
521
 
        return 1
522
 
    except BzrError, e:
523
 
        bzrlib.trace.log_exception()
524
 
        return 1
525
 
    except AssertionError, e:
526
 
        bzrlib.trace.log_exception('assertion failed: ' + str(e))
527
 
        return 3
528
 
    except KeyboardInterrupt, e:
529
 
        bzrlib.trace.log_exception('interrupted')
530
 
        return 2
 
1220
        return run_bzr(argv)
531
1221
    except Exception, e:
532
 
        import errno
533
 
        if (isinstance(e, IOError) 
534
 
            and hasattr(e, 'errno')
535
 
            and e.errno == errno.EPIPE):
536
 
            bzrlib.trace.note('broken pipe')
537
 
            return 2
538
 
        else:
539
 
            ## import pdb
540
 
            ## pdb.pm()
541
 
            bzrlib.trace.log_exception()
542
 
            return 2
543
 
 
544
 
if __name__ == '__main__':
545
 
    sys.exit(main(sys.argv))
 
1222
        if (isinstance(e, (OSError, IOError))
 
1223
            or not getattr(e, 'internal_error', True)):
 
1224
            trace.report_exception(sys.exc_info(), sys.stderr)
 
1225
            return 3
 
1226
        else:
 
1227
            raise
 
1228
 
 
1229
 
 
1230
class HelpCommandIndex(object):
 
1231
    """A index for bzr help that returns commands."""
 
1232
 
 
1233
    def __init__(self):
 
1234
        self.prefix = 'commands/'
 
1235
 
 
1236
    def get_topics(self, topic):
 
1237
        """Search for topic amongst commands.
 
1238
 
 
1239
        :param topic: A topic to search for.
 
1240
        :return: A list which is either empty or contains a single
 
1241
            Command entry.
 
1242
        """
 
1243
        if topic and topic.startswith(self.prefix):
 
1244
            topic = topic[len(self.prefix):]
 
1245
        try:
 
1246
            cmd = _get_cmd_object(topic, check_missing=False)
 
1247
        except KeyError:
 
1248
            return []
 
1249
        else:
 
1250
            return [cmd]
 
1251
 
 
1252
 
 
1253
class Provider(object):
 
1254
    '''Generic class to be overriden by plugins'''
 
1255
 
 
1256
    def plugin_for_command(self, cmd_name):
 
1257
        '''Takes a command and returns the information for that plugin
 
1258
 
 
1259
        :return: A dictionary with all the available information
 
1260
        for the requested plugin
 
1261
        '''
 
1262
        raise NotImplementedError
 
1263
 
 
1264
 
 
1265
class ProvidersRegistry(registry.Registry):
 
1266
    '''This registry exists to allow other providers to exist'''
 
1267
 
 
1268
    def __iter__(self):
 
1269
        for key, provider in self.iteritems():
 
1270
            yield provider
 
1271
 
 
1272
command_providers_registry = ProvidersRegistry()