← 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: 2007-08-13 14:16:53 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-20070813141653-3cbrp00xowq58zv1
Added mini tutorial

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.
19
19
 
20
 
import optparse
21
20
import re
22
21
 
23
22
from bzrlib.lazy_import import lazy_import
24
23
lazy_import(globals(), """
 
24
import optparse
 
25
 
25
26
from bzrlib import (
26
27
    errors,
 
28
    log,
 
29
    registry,
27
30
    revisionspec,
 
31
    symbol_versioning,
28
32
    )
29
33
""")
30
 
 
31
 
from bzrlib import (
32
 
    registry as _mod_registry,
33
 
    )
 
34
from bzrlib.trace import warning
34
35
 
35
36
 
36
37
def _parse_revision_str(revstr):
40
41
    each revision specifier supplied.
41
42
 
42
43
    >>> _parse_revision_str('234')
43
 
    [<RevisionSpec_dwim 234>]
 
44
    [<RevisionSpec_revno 234>]
44
45
    >>> _parse_revision_str('234..567')
45
 
    [<RevisionSpec_dwim 234>, <RevisionSpec_dwim 567>]
 
46
    [<RevisionSpec_revno 234>, <RevisionSpec_revno 567>]
46
47
    >>> _parse_revision_str('..')
47
48
    [<RevisionSpec None>, <RevisionSpec None>]
48
49
    >>> _parse_revision_str('..234')
49
 
    [<RevisionSpec None>, <RevisionSpec_dwim 234>]
 
50
    [<RevisionSpec None>, <RevisionSpec_revno 234>]
50
51
    >>> _parse_revision_str('234..')
51
 
    [<RevisionSpec_dwim 234>, <RevisionSpec None>]
 
52
    [<RevisionSpec_revno 234>, <RevisionSpec None>]
52
53
    >>> _parse_revision_str('234..456..789') # Maybe this should be an error
53
 
    [<RevisionSpec_dwim 234>, <RevisionSpec_dwim 456>, <RevisionSpec_dwim 789>]
 
54
    [<RevisionSpec_revno 234>, <RevisionSpec_revno 456>, <RevisionSpec_revno 789>]
54
55
    >>> _parse_revision_str('234....789') #Error ?
55
 
    [<RevisionSpec_dwim 234>, <RevisionSpec None>, <RevisionSpec_dwim 789>]
 
56
    [<RevisionSpec_revno 234>, <RevisionSpec None>, <RevisionSpec_revno 789>]
56
57
    >>> _parse_revision_str('revid:test@other.com-234234')
57
58
    [<RevisionSpec_revid revid:test@other.com-234234>]
58
59
    >>> _parse_revision_str('revid:test@other.com-234234..revid:test@other.com-234235')
59
60
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_revid revid:test@other.com-234235>]
60
61
    >>> _parse_revision_str('revid:test@other.com-234234..23')
61
 
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_dwim 23>]
 
62
    [<RevisionSpec_revid revid:test@other.com-234234>, <RevisionSpec_revno 23>]
62
63
    >>> _parse_revision_str('date:2005-04-12')
63
64
    [<RevisionSpec_date date:2005-04-12>]
64
65
    >>> _parse_revision_str('date:2005-04-12 12:24:33')
68
69
    >>> _parse_revision_str('date:2005-04-12,12:24:33')
69
70
    [<RevisionSpec_date date:2005-04-12,12:24:33>]
70
71
    >>> _parse_revision_str('-5..23')
71
 
    [<RevisionSpec_dwim -5>, <RevisionSpec_dwim 23>]
 
72
    [<RevisionSpec_revno -5>, <RevisionSpec_revno 23>]
72
73
    >>> _parse_revision_str('-5')
73
 
    [<RevisionSpec_dwim -5>]
 
74
    [<RevisionSpec_revno -5>]
74
75
    >>> _parse_revision_str('123a')
75
 
    [<RevisionSpec_dwim 123a>]
 
76
    Traceback (most recent call last):
 
77
      ...
 
78
    NoSuchRevisionSpec: No namespace registered for string: '123a'
76
79
    >>> _parse_revision_str('abc')
77
 
    [<RevisionSpec_dwim abc>]
 
80
    Traceback (most recent call last):
 
81
      ...
 
82
    NoSuchRevisionSpec: No namespace registered for string: 'abc'
78
83
    >>> _parse_revision_str('branch:../branch2')
79
84
    [<RevisionSpec_branch branch:../branch2>]
80
85
    >>> _parse_revision_str('branch:../../branch2')
81
86
    [<RevisionSpec_branch branch:../../branch2>]
82
87
    >>> _parse_revision_str('branch:../../branch2..23')
83
 
    [<RevisionSpec_branch branch:../../branch2>, <RevisionSpec_dwim 23>]
84
 
    >>> _parse_revision_str('branch:..\\\\branch2')
85
 
    [<RevisionSpec_branch branch:..\\branch2>]
86
 
    >>> _parse_revision_str('branch:..\\\\..\\\\branch2..23')
87
 
    [<RevisionSpec_branch branch:..\\..\\branch2>, <RevisionSpec_dwim 23>]
 
88
    [<RevisionSpec_branch branch:../../branch2>, <RevisionSpec_revno 23>]
88
89
    """
89
90
    # TODO: Maybe move this into revisionspec.py
90
91
    revs = []
91
 
    # split on .. that is not followed by a / or \
92
 
    sep = re.compile(r'\.\.(?![\\/])')
 
92
    # split on the first .. that is not followed by a / ?
 
93
    sep = re.compile("\\.\\.(?!/)")
93
94
    for x in sep.split(revstr):
94
95
        revs.append(revisionspec.RevisionSpec.from_string(x or None))
95
96
    return revs
96
97
 
97
98
 
98
 
def _parse_change_str(revstr):
99
 
    """Parse the revision string and return a tuple with left-most
100
 
    parent of the revision.
101
 
 
102
 
    >>> _parse_change_str('123')
103
 
    (<RevisionSpec_before before:123>, <RevisionSpec_dwim 123>)
104
 
    >>> _parse_change_str('123..124')
105
 
    Traceback (most recent call last):
106
 
      ...
107
 
    RangeInChangeOption: Option --change does not accept revision ranges
108
 
    """
109
 
    revs = _parse_revision_str(revstr)
110
 
    if len(revs) > 1:
111
 
        raise errors.RangeInChangeOption()
112
 
    return (revisionspec.RevisionSpec.from_string('before:' + revstr),
113
 
            revs[0])
114
 
 
115
 
 
116
99
def _parse_merge_type(typestring):
117
100
    return get_merge_type(typestring)
118
101
 
132
115
 
133
116
class Option(object):
134
117
    """Description of a command line option
135
 
 
 
118
    
136
119
    :ivar _short_name: If this option has a single-letter name, this is it.
137
120
    Otherwise None.
138
121
    """
139
122
 
140
 
    # The dictionary of standard options. These are always legal.
141
 
    STD_OPTIONS = {}
 
123
    # TODO: Some way to show in help a description of the option argument
142
124
 
143
 
    # The dictionary of commonly used options. these are only legal
144
 
    # if a command explicitly references them by name in the list
145
 
    # of supported options.
146
125
    OPTIONS = {}
147
126
 
148
127
    def __init__(self, name, help='', type=None, argname=None,
149
 
                 short_name=None, param_name=None, custom_callback=None,
150
 
                 hidden=False):
 
128
                 short_name=None):
151
129
        """Make a new command option.
152
130
 
153
 
        :param name: regular name of the command, used in the double-dash
154
 
            form and also as the parameter to the command's run()
155
 
            method (unless param_name is specified).
156
 
 
157
 
        :param help: help message displayed in command help
158
 
 
159
 
        :param type: function called to parse the option argument, or
 
131
        name -- regular name of the command, used in the double-dash
 
132
            form and also as the parameter to the command's run() 
 
133
            method.
 
134
 
 
135
        help -- help message displayed in command help
 
136
 
 
137
        type -- function called to parse the option argument, or 
160
138
            None (default) if this option doesn't take an argument.
161
139
 
162
 
        :param argname: name of option argument, if any
163
 
 
164
 
        :param short_name: short option code for use with a single -, e.g.
165
 
            short_name="v" to enable parsing of -v.
166
 
 
167
 
        :param param_name: name of the parameter which will be passed to
168
 
            the command's run() method.
169
 
 
170
 
        :param custom_callback: a callback routine to be called after normal
171
 
            processing. The signature of the callback routine is
172
 
            (option, name, new_value, parser).
173
 
        :param hidden: If True, the option should be hidden in help and
174
 
            documentation.
 
140
        argname -- name of option argument, if any
175
141
        """
176
142
        self.name = name
177
143
        self.help = help
178
144
        self.type = type
179
145
        self._short_name = short_name
180
146
        if type is None:
181
 
            if argname:
182
 
                raise ValueError('argname not valid for booleans')
 
147
            assert argname is None
183
148
        elif argname is None:
184
149
            argname = 'ARG'
185
150
        self.argname = argname
186
 
        if param_name is None:
187
 
            self._param_name = self.name.replace('-', '_')
188
 
        else:
189
 
            self._param_name = param_name
190
 
        self.custom_callback = custom_callback
191
 
        self.hidden = hidden
192
151
 
193
152
    def short_name(self):
194
153
        if self._short_name:
208
167
        option_strings = ['--%s' % self.name]
209
168
        if short_name is not None:
210
169
            option_strings.append('-%s' % short_name)
211
 
        if self.hidden:
212
 
            help = optparse.SUPPRESS_HELP
213
 
        else:
214
 
            help = self.help
215
170
        optargfn = self.type
216
171
        if optargfn is None:
217
 
            parser.add_option(action='callback',
218
 
                              callback=self._optparse_bool_callback,
219
 
                              callback_args=(True,),
220
 
                              help=help,
 
172
            parser.add_option(action='store_true', dest=self.name, 
 
173
                              help=self.help,
 
174
                              default=OptionParser.DEFAULT_VALUE,
221
175
                              *option_strings)
222
176
            negation_strings = ['--%s' % self.get_negation_name()]
223
 
            parser.add_option(action='callback',
224
 
                              callback=self._optparse_bool_callback,
225
 
                              callback_args=(False,),
 
177
            parser.add_option(action='store_false', dest=self.name, 
226
178
                              help=optparse.SUPPRESS_HELP, *negation_strings)
227
179
        else:
228
 
            parser.add_option(action='callback',
229
 
                              callback=self._optparse_callback,
 
180
            parser.add_option(action='callback', 
 
181
                              callback=self._optparse_callback, 
230
182
                              type='string', metavar=self.argname.upper(),
231
 
                              help=help,
232
 
                              default=OptionParser.DEFAULT_VALUE,
 
183
                              help=self.help,
 
184
                              default=OptionParser.DEFAULT_VALUE, 
233
185
                              *option_strings)
234
186
 
235
 
    def _optparse_bool_callback(self, option, opt_str, value, parser, bool_v):
236
 
        setattr(parser.values, self._param_name, bool_v)
237
 
        if self.custom_callback is not None:
238
 
            self.custom_callback(option, self._param_name, bool_v, parser)
239
 
 
240
187
    def _optparse_callback(self, option, opt, value, parser):
241
 
        v = self.type(value)
242
 
        setattr(parser.values, self._param_name, v)
243
 
        if self.custom_callback is not None:
244
 
            self.custom_callback(option, self.name, v, parser)
 
188
        setattr(parser.values, self.name, self.type(value))
245
189
 
246
190
    def iter_switches(self):
247
191
        """Iterate through the list of switches provided by the option
248
 
 
 
192
        
249
193
        :return: an iterator of (name, short_name, argname, help)
250
194
        """
251
195
        argname =  self.argname
253
197
            argname = argname.upper()
254
198
        yield self.name, self.short_name(), argname, self.help
255
199
 
256
 
    def is_hidden(self, name):
257
 
        return self.hidden
258
 
 
259
200
 
260
201
class ListOption(Option):
261
202
    """Option used to provide a list of values.
276
217
        parser.add_option(action='callback',
277
218
                          callback=self._optparse_callback,
278
219
                          type='string', metavar=self.argname.upper(),
279
 
                          help=self.help, dest=self._param_name, default=[],
 
220
                          help=self.help, default=[],
280
221
                          *option_strings)
281
222
 
282
223
    def _optparse_callback(self, option, opt, value, parser):
283
 
        values = getattr(parser.values, self._param_name)
 
224
        values = getattr(parser.values, self.name)
284
225
        if value == '-':
285
226
            del values[:]
286
227
        else:
287
228
            values.append(self.type(value))
288
 
        if self.custom_callback is not None:
289
 
            self.custom_callback(option, self._param_name, values, parser)
290
229
 
291
230
 
292
231
class RegistryOption(Option):
310
249
        else:
311
250
            return self.converter(value)
312
251
 
313
 
    def __init__(self, name, help, registry=None, converter=None,
314
 
        value_switches=False, title=None, enum_switch=True,
315
 
        lazy_registry=None, short_name=None, short_value_switches=None):
 
252
    def __init__(self, name, help, registry, converter=None,
 
253
        value_switches=False, title=None, enum_switch=True):
316
254
        """
317
255
        Constructor.
318
256
 
326
264
            '--knit' can be used interchangeably.
327
265
        :param enum_switch: If true, a switch is provided with the option name,
328
266
            which takes a value.
329
 
        :param lazy_registry: A tuple of (module name, attribute name) for a
330
 
            registry to be lazily loaded.
331
 
        :param short_name: The short name for the enum switch, if any
332
 
        :param short_value_switches: A dict mapping values to short names
333
267
        """
334
 
        Option.__init__(self, name, help, type=self.convert, short_name=short_name)
335
 
        self._registry = registry
336
 
        if registry is None:
337
 
            if lazy_registry is None:
338
 
                raise AssertionError(
339
 
                    'One of registry or lazy_registry must be given.')
340
 
            self._lazy_registry = _mod_registry._LazyObjectGetter(
341
 
                *lazy_registry)
342
 
        if registry is not None and lazy_registry is not None:
343
 
            raise AssertionError(
344
 
                'registry and lazy_registry are mutually exclusive')
 
268
        Option.__init__(self, name, help, type=self.convert)
 
269
        self.registry = registry
345
270
        self.name = name
346
271
        self.converter = converter
347
272
        self.value_switches = value_switches
348
273
        self.enum_switch = enum_switch
349
 
        self.short_value_switches = short_value_switches
350
274
        self.title = title
351
275
        if self.title is None:
352
276
            self.title = name
353
277
 
354
 
    @property
355
 
    def registry(self):
356
 
        if self._registry is None:
357
 
            self._registry = self._lazy_registry.get_obj()
358
 
        return self._registry
359
 
 
360
278
    @staticmethod
361
279
    def from_kwargs(name_, help=None, title=None, value_switches=False,
362
280
                    enum_switch=True, **kwargs):
364
282
 
365
283
        name, help, value_switches and enum_switch are passed to the
366
284
        RegistryOption constructor.  Any other keyword arguments are treated
367
 
        as values for the option, and their value is treated as the help.
 
285
        as values for the option, and they value is treated as the help.
368
286
        """
369
 
        reg = _mod_registry.Registry()
370
 
        for name, switch_help in sorted(kwargs.items()):
 
287
        reg = registry.Registry()
 
288
        for name, switch_help in kwargs.iteritems():
371
289
            name = name.replace('_', '-')
372
290
            reg.register(name, name, help=switch_help)
373
 
            if not value_switches:
374
 
                help = help + '  "' + name + '": ' + switch_help
375
 
                if not help.endswith("."):
376
 
                    help = help + "."
377
291
        return RegistryOption(name_, help, reg, title=title,
378
292
            value_switches=value_switches, enum_switch=enum_switch)
379
293
 
386
300
        if self.value_switches:
387
301
            for key in self.registry.keys():
388
302
                option_strings = ['--%s' % key]
389
 
                if self.is_hidden(key):
 
303
                if getattr(self.registry.get_info(key), 'hidden', False):
390
304
                    help = optparse.SUPPRESS_HELP
391
305
                else:
392
306
                    help = self.registry.get_help(key)
393
 
                if (self.short_value_switches and
394
 
                    key in self.short_value_switches):
395
 
                    option_strings.append('-%s' %
396
 
                                          self.short_value_switches[key])
397
307
                parser.add_option(action='callback',
398
308
                              callback=self._optparse_value_callback(key),
399
309
                                  help=help,
401
311
 
402
312
    def _optparse_value_callback(self, cb_value):
403
313
        def cb(option, opt, value, parser):
404
 
            v = self.type(cb_value)
405
 
            setattr(parser.values, self._param_name, v)
406
 
            if self.custom_callback is not None:
407
 
                self.custom_callback(option, self._param_name, v, parser)
 
314
            setattr(parser.values, self.name, self.type(cb_value))
408
315
        return cb
409
316
 
410
317
    def iter_switches(self):
418
325
            for key in sorted(self.registry.keys()):
419
326
                yield key, None, None, self.registry.get_help(key)
420
327
 
421
 
    def is_hidden(self, name):
422
 
        if name == self.name:
423
 
            return Option.is_hidden(self, name)
424
 
        return getattr(self.registry.get_info(name), 'hidden', False)
425
 
 
426
328
 
427
329
class OptionParser(optparse.OptionParser):
428
330
    """OptionParser that raises exceptions instead of exiting"""
443
345
    return parser
444
346
 
445
347
 
446
 
def custom_help(name, help):
447
 
    """Clone a common option overriding the help."""
448
 
    import copy
449
 
    o = copy.copy(Option.OPTIONS[name])
450
 
    o.help = help
451
 
    return o
452
 
 
453
 
 
454
 
def _standard_option(name, **kwargs):
455
 
    """Register a standard option."""
456
 
    # All standard options are implicitly 'global' ones
457
 
    Option.STD_OPTIONS[name] = Option(name, **kwargs)
458
 
    Option.OPTIONS[name] = Option.STD_OPTIONS[name]
459
 
 
460
 
 
461
348
def _global_option(name, **kwargs):
462
 
    """Register a global option."""
 
349
    """Register o as a global option."""
463
350
    Option.OPTIONS[name] = Option(name, **kwargs)
464
351
 
465
352
 
466
 
def _global_registry_option(name, help, registry=None, **kwargs):
 
353
def _global_registry_option(name, help, registry, **kwargs):
467
354
    Option.OPTIONS[name] = RegistryOption(name, help, registry, **kwargs)
468
355
 
469
356
 
470
 
# This is the verbosity level detected during command line parsing.
471
 
# Note that the final value is dependent on the order in which the
472
 
# various flags (verbose, quiet, no-verbose, no-quiet) are given.
473
 
# The final value will be one of the following:
474
 
#
475
 
# * -ve for quiet
476
 
# * 0 for normal
477
 
# * +ve for verbose
478
 
_verbosity_level = 0
479
 
 
480
 
 
481
 
def _verbosity_level_callback(option, opt_str, value, parser):
482
 
    global _verbosity_level
483
 
    if not value:
484
 
        # Either --no-verbose or --no-quiet was specified
485
 
        _verbosity_level = 0
486
 
    elif opt_str == "verbose":
487
 
        if _verbosity_level > 0:
488
 
            _verbosity_level += 1
489
 
        else:
490
 
            _verbosity_level = 1
491
 
    else:
492
 
        if _verbosity_level < 0:
493
 
            _verbosity_level -= 1
494
 
        else:
495
 
            _verbosity_level = -1
496
 
 
497
 
 
498
 
class MergeTypeRegistry(_mod_registry.Registry):
 
357
class MergeTypeRegistry(registry.Registry):
499
358
 
500
359
    pass
501
360
 
507
366
                                   "Merge using external diff3")
508
367
_merge_type_registry.register_lazy('weave', 'bzrlib.merge', 'WeaveMerger',
509
368
                                   "Weave-based merge")
510
 
_merge_type_registry.register_lazy('lca', 'bzrlib.merge', 'LCAMerger',
511
 
                                   "LCA-newness merge")
512
 
 
513
 
# Declare the standard options
514
 
_standard_option('help', short_name='h',
515
 
                 help='Show help message.')
516
 
_standard_option('usage',
517
 
                 help='Show usage message and options.')
518
 
_standard_option('verbose', short_name='v',
519
 
                 help='Display more information.',
520
 
                 custom_callback=_verbosity_level_callback)
521
 
_standard_option('quiet', short_name='q',
522
 
                 help="Only display errors and warnings.",
523
 
                 custom_callback=_verbosity_level_callback)
524
 
 
525
 
# Declare commonly used options
 
369
 
526
370
_global_option('all')
527
371
_global_option('overwrite', help='Ignore differences between branches and '
528
372
               'overwrite unconditionally.')
537
381
               short_name='m',
538
382
               help='Message string.')
539
383
_global_option('no-recurse')
540
 
_global_option('null', short_name='0',
541
 
                 help='Use an ASCII NUL (\\0) separator rather than '
542
 
                      'a newline.')
543
384
_global_option('profile',
544
385
               help='Show performance profiling information.')
545
386
_global_option('revision',
546
387
               type=_parse_revision_str,
547
388
               short_name='r',
548
 
               help='See "help revisionspec" for details.')
549
 
_global_option('change',
550
 
               type=_parse_change_str,
551
 
               short_name='c',
552
 
               param_name='revision',
553
 
               help='Select changes introduced by the specified revision. See also "help revisionspec".')
 
389
               help='See \'help revisionspec\' for details.')
554
390
_global_option('show-ids',
555
391
               help='Show internal object ids.')
556
 
_global_option('timezone',
 
392
_global_option('timezone', 
557
393
               type=str,
558
 
               help='Display timezone as local, original, or utc.')
 
394
               help='display timezone as local, original, or utc')
559
395
_global_option('unbound')
 
396
_global_option('verbose',
 
397
               help='Display more information.',
 
398
               short_name='v')
560
399
_global_option('version')
561
400
_global_option('email')
562
401
_global_option('update')
563
402
_global_registry_option('log-format', "Use specified log format.",
564
 
                        lazy_registry=('bzrlib.log', 'log_formatter_registry'),
565
 
                        value_switches=True, title='Log format',
566
 
                        short_value_switches={'short': 'S'})
 
403
                        log.log_formatter_registry, value_switches=True,
 
404
                        title='Log format')
567
405
_global_option('long', help='Use detailed log format. Same as --log-format long',
568
406
               short_name='l')
569
407
_global_option('short', help='Use moderately short log format. Same as --log-format short')
574
412
                        _merge_type_registry, value_switches=True,
575
413
                        title='Merge algorithm')
576
414
_global_option('pattern', type=str)
 
415
_global_option('quiet', short_name='q')
577
416
_global_option('remember', help='Remember the specified location as a'
578
417
               ' default.')
579
418
_global_option('reprocess', help='Reprocess to reduce spurious conflicts.')
581
420
_global_option('dry-run',
582
421
               help="Show what would be done, but don't actually do anything.")
583
422
_global_option('name-from-revision', help='The path name in the old tree.')
584
 
_global_option('directory', short_name='d', type=unicode,
585
 
               help='Branch to operate on, instead of working directory')
586
423
 
587
 
diff_writer_registry = _mod_registry.Registry()
588
 
diff_writer_registry.register('plain', lambda x: x, 'Plaintext diff output.')
589
 
diff_writer_registry.default_key = 'plain'
 
424
_help_option = Option('help',
 
425
                      help='Show help message.',
 
426
                      short_name='h')