← Back to branch summary

~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: 2008-10-31 04:39:04 UTC
  • mfrom: (3565.6.16 switch_nick)
  • Revision ID: pqm@pqm.ubuntu.com-20081031043904-52fnbfrloojemvcc
(mbp) branch nickname documentation

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/commands.py
1
 
# Copyright (C) 2004, 2005 by Canonical Ltd
2
 
 
 
1
# Copyright (C) 2006, 2008 Canonical Ltd
 
2
#
3
3
# This program is free software; you can redistribute it and/or modify
4
4
# it under the terms of the GNU General Public License as published by
5
5
# the Free Software Foundation; either version 2 of the License, or
6
6
# (at your option) any later version.
7
 
 
 
7
#
8
8
# This program is distributed in the hope that it will be useful,
9
9
# but WITHOUT ANY WARRANTY; without even the implied warranty of
10
10
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11
11
# GNU General Public License for more details.
12
 
 
 
12
#
13
13
# You should have received a copy of the GNU General Public License
14
14
# along with this program; if not, write to the Free Software
15
15
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
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.
 
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.
26
27
 
27
28
# TODO: "--profile=cum", to change sort order.  Is there any value in leaving
28
29
# the profile output behind so it can be interactively examined?
29
30
 
 
31
import os
30
32
import sys
31
 
import os
 
33
 
 
34
from bzrlib.lazy_import import lazy_import
 
35
lazy_import(globals(), """
 
36
import codecs
 
37
import errno
32
38
from warnings import warn
33
 
from inspect import getdoc
34
 
import errno
35
39
 
36
40
import bzrlib
37
 
import bzrlib.trace
38
 
from bzrlib.trace import mutter, note, log_error, warning, be_quiet
39
 
from bzrlib.errors import (BzrError, 
40
 
                           BzrCheckError,
41
 
                           BzrCommandError,
42
 
                           BzrOptionError,
43
 
                           NotBranchError)
44
 
from bzrlib.revisionspec import RevisionSpec
45
 
from bzrlib import BZRDIR
 
41
from bzrlib import (
 
42
    debug,
 
43
    errors,
 
44
    option,
 
45
    osutils,
 
46
    trace,
 
47
    win32utils,
 
48
    )
 
49
""")
 
50
 
 
51
from bzrlib import registry
 
52
# Compatibility
46
53
from bzrlib.option import Option
47
54
 
48
 
plugin_cmds = {}
 
55
 
 
56
class CommandInfo(object):
 
57
    """Information about a command."""
 
58
 
 
59
    def __init__(self, aliases):
 
60
        """The list of aliases for the command."""
 
61
        self.aliases = aliases
 
62
 
 
63
    @classmethod
 
64
    def from_command(klass, command):
 
65
        """Factory to construct a CommandInfo from a command."""
 
66
        return klass(command.aliases)
 
67
 
 
68
 
 
69
class CommandRegistry(registry.Registry):
 
70
 
 
71
    @staticmethod
 
72
    def _get_name(command_name):
 
73
        if command_name.startswith("cmd_"):
 
74
            return _unsquish_command_name(command_name)
 
75
        else:
 
76
            return command_name
 
77
 
 
78
    def register(self, cmd, decorate=False):
 
79
        """Utility function to help register a command
 
80
 
 
81
        :param cmd: Command subclass to register
 
82
        :param decorate: If true, allow overriding an existing command
 
83
            of the same name; the old command is returned by this function.
 
84
            Otherwise it is an error to try to override an existing command.
 
85
        """
 
86
        k = cmd.__name__
 
87
        k_unsquished = self._get_name(k)
 
88
        try:
 
89
            previous = self.get(k_unsquished)
 
90
        except KeyError:
 
91
            previous = _builtin_commands().get(k_unsquished)
 
92
        info = CommandInfo.from_command(cmd)
 
93
        try:
 
94
            registry.Registry.register(self, k_unsquished, cmd,
 
95
                                       override_existing=decorate, info=info)
 
96
        except KeyError:
 
97
            trace.log_error('Two plugins defined the same command: %r' % k)
 
98
            trace.log_error('Not loading the one in %r' %
 
99
                            sys.modules[cmd.__module__])
 
100
            trace.log_error('Previously this command was registered from %r' %
 
101
                            sys.modules[previous.__module__])
 
102
        return previous
 
103
 
 
104
    def register_lazy(self, command_name, aliases, module_name):
 
105
        """Register a command without loading its module.
 
106
 
 
107
        :param command_name: The primary name of the command.
 
108
        :param aliases: A list of aliases for the command.
 
109
        :module_name: The module that the command lives in.
 
110
        """
 
111
        key = self._get_name(command_name)
 
112
        registry.Registry.register_lazy(self, key, module_name, command_name,
 
113
                                        info=CommandInfo(aliases))
 
114
 
 
115
 
 
116
plugin_cmds = CommandRegistry()
49
117
 
50
118
 
51
119
def register_command(cmd, decorate=False):
52
 
    "Utility function to help register a command"
53
120
    global plugin_cmds
54
 
    k = cmd.__name__
55
 
    if k.startswith("cmd_"):
56
 
        k_unsquished = _unsquish_command_name(k)
57
 
    else:
58
 
        k_unsquished = k
59
 
    if not plugin_cmds.has_key(k_unsquished):
60
 
        plugin_cmds[k_unsquished] = cmd
61
 
        mutter('registered plugin command %s', k_unsquished)      
62
 
        if decorate and k_unsquished in builtin_command_names():
63
 
            return _builtin_commands()[k_unsquished]
64
 
    elif decorate:
65
 
        result = plugin_cmds[k_unsquished]
66
 
        plugin_cmds[k_unsquished] = cmd
67
 
        return result
68
 
    else:
69
 
        log_error('Two plugins defined the same command: %r' % k)
70
 
        log_error('Not loading the one in %r' % sys.modules[cmd.__module__])
 
121
    return plugin_cmds.register(cmd, decorate)
71
122
 
72
123
 
73
124
def _squish_command_name(cmd):
75
126
 
76
127
 
77
128
def _unsquish_command_name(cmd):
78
 
    assert cmd.startswith("cmd_")
79
129
    return cmd[4:].replace('_','-')
80
130
 
81
131
 
85
135
    builtins = bzrlib.builtins.__dict__
86
136
    for name in builtins:
87
137
        if name.startswith("cmd_"):
88
 
            real_name = _unsquish_command_name(name)        
 
138
            real_name = _unsquish_command_name(name)
89
139
            r[real_name] = builtins[name]
90
140
    return r
91
 
 
92
141
            
93
142
 
94
143
def builtin_command_names():
104
153
    """Return name->class mapping for all commands."""
105
154
    d = _builtin_commands()
106
155
    if plugins_override:
107
 
        d.update(plugin_cmds)
 
156
        d.update(plugin_cmds.iteritems())
108
157
    return d
109
158
 
110
159
    
120
169
    plugins_override
121
170
        If true, plugin commands can override builtins.
122
171
    """
 
172
    try:
 
173
        return _get_cmd_object(cmd_name, plugins_override)
 
174
    except KeyError:
 
175
        raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
 
176
 
 
177
 
 
178
def _get_cmd_object(cmd_name, plugins_override=True):
 
179
    """Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
123
180
    from bzrlib.externalcommand import ExternalCommand
124
181
 
125
 
    cmd_name = str(cmd_name)            # not unicode
 
182
    # We want only 'ascii' command names, but the user may have typed
 
183
    # in a Unicode name. In that case, they should just get a
 
184
    # 'command not found' error later.
 
185
    # In the future, we may actually support Unicode command names.
126
186
 
127
187
    # first look up this command under the specified name
128
 
    cmds = _get_cmd_dict(plugins_override=plugins_override)
 
188
    if plugins_override:
 
189
        try:
 
190
            return plugin_cmds.get(cmd_name)()
 
191
        except KeyError:
 
192
            pass
 
193
    cmds = _get_cmd_dict(plugins_override=False)
129
194
    try:
130
195
        return cmds[cmd_name]()
131
196
    except KeyError:
132
197
        pass
133
 
 
 
198
    if plugins_override:
 
199
        for key in plugin_cmds.keys():
 
200
            info = plugin_cmds.get_info(key)
 
201
            if cmd_name in info.aliases:
 
202
                return plugin_cmds.get(key)()
134
203
    # look for any command which claims this as an alias
135
204
    for real_cmd_name, cmd_class in cmds.iteritems():
136
205
        if cmd_name in cmd_class.aliases:
140
209
    if cmd_obj:
141
210
        return cmd_obj
142
211
 
143
 
    raise BzrCommandError("unknown command %r" % cmd_name)
 
212
    # look for plugins that provide this command but aren't installed
 
213
    for provider in command_providers_registry:
 
214
        try:
 
215
            plugin_metadata = provider.plugin_for_command(cmd_name)
 
216
        except errors.NoPluginAvailable:
 
217
            pass
 
218
        else:
 
219
            raise errors.CommandAvailableInPlugin(cmd_name, 
 
220
                                                  plugin_metadata, provider)
 
221
 
 
222
    raise KeyError
144
223
 
145
224
 
146
225
class Command(object):
168
247
        List of argument forms, marked with whether they are optional,
169
248
        repeated, etc.
170
249
 
171
 
                Examples:
172
 
 
173
 
                ['to_location', 'from_branch?', 'file*']
174
 
 
175
 
                'to_location' is required
176
 
                'from_branch' is optional
177
 
                'file' can be specified 0 or more times
 
250
                Examples:
 
251
 
 
252
                ['to_location', 'from_branch?', 'file*']
 
253
 
 
254
                'to_location' is required
 
255
                'from_branch' is optional
 
256
                'file' can be specified 0 or more times
178
257
 
179
258
    takes_options
180
259
        List of options that may be given for this command.  These can
184
263
    hidden
185
264
        If true, this command isn't advertised.  This is typically
186
265
        for commands intended for expert users.
 
266
 
 
267
    encoding_type
 
268
        Command objects will get a 'outf' attribute, which has been
 
269
        setup to properly handle encoding of unicode strings.
 
270
        encoding_type determines what will happen when characters cannot
 
271
        be encoded
 
272
            strict - abort if we cannot decode
 
273
            replace - put in a bogus character (typically '?')
 
274
            exact - do not encode sys.stdout
 
275
 
 
276
            NOTE: by default on Windows, sys.stdout is opened as a text
 
277
            stream, therefore LF line-endings are converted to CRLF.
 
278
            When a command uses encoding_type = 'exact', then
 
279
            sys.stdout is forced to be a binary stream, and line-endings
 
280
            will not mangled.
 
281
 
187
282
    """
188
283
    aliases = []
189
284
    takes_args = []
190
285
    takes_options = []
 
286
    encoding_type = 'strict'
191
287
 
192
288
    hidden = False
193
289
    
195
291
        """Construct an instance of this command."""
196
292
        if self.__doc__ == Command.__doc__:
197
293
            warn("No help message set for %r" % self)
 
294
        # List of standard options directly supported
 
295
        self.supported_std_options = []
 
296
 
 
297
    def _maybe_expand_globs(self, file_list):
 
298
        """Glob expand file_list if the platform does not do that itself.
 
299
        
 
300
        :return: A possibly empty list of unicode paths.
 
301
 
 
302
        Introduced in bzrlib 0.18.
 
303
        """
 
304
        if not file_list:
 
305
            file_list = []
 
306
        if sys.platform == 'win32':
 
307
            file_list = win32utils.glob_expand(file_list)
 
308
        return list(file_list)
 
309
 
 
310
    def _usage(self):
 
311
        """Return single-line grammar for this command.
 
312
 
 
313
        Only describes arguments, not options.
 
314
        """
 
315
        s = 'bzr ' + self.name() + ' '
 
316
        for aname in self.takes_args:
 
317
            aname = aname.upper()
 
318
            if aname[-1] in ['$', '+']:
 
319
                aname = aname[:-1] + '...'
 
320
            elif aname[-1] == '?':
 
321
                aname = '[' + aname[:-1] + ']'
 
322
            elif aname[-1] == '*':
 
323
                aname = '[' + aname[:-1] + '...]'
 
324
            s += aname + ' '
 
325
        s = s[:-1]      # remove last space
 
326
        return s
 
327
 
 
328
    def get_help_text(self, additional_see_also=None, plain=True,
 
329
                      see_also_as_links=False):
 
330
        """Return a text string with help for this command.
 
331
        
 
332
        :param additional_see_also: Additional help topics to be
 
333
            cross-referenced.
 
334
        :param plain: if False, raw help (reStructuredText) is
 
335
            returned instead of plain text.
 
336
        :param see_also_as_links: if True, convert items in 'See also'
 
337
            list to internal links (used by bzr_man rstx generator)
 
338
        """
 
339
        doc = self.help()
 
340
        if doc is None:
 
341
            raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
 
342
 
 
343
        # Extract the summary (purpose) and sections out from the text
 
344
        purpose,sections = self._get_help_parts(doc)
 
345
 
 
346
        # If a custom usage section was provided, use it
 
347
        if sections.has_key('Usage'):
 
348
            usage = sections.pop('Usage')
 
349
        else:
 
350
            usage = self._usage()
 
351
 
 
352
        # The header is the purpose and usage
 
353
        result = ""
 
354
        result += ':Purpose: %s\n' % purpose
 
355
        if usage.find('\n') >= 0:
 
356
            result += ':Usage:\n%s\n' % usage
 
357
        else:
 
358
            result += ':Usage:   %s\n' % usage
 
359
        result += '\n'
 
360
 
 
361
        # Add the options
 
362
        options = option.get_optparser(self.options()).format_option_help()
 
363
        if options.startswith('Options:'):
 
364
            result += ':' + options
 
365
        elif options.startswith('options:'):
 
366
            # Python 2.4 version of optparse
 
367
            result += ':Options:' + options[len('options:'):]
 
368
        else:
 
369
            result += options
 
370
        result += '\n'
 
371
 
 
372
        # Add the description, indenting it 2 spaces
 
373
        # to match the indentation of the options
 
374
        if sections.has_key(None):
 
375
            text = sections.pop(None)
 
376
            text = '\n  '.join(text.splitlines())
 
377
            result += ':%s:\n  %s\n\n' % ('Description',text)
 
378
 
 
379
        # Add the custom sections (e.g. Examples). Note that there's no need
 
380
        # to indent these as they must be indented already in the source.
 
381
        if sections:
 
382
            labels = sorted(sections.keys())
 
383
            for label in labels:
 
384
                result += ':%s:\n%s\n\n' % (label,sections[label])
 
385
 
 
386
        # Add the aliases, source (plug-in) and see also links, if any
 
387
        if self.aliases:
 
388
            result += ':Aliases:  '
 
389
            result += ', '.join(self.aliases) + '\n'
 
390
        plugin_name = self.plugin_name()
 
391
        if plugin_name is not None:
 
392
            result += ':From:     plugin "%s"\n' % plugin_name
 
393
        see_also = self.get_see_also(additional_see_also)
 
394
        if see_also:
 
395
            if not plain and see_also_as_links:
 
396
                see_also_links = []
 
397
                for item in see_also:
 
398
                    if item == 'topics':
 
399
                        # topics doesn't have an independent section
 
400
                        # so don't create a real link
 
401
                        see_also_links.append(item)
 
402
                    else:
 
403
                        # Use a reST link for this entry
 
404
                        see_also_links.append("`%s`_" % (item,))
 
405
                see_also = see_also_links
 
406
            result += ':See also: '
 
407
            result += ', '.join(see_also) + '\n'
 
408
 
 
409
        # If this will be rendered as plain text, convert it
 
410
        if plain:
 
411
            import bzrlib.help_topics
 
412
            result = bzrlib.help_topics.help_as_plain_text(result)
 
413
        return result
 
414
 
 
415
    @staticmethod
 
416
    def _get_help_parts(text):
 
417
        """Split help text into a summary and named sections.
 
418
 
 
419
        :return: (summary,sections) where summary is the top line and
 
420
            sections is a dictionary of the rest indexed by section name.
 
421
            A section starts with a heading line of the form ":xxx:".
 
422
            Indented text on following lines is the section value.
 
423
            All text found outside a named section is assigned to the
 
424
            default section which is given the key of None.
 
425
        """
 
426
        def save_section(sections, label, section):
 
427
            if len(section) > 0:
 
428
                if sections.has_key(label):
 
429
                    sections[label] += '\n' + section
 
430
                else:
 
431
                    sections[label] = section
 
432
 
 
433
        lines = text.rstrip().splitlines()
 
434
        summary = lines.pop(0)
 
435
        sections = {}
 
436
        label,section = None,''
 
437
        for line in lines:
 
438
            if line.startswith(':') and line.endswith(':') and len(line) > 2:
 
439
                save_section(sections, label, section)
 
440
                label,section = line[1:-1],''
 
441
            elif (label is not None) and len(line) > 1 and not line[0].isspace():
 
442
                save_section(sections, label, section)
 
443
                label,section = None,line
 
444
            else:
 
445
                if len(section) > 0:
 
446
                    section += '\n' + line
 
447
                else:
 
448
                    section = line
 
449
        save_section(sections, label, section)
 
450
        return summary, sections
 
451
 
 
452
    def get_help_topic(self):
 
453
        """Return the commands help topic - its name."""
 
454
        return self.name()
 
455
 
 
456
    def get_see_also(self, additional_terms=None):
 
457
        """Return a list of help topics that are related to this command.
 
458
        
 
459
        The list is derived from the content of the _see_also attribute. Any
 
460
        duplicates are removed and the result is in lexical order.
 
461
        :param additional_terms: Additional help topics to cross-reference.
 
462
        :return: A list of help topics.
 
463
        """
 
464
        see_also = set(getattr(self, '_see_also', []))
 
465
        if additional_terms:
 
466
            see_also.update(additional_terms)
 
467
        return sorted(see_also)
198
468
 
199
469
    def options(self):
200
470
        """Return dict of valid options for this command.
201
471
 
202
472
        Maps from long option name to option object."""
203
 
        r = dict()
204
 
        r['help'] = Option.OPTIONS['help']
 
473
        r = Option.STD_OPTIONS.copy()
 
474
        std_names = r.keys()
205
475
        for o in self.takes_options:
206
 
            if not isinstance(o, Option):
207
 
                o = Option.OPTIONS[o]
 
476
            if isinstance(o, basestring):
 
477
                o = option.Option.OPTIONS[o]
208
478
            r[o.name] = o
 
479
            if o.name in std_names:
 
480
                self.supported_std_options.append(o.name)
209
481
        return r
210
482
 
211
 
    def run_argv(self, argv):
212
 
        """Parse command line and run."""
213
 
        args, opts = parse_args(self, argv)
 
483
    def _setup_outf(self):
 
484
        """Return a file linked to stdout, which has proper encoding."""
 
485
        # Originally I was using self.stdout, but that looks
 
486
        # *way* too much like sys.stdout
 
487
        if self.encoding_type == 'exact':
 
488
            # force sys.stdout to be binary stream on win32
 
489
            if sys.platform == 'win32':
 
490
                fileno = getattr(sys.stdout, 'fileno', None)
 
491
                if fileno:
 
492
                    import msvcrt
 
493
                    msvcrt.setmode(fileno(), os.O_BINARY)
 
494
            self.outf = sys.stdout
 
495
            return
 
496
 
 
497
        output_encoding = osutils.get_terminal_encoding()
 
498
 
 
499
        self.outf = codecs.getwriter(output_encoding)(sys.stdout,
 
500
                        errors=self.encoding_type)
 
501
        # For whatever reason codecs.getwriter() does not advertise its encoding
 
502
        # it just returns the encoding of the wrapped file, which is completely
 
503
        # bogus. So set the attribute, so we can find the correct encoding later.
 
504
        self.outf.encoding = output_encoding
 
505
 
 
506
    def run_argv_aliases(self, argv, alias_argv=None):
 
507
        """Parse the command line and run with extra aliases in alias_argv."""
 
508
        if argv is None:
 
509
            warn("Passing None for [] is deprecated from bzrlib 0.10",
 
510
                 DeprecationWarning, stacklevel=2)
 
511
            argv = []
 
512
        args, opts = parse_args(self, argv, alias_argv)
 
513
 
 
514
        # Process the standard options
214
515
        if 'help' in opts:  # e.g. bzr add --help
215
 
            from bzrlib.help import help_on_command
216
 
            help_on_command(self.name())
 
516
            sys.stdout.write(self.get_help_text())
217
517
            return 0
218
 
        # XXX: This should be handled by the parser
219
 
        allowed_names = self.options().keys()
220
 
        for oname in opts:
221
 
            if oname not in allowed_names:
222
 
                raise BzrCommandError("option '--%s' is not allowed for command %r"
223
 
                                      % (oname, self.name()))
 
518
        trace.set_verbosity_level(option._verbosity_level)
 
519
        if 'verbose' in self.supported_std_options:
 
520
            opts['verbose'] = trace.is_verbose()
 
521
        elif opts.has_key('verbose'):
 
522
            del opts['verbose']
 
523
        if 'quiet' in self.supported_std_options:
 
524
            opts['quiet'] = trace.is_quiet()
 
525
        elif opts.has_key('quiet'):
 
526
            del opts['quiet']
 
527
 
224
528
        # mix arguments and options into one dictionary
225
529
        cmdargs = _match_argform(self.name(), self.takes_args, args)
226
530
        cmdopts = {}
230
534
        all_cmd_args = cmdargs.copy()
231
535
        all_cmd_args.update(cmdopts)
232
536
 
 
537
        self._setup_outf()
 
538
 
233
539
        return self.run(**all_cmd_args)
234
 
    
 
540
 
235
541
    def run(self):
236
542
        """Actually run the command.
237
543
 
242
548
        shell error code if not.  It's OK for this method to allow
243
549
        an exception to raise up.
244
550
        """
245
 
        raise NotImplementedError()
246
 
 
 
551
        raise NotImplementedError('no implementation of command %r'
 
552
                                  % self.name())
247
553
 
248
554
    def help(self):
249
555
        """Return help message for this class."""
 
556
        from inspect import getdoc
250
557
        if self.__doc__ is Command.__doc__:
251
558
            return None
252
559
        return getdoc(self)
254
561
    def name(self):
255
562
        return _unsquish_command_name(self.__class__.__name__)
256
563
 
 
564
    def plugin_name(self):
 
565
        """Get the name of the plugin that provides this command.
257
566
 
258
 
def parse_spec(spec):
259
 
    """
260
 
    >>> parse_spec(None)
261
 
    [None, None]
262
 
    >>> parse_spec("./")
263
 
    ['./', None]
264
 
    >>> parse_spec("../@")
265
 
    ['..', -1]
266
 
    >>> parse_spec("../f/@35")
267
 
    ['../f', 35]
268
 
    >>> parse_spec('./@revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67')
269
 
    ['.', 'revid:john@arbash-meinel.com-20050711044610-3ca0327c6a222f67']
270
 
    """
271
 
    if spec is None:
272
 
        return [None, None]
273
 
    if '/@' in spec:
274
 
        parsed = spec.split('/@')
275
 
        assert len(parsed) == 2
276
 
        if parsed[1] == "":
277
 
            parsed[1] = -1
 
567
        :return: The name of the plugin or None if the command is builtin.
 
568
        """
 
569
        mod_parts = self.__module__.split('.')
 
570
        if len(mod_parts) >= 3 and mod_parts[1] == 'plugins':
 
571
            return mod_parts[2]
278
572
        else:
279
 
            try:
280
 
                parsed[1] = int(parsed[1])
281
 
            except ValueError:
282
 
                pass # We can allow stuff like ./@revid:blahblahblah
283
 
            else:
284
 
                assert parsed[1] >=0
285
 
    else:
286
 
        parsed = [spec, None]
287
 
    return parsed
288
 
 
289
 
def parse_args(command, argv):
 
573
            return None
 
574
 
 
575
 
 
576
def parse_args(command, argv, alias_argv=None):
290
577
    """Parse command line.
291
578
    
292
579
    Arguments and options are parsed at this level before being passed
294
581
    lookup table, something about the available options, what optargs
295
582
    they take, and which commands will accept them.
296
583
    """
297
 
    # TODO: chop up this beast; make it a method of the Command
298
 
    args = []
299
 
    opts = {}
300
 
 
301
 
    cmd_options = command.options()
302
 
    argsover = False
303
 
    while argv:
304
 
        a = argv.pop(0)
305
 
        if argsover:
306
 
            args.append(a)
307
 
            continue
308
 
        elif a == '--':
309
 
            # We've received a standalone -- No more flags
310
 
            argsover = True
311
 
            continue
312
 
        if a[0] == '-':
313
 
            # option names must not be unicode
314
 
            a = str(a)
315
 
            optarg = None
316
 
            if a[1] == '-':
317
 
                mutter("  got option %r", a)
318
 
                if '=' in a:
319
 
                    optname, optarg = a[2:].split('=', 1)
320
 
                else:
321
 
                    optname = a[2:]
322
 
                if optname not in cmd_options:
323
 
                    raise BzrOptionError('unknown long option %r for command %s'
324
 
                        % (a, command.name()))
325
 
            else:
326
 
                shortopt = a[1:]
327
 
                if shortopt in Option.SHORT_OPTIONS:
328
 
                    # Multi-character options must have a space to delimit
329
 
                    # their value
330
 
                    # ^^^ what does this mean? mbp 20051014
331
 
                    optname = Option.SHORT_OPTIONS[shortopt].name
332
 
                else:
333
 
                    # Single character short options, can be chained,
334
 
                    # and have their value appended to their name
335
 
                    shortopt = a[1:2]
336
 
                    if shortopt not in Option.SHORT_OPTIONS:
337
 
                        # We didn't find the multi-character name, and we
338
 
                        # didn't find the single char name
339
 
                        raise BzrError('unknown short option %r' % a)
340
 
                    optname = Option.SHORT_OPTIONS[shortopt].name
341
 
 
342
 
                    if a[2:]:
343
 
                        # There are extra things on this option
344
 
                        # see if it is the value, or if it is another
345
 
                        # short option
346
 
                        optargfn = Option.OPTIONS[optname].type
347
 
                        if optargfn is None:
348
 
                            # This option does not take an argument, so the
349
 
                            # next entry is another short option, pack it back
350
 
                            # into the list
351
 
                            argv.insert(0, '-' + a[2:])
352
 
                        else:
353
 
                            # This option takes an argument, so pack it
354
 
                            # into the array
355
 
                            optarg = a[2:]
356
 
            
357
 
                if optname not in cmd_options:
358
 
                    raise BzrOptionError('unknown short option %r for command'
359
 
                        ' %s' % (shortopt, command.name()))
360
 
            if optname in opts:
361
 
                # XXX: Do we ever want to support this, e.g. for -r?
362
 
                raise BzrError('repeated option %r' % a)
363
 
                
364
 
            option_obj = cmd_options[optname]
365
 
            optargfn = option_obj.type
366
 
            if optargfn:
367
 
                if optarg == None:
368
 
                    if not argv:
369
 
                        raise BzrError('option %r needs an argument' % a)
370
 
                    else:
371
 
                        optarg = argv.pop(0)
372
 
                opts[optname] = optargfn(optarg)
373
 
            else:
374
 
                if optarg != None:
375
 
                    raise BzrError('option %r takes no argument' % optname)
376
 
                opts[optname] = True
377
 
        else:
378
 
            args.append(a)
 
584
    # TODO: make it a method of the Command?
 
585
    parser = option.get_optparser(command.options())
 
586
    if alias_argv is not None:
 
587
        args = alias_argv + argv
 
588
    else:
 
589
        args = argv
 
590
 
 
591
    options, args = parser.parse_args(args)
 
592
    opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
 
593
                 v is not option.OptionParser.DEFAULT_VALUE])
379
594
    return args, opts
380
595
 
381
596
 
396
611
                argdict[argname + '_list'] = None
397
612
        elif ap[-1] == '+':
398
613
            if not args:
399
 
                raise BzrCommandError("command %r needs one or more %s"
400
 
                        % (cmd, argname.upper()))
 
614
                raise errors.BzrCommandError("command %r needs one or more %s"
 
615
                                             % (cmd, argname.upper()))
401
616
            else:
402
617
                argdict[argname + '_list'] = args[:]
403
618
                args = []
404
619
        elif ap[-1] == '$': # all but one
405
620
            if len(args) < 2:
406
 
                raise BzrCommandError("command %r needs one or more %s"
407
 
                        % (cmd, argname.upper()))
 
621
                raise errors.BzrCommandError("command %r needs one or more %s"
 
622
                                             % (cmd, argname.upper()))
408
623
            argdict[argname + '_list'] = args[:-1]
409
 
            args[:-1] = []                
 
624
            args[:-1] = []
410
625
        else:
411
626
            # just a plain arg
412
627
            argname = ap
413
628
            if not args:
414
 
                raise BzrCommandError("command %r requires argument %s"
415
 
                        % (cmd, argname.upper()))
 
629
                raise errors.BzrCommandError("command %r requires argument %s"
 
630
                               % (cmd, argname.upper()))
416
631
            else:
417
632
                argdict[argname] = args.pop(0)
418
633
            
419
634
    if args:
420
 
        raise BzrCommandError("extra argument to command %s: %s"
421
 
                              % (cmd, args[0]))
 
635
        raise errors.BzrCommandError("extra argument to command %s: %s"
 
636
                                     % (cmd, args[0]))
422
637
 
423
638
    return argdict
424
639
 
 
640
def apply_coveraged(dirname, the_callable, *args, **kwargs):
 
641
    # Cannot use "import trace", as that would import bzrlib.trace instead of
 
642
    # the standard library's trace.
 
643
    trace = __import__('trace')
 
644
 
 
645
    tracer = trace.Trace(count=1, trace=0)
 
646
    sys.settrace(tracer.globaltrace)
 
647
 
 
648
    ret = the_callable(*args, **kwargs)
 
649
 
 
650
    sys.settrace(None)
 
651
    results = tracer.results()
 
652
    results.write_results(show_missing=1, summary=False,
 
653
                          coverdir=dirname)
425
654
 
426
655
 
427
656
def apply_profiled(the_callable, *args, **kwargs):
447
676
        os.remove(pfname)
448
677
 
449
678
 
 
679
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
 
680
    from bzrlib.lsprof import profile
 
681
    ret, stats = profile(the_callable, *args, **kwargs)
 
682
    stats.sort()
 
683
    if filename is None:
 
684
        stats.pprint()
 
685
    else:
 
686
        stats.save(filename)
 
687
        trace.note('Profile data written to "%s".', filename)
 
688
    return ret
 
689
 
 
690
 
 
691
def shlex_split_unicode(unsplit):
 
692
    import shlex
 
693
    return [u.decode('utf-8') for u in shlex.split(unsplit.encode('utf-8'))]
 
694
 
 
695
 
 
696
def get_alias(cmd, config=None):
 
697
    """Return an expanded alias, or None if no alias exists.
 
698
 
 
699
    cmd
 
700
        Command to be checked for an alias.
 
701
    config
 
702
        Used to specify an alternative config to use,
 
703
        which is especially useful for testing.
 
704
        If it is unspecified, the global config will be used.
 
705
    """
 
706
    if config is None:
 
707
        import bzrlib.config
 
708
        config = bzrlib.config.GlobalConfig()
 
709
    alias = config.get_alias(cmd)
 
710
    if (alias):
 
711
        return shlex_split_unicode(alias)
 
712
    return None
 
713
 
 
714
 
450
715
def run_bzr(argv):
451
716
    """Execute a command.
452
717
 
453
 
    This is similar to main(), but without all the trappings for
454
 
    logging and error handling.  
455
 
    
456
718
    argv
457
719
       The command-line arguments, without the program name from argv[0]
 
720
       These should already be decoded. All library/test code calling
 
721
       run_bzr should be passing valid strings (don't need decoding).
458
722
    
459
723
    Returns a command status or raises an exception.
460
724
 
464
728
    --no-plugins
465
729
        Do not load plugin modules at all
466
730
 
 
731
    --no-aliases
 
732
        Do not allow aliases
 
733
 
467
734
    --builtin
468
735
        Only use builtin commands.  (Plugins are still allowed to change
469
736
        other behaviour.)
470
737
 
471
738
    --profile
472
 
        Run under the Python profiler.
 
739
        Run under the Python hotshot profiler.
 
740
 
 
741
    --lsprof
 
742
        Run under the Python lsprof profiler.
 
743
 
 
744
    --coverage
 
745
        Generate line coverage report in the specified directory.
473
746
    """
474
 
    argv = [a.decode(bzrlib.user_encoding) for a in argv]
 
747
    argv = list(argv)
 
748
    trace.mutter("bzr arguments: %r", argv)
475
749
 
476
 
    opt_profile = opt_no_plugins = opt_builtin = False
 
750
    opt_lsprof = opt_profile = opt_no_plugins = opt_builtin =  \
 
751
                opt_no_aliases = False
 
752
    opt_lsprof_file = opt_coverage_dir = None
477
753
 
478
754
    # --no-plugins is handled specially at a very early stage. We need
479
755
    # to load plugins before doing other command parsing so that they
480
756
    # can override commands, but this needs to happen first.
481
757
 
482
 
    for a in argv:
 
758
    argv_copy = []
 
759
    i = 0
 
760
    while i < len(argv):
 
761
        a = argv[i]
483
762
        if a == '--profile':
484
763
            opt_profile = True
 
764
        elif a == '--lsprof':
 
765
            opt_lsprof = True
 
766
        elif a == '--lsprof-file':
 
767
            opt_lsprof = True
 
768
            opt_lsprof_file = argv[i + 1]
 
769
            i += 1
485
770
        elif a == '--no-plugins':
486
771
            opt_no_plugins = True
 
772
        elif a == '--no-aliases':
 
773
            opt_no_aliases = True
487
774
        elif a == '--builtin':
488
775
            opt_builtin = True
489
 
        elif a in ('--quiet', '-q'):
490
 
            be_quiet()
 
776
        elif a == '--coverage':
 
777
            opt_coverage_dir = argv[i + 1]
 
778
            i += 1
 
779
        elif a.startswith('-D'):
 
780
            debug.debug_flags.add(a[2:])
491
781
        else:
492
 
            continue
493
 
        argv.remove(a)
 
782
            argv_copy.append(a)
 
783
        i += 1
494
784
 
495
 
    if (not argv) or (argv[0] == '--help'):
496
 
        from bzrlib.help import help
497
 
        if len(argv) > 1:
498
 
            help(argv[1])
499
 
        else:
500
 
            help()
 
785
    argv = argv_copy
 
786
    if (not argv):
 
787
        from bzrlib.builtins import cmd_help
 
788
        cmd_help().run_argv_aliases([])
501
789
        return 0
502
790
 
503
791
    if argv[0] == '--version':
504
 
        from bzrlib.builtins import show_version
505
 
        show_version()
 
792
        from bzrlib.builtins import cmd_version
 
793
        cmd_version().run_argv_aliases([])
506
794
        return 0
507
 
        
 
795
 
508
796
    if not opt_no_plugins:
509
797
        from bzrlib.plugin import load_plugins
510
798
        load_plugins()
511
 
 
512
 
    cmd = str(argv.pop(0))
 
799
    else:
 
800
        from bzrlib.plugin import disable_plugins
 
801
        disable_plugins()
 
802
 
 
803
    alias_argv = None
 
804
 
 
805
    if not opt_no_aliases:
 
806
        alias_argv = get_alias(argv[0])
 
807
        if alias_argv:
 
808
            user_encoding = osutils.get_user_encoding()
 
809
            alias_argv = [a.decode(user_encoding) for a in alias_argv]
 
810
            argv[0] = alias_argv.pop(0)
 
811
 
 
812
    cmd = argv.pop(0)
 
813
    # We want only 'ascii' command names, but the user may have typed
 
814
    # in a Unicode name. In that case, they should just get a
 
815
    # 'command not found' error later.
513
816
 
514
817
    cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
 
818
    run = cmd_obj.run_argv_aliases
 
819
    run_argv = [argv, alias_argv]
515
820
 
516
821
    try:
517
 
        if opt_profile:
518
 
            ret = apply_profiled(cmd_obj.run_argv, argv)
 
822
        # We can be called recursively (tests for example), but we don't want
 
823
        # the verbosity level to propagate.
 
824
        saved_verbosity_level = option._verbosity_level
 
825
        option._verbosity_level = 0
 
826
        if opt_lsprof:
 
827
            if opt_coverage_dir:
 
828
                trace.warning(
 
829
                    '--coverage ignored, because --lsprof is in use.')
 
830
            ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
 
831
        elif opt_profile:
 
832
            if opt_coverage_dir:
 
833
                trace.warning(
 
834
                    '--coverage ignored, because --profile is in use.')
 
835
            ret = apply_profiled(run, *run_argv)
 
836
        elif opt_coverage_dir:
 
837
            ret = apply_coveraged(opt_coverage_dir, run, *run_argv)
519
838
        else:
520
 
            ret = cmd_obj.run_argv(argv)
 
839
            ret = run(*run_argv)
 
840
        if 'memory' in debug.debug_flags:
 
841
            trace.debug_memory('Process status after command:', short=False)
521
842
        return ret or 0
522
843
    finally:
523
 
        # reset, in case we may do other commands later within the same process
524
 
        be_quiet(False)
 
844
        # reset, in case we may do other commands later within the same
 
845
        # process. Commands that want to execute sub-commands must propagate
 
846
        # --verbose in their own way.
 
847
        option._verbosity_level = saved_verbosity_level
525
848
 
526
849
def display_command(func):
527
850
    """Decorator that suppresses pipe/interrupt errors."""
531
854
            sys.stdout.flush()
532
855
            return result
533
856
        except IOError, e:
534
 
            if not hasattr(e, 'errno'):
 
857
            if getattr(e, 'errno', None) is None:
535
858
                raise
536
859
            if e.errno != errno.EPIPE:
537
 
                raise
 
860
                # Win32 raises IOError with errno=0 on a broken pipe
 
861
                if sys.platform != 'win32' or (e.errno not in (0, errno.EINVAL)):
 
862
                    raise
538
863
            pass
539
864
        except KeyboardInterrupt:
540
865
            pass
544
869
def main(argv):
545
870
    import bzrlib.ui
546
871
    from bzrlib.ui.text import TextUIFactory
547
 
    ## bzrlib.trace.enable_default_logging()
548
 
    bzrlib.trace.log_startup(argv)
549
872
    bzrlib.ui.ui_factory = TextUIFactory()
550
 
    ret = run_bzr_catch_errors(argv[1:])
551
 
    mutter("return code %d", ret)
 
873
 
 
874
    # Is this a final release version? If so, we should suppress warnings
 
875
    if bzrlib.version_info[3] == 'final':
 
876
        from bzrlib import symbol_versioning
 
877
        symbol_versioning.suppress_deprecation_warnings(override=False)
 
878
    try:
 
879
        user_encoding = osutils.get_user_encoding()
 
880
        argv = [a.decode(user_encoding) for a in argv[1:]]
 
881
    except UnicodeDecodeError:
 
882
        raise errors.BzrError(("Parameter '%r' is unsupported by the current "
 
883
                                                            "encoding." % a))
 
884
    ret = run_bzr_catch_errors(argv)
 
885
    trace.mutter("return code %d", ret)
552
886
    return ret
553
887
 
554
888
 
555
889
def run_bzr_catch_errors(argv):
 
890
    # Note: The except clause logic below should be kept in sync with the
 
891
    # profile() routine in lsprof.py.
556
892
    try:
557
 
        try:
558
 
            return run_bzr(argv)
559
 
        finally:
560
 
            # do this here inside the exception wrappers to catch EPIPE
561
 
            sys.stdout.flush()
562
 
    except Exception, e:
 
893
        return run_bzr(argv)
 
894
    except (KeyboardInterrupt, Exception), e:
563
895
        # used to handle AssertionError and KeyboardInterrupt
564
896
        # specially here, but hopefully they're handled ok by the logger now
565
 
        import errno
566
 
        if (isinstance(e, IOError) 
567
 
            and hasattr(e, 'errno')
568
 
            and e.errno == errno.EPIPE):
569
 
            bzrlib.trace.note('broken pipe')
570
 
            return 3
571
 
        else:
572
 
            bzrlib.trace.log_exception()
573
 
            if os.environ.get('BZR_PDB'):
574
 
                print '**** entering debugger'
575
 
                import pdb
576
 
                pdb.post_mortem(sys.exc_traceback)
577
 
            return 3
 
897
        exitcode = trace.report_exception(sys.exc_info(), sys.stderr)
 
898
        if os.environ.get('BZR_PDB'):
 
899
            print '**** entering debugger'
 
900
            import pdb
 
901
            pdb.post_mortem(sys.exc_traceback)
 
902
        return exitcode
 
903
 
 
904
 
 
905
def run_bzr_catch_user_errors(argv):
 
906
    """Run bzr and report user errors, but let internal errors propagate.
 
907
 
 
908
    This is used for the test suite, and might be useful for other programs
 
909
    that want to wrap the commandline interface.
 
910
    """
 
911
    try:
 
912
        return run_bzr(argv)
 
913
    except Exception, e:
 
914
        if (isinstance(e, (OSError, IOError))
 
915
            or not getattr(e, 'internal_error', True)):
 
916
            trace.report_exception(sys.exc_info(), sys.stderr)
 
917
            return 3
 
918
        else:
 
919
            raise
 
920
 
 
921
 
 
922
class HelpCommandIndex(object):
 
923
    """A index for bzr help that returns commands."""
 
924
 
 
925
    def __init__(self):
 
926
        self.prefix = 'commands/'
 
927
 
 
928
    def get_topics(self, topic):
 
929
        """Search for topic amongst commands.
 
930
 
 
931
        :param topic: A topic to search for.
 
932
        :return: A list which is either empty or contains a single
 
933
            Command entry.
 
934
        """
 
935
        if topic and topic.startswith(self.prefix):
 
936
            topic = topic[len(self.prefix):]
 
937
        try:
 
938
            cmd = _get_cmd_object(topic)
 
939
        except KeyError:
 
940
            return []
 
941
        else:
 
942
            return [cmd]
 
943
 
 
944
 
 
945
class Provider(object):
 
946
    '''Generic class to be overriden by plugins'''
 
947
 
 
948
    def plugin_for_command(self, cmd_name):
 
949
        '''Takes a command and returns the information for that plugin
 
950
        
 
951
        :return: A dictionary with all the available information 
 
952
        for the requested plugin
 
953
        '''
 
954
        raise NotImplementedError
 
955
 
 
956
 
 
957
class ProvidersRegistry(registry.Registry):
 
958
    '''This registry exists to allow other providers to exist'''
 
959
 
 
960
    def __iter__(self):
 
961
        for key, provider in self.iteritems():
 
962
            yield provider
 
963
 
 
964
command_providers_registry = ProvidersRegistry()
 
965
 
578
966
 
579
967
if __name__ == '__main__':
580
968
    sys.exit(main(sys.argv))