← Back to branch summary

~bzr-pqm/bzr/bzr.dev

« back to all changes in this revision

Viewing changes to bzrlib/option.py

  • Committer: Ian Clatworthy
  • Date: 2008-12-15 04:37:10 UTC
  • mfrom: (3892.1.6 bzr.help-formats)
  • mto: This revision was merged to the branch mainline in revision 3905.
  • Revision ID: ian.clatworthy@canonical.com-20081215043710-ybhxvqjeir13k5ht
Improved help on storage formats (Ian Clatworthy)

Show diffs side-by-side

added added

removed removed

Lines of Context:
bzrlib/option.py
1
 
# Copyright (C) 2005-2010 Canonical Ltd
 
1
# Copyright (C) 2004, 2005, 2006, 2007 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
# TODO: For things like --diff-prefix, we want a way to customize the display
18
18
# of the option argument.
25
25
from bzrlib import (
26
26
    errors,
27
27
    revisionspec,
28
 
    i18n,
29
28
    )
30
29
""")
31
30
 
41
40
    each revision specifier supplied.
42
41
 
43
42
    >>> _parse_revision_str('234')
44
 
    [<RevisionSpec_dwim 234>]
 
43
    [<RevisionSpec_revno 234>]
45
44
    >>> _parse_revision_str('234..567')
46
 
    [<RevisionSpec_dwim 234>, <RevisionSpec_dwim 567>]
 
45
    [<RevisionSpec_revno 234>, <RevisionSpec_revno 567>]
47
46
    >>> _parse_revision_str('..')
48
47
    [<RevisionSpec None>, <RevisionSpec None>]
49
48
    >>> _parse_revision_str('..234')
50
 
    [<RevisionSpec None>, <RevisionSpec_dwim 234>]
 
49
    [<RevisionSpec None>, <RevisionSpec_revno 234>]
51
50
    >>> _parse_revision_str('234..')
52
 
    [<RevisionSpec_dwim 234>, <RevisionSpec None>]
 
51
    [<RevisionSpec_revno 234>, <RevisionSpec None>]
53
52
    >>> _parse_revision_str('234..456..789') # Maybe this should be an error
54
 
    [<RevisionSpec_dwim 234>, <RevisionSpec_dwim 456>, <RevisionSpec_dwim 789>]
 
53
    [<RevisionSpec_revno 234>, <RevisionSpec_revno 456>, <RevisionSpec_revno 789>]
55
54
    >>> _parse_revision_str('234....789') #Error ?
56
 
    [<RevisionSpec_dwim 234>, <RevisionSpec None>, <RevisionSpec_dwim 789>]
 
55
    [<RevisionSpec_revno 234>, <RevisionSpec None>, <RevisionSpec_revno 789>]
57
56
    >>> _parse_revision_str('revid:test@other.com-234234')
58
57
    [<RevisionSpec_revid revid:test@other.com-234234>]
59
58
    >>> _parse_revision_str('revid:test@other.com-234234..revid:test@other.com-234235')
60
59
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_revid revid:test@other.com-234235>]
61
60
    >>> _parse_revision_str('revid:test@other.com-234234..23')
62
 
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_dwim 23>]
 
61
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_revno 23>]
63
62
    >>> _parse_revision_str('date:2005-04-12')
64
63
    [<RevisionSpec_date date:2005-04-12>]
65
64
    >>> _parse_revision_str('date:2005-04-12 12:24:33')
69
68
    >>> _parse_revision_str('date:2005-04-12,12:24:33')
70
69
    [<RevisionSpec_date date:2005-04-12,12:24:33>]
71
70
    >>> _parse_revision_str('-5..23')
72
 
    [<RevisionSpec_dwim -5>, <RevisionSpec_dwim 23>]
 
71
    [<RevisionSpec_revno -5>, <RevisionSpec_revno 23>]
73
72
    >>> _parse_revision_str('-5')
74
 
    [<RevisionSpec_dwim -5>]
 
73
    [<RevisionSpec_revno -5>]
75
74
    >>> _parse_revision_str('123a')
76
 
    [<RevisionSpec_dwim 123a>]
 
75
    Traceback (most recent call last):
 
76
      ...
 
77
    NoSuchRevisionSpec: No namespace registered for string: '123a'
77
78
    >>> _parse_revision_str('abc')
78
 
    [<RevisionSpec_dwim abc>]
 
79
    Traceback (most recent call last):
 
80
      ...
 
81
    NoSuchRevisionSpec: No namespace registered for string: 'abc'
79
82
    >>> _parse_revision_str('branch:../branch2')
80
83
    [<RevisionSpec_branch branch:../branch2>]
81
84
    >>> _parse_revision_str('branch:../../branch2')
82
85
    [<RevisionSpec_branch branch:../../branch2>]
83
86
    >>> _parse_revision_str('branch:../../branch2..23')
84
 
    [<RevisionSpec_branch branch:../../branch2>, <RevisionSpec_dwim 23>]
 
87
    [<RevisionSpec_branch branch:../../branch2>, <RevisionSpec_revno 23>]
85
88
    >>> _parse_revision_str('branch:..\\\\branch2')
86
89
    [<RevisionSpec_branch branch:..\\branch2>]
87
90
    >>> _parse_revision_str('branch:..\\\\..\\\\branch2..23')
88
 
    [<RevisionSpec_branch branch:..\\..\\branch2>, <RevisionSpec_dwim 23>]
 
91
    [<RevisionSpec_branch branch:..\\..\\branch2>, <RevisionSpec_revno 23>]
89
92
    """
90
93
    # TODO: Maybe move this into revisionspec.py
91
94
    revs = []
101
104
    parent of the revision.
102
105
 
103
106
    >>> _parse_change_str('123')
104
 
    (<RevisionSpec_before before:123>, <RevisionSpec_dwim 123>)
 
107
    (<RevisionSpec_before before:123>, <RevisionSpec_revno 123>)
105
108
    >>> _parse_change_str('123..124')
106
109
    Traceback (most recent call last):
107
110
      ...
133
136
 
134
137
class Option(object):
135
138
    """Description of a command line option
136
 
 
 
139
    
137
140
    :ivar _short_name: If this option has a single-letter name, this is it.
138
141
    Otherwise None.
139
142
    """
147
150
    OPTIONS = {}
148
151
 
149
152
    def __init__(self, name, help='', type=None, argname=None,
150
 
                 short_name=None, param_name=None, custom_callback=None,
151
 
                 hidden=False):
 
153
                 short_name=None, param_name=None, custom_callback=None):
152
154
        """Make a new command option.
153
155
 
154
156
        :param name: regular name of the command, used in the double-dash
155
 
            form and also as the parameter to the command's run()
 
157
            form and also as the parameter to the command's run() 
156
158
            method (unless param_name is specified).
157
159
 
158
160
        :param help: help message displayed in command help
159
161
 
160
 
        :param type: function called to parse the option argument, or
 
162
        :param type: function called to parse the option argument, or 
161
163
            None (default) if this option doesn't take an argument.
162
164
 
163
165
        :param argname: name of option argument, if any
171
173
        :param custom_callback: a callback routine to be called after normal
172
174
            processing. The signature of the callback routine is
173
175
            (option, name, new_value, parser).
174
 
        :param hidden: If True, the option should be hidden in help and
175
 
            documentation.
176
176
        """
177
177
        self.name = name
178
178
        self.help = help
189
189
        else:
190
190
            self._param_name = param_name
191
191
        self.custom_callback = custom_callback
192
 
        self.hidden = hidden
193
192
 
194
193
    def short_name(self):
195
194
        if self._short_name:
209
208
        option_strings = ['--%s' % self.name]
210
209
        if short_name is not None:
211
210
            option_strings.append('-%s' % short_name)
212
 
        if self.hidden:
213
 
            help = optparse.SUPPRESS_HELP
214
 
        else:
215
 
            help = self.help
216
211
        optargfn = self.type
217
212
        if optargfn is None:
218
213
            parser.add_option(action='callback',
219
214
                              callback=self._optparse_bool_callback,
220
215
                              callback_args=(True,),
221
 
                              help=help,
 
216
                              help=self.help,
222
217
                              *option_strings)
223
218
            negation_strings = ['--%s' % self.get_negation_name()]
224
219
            parser.add_option(action='callback',
229
224
            parser.add_option(action='callback',
230
225
                              callback=self._optparse_callback,
231
226
                              type='string', metavar=self.argname.upper(),
232
 
                              help=help,
 
227
                              help=self.help,
233
228
                              default=OptionParser.DEFAULT_VALUE,
234
229
                              *option_strings)
235
230
 
246
241
 
247
242
    def iter_switches(self):
248
243
        """Iterate through the list of switches provided by the option
249
 
 
 
244
        
250
245
        :return: an iterator of (name, short_name, argname, help)
251
246
        """
252
247
        argname =  self.argname
255
250
        yield self.name, self.short_name(), argname, self.help
256
251
 
257
252
    def is_hidden(self, name):
258
 
        return self.hidden
 
253
        return False
259
254
 
260
255
 
261
256
class ListOption(Option):
277
272
        parser.add_option(action='callback',
278
273
                          callback=self._optparse_callback,
279
274
                          type='string', metavar=self.argname.upper(),
280
 
                          help=self.help, dest=self._param_name, default=[],
 
275
                          help=self.help, default=[],
281
276
                          *option_strings)
282
277
 
283
278
    def _optparse_callback(self, option, opt, value, parser):
313
308
 
314
309
    def __init__(self, name, help, registry=None, converter=None,
315
310
        value_switches=False, title=None, enum_switch=True,
316
 
        lazy_registry=None, short_name=None, short_value_switches=None):
 
311
        lazy_registry=None):
317
312
        """
318
313
        Constructor.
319
314
 
329
324
            which takes a value.
330
325
        :param lazy_registry: A tuple of (module name, attribute name) for a
331
326
            registry to be lazily loaded.
332
 
        :param short_name: The short name for the enum switch, if any
333
 
        :param short_value_switches: A dict mapping values to short names
334
327
        """
335
 
        Option.__init__(self, name, help, type=self.convert,
336
 
                        short_name=short_name)
 
328
        Option.__init__(self, name, help, type=self.convert)
337
329
        self._registry = registry
338
330
        if registry is None:
339
331
            if lazy_registry is None:
348
340
        self.converter = converter
349
341
        self.value_switches = value_switches
350
342
        self.enum_switch = enum_switch
351
 
        self.short_value_switches = short_value_switches
352
343
        self.title = title
353
344
        if self.title is None:
354
345
            self.title = name
358
349
        if self._registry is None:
359
350
            self._registry = self._lazy_registry.get_obj()
360
351
        return self._registry
361
 
 
 
352
    
362
353
    @staticmethod
363
354
    def from_kwargs(name_, help=None, title=None, value_switches=False,
364
355
                    enum_switch=True, **kwargs):
366
357
 
367
358
        name, help, value_switches and enum_switch are passed to the
368
359
        RegistryOption constructor.  Any other keyword arguments are treated
369
 
        as values for the option, and their value is treated as the help.
 
360
        as values for the option, and they value is treated as the help.
370
361
        """
371
362
        reg = _mod_registry.Registry()
372
 
        for name, switch_help in sorted(kwargs.items()):
 
363
        for name, switch_help in kwargs.iteritems():
373
364
            name = name.replace('_', '-')
374
365
            reg.register(name, name, help=switch_help)
375
366
            if not value_switches:
392
383
                    help = optparse.SUPPRESS_HELP
393
384
                else:
394
385
                    help = self.registry.get_help(key)
395
 
                if (self.short_value_switches and
396
 
                    key in self.short_value_switches):
397
 
                    option_strings.append('-%s' %
398
 
                                          self.short_value_switches[key])
399
386
                parser.add_option(action='callback',
400
387
                              callback=self._optparse_value_callback(key),
401
388
                                  help=help,
431
418
 
432
419
    DEFAULT_VALUE = object()
433
420
 
434
 
    def __init__(self):
435
 
        optparse.OptionParser.__init__(self)
436
 
        self.formatter = GettextIndentedHelpFormatter()
437
 
 
438
421
    def error(self, message):
439
422
        raise errors.BzrCommandError(message)
440
423
 
441
424
 
442
 
class GettextIndentedHelpFormatter(optparse.IndentedHelpFormatter):
443
 
    """Adds gettext() call to format_option()"""
444
 
    def __init__(self):
445
 
        optparse.IndentedHelpFormatter.__init__(self)
446
 
 
447
 
    def format_option(self, option):
448
 
        """code taken from Python's optparse.py"""
449
 
        if option.help:
450
 
            option.help = i18n.gettext(option.help)
451
 
        return optparse.IndentedHelpFormatter.format_option(self, option)
452
 
 
453
 
 
454
425
def get_optparser(options):
455
426
    """Generate an optparse parser for bzrlib-style options"""
456
427
 
519
490
 
520
491
 
521
492
_merge_type_registry = MergeTypeRegistry()
 
493
_merge_type_registry.register_lazy('merge3', 'bzrlib.merge', 'Merge3Merger',
 
494
                                   "Native diff3-style merge")
522
495
_merge_type_registry.register_lazy('diff3', 'bzrlib.merge', 'Diff3Merger',
523
496
                                   "Merge using external diff3")
 
497
_merge_type_registry.register_lazy('weave', 'bzrlib.merge', 'WeaveMerger',
 
498
                                   "Weave-based merge")
524
499
_merge_type_registry.register_lazy('lca', 'bzrlib.merge', 'LCAMerger',
525
500
                                   "LCA-newness merge")
526
 
_merge_type_registry.register_lazy('merge3', 'bzrlib.merge', 'Merge3Merger',
527
 
                                   "Native diff3-style merge")
528
 
_merge_type_registry.register_lazy('weave', 'bzrlib.merge', 'WeaveMerger',
529
 
                                   "Weave-based merge")
530
501
 
531
502
# Declare the standard options
532
503
_standard_option('help', short_name='h',
533
504
                 help='Show help message.')
534
 
_standard_option('usage',
535
 
                 help='Show usage message and options.')
536
505
_standard_option('verbose', short_name='v',
537
506
                 help='Display more information.',
538
507
                 custom_callback=_verbosity_level_callback)
542
511
 
543
512
# Declare commonly used options
544
513
_global_option('all')
 
514
_global_option('overwrite', help='Ignore differences between branches and '
 
515
               'overwrite unconditionally.')
545
516
_global_option('basis', type=str)
546
517
_global_option('bound')
547
 
_global_option('change',
548
 
               type=_parse_change_str,
549
 
               short_name='c',
550
 
               param_name='revision',
551
 
               help='Select changes introduced by the specified revision. See also "help revisionspec".')
552
518
_global_option('diff-options', type=str)
553
 
_global_option('directory', short_name='d', type=unicode,
554
 
               help='Branch to operate on, instead of working directory')
555
 
_global_option('dry-run',
556
 
               help="Show what would be done, but don't actually do anything.")
557
 
_global_option('email')
558
519
_global_option('file', type=unicode, short_name='F')
559
520
_global_option('force')
560
521
_global_option('format', type=unicode)
561
522
_global_option('forward')
562
 
_global_option('kind', type=str)
563
 
_global_option('line', help='Use log format with one line per revision.'
564
 
               ' Same as --log-format line')
565
 
_global_registry_option('log-format', "Use specified log format.",
566
 
                        lazy_registry=('bzrlib.log', 'log_formatter_registry'),
567
 
                        value_switches=True, title='Log format',
568
 
                        short_value_switches={'short': 'S'})
569
 
_global_option('long', help='Use detailed log format.'
570
 
               ' Same as --log-format long',
571
 
               short_name='l')
572
 
_global_registry_option('merge-type', 'Select a particular merge algorithm.',
573
 
                        _merge_type_registry, value_switches=True,
574
 
                        title='Merge algorithm')
575
523
_global_option('message', type=unicode,
576
524
               short_name='m',
577
525
               help='Message string.')
578
 
_global_option('name-from-revision', help='The path name in the old tree.')
579
 
_global_option('no-backup')
580
526
_global_option('no-recurse')
581
 
_global_option('null', short_name='0',
582
 
                 help='Use an ASCII NUL (\\0) separator rather than '
583
 
                      'a newline.')
584
 
_global_option('overwrite', help='Ignore differences between branches and '
585
 
               'overwrite unconditionally.')
586
 
_global_option('pattern', type=str)
587
527
_global_option('profile',
588
528
               help='Show performance profiling information.')
589
 
_global_option('reprocess', help='Reprocess to reduce spurious conflicts.')
590
 
_global_option('remember', help='Remember the specified location as a'
591
 
               ' default.')
592
529
_global_option('revision',
593
530
               type=_parse_revision_str,
594
531
               short_name='r',
595
532
               help='See "help revisionspec" for details.')
596
 
_global_option('short', help='Use moderately short log format.'
597
 
               ' Same as --log-format short')
 
533
_global_option('change',
 
534
               type=_parse_change_str,
 
535
               short_name='c',
 
536
               param_name='revision',
 
537
               help='Select changes introduced by the specified revision. See also "help revisionspec".')
598
538
_global_option('show-ids',
599
539
               help='Show internal object ids.')
600
540
_global_option('timezone',
601
541
               type=str,
602
542
               help='Display timezone as local, original, or utc.')
603
 
_global_option('root', type=str)
604
543
_global_option('unbound')
 
544
_global_option('version')
 
545
_global_option('email')
605
546
_global_option('update')
606
 
_global_option('version')
 
547
_global_registry_option('log-format', "Use specified log format.",
 
548
                        lazy_registry=('bzrlib.log', 'log_formatter_registry'),
 
549
                        value_switches=True, title='Log format')
 
550
_global_option('long', help='Use detailed log format. Same as --log-format long',
 
551
               short_name='l')
 
552
_global_option('short', help='Use moderately short log format. Same as --log-format short')
 
553
_global_option('line', help='Use log format with one line per revision. Same as --log-format line')
 
554
_global_option('root', type=str)
 
555
_global_option('no-backup')
 
556
_global_registry_option('merge-type', 'Select a particular merge algorithm.',
 
557
                        _merge_type_registry, value_switches=True,
 
558
                        title='Merge algorithm')
 
559
_global_option('pattern', type=str)
 
560
_global_option('remember', help='Remember the specified location as a'
 
561
               ' default.')
 
562
_global_option('reprocess', help='Reprocess to reduce spurious conflicts.')
 
563
_global_option('kind', type=str)
 
564
_global_option('dry-run',
 
565
               help="Show what would be done, but don't actually do anything.")
 
566
_global_option('name-from-revision', help='The path name in the old tree.')
607
567
 
608
568
diff_writer_registry = _mod_registry.Registry()
609
569
diff_writer_registry.register('plain', lambda x: x, 'Plaintext diff output.')