358
359
summary, then a complete description of the command. A grammar
359
360
description will be inserted.
362
Other accepted names for this command.
365
List of argument forms, marked with whether they are optional,
370
['to_location', 'from_branch?', 'file*']
372
'to_location' is required
373
'from_branch' is optional
374
'file' can be specified 0 or more times
377
List of options that may be given for this command. These can
378
be either strings, referring to globally-defined options,
379
or option objects. Retrieve through options().
382
If true, this command isn't advertised. This is typically
362
:cvar aliases: Other accepted names for this command.
364
:cvar takes_args: List of argument forms, marked with whether they are
365
optional, repeated, etc. Examples::
367
['to_location', 'from_branch?', 'file*']
369
* 'to_location' is required
370
* 'from_branch' is optional
371
* 'file' can be specified 0 or more times
373
:cvar takes_options: List of options that may be given for this command.
374
These can be either strings, referring to globally-defined options, or
375
option objects. Retrieve through options().
377
:cvar hidden: If true, this command isn't advertised. This is typically
383
378
for commands intended for expert users.
386
Command objects will get a 'outf' attribute, which has been
387
setup to properly handle encoding of unicode strings.
388
encoding_type determines what will happen when characters cannot
390
strict - abort if we cannot decode
391
replace - put in a bogus character (typically '?')
392
exact - do not encode sys.stdout
394
NOTE: by default on Windows, sys.stdout is opened as a text
395
stream, therefore LF line-endings are converted to CRLF.
396
When a command uses encoding_type = 'exact', then
397
sys.stdout is forced to be a binary stream, and line-endings
380
:cvar encoding_type: Command objects will get a 'outf' attribute, which has
381
been setup to properly handle encoding of unicode strings.
382
encoding_type determines what will happen when characters cannot be
385
* strict - abort if we cannot decode
386
* replace - put in a bogus character (typically '?')
387
* exact - do not encode sys.stdout
389
NOTE: by default on Windows, sys.stdout is opened as a text stream,
390
therefore LF line-endings are converted to CRLF. When a command uses
391
encoding_type = 'exact', then sys.stdout is forced to be a binary
392
stream, and line-endings will not mangled.
395
A string indicating the real name under which this command was
396
invoked, before expansion of aliases.
397
(This may be None if the command was constructed and run in-process.)
400
399
:cvar hooks: An instance of CommandHooks.
401
:ivar __doc__: The help shown by 'bzr help command' for this command.
401
:cvar __doc__: The help shown by 'bzr help command' for this command.
402
402
This is set by assigning explicitly to __doc__ so that -OO can
406
__doc__ = "My help goes here"
406
__doc__ = "My help goes here"
410
410
takes_options = []
411
411
encoding_type = 'strict'
486
488
usage help (e.g. Purpose, Usage, Options) with a
487
489
message explaining how to obtain full help.
491
if self.l10n and not i18n.installed():
492
i18n.install() # Install i18n only for get_help_text for now.
489
493
doc = self.help()
491
doc = "No help for this command."
495
# Note: If self.gettext() translates ':Usage:\n', the section will
496
# be shown after "Description" section and we don't want to
497
# translate the usage string.
498
# Though, bzr export-pot don't exports :Usage: section and it must
500
doc = self.gettext(doc)
502
doc = gettext("No help for this command.")
493
504
# Extract the summary (purpose) and sections out from the text
494
505
purpose,sections,order = self._get_help_parts(doc)
537
546
if sections.has_key(None):
538
547
text = sections.pop(None)
539
548
text = '\n '.join(text.splitlines())
540
result += ':%s:\n %s\n\n' % ('Description',text)
549
result += gettext(':Description:\n %s\n\n') % (text,)
542
551
# Add the custom sections (e.g. Examples). Note that there's no need
543
552
# to indent these as they must be indented already in the source.
545
554
for label in order:
546
if sections.has_key(label):
547
result += ':%s:\n%s\n' % (label,sections[label])
555
if label in sections:
556
result += ':%s:\n%s\n' % (label, sections[label])
550
result += ("See bzr help %s for more details and examples.\n\n"
559
result += (gettext("See bzr help %s for more details and examples.\n\n")
553
562
# Add the aliases, source (plug-in) and see also links, if any
555
result += ':Aliases: '
564
result += gettext(':Aliases: ')
556
565
result += ', '.join(self.aliases) + '\n'
557
566
plugin_name = self.plugin_name()
558
567
if plugin_name is not None:
559
result += ':From: plugin "%s"\n' % plugin_name
568
result += gettext(':From: plugin "%s"\n') % plugin_name
560
569
see_also = self.get_see_also(additional_see_also)
562
571
if not plain and see_also_as_links:
568
577
see_also_links.append(item)
570
579
# Use a Sphinx link for this entry
571
link_text = ":doc:`%s <%s-help>`" % (item, item)
580
link_text = gettext(":doc:`%s <%s-help>`") % (item, item)
572
581
see_also_links.append(link_text)
573
582
see_also = see_also_links
574
result += ':See also: '
575
result += ', '.join(see_also) + '\n'
583
result += gettext(':See also: %s') % ', '.join(see_also) + '\n'
577
585
# If this will be rendered as plain text, convert it
659
667
def run_argv_aliases(self, argv, alias_argv=None):
660
668
"""Parse the command line and run with extra aliases in alias_argv."""
661
669
args, opts = parse_args(self, argv, alias_argv)
663
672
# Process the standard options
664
673
if 'help' in opts: # e.g. bzr add --help
665
sys.stdout.write(self.get_help_text())
674
self.outf.write(self.get_help_text())
667
676
if 'usage' in opts: # e.g. bzr add --usage
668
sys.stdout.write(self.get_help_text(verbose=False))
677
self.outf.write(self.get_help_text(verbose=False))
670
679
trace.set_verbosity_level(option._verbosity_level)
671
680
if 'verbose' in self.supported_std_options:
776
795
These are all empty initially, because by default nothing should get
780
self.create_hook(HookPoint('extend_command',
798
Hooks.__init__(self, "bzrlib.commands", "Command.hooks")
799
self.add_hook('extend_command',
781
800
"Called after creating a command object to allow modifications "
782
801
"such as adding or removing options, docs etc. Called with the "
783
"new bzrlib.commands.Command object.", (1, 13), None))
784
self.create_hook(HookPoint('get_command',
802
"new bzrlib.commands.Command object.", (1, 13))
803
self.add_hook('get_command',
785
804
"Called when creating a single command. Called with "
786
805
"(cmd_or_None, command_name). get_command should either return "
787
806
"the cmd_or_None parameter, or a replacement Command object that "
788
807
"should be used for the command. Note that the Command.hooks "
789
808
"hooks are core infrastructure. Many users will prefer to use "
790
809
"bzrlib.commands.register_command or plugin_cmds.register_lazy.",
792
self.create_hook(HookPoint('get_missing_command',
811
self.add_hook('get_missing_command',
793
812
"Called when creating a single command if no command could be "
794
813
"found. Called with (command_name). get_missing_command should "
795
814
"either return None, or a Command object to be used for the "
796
"command.", (1, 17), None))
797
self.create_hook(HookPoint('list_commands',
816
self.add_hook('list_commands',
798
817
"Called when enumerating commands. Called with a set of "
799
818
"cmd_name strings for all the commands found so far. This set "
800
819
" is safe to mutate - e.g. to remove a command. "
801
820
"list_commands should return the updated set of command names.",
804
823
Command.hooks = CommandHooks()
1266
1290
class Provider(object):
1267
'''Generic class to be overriden by plugins'''
1291
"""Generic class to be overriden by plugins"""
1269
1293
def plugin_for_command(self, cmd_name):
1270
'''Takes a command and returns the information for that plugin
1294
"""Takes a command and returns the information for that plugin
1272
1296
:return: A dictionary with all the available information
1273
for the requested plugin
1297
for the requested plugin
1275
1299
raise NotImplementedError
1278
1302
class ProvidersRegistry(registry.Registry):
1279
'''This registry exists to allow other providers to exist'''
1303
"""This registry exists to allow other providers to exist"""
1281
1305
def __iter__(self):
1282
1306
for key, provider in self.iteritems():