SCons/Variables/EnumVariable.py

   1 # MIT License
   2 #
   3 # Copyright The SCons Foundation
   4 #
   5 # Permission is hereby granted, free of charge, to any person obtaining
   6 # a copy of this software and associated documentation files (the
   7 # "Software"), to deal in the Software without restriction, including
   8 # without limitation the rights to use, copy, modify, merge, publish,
   9 # distribute, sublicense, and/or sell copies of the Software, and to
  10 # permit persons to whom the Software is furnished to do so, subject to
  11 # the following conditions:
  12 #
  13 # The above copyright notice and this permission notice shall be included
  14 # in all copies or substantial portions of the Software.
  15 #
  16 # THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  17 # KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  18 # WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19 # NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20 # LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21 # OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22 # WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23
  24 """Variable type for enumeration Variables.
  25
  26 Enumeration variables allow selection of one from a specified set of values.
  27
  28 Usage example::
  29
  30     opts = Variables()
  31     opts.Add(
  32         EnumVariable(
  33             'debug',
  34             help='debug output and symbols',
  35             default='no',
  36             allowed_values=('yes', 'no', 'full'),
  37             map={},
  38             ignorecase=2,
  39         )
  40     )
  41     ...
  42     if env['debug'] == 'full':
  43     ...
  44 """
  45
  46 from typing import Tuple, Callable
  47
  48 import SCons.Errors
  49
  50 __all__ = ['EnumVariable',]
  51
  52
  53 def _validator(key, val, env, vals) -> None:
  54     if val not in vals:
  55         raise SCons.Errors.UserError(
  56             'Invalid value for option %s: %s.  Valid values are: %s' % (key, val, vals))
  57
  58
  59 def EnumVariable(key, help, default, allowed_values, map={}, ignorecase: int=0) -> Tuple[str, str, str, Callable, Callable]:
  60     """Return a tuple describing an enumaration SCons Variable.
  61
  62     The input parameters describe an option with only certain values
  63     allowed. Returns A tuple including an appropriate converter and
  64     validator. The result is usable as input to :meth:`Add`.
  65
  66     *key* and *default* are passed directly on to :meth:`Add`.
  67
  68     *help* is the descriptive part of the help text,
  69     and will have the allowed values automatically appended.
  70
  71     *allowed_values* is a list of strings, which are the allowed values
  72     for this option.
  73
  74     The *map*-dictionary may be used for converting the input value
  75     into canonical values (e.g. for aliases).
  76
  77     The value of *ignorecase* defines the behaviour of the validator:
  78
  79         * 0: the validator/converter are case-sensitive.
  80         * 1: the validator/converter are case-insensitive.
  81         * 2: the validator/converter is case-insensitive and the
  82           converted value will always be lower-case.
  83
  84     The *validator* tests whether the value is in the list of allowed values.
  85     The *converter* converts input values according to the given
  86     *map*-dictionary (unmapped input values are returned unchanged).
  87     """
  88
  89     help = '%s (%s)' % (help, '|'.join(allowed_values))
  90     # define validator
  91     if ignorecase:
  92         validator = lambda key, val, env: \
  93                     _validator(key, val.lower(), env, allowed_values)
  94     else:
  95         validator = lambda key, val, env: \
  96                     _validator(key, val, env, allowed_values)
  97     # define converter
  98     if ignorecase == 2:
  99         converter = lambda val: map.get(val.lower(), val).lower()
 100     elif ignorecase == 1:
 101         converter = lambda val: map.get(val.lower(), val)
 102     else:
 103         converter = lambda val: map.get(val, val)
 104     return (key, help, default, validator, converter)
 105
 106 # Local Variables:
 107 # tab-width:4
 108 # indent-tabs-mode:nil
 109 # End:
 110 # vim: set expandtab tabstop=4 shiftwidth=4: