1
# Copyright (C) 2006 Canonical Ltd
1
# Copyright (C) 2004, 2005 by Canonical Ltd
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.
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.
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.
21
# TODO: Help messages for options.
21
23
# TODO: Define arguments by objects, rather than just using names.
22
24
# Those objects can specify the expected type of the argument, which
23
# would help with validation and shell completion. They could also provide
24
# help/explanation for that argument in a structured way.
26
# TODO: Specific "examples" property on commands for consistent formatting.
25
# would help with validation and shell completion.
28
27
# TODO: "--profile=cum", to change sort order. Is there any value in leaving
29
28
# the profile output behind so it can be interactively examined?
34
from bzrlib.lazy_import import lazy_import
35
lazy_import(globals(), """
32
from warnings import warn
33
from inspect import getdoc
38
from warnings import warn
50
from bzrlib.symbol_versioning import (
38
from bzrlib.trace import mutter, note, log_error, warning, be_quiet
39
from bzrlib.errors import (BzrError,
44
from bzrlib.revisionspec import RevisionSpec
45
from bzrlib import BZRDIR
57
46
from bzrlib.option import Option
63
51
def register_command(cmd, decorate=False):
64
"""Utility function to help register a command
66
:param cmd: Command subclass to register
67
:param decorate: If true, allow overriding an existing command
68
of the same name; the old command is returned by this function.
69
Otherwise it is an error to try to override an existing command.
52
"Utility function to help register a command"
73
55
if k.startswith("cmd_"):
74
56
k_unsquished = _unsquish_command_name(k)
77
if k_unsquished not in plugin_cmds:
59
if not plugin_cmds.has_key(k_unsquished):
78
60
plugin_cmds[k_unsquished] = cmd
79
## trace.mutter('registered plugin command %s', k_unsquished)
61
mutter('registered plugin command %s', k_unsquished)
80
62
if decorate and k_unsquished in builtin_command_names():
81
63
return _builtin_commands()[k_unsquished]
138
121
If true, plugin commands can override builtins.
141
return _get_cmd_object(cmd_name, plugins_override)
143
raise errors.BzrCommandError('unknown command "%s"' % cmd_name)
146
def _get_cmd_object(cmd_name, plugins_override=True):
147
"""Worker for get_cmd_object which raises KeyError rather than BzrCommandError."""
148
123
from bzrlib.externalcommand import ExternalCommand
150
# We want only 'ascii' command names, but the user may have typed
151
# in a Unicode name. In that case, they should just get a
152
# 'command not found' error later.
153
# In the future, we may actually support Unicode command names.
125
cmd_name = str(cmd_name) # not unicode
155
127
# first look up this command under the specified name
156
128
cmds = _get_cmd_dict(plugins_override=plugins_override)
212
185
If true, this command isn't advertised. This is typically
213
186
for commands intended for expert users.
216
Command objects will get a 'outf' attribute, which has been
217
setup to properly handle encoding of unicode strings.
218
encoding_type determines what will happen when characters cannot
220
strict - abort if we cannot decode
221
replace - put in a bogus character (typically '?')
222
exact - do not encode sys.stdout
224
NOTE: by default on Windows, sys.stdout is opened as a text
225
stream, therefore LF line-endings are converted to CRLF.
226
When a command uses encoding_type = 'exact', then
227
sys.stdout is forced to be a binary stream, and line-endings
233
190
takes_options = []
234
encoding_type = 'strict'
240
196
if self.__doc__ == Command.__doc__:
241
197
warn("No help message set for %r" % self)
244
"""Return single-line grammar for this command.
246
Only describes arguments, not options.
248
s = 'bzr ' + self.name() + ' '
249
for aname in self.takes_args:
250
aname = aname.upper()
251
if aname[-1] in ['$', '+']:
252
aname = aname[:-1] + '...'
253
elif aname[-1] == '?':
254
aname = '[' + aname[:-1] + ']'
255
elif aname[-1] == '*':
256
aname = '[' + aname[:-1] + '...]'
263
def get_help_text(self, additional_see_also=None):
264
"""Return a text string with help for this command.
266
:param additional_see_also: Additional help topics to be
271
raise NotImplementedError("sorry, no detailed help yet for %r" % self.name())
274
result += 'usage: %s\n' % self._usage()
277
result += 'aliases: '
278
result += ', '.join(self.aliases) + '\n'
282
plugin_name = self.plugin_name()
283
if plugin_name is not None:
284
result += '(From plugin "%s")' % plugin_name
288
if result[-1] != '\n':
291
result += option.get_optparser(self.options()).format_option_help()
292
see_also = self.get_see_also(additional_see_also)
294
result += '\nSee also: '
295
result += ', '.join(see_also)
299
def get_help_topic(self):
300
"""Return the commands help topic - its name."""
303
def get_see_also(self, additional_terms=None):
304
"""Return a list of help topics that are related to this ommand.
306
The list is derived from the content of the _see_also attribute. Any
307
duplicates are removed and the result is in lexical order.
308
:param additional_terms: Additional help topics to cross-reference.
309
:return: A list of help topics.
311
see_also = set(getattr(self, '_see_also', []))
313
see_also.update(additional_terms)
314
return sorted(see_also)
316
199
def options(self):
317
200
"""Return dict of valid options for this command.
319
202
Maps from long option name to option object."""
321
r['help'] = option.Option.OPTIONS['help']
204
r['help'] = Option.OPTIONS['help']
322
205
for o in self.takes_options:
323
if isinstance(o, basestring):
324
o = option.Option.OPTIONS[o]
206
if not isinstance(o, Option):
207
o = Option.OPTIONS[o]
328
def _setup_outf(self):
329
"""Return a file linked to stdout, which has proper encoding."""
330
assert self.encoding_type in ['strict', 'exact', 'replace']
332
# Originally I was using self.stdout, but that looks
333
# *way* too much like sys.stdout
334
if self.encoding_type == 'exact':
335
# force sys.stdout to be binary stream on win32
336
if sys.platform == 'win32':
337
fileno = getattr(sys.stdout, 'fileno', None)
340
msvcrt.setmode(fileno(), os.O_BINARY)
341
self.outf = sys.stdout
344
output_encoding = osutils.get_terminal_encoding()
346
# use 'replace' so that we don't abort if trying to write out
347
# in e.g. the default C locale.
348
self.outf = codecs.getwriter(output_encoding)(sys.stdout, errors=self.encoding_type)
349
# For whatever reason codecs.getwriter() does not advertise its encoding
350
# it just returns the encoding of the wrapped file, which is completely
351
# bogus. So set the attribute, so we can find the correct encoding later.
352
self.outf.encoding = output_encoding
354
def run_argv_aliases(self, argv, alias_argv=None):
355
"""Parse the command line and run with extra aliases in alias_argv."""
357
warn("Passing None for [] is deprecated from bzrlib 0.10",
358
DeprecationWarning, stacklevel=2)
360
args, opts = parse_args(self, argv, alias_argv)
211
def run_argv(self, argv):
212
"""Parse command line and run."""
213
args, opts = parse_args(self, argv)
361
214
if 'help' in opts: # e.g. bzr add --help
362
sys.stdout.write(self.get_help_text())
215
from bzrlib.help import help_on_command
216
help_on_command(self.name())
218
# XXX: This should be handled by the parser
219
allowed_names = self.options().keys()
221
if oname not in allowed_names:
222
raise BzrCommandError("option '--%s' is not allowed for command %r"
223
% (oname, self.name()))
364
224
# mix arguments and options into one dictionary
365
225
cmdargs = _match_argform(self.name(), self.takes_args, args)
451
294
lookup table, something about the available options, what optargs
452
295
they take, and which commands will accept them.
454
# TODO: make it a method of the Command?
455
parser = option.get_optparser(command.options())
456
if alias_argv is not None:
457
args = alias_argv + argv
461
options, args = parser.parse_args(args)
462
opts = dict([(k, v) for k, v in options.__dict__.iteritems() if
463
v is not option.OptionParser.DEFAULT_VALUE])
297
# TODO: chop up this beast; make it a method of the Command
301
cmd_options = command.options()
309
# We've received a standalone -- No more flags
313
# option names must not be unicode
317
mutter(" got option %r", a)
319
optname, optarg = a[2:].split('=', 1)
322
if optname not in cmd_options:
323
raise BzrOptionError('unknown long option %r for command %s'
324
% (a, command.name()))
327
if shortopt in Option.SHORT_OPTIONS:
328
# Multi-character options must have a space to delimit
330
# ^^^ what does this mean? mbp 20051014
331
optname = Option.SHORT_OPTIONS[shortopt].name
333
# Single character short options, can be chained,
334
# and have their value appended to their name
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
343
# There are extra things on this option
344
# see if it is the value, or if it is another
346
optargfn = Option.OPTIONS[optname].type
348
# This option does not take an argument, so the
349
# next entry is another short option, pack it back
351
argv.insert(0, '-' + a[2:])
353
# This option takes an argument, so pack it
357
if optname not in cmd_options:
358
raise BzrOptionError('unknown short option %r for command'
359
' %s' % (shortopt, command.name()))
361
# XXX: Do we ever want to support this, e.g. for -r?
362
raise BzrError('repeated option %r' % a)
364
option_obj = cmd_options[optname]
365
optargfn = option_obj.type
369
raise BzrError('option %r needs an argument' % a)
372
opts[optname] = optargfn(optarg)
375
raise BzrError('option %r takes no argument' % optname)
464
379
return args, opts
481
396
argdict[argname + '_list'] = None
482
397
elif ap[-1] == '+':
484
raise errors.BzrCommandError("command %r needs one or more %s"
485
% (cmd, argname.upper()))
399
raise BzrCommandError("command %r needs one or more %s"
400
% (cmd, argname.upper()))
487
402
argdict[argname + '_list'] = args[:]
489
404
elif ap[-1] == '$': # all but one
490
405
if len(args) < 2:
491
raise errors.BzrCommandError("command %r needs one or more %s"
492
% (cmd, argname.upper()))
406
raise BzrCommandError("command %r needs one or more %s"
407
% (cmd, argname.upper()))
493
408
argdict[argname + '_list'] = args[:-1]
496
411
# just a plain arg
499
raise errors.BzrCommandError("command %r requires argument %s"
500
% (cmd, argname.upper()))
414
raise BzrCommandError("command %r requires argument %s"
415
% (cmd, argname.upper()))
502
417
argdict[argname] = args.pop(0)
505
raise errors.BzrCommandError("extra argument to command %s: %s"
420
raise BzrCommandError("extra argument to command %s: %s"
532
447
os.remove(pfname)
535
def apply_lsprofiled(filename, the_callable, *args, **kwargs):
536
from bzrlib.lsprof import profile
538
ret, stats = profile(the_callable, *args, **kwargs)
544
cPickle.dump(stats, open(filename, 'w'), 2)
545
print 'Profile data written to %r.' % filename
549
def get_alias(cmd, config=None):
550
"""Return an expanded alias, or None if no alias exists.
553
Command to be checked for an alias.
555
Used to specify an alternative config to use,
556
which is especially useful for testing.
557
If it is unspecified, the global config will be used.
561
config = bzrlib.config.GlobalConfig()
562
alias = config.get_alias(cmd)
565
return [a.decode('utf-8') for a in shlex.split(alias.encode('utf-8'))]
569
450
def run_bzr(argv):
570
451
"""Execute a command.
586
465
Do not load plugin modules at all
592
468
Only use builtin commands. (Plugins are still allowed to change
593
469
other behaviour.)
596
Run under the Python hotshot profiler.
599
Run under the Python lsprof profiler.
472
Run under the Python profiler.
602
trace.mutter("bzr arguments: %r", argv)
474
argv = [a.decode(bzrlib.user_encoding) for a in argv]
604
opt_lsprof = opt_profile = opt_no_plugins = opt_builtin = \
605
opt_no_aliases = False
606
opt_lsprof_file = None
476
opt_profile = opt_no_plugins = opt_builtin = False
608
478
# --no-plugins is handled specially at a very early stage. We need
609
479
# to load plugins before doing other command parsing so that they
610
480
# can override commands, but this needs to happen first.
616
483
if a == '--profile':
617
484
opt_profile = True
618
elif a == '--lsprof':
620
elif a == '--lsprof-file':
622
opt_lsprof_file = argv[i + 1]
624
485
elif a == '--no-plugins':
625
486
opt_no_plugins = True
626
elif a == '--no-aliases':
627
opt_no_aliases = True
628
487
elif a == '--builtin':
629
488
opt_builtin = True
630
489
elif a in ('--quiet', '-q'):
632
elif a.startswith('-D'):
633
debug.debug_flags.add(a[2:])
640
from bzrlib.builtins import cmd_help
641
cmd_help().run_argv_aliases([])
495
if (not argv) or (argv[0] == '--help'):
496
from bzrlib.help import help
644
503
if argv[0] == '--version':
645
from bzrlib.version import show_version
504
from bzrlib.builtins import show_version
649
508
if not opt_no_plugins:
650
509
from bzrlib.plugin import load_plugins
653
from bzrlib.plugin import disable_plugins
658
if not opt_no_aliases:
659
alias_argv = get_alias(argv[0])
661
alias_argv = [a.decode(bzrlib.user_encoding) for a in alias_argv]
662
argv[0] = alias_argv.pop(0)
665
# We want only 'ascii' command names, but the user may have typed
666
# in a Unicode name. In that case, they should just get a
667
# 'command not found' error later.
512
cmd = str(argv.pop(0))
669
514
cmd_obj = get_cmd_object(cmd, plugins_override=not opt_builtin)
670
run = cmd_obj.run_argv_aliases
671
run_argv = [argv, alias_argv]
675
ret = apply_lsprofiled(opt_lsprof_file, run, *run_argv)
677
ret = apply_profiled(run, *run_argv)
518
ret = apply_profiled(cmd_obj.run_argv, argv)
520
ret = cmd_obj.run_argv(argv)
682
523
# reset, in case we may do other commands later within the same process
683
trace.be_quiet(False)
685
526
def display_command(func):
686
527
"""Decorator that suppresses pipe/interrupt errors."""
720
559
# do this here inside the exception wrappers to catch EPIPE
721
560
sys.stdout.flush()
722
except (KeyboardInterrupt, Exception), e:
723
562
# used to handle AssertionError and KeyboardInterrupt
724
563
# specially here, but hopefully they're handled ok by the logger now
725
trace.report_exception(sys.exc_info(), sys.stderr)
726
if os.environ.get('BZR_PDB'):
727
print '**** entering debugger'
729
pdb.post_mortem(sys.exc_traceback)
733
class HelpCommandIndex(object):
734
"""A index for bzr help that returns commands."""
737
self.prefix = 'commands/'
739
def get_topics(self, topic):
740
"""Search for topic amongst commands.
742
:param topic: A topic to search for.
743
:return: A list which is either empty or contains a single
746
if topic and topic.startswith(self.prefix):
747
topic = topic[len(self.prefix):]
749
cmd = _get_cmd_object(topic)
565
if (isinstance(e, IOError)
566
and hasattr(e, 'errno')
567
and e.errno == errno.EPIPE):
568
bzrlib.trace.note('broken pipe')
571
bzrlib.trace.log_exception()
572
if os.environ.get('BZR_PDB'):
573
print '**** entering debugger'
575
pdb.post_mortem(sys.exc_traceback)
756
578
if __name__ == '__main__':
757
579
sys.exit(main(sys.argv))
added
removed
bzrlib/commands.py
