1if [ ! "$_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#
28############################################################ INCLUDES
29
30BSDCFG_SHARE="/usr/share/bsdconfig"
31. $BSDCFG_SHARE/common.subr || exit 1
32
33############################################################ FUNCTIONS
34
35# f_struct_define $type $member_name1 ...
36#
37# Define a new `structure' type $type made up of the properties $member_name1
38# $member_name2 and so-on. Properties are not typed and can hold any type of
39# data (including names of other structs).
40#
41# Before creating instances of a struct (using f_struct_new $type $name) you
42# should use this function to define $type.
43#
44# Both $type and member names should consist only of alpha-numeric letters or
45# the underscore.
46#
47f_struct_define()
48{
49	local type="$1"
50	[ "$type" ] || return $FAILURE
51	shift
52	setvar "_struct_typedef_$type" "$*"
53}
54
55# f_struct_new $type $name
56#
57# Create a new `structure' named $name of type $type.  There are two ways to
58# access properties of a struct, but they are not equal (each method has its
59# own unique benefits, discussed below).
60#
61# The primary method of accessing (both setting and getting) properties of any
62# struct is through the f_struct() function below.
63#
64# The secondary method of accessing data is by using $name as a function.
65#
66# Both access methods are cross-platform compatible with any version of sh(1).
67# Below is an example of the primary access method:
68#
69# 	f_struct_new MY_STRUCT_TYPE my_struct
70# 	f_struct my_struct set abc 123
71# 	f_struct my_struct get abc # prints 123 to stdout
72# 	f_struct my_struct get abc abc # sets local variable $abc to 123
73#
74# Alternatively, the secondary access method (details below):
75#
76# 	f_struct_new MY_STRUCT_TYPE my_struct
77# 	my_struct set abc 123
78# 	my_struct get abc # prints 123 to stdout
79# 	my_struct get abc abc # sets local variable $abc to 123
80#
81# The secondary form should only be used if/when:
82# 	+ You are certain that the structure already exists
83# 	+ You want a syntax error if/when the struct does not exist
84#
85# The primary benefit to the secondary form is syntax cleanliness and read-
86# ability. If you are unsure if a given struct exists (which would cause a
87# syntax error when using this form), you can use the primary access method to
88# first test for the existence of the struct. For example:
89#
90# 	if f_struct my_struct; then
91# 		my_struct get abc # only executed if my_struct exists
92# 	fi
93#
94# For more information, see the f_struct() function.
95#
96f_struct_new()
97{
98	local type="$1" name="$2"
99	f_dprintf "f_struct_new: type=[%s] name=[%s]" "$type" "$name"
100	[ "$name" ] || return $FAILURE
101	setvar "_struct_type_$name" "$type" || return $FAILURE
102	# OK to use bare $name at this point
103	eval $name\(\){ f_struct $name \"\$@\"\; }
104}
105
106# f_struct $name
107# f_struct $name get $property [$var_to_set]
108# f_struct $name set $property $new_value
109# f_struct $name unset $property
110#
111# Access routine for getting, setting, unsetting, and testing properties of
112# `structures'.
113#
114# If only given $name, returns success if struct $name has been created (using
115# the f_struct_new() function above).
116#
117# For getting properties of a struct (versus setting) there are two methods of
118# access. If $var_to_set is missing or NULL, the value of the property is
119# printed to standard output for capturing in a sub-shell (which is less-
120# recommended because of performance degredation; for example, when called in a
121# loop). Returns success unless the property is unset.
122#
123# For setting properties of a struct, sets the value of $property to $new_value
124# and returns success.
125#
126# For unsetting, the underlying environment variable associated with the given
127# $property is unset.
128#
129f_struct()
130{
131	local __name="$1" __action="$2" __property="$3"
132	case $# in
133	0) return $FAILURE ;;
134	1) f_have "$__name" ;;
135	*) case "$__action" in
136	   get) local __var_to_set="$4"
137	        f_getvar "_struct_value_${__name}_$__property" "$__var_to_set"
138	        ;;
139	   set) local new_value="$4"
140	        setvar "_struct_value_${__name}_$__property" "$new_value" ;;
141	   unset) unset "_struct_value_${__name}_$__property" ;;
142	   esac
143	esac
144	# Return the status of the last command above
145}
146
147# f_struct_free $name
148#
149# Unset the collection of environment variables and accessor-function
150# associated with struct $name.
151#
152f_struct_free()
153{
154	local name="$1" type member members
155	f_getvar "_struct_type_$name" type
156	f_dprintf "f_struct_free: name=[%s] type=[%s]" "$name" "$type"
157	[ "$name" ] || return $FAILURE
158	f_getvar "_struct_typedef_$type" members
159	for member in $members; do
160		f_struct "$name" unset $member
161	done
162	unset -f "$name"
163	unset "_struct_type_$name"
164}
165
166# f_struct_copy $from_name $to_name
167#
168# Copy the properties of one struct to another. If struct $to_name does not
169# exist, it is created. If struct $from_name does not exist, nothing is done
170# and struct $to_name remains unmodified.
171#
172# Returns success unless struct $to_name did not exist and f_struct_new() was
173# unable to create it.
174#
175f_struct_copy()
176{
177	local from_name="$1" to_name="$2" type
178	f_dprintf "f_struct_copy: from_name=[%s] to_name=[%s]" \
179	          "$from_name" "$to_name"
180	f_getvar "_struct_type_$from_name" type
181	f_struct "$to_name" ||
182		f_struct_new "$type" "$to_name" || return $FAILURE
183	f_struct "$from_name" || return $SUCCESS
184	f_dprintf "f_struct_copy: copying properties from %s to %s" \
185	          "$from_name" "$to_name"
186	local property properties from_value n=0 k=0
187	f_getvar "_struct_typedef_$type" properties
188	for property in $properties; do
189		k=$(( $k + 1 ))
190		if f_struct "$from_name" get $property from_value; then
191			f_struct "$to_name" set $property "$from_value"
192			n=$(( $n + 1 ))
193		else
194			f_struct "$to_name" unset $property
195		fi
196	done
197	f_dprintf "f_struct_copy: copied %u of %u properties from %s to %s" \
198	          "$n" "$k" "$from_name" "$to_name"
199}
200
201############################################################ MAIN
202
203f_dprintf "%s: Successfully loaded." struct.subr
204
205fi # ! $_STRUCT_SUBR
206