~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/commands.py

  • Committer: Ian Clatworthy
  • Date: 2007-08-10 05:17:09 UTC
  • mto: (2733.1.1 ianc-integration)
  • mto: This revision was merged to the branch mainline in revision 2734.
  • Revision ID: ian.clatworthy@internode.on.net-20070810051709-0rnxlur94samh192
move most existing topics into the User Guide dir for English

Show diffs side-by-side

added added

removed removed

Lines of Context:
1
 
# Copyright (C) 2005-2010 Canonical Ltd
 
1
# Copyright (C) 2006 Canonical Ltd
2
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
12
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
 
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
16
16
 
17
17
 
18
18
# TODO: probably should say which arguments are candidates for glob
35
35
lazy_import(globals(), """
36
36
import codecs
37
37
import errno
38
 
import threading
39
38
from warnings import warn
40
39
 
41
40
import bzrlib
42
41
from bzrlib import (
43
 
    cleanup,
44
 
    cmdline,
45
42
    debug,
46
43
    errors,
47
44
    option,
48
45
    osutils,
49
46
    trace,
50
 
    ui,
51
47
    win32utils,
52
48
    )
53
49
""")
54
50
 
55
 
from bzrlib.hooks import HookPoint, Hooks
56
 
# Compatibility - Option used to be in commands.
57
 
from bzrlib.option import Option
58
 
from bzrlib.plugin import disable_plugins, load_plugins
59
 
from bzrlib import registry
60
51
from bzrlib.symbol_versioning import (
61
52
    deprecated_function,
62
 
    deprecated_in,
63
53
    deprecated_method,
 
54
    zero_eight,
 
55
    zero_eleven,
64
56
    )
65
 
 
66
 
 
67
 
class CommandInfo(object):
68
 
    """Information about a command."""
69
 
 
70
 
    def __init__(self, aliases):
71
 
        """The list of aliases for the command."""
72
 
        self.aliases = aliases
73
 
 
74
 
    @classmethod
75
 
    def from_command(klass, command):
76
 
        """Factory to construct a CommandInfo from a command."""
77
 
        return klass(command.aliases)
78
 
 
79
 
 
80
 
class CommandRegistry(registry.Registry):
81
 
 
82
 
    @staticmethod
83
 
    def _get_name(command_name):
84
 
        if command_name.startswith("cmd_"):
85
 
            return _unsquish_command_name(command_name)
86
 
        else:
87
 
            return command_name
88
 
 
89
 
    def register(self, cmd, decorate=False):
90
 
        """Utility function to help register a command
91
 
 
92
 
        :param cmd: Command subclass to register
93
 
        :param decorate: If true, allow overriding an existing command
94
 
            of the same name; the old command is returned by this function.
95
 
            Otherwise it is an error to try to override an existing command.
96
 
        """
97
 
        k = cmd.__name__
98
 
        k_unsquished = self._get_name(k)
99
 
        try:
100
 
            previous = self.get(k_unsquished)
101
 
        except KeyError:
102
 
            previous = _builtin_commands().get(k_unsquished)
103
 
        info = CommandInfo.from_command(cmd)
104
 
        try:
105
 
            registry.Registry.register(self, k_unsquished, cmd,
106
 
                                       override_existing=decorate, info=info)
107
 
        except KeyError:
108
 
            trace.warning('Two plugins defined the same command: %r' % k)
109
 
            trace.warning('Not loading the one in %r' %
110
 
                sys.modules[cmd.__module__])
111
 
            trace.warning('Previously this command was registered from %r' %
112
 
                sys.modules[previous.__module__])
113
 
        return previous
114
 
 
115
 
    def register_lazy(self, command_name, aliases, module_name):
116
 
        """Register a command without loading its module.
117
 
 
118
 
        :param command_name: The primary name of the command.
119
 
        :param aliases: A list of aliases for the command.
120
 
        :module_name: The module that the command lives in.
121
 
        """
122
 
        key = self._get_name(command_name)
123
 
        registry.Registry.register_lazy(self, key, module_name, command_name,
124
 
                                        info=CommandInfo(aliases))
125
 
 
126
 
 
127
 
plugin_cmds = CommandRegistry()
 
57
# Compatibility
 
58
from bzrlib.option import Option
 
59
 
 
60
 
 
61
plugin_cmds = {}
128
62
 
129
63
 
130
64
def register_command(cmd, decorate=False):
 
65
    """Utility function to help register a command
 
66
 
 
67
    :param cmd: Command subclass to register
 
68
    :param decorate: If true, allow overriding an existing command
 
69
        of the same name; the old command is returned by this function.
 
70
        Otherwise it is an error to try to override an existing command.
 
71
    """
131
72
    global plugin_cmds
132
 
    return plugin_cmds.register(cmd, decorate)
 
73
    k = cmd.__name__
 
74
    if k.startswith("cmd_"):
 
75
        k_unsquished = _unsquish_command_name(k)
 
76
    else:
 
77
        k_unsquished = k
 
78
    if k_unsquished not in plugin_cmds:
 
79
        plugin_cmds[k_unsquished] = cmd
 
80
        ## trace.mutter('registered plugin command %s', k_unsquished)
 
81
        if decorate and k_unsquished in builtin_command_names():
 
82
            return _builtin_commands()[k_unsquished]
 
83
    elif decorate:
 
84
        result = plugin_cmds[k_unsquished]
 
85
        plugin_cmds[k_unsquished] = cmd
 
86
        return result
 
87
    else:
 
88
        trace.log_error('Two plugins defined the same command: %r' % k)
 
89
        trace.log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
133
90
 
134
91
 
135
92
def _squish_command_name(cmd):
137
94
 
138
95
 
139
96
def _unsquish_command_name(cmd):
 
97
    assert cmd.startswith("cmd_")
140
98
    return cmd[4:].replace('_','-')
141
99
 
142
100
 
143
101
def _builtin_commands():
144
102
    import bzrlib.builtins
145
 
    return _scan_module_for_commands(bzrlib.builtins)
146
 
 
147
 
 
148
 
def _scan_module_for_commands(module):
149
103
    r = {}
150
 
    for name, obj in module.__dict__.iteritems():
 
104
    builtins = bzrlib.builtins.__dict__
 
105
    for name in builtins:
151
106
        if name.startswith("cmd_"):
152
107
            real_name = _unsquish_command_name(name)
153
 
            r[real_name] = obj
 
108
            r[real_name] = builtins[name]
154
109
    return r
155
 
 
156
 
 
157
 
def _list_bzr_commands(names):
158
 
    """Find commands from bzr's core and plugins."""
159
 
    # to eliminate duplicates
160
 
    names.update(builtin_command_names())
161
 
    names.update(plugin_command_names())
162
 
    return names
163
 
 
164
 
 
165
 
def all_command_names():
166
 
    """Return a set of all command names."""
167
 
    names = set()
168
 
    for hook in Command.hooks['list_commands']:
169
 
        names = hook(names)
170
 
        if names is None:
171
 
            raise AssertionError(
172
 
                'hook %s returned None' % Command.hooks.get_hook_name(hook))
173
 
    return names
174
 
 
 
110
            
175
111
 
176
112
def builtin_command_names():
177
 
    """Return list of builtin command names.
178
 
    
179
 
    Use of all_command_names() is encouraged rather than builtin_command_names
180
 
    and/or plugin_command_names.
181
 
    """
 
113
    """Return list of builtin command names."""
182
114
    return _builtin_commands().keys()
183
 
 
 
115
    
184
116
 
185
117
def plugin_command_names():
186
 
    """Returns command names from commands registered by plugins."""
187
118
    return plugin_cmds.keys()
188
119
 
189
120
 
 
121
def _get_cmd_dict(plugins_override=True):
 
122
    """Return name->class mapping for all commands."""
 
123
    d = _builtin_commands()
 
124
    if plugins_override:
 
125
        d.update(plugin_cmds)
 
126
    return d
 
127
 
 
128
    
 
129
def get_all_cmds(plugins_override=True):
 
130
    """Return canonical name and class for all registered commands."""
 
131
    for k, v in _get_cmd_dict(plugins_override=plugins_override).iteritems():
 
132
        yield k,v
 
133
 
 
134
 
190
135
def get_cmd_object(cmd_name, plugins_override=True):
191
 
    """Return the command object for a command.
 
136
    """Return the canonical name and command class for a command.
192
137
 
193
138
    plugins_override
194
139
        If true, plugin commands can override builtins.
199
144
        raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
200
145
 
201
146
 
202
 
def _get_cmd_object(cmd_name, plugins_override=True, check_missing=True):
203
 
    """Get a command object.
 
147
def _get_cmd_object(cmd_name, plugins_override=True):
 
148
    """Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
 
149
    from bzrlib.externalcommand import ExternalCommand
204
150
 
205
 
    :param cmd_name: The name of the command.
206
 
    :param plugins_override: Allow plugins to override builtins.
207
 
    :param check_missing: Look up commands not found in the regular index via
208
 
        the get_missing_command hook.
209
 
    :return: A Command object instance
210
 
    :raises KeyError: If no command is found.
211
 
    """
212
151
    # We want only 'ascii' command names, but the user may have typed
213
152
    # in a Unicode name. In that case, they should just get a
214
153
    # 'command not found' error later.
215
154
    # In the future, we may actually support Unicode command names.
216
 
    cmd = None
217
 
    # Get a command
218
 
    for hook in Command.hooks['get_command']:
219
 
        cmd = hook(cmd, cmd_name)
220
 
        if cmd is not None and not plugins_override and not cmd.plugin_name():
221
 
            # We've found a non-plugin command, don't permit it to be
222
 
            # overridden.
223
 
            break
224
 
    if cmd is None and check_missing:
225
 
        for hook in Command.hooks['get_missing_command']:
226
 
            cmd = hook(cmd_name)
227
 
            if cmd is not None:
228
 
                break
229
 
    if cmd is None:
230
 
        # No command found.
231
 
        raise KeyError
232
 
    # Allow plugins to extend commands
233
 
    for hook in Command.hooks['extend_command']:
234
 
        hook(cmd)
235
 
    return cmd
236
 
 
237
 
 
238
 
def _try_plugin_provider(cmd_name):
239
 
    """Probe for a plugin provider having cmd_name."""
240
 
    try:
241
 
        plugin_metadata, provider = probe_for_provider(cmd_name)
242
 
        raise errors.CommandAvailableInPlugin(cmd_name,
243
 
            plugin_metadata, provider)
244
 
    except errors.NoPluginAvailable:
245
 
        pass
246
 
 
247
 
 
248
 
def probe_for_provider(cmd_name):
249
 
    """Look for a provider for cmd_name.
250
 
 
251
 
    :param cmd_name: The command name.
252
 
    :return: plugin_metadata, provider for getting cmd_name.
253
 
    :raises NoPluginAvailable: When no provider can supply the plugin.
254
 
    """
255
 
    # look for providers that provide this command but aren't installed
256
 
    for provider in command_providers_registry:
257
 
        try:
258
 
            return provider.plugin_for_command(cmd_name), provider
259
 
        except errors.NoPluginAvailable:
260
 
            pass
261
 
    raise errors.NoPluginAvailable(cmd_name)
262
 
 
263
 
 
264
 
def _get_bzr_command(cmd_or_None, cmd_name):
265
 
    """Get a command from bzr's core."""
266
 
    cmds = _builtin_commands()
 
155
 
 
156
    # first look up this command under the specified name
 
157
    cmds = _get_cmd_dict(plugins_override=plugins_override)
267
158
    try:
268
159
        return cmds[cmd_name]()
269
160
    except KeyError:
270
161
        pass
 
162
 
271
163
    # look for any command which claims this as an alias
272
164
    for real_cmd_name, cmd_class in cmds.iteritems():
273
165
        if cmd_name in cmd_class.aliases:
274
166
            return cmd_class()
275
 
    return cmd_or_None
276
 
 
277
 
 
278
 
def _get_external_command(cmd_or_None, cmd_name):
279
 
    """Lookup a command that is a shell script."""
280
 
    # Only do external command lookups when no command is found so far.
281
 
    if cmd_or_None is not None:
282
 
        return cmd_or_None
283
 
    from bzrlib.externalcommand import ExternalCommand
 
167
 
284
168
    cmd_obj = ExternalCommand.find_command(cmd_name)
285
169
    if cmd_obj:
286
170
        return cmd_obj
287
 
 
288
 
 
289
 
def _get_plugin_command(cmd_or_None, cmd_name):
290
 
    """Get a command from bzr's plugins."""
291
 
    try:
292
 
        return plugin_cmds.get(cmd_name)()
293
 
    except KeyError:
294
 
        pass
295
 
    for key in plugin_cmds.keys():
296
 
        info = plugin_cmds.get_info(key)
297
 
        if cmd_name in info.aliases:
298
 
            return plugin_cmds.get(key)()
299
 
    return cmd_or_None
 
171
    raise KeyError
300
172
 
301
173
 
302
174
class Command(object):
356
228
            sys.stdout is forced to be a binary stream, and line-endings
357
229
            will not mangled.
358
230
 
359
 
    :cvar hooks: An instance of CommandHooks.
360
231
    """
361
232
    aliases = []
362
233
    takes_args = []
364
235
    encoding_type = 'strict'
365
236
 
366
237
    hidden = False
367
 
 
 
238
    
368
239
    def __init__(self):
369
240
        """Construct an instance of this command."""
370
241
        if self.__doc__ == Command.__doc__:
371
242
            warn("No help message set for %r" % self)
372
 
        # List of standard options directly supported
373
 
        self.supported_std_options = []
374
 
        self._operation = cleanup.OperationWithCleanups(self.run)
375
 
 
376
 
    def add_cleanup(self, cleanup_func, *args, **kwargs):
377
 
        """Register a function to call after self.run returns or raises.
378
 
 
379
 
        Functions will be called in LIFO order.
380
 
        """
381
 
        self._operation.add_cleanup(cleanup_func, *args, **kwargs)
382
 
 
383
 
    def cleanup_now(self):
384
 
        """Execute and empty pending cleanup functions immediately.
385
 
 
386
 
        After cleanup_now all registered cleanups are forgotten.  add_cleanup
387
 
        may be called again after cleanup_now; these cleanups will be called
388
 
        after self.run returns or raises (or when cleanup_now is next called).
389
 
 
390
 
        This is useful for releasing expensive or contentious resources (such
391
 
        as write locks) before doing further work that does not require those
392
 
        resources (such as writing results to self.outf).
393
 
        """
394
 
        self._operation.cleanup_now()
395
 
 
396
 
    @deprecated_method(deprecated_in((2, 1, 0)))
 
243
 
397
244
    def _maybe_expand_globs(self, file_list):
398
245
        """Glob expand file_list if the platform does not do that itself.
399
 
 
400
 
        Not used anymore, now that the bzr command-line parser globs on
401
 
        Windows.
402
 
 
 
246
        
403
247
        :return: A possibly empty list of unicode paths.
404
248
 
405
249
        Introduced in bzrlib 0.18.
406
250
        """
407
 
        return file_list
 
251
        if not file_list:
 
252
            file_list = []
 
253
        if sys.platform == 'win32':
 
254
            file_list = win32utils.glob_expand(file_list)
 
255
        return list(file_list)
408
256
 
409
257
    def _usage(self):
410
258
        """Return single-line grammar for this command.
421
269
            elif aname[-1] == '*':
422
270
                aname = '[' + aname[:-1] + '...]'
423
271
            s += aname + ' '
424
 
        s = s[:-1]      # remove last space
 
272
                
 
273
        assert s[-1] == ' '
 
274
        s = s[:-1]
425
275
        return s
426
276
 
427
277
    def get_help_text(self, additional_see_also=None, plain=True,
428
 
                      see_also_as_links=False, verbose=True):
 
278
                      see_also_as_links=False):
429
279
        """Return a text string with help for this command.
430
 
 
 
280
        
431
281
        :param additional_see_also: Additional help topics to be
432
282
            cross-referenced.
433
283
        :param plain: if False, raw help (reStructuredText) is
434
284
            returned instead of plain text.
435
285
        :param see_also_as_links: if True, convert items in 'See also'
436
286
            list to internal links (used by bzr_man rstx generator)
437
 
        :param verbose: if True, display the full help, otherwise
438
 
            leave out the descriptive sections and just display
439
 
            usage help (e.g. Purpose, Usage, Options) with a
440
 
            message explaining how to obtain full help.
441
287
        """
442
288
        doc = self.help()
443
289
        if doc is None:
444
290
            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
445
291
 
446
292
        # Extract the summary (purpose) and sections out from the text
447
 
        purpose,sections,order = self._get_help_parts(doc)
 
293
        purpose,sections = self._get_help_parts(doc)
448
294
 
449
295
        # If a custom usage section was provided, use it
450
296
        if sections.has_key('Usage'):
462
308
        result += '\n'
463
309
 
464
310
        # Add the options
465
 
        #
466
 
        # XXX: optparse implicitly rewraps the help, and not always perfectly,
467
 
        # so we get <https://bugs.launchpad.net/bzr/+bug/249908>.  -- mbp
468
 
        # 20090319
469
311
        options = option.get_optparser(self.options()).format_option_help()
470
 
        # XXX: According to the spec, ReST option lists actually don't support 
471
 
        # options like --1.9 so that causes syntax errors (in Sphinx at least).
472
 
        # As that pattern always appears in the commands that break, we trap
473
 
        # on that and then format that block of 'format' options as a literal
474
 
        # block.
475
 
        if not plain and options.find('  --1.9  ') != -1:
476
 
            options = options.replace(' format:\n', ' format::\n\n', 1)
477
312
        if options.startswith('Options:'):
478
313
            result += ':' + options
479
314
        elif options.startswith('options:'):
483
318
            result += options
484
319
        result += '\n'
485
320
 
486
 
        if verbose:
487
 
            # Add the description, indenting it 2 spaces
488
 
            # to match the indentation of the options
489
 
            if sections.has_key(None):
490
 
                text = sections.pop(None)
491
 
                text = '\n  '.join(text.splitlines())
492
 
                result += ':%s:\n  %s\n\n' % ('Description',text)
 
321
        # Add the description, indenting it 2 spaces
 
322
        # to match the indentation of the options
 
323
        if sections.has_key(None):
 
324
            text = sections.pop(None)
 
325
            text = '\n  '.join(text.splitlines())
 
326
            result += ':%s:\n  %s\n\n' % ('Description',text)
493
327
 
494
 
            # Add the custom sections (e.g. Examples). Note that there's no need
495
 
            # to indent these as they must be indented already in the source.
496
 
            if sections:
497
 
                for label in order:
498
 
                    if sections.has_key(label):
499
 
                        result += ':%s:\n%s\n' % (label,sections[label])
500
 
                result += '\n'
501
 
        else:
502
 
            result += ("See bzr help %s for more details and examples.\n\n"
503
 
                % self.name())
 
328
        # Add the custom sections (e.g. Examples). Note that there's no need
 
329
        # to indent these as they must be indented already in the source.
 
330
        if sections:
 
331
            labels = sorted(sections.keys())
 
332
            for label in labels:
 
333
                result += ':%s:\n%s\n\n' % (label,sections[label])
504
334
 
505
335
        # Add the aliases, source (plug-in) and see also links, if any
506
336
        if self.aliases:
519
349
                        # so don't create a real link
520
350
                        see_also_links.append(item)
521
351
                    else:
522
 
                        # Use a Sphinx link for this entry
523
 
                        link_text = ":doc:`%s <%s-help>`" % (item, item)
524
 
                        see_also_links.append(link_text)
 
352
                        # Use a reST link for this entry
 
353
                        see_also_links.append("`%s`_" % (item,))
525
354
                see_also = see_also_links
526
355
            result += ':See also: '
527
356
            result += ', '.join(see_also) + '\n'
528
357
 
529
 
        # If this will be rendered as plain text, convert it
 
358
        # If this will be rendered as plan text, convert it
530
359
        if plain:
531
360
            import bzrlib.help_topics
532
361
            result = bzrlib.help_topics.help_as_plain_text(result)
536
365
    def _get_help_parts(text):
537
366
        """Split help text into a summary and named sections.
538
367
 
539
 
        :return: (summary,sections,order) where summary is the top line and
 
368
        :return: (summary,sections) where summary is the top line and
540
369
            sections is a dictionary of the rest indexed by section name.
541
 
            order is the order the section appear in the text.
542
370
            A section starts with a heading line of the form ":xxx:".
543
371
            Indented text on following lines is the section value.
544
372
            All text found outside a named section is assigned to the
545
373
            default section which is given the key of None.
546
374
        """
547
 
        def save_section(sections, order, label, section):
 
375
        def save_section(sections, label, section):
548
376
            if len(section) > 0:
549
377
                if sections.has_key(label):
550
378
                    sections[label] += '\n' + section
551
379
                else:
552
 
                    order.append(label)
553
380
                    sections[label] = section
554
 
 
 
381
            
555
382
        lines = text.rstrip().splitlines()
556
383
        summary = lines.pop(0)
557
384
        sections = {}
558
 
        order = []
559
385
        label,section = None,''
560
386
        for line in lines:
561
387
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
562
 
                save_section(sections, order, label, section)
 
388
                save_section(sections, label, section)
563
389
                label,section = line[1:-1],''
564
 
            elif (label is not None) and len(line) > 1 and not line[0].isspace():
565
 
                save_section(sections, order, label, section)
 
390
            elif label != None and len(line) > 1 and not line[0].isspace():
 
391
                save_section(sections, label, section)
566
392
                label,section = None,line
567
393
            else:
568
394
                if len(section) > 0:
569
395
                    section += '\n' + line
570
396
                else:
571
397
                    section = line
572
 
        save_section(sections, order, label, section)
573
 
        return summary, sections, order
 
398
        save_section(sections, label, section)
 
399
        return summary, sections
574
400
 
575
401
    def get_help_topic(self):
576
402
        """Return the commands help topic - its name."""
578
404
 
579
405
    def get_see_also(self, additional_terms=None):
580
406
        """Return a list of help topics that are related to this command.
581
 
 
 
407
        
582
408
        The list is derived from the content of the _see_also attribute. Any
583
409
        duplicates are removed and the result is in lexical order.
584
410
        :param additional_terms: Additional help topics to cross-reference.
593
419
        """Return dict of valid options for this command.
594
420
 
595
421
        Maps from long option name to option object."""
596
 
        r = Option.STD_OPTIONS.copy()
597
 
        std_names = r.keys()
 
422
        r = dict()
 
423
        r['help'] = option._help_option
598
424
        for o in self.takes_options:
599
425
            if isinstance(o, basestring):
600
426
                o = option.Option.OPTIONS[o]
601
427
            r[o.name] = o
602
 
            if o.name in std_names:
603
 
                self.supported_std_options.append(o.name)
604
428
        return r
605
429
 
606
430
    def _setup_outf(self):
607
431
        """Return a file linked to stdout, which has proper encoding."""
608
 
        self.outf = ui.ui_factory.make_output_stream(
609
 
            encoding_type=self.encoding_type)
 
432
        assert self.encoding_type in ['strict', 'exact', 'replace']
 
433
 
 
434
        # Originally I was using self.stdout, but that looks
 
435
        # *way* too much like sys.stdout
 
436
        if self.encoding_type == 'exact':
 
437
            # force sys.stdout to be binary stream on win32
 
438
            if sys.platform == 'win32':
 
439
                fileno = getattr(sys.stdout, 'fileno', None)
 
440
                if fileno:
 
441
                    import msvcrt
 
442
                    msvcrt.setmode(fileno(), os.O_BINARY)
 
443
            self.outf = sys.stdout
 
444
            return
 
445
 
 
446
        output_encoding = osutils.get_terminal_encoding()
 
447
 
 
448
        # use 'replace' so that we don't abort if trying to write out
 
449
        # in e.g. the default C locale.
 
450
        self.outf = codecs.getwriter(output_encoding)(sys.stdout, errors=self.encoding_type)
 
451
        # For whatever reason codecs.getwriter() does not advertise its encoding
 
452
        # it just returns the encoding of the wrapped file, which is completely
 
453
        # bogus. So set the attribute, so we can find the correct encoding later.
 
454
        self.outf.encoding = output_encoding
610
455
 
611
456
    def run_argv_aliases(self, argv, alias_argv=None):
612
457
        """Parse the command line and run with extra aliases in alias_argv."""
 
458
        if argv is None:
 
459
            warn("Passing None for [] is deprecated from bzrlib 0.10",
 
460
                 DeprecationWarning, stacklevel=2)
 
461
            argv = []
613
462
        args, opts = parse_args(self, argv, alias_argv)
614
 
 
615
 
        # Process the standard options
616
463
        if 'help' in opts:  # e.g. bzr add --help
617
464
            sys.stdout.write(self.get_help_text())
618
465
            return 0
619
 
        if 'usage' in opts:  # e.g. bzr add --usage
620
 
            sys.stdout.write(self.get_help_text(verbose=False))
621
 
            return 0
622
 
        trace.set_verbosity_level(option._verbosity_level)
623
 
        if 'verbose' in self.supported_std_options:
624
 
            opts['verbose'] = trace.is_verbose()
625
 
        elif opts.has_key('verbose'):
626
 
            del opts['verbose']
627
 
        if 'quiet' in self.supported_std_options:
628
 
            opts['quiet'] = trace.is_quiet()
629
 
        elif opts.has_key('quiet'):
630
 
            del opts['quiet']
631
 
 
632
466
        # mix arguments and options into one dictionary
633
467
        cmdargs = _match_argform(self.name(), self.takes_args, args)
634
468
        cmdopts = {}
640
474
 
641
475
        self._setup_outf()
642
476
 
643
 
        return self.run_direct(**all_cmd_args)
644
 
 
645
 
    def run_direct(self, *args, **kwargs):
646
 
        """Call run directly with objects (without parsing an argv list)."""
647
 
        return self._operation.run_simple(*args, **kwargs)
648
 
 
 
477
        return self.run(**all_cmd_args)
 
478
    
649
479
    def run(self):
650
480
        """Actually run the command.
651
481
 
681
511
            return None
682
512
 
683
513
 
684
 
class CommandHooks(Hooks):
685
 
    """Hooks related to Command object creation/enumeration."""
686
 
 
687
 
    def __init__(self):
688
 
        """Create the default hooks.
689
 
 
690
 
        These are all empty initially, because by default nothing should get
691
 
        notified.
692
 
        """
693
 
        Hooks.__init__(self)
694
 
        self.create_hook(HookPoint('extend_command',
695
 
            "Called after creating a command object to allow modifications "
696
 
            "such as adding or removing options, docs etc. Called with the "
697
 
            "new bzrlib.commands.Command object.", (1, 13), None))
698
 
        self.create_hook(HookPoint('get_command',
699
 
            "Called when creating a single command. Called with "
700
 
            "(cmd_or_None, command_name). get_command should either return "
701
 
            "the cmd_or_None parameter, or a replacement Command object that "
702
 
            "should be used for the command. Note that the Command.hooks "
703
 
            "hooks are core infrastructure. Many users will prefer to use "
704
 
            "bzrlib.commands.register_command or plugin_cmds.register_lazy.",
705
 
            (1, 17), None))
706
 
        self.create_hook(HookPoint('get_missing_command',
707
 
            "Called when creating a single command if no command could be "
708
 
            "found. Called with (command_name). get_missing_command should "
709
 
            "either return None, or a Command object to be used for the "
710
 
            "command.", (1, 17), None))
711
 
        self.create_hook(HookPoint('list_commands',
712
 
            "Called when enumerating commands. Called with a set of "
713
 
            "cmd_name strings for all the commands found so far. This set "
714
 
            " is safe to mutate - e.g. to remove a command. "
715
 
            "list_commands should return the updated set of command names.",
716
 
            (1, 17), None))
717
 
 
718
 
Command.hooks = CommandHooks()
719
 
 
 
514
# Technically, this function hasn't been use in a *really* long time
 
515
# but we are only deprecating it now.
 
516
@deprecated_function(zero_eleven)
 
517
def parse_spec(spec):
 
518
    """
 
519
    >>> parse_spec(None)
 
520
    [None, None]
 
521
    >>> parse_spec("./")
 
522
    ['./', None]
 
523
    >>> parse_spec("../@")
 
524
    ['..', -1]
 
525
    >>> parse_spec("../f/@35")
 
526
    ['../f', 35]
 
527
    >>> parse_spec('./@revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67')
 
528
    ['.', 'revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67']
 
529
    """
 
530
    if spec is None:
 
531
        return [None, None]
 
532
    if '/@' in spec:
 
533
        parsed = spec.split('/@')
 
534
        assert len(parsed) == 2
 
535
        if parsed[1] == "":
 
536
            parsed[1] = -1
 
537
        else:
 
538
            try:
 
539
                parsed[1] = int(parsed[1])
 
540
            except ValueError:
 
541
                pass # We can allow stuff like ./@revid:blahblahblah
 
542
            else:
 
543
                assert parsed[1] >=0
 
544
    else:
 
545
        parsed = [spec, None]
 
546
    return parsed
720
547
 
721
548
def parse_args(command, argv, alias_argv=None):
722
549
    """Parse command line.
723
 
 
 
550
    
724
551
    Arguments and options are parsed at this level before being passed
725
552
    down to specific command handlers.  This routine knows, from a
726
553
    lookup table, something about the available options, what optargs
775
602
                               % (cmd, argname.upper()))
776
603
            else:
777
604
                argdict[argname] = args.pop(0)
778
 
 
 
605
            
779
606
    if args:
780
607
        raise errors.BzrCommandError("extra argument to command %s: %s"
781
608
                                     % (cmd, args[0]))
782
609
 
783
610
    return argdict
784
611
 
785
 
def apply_coveraged(dirname, the_callable, *args, **kwargs):
786
 
    # Cannot use "import trace", as that would import bzrlib.trace instead of
787
 
    # the standard library's trace.
788
 
    trace = __import__('trace')
789
 
 
790
 
    tracer = trace.Trace(count=1, trace=0)
791
 
    sys.settrace(tracer.globaltrace)
792
 
    threading.settrace(tracer.globaltrace)
793
 
 
794
 
    try:
795
 
        return exception_to_return_code(the_callable, *args, **kwargs)
796
 
    finally:
797
 
        sys.settrace(None)
798
 
        results = tracer.results()
799
 
        results.write_results(show_missing=1, summary=False,
800
 
                              coverdir=dirname)
801
612
 
802
613
 
803
614
def apply_profiled(the_callable, *args, **kwargs):
808
619
    try:
809
620
        prof = hotshot.Profile(pfname)
810
621
        try:
811
 
            ret = prof.runcall(exception_to_return_code, the_callable, *args,
812
 
                **kwargs) or 0
 
622
            ret = prof.runcall(the_callable, *args, **kwargs) or 0
813
623
        finally:
814
624
            prof.close()
815
625
        stats = hotshot.stats.load(pfname)
824
634
        os.remove(pfname)
825
635
 
826
636
 
827
 
def exception_to_return_code(the_callable, *args, **kwargs):
828
 
    """UI level helper for profiling and coverage.
829
 
 
830
 
    This transforms exceptions into a return value of 3. As such its only
831
 
    relevant to the UI layer, and should never be called where catching
832
 
    exceptions may be desirable.
833
 
    """
834
 
    try:
835
 
        return the_callable(*args, **kwargs)
836
 
    except (KeyboardInterrupt, Exception), e:
837
 
        # used to handle AssertionError and KeyboardInterrupt
838
 
        # specially here, but hopefully they're handled ok by the logger now
839
 
        exc_info = sys.exc_info()
840
 
        exitcode = trace.report_exception(exc_info, sys.stderr)
841
 
        if os.environ.get('BZR_PDB'):
842
 
            print '**** entering debugger'
843
 
            tb = exc_info[2]
844
 
            import pdb
845
 
            if sys.version_info[:2] < (2, 6):
846
 
                # XXX: we want to do
847
 
                #    pdb.post_mortem(tb)
848
 
                # but because pdb.post_mortem gives bad results for tracebacks
849
 
                # from inside generators, we do it manually.
850
 
                # (http://bugs.python.org/issue4150, fixed in Python 2.6)
851
 
 
852
 
                # Setup pdb on the traceback
853
 
                p = pdb.Pdb()
854
 
                p.reset()
855
 
                p.setup(tb.tb_frame, tb)
856
 
                # Point the debugger at the deepest frame of the stack
857
 
                p.curindex = len(p.stack) - 1
858
 
                p.curframe = p.stack[p.curindex][0]
859
 
                # Start the pdb prompt.
860
 
                p.print_stack_entry(p.stack[p.curindex])
861
 
                p.execRcLines()
862
 
                p.cmdloop()
863
 
            else:
864
 
                pdb.post_mortem(tb)
865
 
        return exitcode
866
 
 
867
 
 
868
637
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
869
638
    from bzrlib.lsprof import profile
870
 
    ret, stats = profile(exception_to_return_code, the_callable, *args, **kwargs)
 
639
    ret, stats = profile(the_callable, *args, **kwargs)
871
640
    stats.sort()
872
641
    if filename is None:
873
642
        stats.pprint()
877
646
    return ret
878
647
 
879
648
 
880
 
@deprecated_function(deprecated_in((2, 2, 0)))
881
 
def shlex_split_unicode(unsplit):
882
 
    return cmdline.split(unsplit)
883
 
 
884
 
 
885
649
def get_alias(cmd, config=None):
886
650
    """Return an expanded alias, or None if no alias exists.
887
651
 
897
661
        config = bzrlib.config.GlobalConfig()
898
662
    alias = config.get_alias(cmd)
899
663
    if (alias):
900
 
        return cmdline.split(alias)
 
664
        import shlex
 
665
        return [a.decode('utf-8') for a in shlex.split(alias.encode('utf-8'))]
901
666
    return None
902
667
 
903
668
 
904
 
def run_bzr(argv, load_plugins=load_plugins, disable_plugins=disable_plugins):
 
669
def run_bzr(argv):
905
670
    """Execute a command.
906
671
 
907
 
    :param argv: The command-line arguments, without the program name from
908
 
        argv[0] These should already be decoded. All library/test code calling
909
 
        run_bzr should be passing valid strings (don't need decoding).
910
 
    :param load_plugins: What function to call when triggering plugin loading.
911
 
        This function should take no arguments and cause all plugins to be
912
 
        loaded.
913
 
    :param disable_plugins: What function to call when disabling plugin
914
 
        loading. This function should take no arguments and cause all plugin
915
 
        loading to be prohibited (so that code paths in your application that
916
 
        know about some plugins possibly being present will fail to import
917
 
        those plugins even if they are installed.)
918
 
    :return: Returns a command exit code or raises an exception.
 
672
    This is similar to main(), but without all the trappings for
 
673
    logging and error handling.  
 
674
    
 
675
    argv
 
676
       The command-line arguments, without the program name from argv[0]
 
677
       These should already be decoded. All library/test code calling
 
678
       run_bzr should be passing valid strings (don't need decoding).
 
679
    
 
680
    Returns a command status or raises an exception.
919
681
 
920
682
    Special master options: these must come before the command because
921
683
    they control how the command is interpreted.
935
697
 
936
698
    --lsprof
937
699
        Run under the Python lsprof profiler.
938
 
 
939
 
    --coverage
940
 
        Generate line coverage report in the specified directory.
941
 
 
942
 
    --concurrency
943
 
        Specify the number of processes that can be run concurrently (selftest).
944
700
    """
945
 
    trace.mutter("bazaar version: " + bzrlib.__version__)
946
701
    argv = list(argv)
947
702
    trace.mutter("bzr arguments: %r", argv)
948
703
 
949
704
    opt_lsprof = opt_profile = opt_no_plugins = opt_builtin =  \
950
705
                opt_no_aliases = False
951
 
    opt_lsprof_file = opt_coverage_dir = None
 
706
    opt_lsprof_file = None
952
707
 
953
708
    # --no-plugins is handled specially at a very early stage. We need
954
709
    # to load plugins before doing other command parsing so that they
972
727
            opt_no_aliases = True
973
728
        elif a == '--builtin':
974
729
            opt_builtin = True
975
 
        elif a == '--concurrency':
976
 
            os.environ['BZR_CONCURRENCY'] = argv[i + 1]
977
 
            i += 1
978
 
        elif a == '--coverage':
979
 
            opt_coverage_dir = argv[i + 1]
980
 
            i += 1
 
730
        elif a in ('--quiet', '-q'):
 
731
            trace.be_quiet()
981
732
        elif a.startswith('-D'):
982
733
            debug.debug_flags.add(a[2:])
983
734
        else:
984
735
            argv_copy.append(a)
985
736
        i += 1
986
737
 
987
 
    debug.set_debug_flags_from_config()
 
738
    argv = argv_copy
 
739
    if (not argv):
 
740
        from bzrlib.builtins import cmd_help
 
741
        cmd_help().run_argv_aliases([])
 
742
        return 0
988
743
 
 
744
    if argv[0] == '--version':
 
745
        from bzrlib.version import show_version
 
746
        show_version()
 
747
        return 0
 
748
        
989
749
    if not opt_no_plugins:
 
750
        from bzrlib.plugin import load_plugins
990
751
        load_plugins()
991
752
    else:
 
753
        from bzrlib.plugin import disable_plugins
992
754
        disable_plugins()
993
755
 
994
 
    argv = argv_copy
995
 
    if (not argv):
996
 
        get_cmd_object('help').run_argv_aliases([])
997
 
        return 0
998
 
 
999
 
    if argv[0] == '--version':
1000
 
        get_cmd_object('version').run_argv_aliases([])
1001
 
        return 0
1002
 
 
1003
756
    alias_argv = None
1004
757
 
1005
758
    if not opt_no_aliases:
1006
759
        alias_argv = get_alias(argv[0])
1007
760
        if alias_argv:
1008
 
            user_encoding = osutils.get_user_encoding()
1009
 
            alias_argv = [a.decode(user_encoding) for a in alias_argv]
 
761
            alias_argv = [a.decode(bzrlib.user_encoding) for a in alias_argv]
1010
762
            argv[0] = alias_argv.pop(0)
1011
763
 
1012
764
    cmd = argv.pop(0)
1019
771
    run_argv = [argv, alias_argv]
1020
772
 
1021
773
    try:
1022
 
        # We can be called recursively (tests for example), but we don't want
1023
 
        # the verbosity level to propagate.
1024
 
        saved_verbosity_level = option._verbosity_level
1025
 
        option._verbosity_level = 0
1026
774
        if opt_lsprof:
1027
 
            if opt_coverage_dir:
1028
 
                trace.warning(
1029
 
                    '--coverage ignored, because --lsprof is in use.')
1030
775
            ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
1031
776
        elif opt_profile:
1032
 
            if opt_coverage_dir:
1033
 
                trace.warning(
1034
 
                    '--coverage ignored, because --profile is in use.')
1035
777
            ret = apply_profiled(run, *run_argv)
1036
 
        elif opt_coverage_dir:
1037
 
            ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
1038
778
        else:
1039
779
            ret = run(*run_argv)
1040
780
        return ret or 0
1041
781
    finally:
1042
 
        # reset, in case we may do other commands later within the same
1043
 
        # process. Commands that want to execute sub-commands must propagate
1044
 
        # --verbose in their own way.
1045
 
        if 'memory' in debug.debug_flags:
1046
 
            trace.debug_memory('Process status after command:', short=False)
1047
 
        option._verbosity_level = saved_verbosity_level
1048
 
 
 
782
        # reset, in case we may do other commands later within the same process
 
783
        trace.be_quiet(False)
1049
784
 
1050
785
def display_command(func):
1051
786
    """Decorator that suppresses pipe/interrupt errors."""
1067
802
    return ignore_pipe
1068
803
 
1069
804
 
1070
 
def install_bzr_command_hooks():
1071
 
    """Install the hooks to supply bzr's own commands."""
1072
 
    if _list_bzr_commands in Command.hooks["list_commands"]:
1073
 
        return
1074
 
    Command.hooks.install_named_hook("list_commands", _list_bzr_commands,
1075
 
        "bzr commands")
1076
 
    Command.hooks.install_named_hook("get_command", _get_bzr_command,
1077
 
        "bzr commands")
1078
 
    Command.hooks.install_named_hook("get_command", _get_plugin_command,
1079
 
        "bzr plugin commands")
1080
 
    Command.hooks.install_named_hook("get_command", _get_external_command,
1081
 
        "bzr external command lookup")
1082
 
    Command.hooks.install_named_hook("get_missing_command", _try_plugin_provider,
1083
 
        "bzr plugin-provider-db check")
1084
 
 
1085
 
 
1086
 
 
1087
 
def _specified_or_unicode_argv(argv):
1088
 
    # For internal or testing use, argv can be passed.  Otherwise, get it from
1089
 
    # the process arguments in a unicode-safe way.
1090
 
    if argv is None:
1091
 
        return osutils.get_unicode_argv()
1092
 
    else:
1093
 
        new_argv = []
1094
 
        try:
1095
 
            # ensure all arguments are unicode strings
1096
 
            for a in argv[1:]:
1097
 
                if isinstance(a, unicode):
1098
 
                    new_argv.append(a)
1099
 
                else:
1100
 
                    new_argv.append(a.decode('ascii'))
1101
 
        except UnicodeDecodeError:
1102
 
            raise errors.BzrError("argv should be list of unicode strings.")
1103
 
        return new_argv
1104
 
 
1105
 
 
1106
 
def main(argv=None):
1107
 
    """Main entry point of command-line interface.
1108
 
 
1109
 
    Typically `bzrlib.initialize` should be called first.
1110
 
 
1111
 
    :param argv: list of unicode command-line arguments similar to sys.argv.
1112
 
        argv[0] is script name usually, it will be ignored.
1113
 
        Don't pass here sys.argv because this list contains plain strings
1114
 
        and not unicode; pass None instead.
1115
 
 
1116
 
    :return: exit code of bzr command.
1117
 
    """
1118
 
    argv = _specified_or_unicode_argv(argv)
 
805
def main(argv):
 
806
    import bzrlib.ui
 
807
    from bzrlib.ui.text import TextUIFactory
 
808
    bzrlib.ui.ui_factory = TextUIFactory()
 
809
    argv = [a.decode(bzrlib.user_encoding) for a in argv[1:]]
1119
810
    ret = run_bzr_catch_errors(argv)
1120
 
    bzrlib.ui.ui_factory.log_transport_activity(
1121
 
        display=('bytes' in debug.debug_flags))
1122
811
    trace.mutter("return code %d", ret)
1123
812
    return ret
1124
813
 
1125
814
 
1126
815
def run_bzr_catch_errors(argv):
1127
 
    """Run a bzr command with parameters as described by argv.
1128
 
 
1129
 
    This function assumed that that UI layer is setup, that symbol deprecations
1130
 
    are already applied, and that unicode decoding has already been performed on argv.
1131
 
    """
1132
 
    # done here so that they're covered for every test run
1133
 
    install_bzr_command_hooks()
1134
 
    return exception_to_return_code(run_bzr, argv)
1135
 
 
1136
 
 
1137
 
def run_bzr_catch_user_errors(argv):
1138
 
    """Run bzr and report user errors, but let internal errors propagate.
1139
 
 
1140
 
    This is used for the test suite, and might be useful for other programs
1141
 
    that want to wrap the commandline interface.
1142
 
    """
1143
 
    # done here so that they're covered for every test run
1144
 
    install_bzr_command_hooks()
1145
816
    try:
1146
817
        return run_bzr(argv)
1147
 
    except Exception, e:
1148
 
        if (isinstance(e, (OSError, IOError))
1149
 
            or not getattr(e, 'internal_error', True)):
1150
 
            trace.report_exception(sys.exc_info(), sys.stderr)
1151
 
            return 3
1152
 
        else:
1153
 
            raise
 
818
    except (KeyboardInterrupt, Exception), e:
 
819
        # used to handle AssertionError and KeyboardInterrupt
 
820
        # specially here, but hopefully they're handled ok by the logger now
 
821
        trace.report_exception(sys.exc_info(), sys.stderr)
 
822
        if os.environ.get('BZR_PDB'):
 
823
            print '**** entering debugger'
 
824
            import pdb
 
825
            pdb.post_mortem(sys.exc_traceback)
 
826
        return 3
1154
827
 
1155
828
 
1156
829
class HelpCommandIndex(object):
1169
842
        if topic and topic.startswith(self.prefix):
1170
843
            topic = topic[len(self.prefix):]
1171
844
        try:
1172
 
            cmd = _get_cmd_object(topic, check_missing=False)
 
845
            cmd = _get_cmd_object(topic)
1173
846
        except KeyError:
1174
847
            return []
1175
848
        else:
1176
849
            return [cmd]
1177
850
 
1178
851
 
1179
 
class Provider(object):
1180
 
    '''Generic class to be overriden by plugins'''
1181
 
 
1182
 
    def plugin_for_command(self, cmd_name):
1183
 
        '''Takes a command and returns the information for that plugin
1184
 
 
1185
 
        :return: A dictionary with all the available information
1186
 
        for the requested plugin
1187
 
        '''
1188
 
        raise NotImplementedError
1189
 
 
1190
 
 
1191
 
class ProvidersRegistry(registry.Registry):
1192
 
    '''This registry exists to allow other providers to exist'''
1193
 
 
1194
 
    def __iter__(self):
1195
 
        for key, provider in self.iteritems():
1196
 
            yield provider
1197
 
 
1198
 
command_providers_registry = ProvidersRegistry()
 
852
if __name__ == '__main__':
 
853
    sys.exit(main(sys.argv))