devel/shtk/files/config.subr

   1 # Copyright 2012 Google Inc.
   2 # All rights reserved.
   3 #
   4 # Redistribution and use in source and binary forms, with or without
   5 # modification, are permitted provided that the following conditions are
   6 # met:
   7 #
   8 # * Redistributions of source code must retain the above copyright
   9 #   notice, this list of conditions and the following disclaimer.
  10 # * Redistributions in binary form must reproduce the above copyright
  11 #   notice, this list of conditions and the following disclaimer in the
  12 #   documentation and/or other materials provided with the distribution.
  13 # * Neither the name of Google Inc. nor the names of its contributors
  14 #   may be used to endorse or promote products derived from this software
  15 #   without specific prior written permission.
  16 #
  17 # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 # "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 # LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 # A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 # OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 # SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 # LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 # DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 # THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 # (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 # OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28
  29 # \file config.subr
  30 # Configuration file processing and queries.
  31
  32 shtk_import cli
  33
  34
  35 # List of valid configuration variables.
  36 #
  37 # This is initialized by shtk_config_init and should remain unchanged thorough the
  38 # execution of the program.
  39 _Shtk_ConfigVars=
  40
  41
  42 # List of overrides to apply by shtk_config_apply_overrides.
  43 #
  44 # The overrides are recorded and applied separately because they need to happen
  45 # after a configuration file has been loaded.  The contents of this list are
  46 # words of the form: set:<variable> or unset:<variable>.  For those variables
  47 # listed in set:, there is a corresponding shtk_config_override_var_<variable>
  48 # variable containing the new value.
  49 _Shtk_ConfigOverrides=
  50
  51
  52 # Initializes the configuration module.
  53 #
  54 # \param ... List of configuration variables to recognize in configuration files
  55 #     and user overrides.
  56 shtk_config_init() {
  57     _Shtk_ConfigVars="${@}"
  58 }
  59
  60
  61 # Checks if a configuration variable is known.
  62 #
  63 # \param var Name of the variable to check.
  64 #
  65 # \return True if the variable was registered by shtk_config_init, false otherwise.
  66 shtk_config_is_valid() {
  67     local var="${1}"; shift
  68
  69     local known_var
  70     for known_var in ${_Shtk_ConfigVars}; do
  71         if [ "${known_var}" = "${var}" ]; then
  72             return 0
  73         fi
  74     done
  75     return 1
  76 }
  77
  78
  79 # Checks if a configuration variable is defined.
  80 #
  81 # \param var The name of the variable to check.
  82 #
  83 # \return True if the variable is defined (even if empty), false otherwise.
  84 shtk_config_has() {
  85     local var="${1}"; shift
  86
  87     local is_unset
  88     eval is_unset="\${shtk_config_var_${var}-yes_this_is_unset}"
  89     if [ "${is_unset}" = yes_this_is_unset ]; then
  90         return 1
  91     else
  92         return 0
  93     fi
  94 }
  95
  96
  97 # Gets the value of a defined configuration variable.
  98 #
  99 # \post The value of the variable is printed to stdout, if any.
 100 #
 101 # \post If the variable is not defined, this terminates execution with an error.
 102 #
 103 # \param var Name of the configuration variable to query.
 104 shtk_config_get() {
 105     local var="${1}"; shift
 106
 107     if shtk_config_has "${var}"; then
 108         eval echo "\${shtk_config_var_${var}}"
 109     else
 110         shtk_cli_error "Required configuration variable ${var} not set"
 111     fi
 112 }
 113
 114
 115 # Gets the value of configuration variable interpreting it as a boolean.
 116 #
 117 # \param var The variable to query.
 118 #
 119 # \return True if the variable is set to a truth value, false if its value is
 120 # false or if it is not defined.
 121 shtk_config_get_bool() {
 122     local var="${1}"; shift
 123
 124     if shtk_config_has "${var}"; then
 125         case "$(shtk_config_get "${var}")" in
 126             [Yy][Ee][Ss]|[Tt][Rr][Uu][Ee])
 127                 return 0
 128                 ;;
 129             [Nn][Oo]|[Ff][Aa][Ll][Ss][Ee])
 130                 return 1
 131                 ;;
 132             *)
 133                 shtk_cli_error "Invalid boolean value in variable ${var}"
 134                 ;;
 135         esac
 136     else
 137         return 1
 138     fi
 139 }
 140
 141
 142 # Gets the value of a configuration variable with a default fallback.
 143 #
 144 # \post The value of the variable is printed to stdout, if any.
 145 #
 146 # \param var Name of the configuration variable to query.
 147 # \param default Default value to return if the variable is not defined.
 148 shtk_config_get_default() {
 149     local var="${1}"; shift
 150     local default="${1}"; shift
 151
 152     if shtk_config_has "${var}"; then
 153         shtk_config_get "${var}"
 154     else
 155         echo "${default}"
 156     fi
 157 }
 158
 159
 160 # Sets a configuration variable.
 161 #
 162 # \post Execution terminates if the variable is not valid.
 163 #
 164 # \param var The name of the configuration variable to set.
 165 # \param value The value to set.
 166 shtk_config_set() {
 167     local var="${1}"; shift
 168     local value="${1}"; shift
 169
 170     shtk_config_is_valid "${var}" \
 171         || shtk_cli_usage_error "Unknown configuration variable ${var}"
 172     eval "shtk_config_var_${var}=\"\${value}\""
 173 }
 174
 175
 176 # Unsets a configuration variable.
 177 #
 178 # \param var The name of the configuration variable to unset.
 179 shtk_config_unset() {
 180     local var="${1}"; shift
 181
 182     shtk_config_is_valid "${var}" \
 183         || shtk_cli_usage_error "Unknown configuration variable ${var}"
 184     eval unset "shtk_config_var_${var}"
 185 }
 186
 187
 188 # Loads a configuration file.
 189 #
 190 # \pre shtk_config_init should have been called to register the valid configuration
 191 # variables.  Any non-registered configuration variable found in the file will
 192 # not be available through any of the functions in this module.
 193 #
 194 # \post The configuration module is updated with the values defined in the
 195 # configuration file.
 196 #
 197 # \post Any errors in the processing of the configuration file terminate the
 198 # execution of the script.
 199 #
 200 # \param config_file Path to the file to load.
 201 shtk_config_load() {
 202     local config_file="${1}"; shift
 203
 204     [ -e "${config_file}" ] || shtk_cli_error "Configuration file" \
 205         "${config_file} does not exist"
 206
 207     # User-facing variables.
 208     local var
 209     for var in ${_Shtk_ConfigVars}; do
 210         unset "${var}" || true
 211         eval local "${var}"
 212     done
 213
 214     local real_config_file
 215     case "${config_file}" in
 216         */*) real_config_file="${config_file}" ;;
 217         *) real_config_file="./${config_file}" ;;
 218     esac
 219     ( . "${real_config_file}" ) || shtk_cli_error "Failed to load" \
 220         "configuration file ${config_file}"
 221     . "${real_config_file}"
 222
 223     for var in ${_Shtk_ConfigVars}; do
 224         local value
 225         eval value="\${${var}-unset}"
 226         [ "${value-unset}" != unset ] || continue
 227
 228         if [ -n "${value}" ]; then
 229             shtk_config_set "${var}" "${value}"
 230         else
 231             unset "shtk_config_var_${var}" || true
 232         fi
 233     done
 234
 235     shtk_config_apply_overrides
 236 }
 237
 238
 239 # Applies recorded overrides to the current configuration.
 240 #
 241 # This is just a helper function for shtk_config_load and should not be used
 242 # directly.
 243 #
 244 # \post The configuration data in memory is modified according to the data
 245 # recorded in the overrides.
 246 #
 247 # \post The contents of _Shtk_ConfigOverrides is cleared.
 248 shtk_config_apply_overrides() {
 249     for override in ${_Shtk_ConfigOverrides}; do
 250         case "${override}" in
 251             set:*)
 252                 local var="$(echo ${override} | cut -d : -f 2)"
 253                 local value
 254                 eval value="\"\${shtk_config_override_var_${var}}\""
 255                 shtk_config_set "${var}" "${value}"
 256                 ;;
 257             unset:*)
 258                 local var="$(echo ${override} | cut -d : -f 2)"
 259                 unset "shtk_config_var_${var}" || true
 260                 ;;
 261         esac
 262     done
 263     _Shtk_ConfigOverrides=
 264 }
 265
 266
 267 # Records an override to be applied to the configuration.
 268 #
 269 # Overrides are configuration variables set through the command line.  These can
 270 # be set before loading the configuration file with shtk_config_load.
 271 #
 272 # \post Any errors in the processing of the configuration override terminate the
 273 # execution of the script.
 274 #
 275 # \param arg An override of the form variable=value.
 276 shtk_config_override() {
 277     local arg="${1}"; shift
 278
 279     case "${arg}" in
 280         *=*)
 281             ;;
 282         *)
 283             shtk_cli_usage_error "Invalid configuration override" \
 284                 "${arg}; must be of the form variable=value"
 285             ;;
 286     esac
 287     local var="$(echo "${arg}" | cut -d = -f 1)"
 288     local value="$(echo "${arg}" | cut -d = -f 2-)"
 289
 290     [ -n "${var}" ] || shtk_cli_usage_error "Invalid configuration override" \
 291         "${arg}; must be of the form variable=value"
 292     shtk_config_is_valid "${var}" \
 293         || shtk_cli_usage_error "Unknown configuration variable ${var}"
 294
 295     if [ -n "${value}" ]; then
 296         eval "shtk_config_override_var_${var}=\"${value}\""
 297         _Shtk_ConfigOverrides="${_Shtk_ConfigOverrides} set:${var}"
 298     else
 299         _Shtk_ConfigOverrides="${_Shtk_ConfigOverrides} unset:${var}"
 300     fi
 301 }