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     env = Environment(variables=opts)
  42     if env['debug'] == 'full':
  43         ...
  44 """
  45
  46 from typing import Callable, List, Optional, Tuple
  47
  48 import SCons.Errors
  49
  50 __all__ = ['EnumVariable',]
  51
  52
  53 def _validator(key, val, env, vals) -> None:
  54     """Validate that val is in vals.
  55
  56     Usable as the base for :class:`EnumVariable` validators.
  57     """
  58     if val not in vals:
  59         msg = (
  60             f"Invalid value for enum variable {key!r}: {val!r}. "
  61             f"Valid values are: {vals}"
  62         )
  63         raise SCons.Errors.UserError(msg) from None
  64
  65
  66 # lint: W0622: Redefining built-in 'help' (redefined-builtin)
  67 # lint:  W0622: Redefining built-in 'map' (redefined-builtin)
  68 def EnumVariable(
  69     key,
  70     help: str,
  71     default: str,
  72     allowed_values: List[str],
  73     map: Optional[dict] = None,
  74     ignorecase: int = 0,
  75 ) -> Tuple[str, str, str, Callable, Callable]:
  76     """Return a tuple describing an enumaration SCons Variable.
  77
  78     The input parameters describe a variable with only predefined values
  79     allowed.  The value of *ignorecase* defines the behavior of the
  80     validator and converter: if ``0``, the validator/converter are
  81     case-sensitive; if ``1``, the validator/converter are case-insensitive;
  82     if ``2``, the validator/converter are case-insensitive and the
  83     converted value will always be lower-case.
  84
  85     Arguments:
  86        key: variable name, passed directly through to the return tuple.
  87        default: default values, passed directly through to the return tuple.
  88        help: descriptive part of the help text,
  89           will have the allowed values automatically appended.
  90        allowed_values: list of the allowed values for this variable.
  91        map: optional dictionary which may be used for converting the
  92           input value into canonical values (e.g. for aliases).
  93        ignorecase: defines the behavior of the validator and converter.
  94
  95     Returns:
  96        A tuple including an appropriate converter and validator.
  97        The result is usable as input to :meth:`~SCons.Variables.Variables.Add`.
  98        and :meth:`~SCons.Variables.Variables.AddVariables`.
  99     """
 100     # these are all inner functions so they can access EnumVariable locals.
 101     def validator_rcase(key, val, env):
 102         """Case-respecting validator."""
 103         return _validator(key, val, env, allowed_values)
 104
 105     def validator_icase(key, val, env):
 106         """Case-ignoring validator."""
 107         return _validator(key, val.lower(), env, allowed_values)
 108
 109     def converter_rcase(val):
 110         """Case-respecting converter."""
 111         return map.get(val, val)
 112
 113     def converter_icase(val):
 114         """Case-ignoring converter."""
 115         return map.get(val.lower(), val)
 116
 117     def converter_lcase(val):
 118         """Case-lowering converter."""
 119         return map.get(val.lower(), val).lower()
 120
 121     if map is None:
 122         map = {}
 123     help = f"{help} ({'|'.join(allowed_values)})"
 124
 125     # define validator
 126     if ignorecase:
 127         validator = validator_icase
 128     else:
 129         validator = validator_rcase
 130
 131     # define converter
 132     if ignorecase == 2:
 133         converter = converter_lcase
 134     elif ignorecase == 1:
 135         converter = converter_icase
 136     else:
 137         converter = converter_rcase
 138
 139     return key, help, default, validator, converter
 140
 141 # Local Variables:
 142 # tab-width:4
 143 # indent-tabs-mode:nil
 144 # End:
 145 # vim: set expandtab tabstop=4 shiftwidth=4: