~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/commands.py

  • Committer: Canonical.com Patch Queue Manager
  • Date: 2010-01-21 10:00:42 UTC
  • mfrom: (4978.1.2 integration)
  • Revision ID: pqm@pqm.ubuntu.com-20100121100042-77858a88k2zpec7b
(nmb) Add documentation for multi-parent merges

Show diffs side-by-side

added added

removed removed

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