usr.sbin/bsdconfig/share/struct.subr

   1 if [ ! "$_STRUCT_SUBR" ]; then _STRUCT_SUBR=1
   2 #
   3 # Copyright (c) 2012-2013 Devin Teske
   4 # All rights reserved.
   5 #
   6 # Redistribution and use in source and binary forms, with or without
   7 # modification, are permitted provided that the following conditions
   8 # are met:
   9 # 1. Redistributions of source code must retain the above copyright
  10 #    notice, this list of conditions and the following disclaimer.
  11 # 2. Redistributions in binary form must reproduce the above copyright
  12 #    notice, this list of conditions and the following disclaimer in the
  13 #    documentation and/or other materials provided with the distribution.
  14 #
  15 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 # ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 # SUCH DAMAGE.
  26 #
  27 # $FreeBSD$
  28 #
  29 ############################################################ INCLUDES
  30
  31 BSDCFG_SHARE="/usr/share/bsdconfig"
  32 . $BSDCFG_SHARE/common.subr || exit 1
  33
  34 ############################################################ FUNCTIONS
  35
  36 # f_struct_define $type $member_name1 ...
  37 #
  38 # Define a new `structure' type $type made up of the properties $member_name1
  39 # $member_name2 and so-on. Properties are not typed and can hold any type of
  40 # data (including names of other structs).
  41 #
  42 # Before creating instances of a struct (using f_struct_new $type $name) you
  43 # should use this function to define $type.
  44 #
  45 # Both $type and member names should consist only of alpha-numeric letters or
  46 # the underscore.
  47 #
  48 f_struct_define()
  49 {
  50         local type="$1"
  51         [ "$type" ] || return $FAILURE
  52         shift
  53         setvar "_struct_typedef_$type" "$*"
  54 }
  55
  56 # f_struct_new $type $name
  57 #
  58 # Create a new `structure' named $name of type $type.  There are two ways to
  59 # access properties of a struct, but they are not equal (each method has its
  60 # own unique benefits, discussed below).
  61 #
  62 # The primary method of accessing (both setting and getting) properties of any
  63 # struct is through the f_struct() function below.
  64 #
  65 # The secondary method of accessing data is by using $name as a function.
  66 #
  67 # Both access methods are cross-platform compatible with any version of sh(1).
  68 # Below is an example of the primary access method:
  69 #
  70 #       f_struct_new MY_STRUCT_TYPE my_struct
  71 #       f_struct my_struct set abc 123
  72 #       f_struct my_struct get abc # prints 123 to stdout
  73 #       f_struct my_struct get abc abc # sets local variable $abc to 123
  74 #
  75 # Alternatively, the secondary access method (details below):
  76 #
  77 #       f_struct_new MY_STRUCT_TYPE my_struct
  78 #       my_struct set abc 123
  79 #       my_struct get abc # prints 123 to stdout
  80 #       my_struct get abc abc # sets local variable $abc to 123
  81 #
  82 # The secondary form should only be used if/when:
  83 #       + You are certain that the structure already exists
  84 #       + You want a syntax error if/when the struct does not exist
  85 #
  86 # The primary benefit to the secondary form is syntax cleanliness and read-
  87 # ability. If you are unsure if a given struct exists (which would cause a
  88 # syntax error when using this form), you can use the primary access method to
  89 # first test for the existence of the struct. For example:
  90 #
  91 #       if f_struct my_struct; then
  92 #               my_struct get abc # only executed if my_struct exists
  93 #       fi
  94 #
  95 # For more information, see the f_struct() function.
  96 #
  97 f_struct_new()
  98 {
  99         local type="$1" name="$2"
 100         f_dprintf "f_struct_new: type=[%s] name=[%s]" "$type" "$name"
 101         [ "$name" ] || return $FAILURE
 102         setvar "_struct_type_$name" "$type" || return $FAILURE
 103         # OK to use bare $name at this point
 104         eval $name\(\){ f_struct $name \"\$@\"\; }
 105 }
 106
 107 # f_struct $name
 108 # f_struct $name get $property [$var_to_set]
 109 # f_struct $name set $property $new_value
 110 # f_struct $name unset $property
 111 #
 112 # Access routine for getting, setting, unsetting, and testing properties of
 113 # `structures'.
 114 #
 115 # If only given $name, returns success if struct $name has been created (using
 116 # the f_struct_new() function above).
 117 #
 118 # For getting properties of a struct (versus setting) there are two methods of
 119 # access. If $var_to_set is missing or NULL, the value of the property is
 120 # printed to standard output for capturing in a sub-shell (which is less-
 121 # recommended because of performance degredation; for example, when called in a
 122 # loop). Returns success unless the property is unset.
 123 #
 124 # For setting properties of a struct, sets the value of $property to $new_value
 125 # and returns success.
 126 #
 127 # For unsetting, the underlying environment variable associated with the given
 128 # $property is unset.
 129 #
 130 f_struct()
 131 {
 132         local __name="$1" __action="$2" __property="$3"
 133         case $# in
 134         0) return $FAILURE ;;
 135         1) f_have $__name ;;
 136         *) case "$__action" in
 137            get) local __var_to_set="$4"
 138                 f_getvar "_struct_value_${__name}_$__property" "$__var_to_set"
 139                 ;;
 140            set) local new_value="$4"
 141                 setvar "_struct_value_${__name}_$__property" "$new_value" ;;
 142            unset) unset "_struct_value_${__name}_$__property" ;;
 143            esac
 144         esac
 145         # Return the status of the last command above
 146 }
 147
 148 # f_struct_free $name
 149 #
 150 # Unset the collection of environment variables and accessor-function
 151 # associated with struct $name.
 152 #
 153 f_struct_free()
 154 {
 155         local name="$1" type member members
 156         f_getvar "_struct_type_$name" type
 157         f_dprintf "f_struct_free: name=[%s] type=[%s]" "$name" "$type"
 158         [ "$name" ] || return $FAILURE
 159         f_getvar "_struct_typedef_$type" members
 160         for member in $members; do
 161                 f_struct "$name" unset $member
 162         done
 163         unset -f "$name"
 164         unset "_struct_type_$name"
 165 }
 166
 167 # f_struct_copy $from_name $to_name
 168 #
 169 # Copy the properties of one struct to another. If struct $to_name does not
 170 # exist, it is created. If struct $from_name does not exist, nothing is done
 171 # and struct $to_name remains unmodified.
 172 #
 173 # Returns success unless struct $to_name did not exist and f_struct_new() was
 174 # unable to create it.
 175 #
 176 f_struct_copy()
 177 {
 178         local from_name="$1" to_name="$2" type
 179         f_dprintf "f_struct_copy: from_name=[%s] to_name=[%s]" \
 180                   "$from_name" "$to_name"
 181         f_getvar "_struct_type_$from_name" type
 182         f_struct "$to_name" ||
 183                 f_struct_new "$type" "$to_name" || return $FAILURE
 184         f_struct "$from_name" || return $SUCCESS
 185         f_dprintf "f_struct_copy: copying properties from %s to %s" \
 186                   "$from_name" "$to_name"
 187         local property properties from_value n=0 k=0
 188         f_getvar "_struct_typedef_$type" properties
 189         for property in $properties; do
 190                 k=$(( $k + 1 ))
 191                 if f_struct "$from_name" get $property from_value; then
 192                         f_struct "$to_name" set $property "$from_value"
 193                         n=$(( $n + 1 ))
 194                 else
 195                         f_struct "$to_name" unset $property
 196                 fi
 197         done
 198         f_dprintf "f_struct_copy: copied %u of %u properties from %s to %s" \
 199                   "$n" "$k" "$from_name" "$to_name"
 200 }
 201
 202 ############################################################ MAIN
 203
 204 f_dprintf "%s: Successfully loaded." struct.subr
 205
 206 fi # ! $_STRUCT_SUBR