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