1struct::record(n) Tcl Data Structures struct::record(n)
2______________________________________________________________________________
6
8 struct::record - Define and create records (similar to 'C' structures)
9
11 package require Tcl 8.2
12 package require struct::record ?1.2.1?
14 record define recordName recordMembers ?instanceName1 instanceName2
16 ...?
17 record show record
19 record show instances recordName
21 record show members recordName
23 record show values instanceName
25 record exists record recordName
27 record exists instance instanceName
29 record delete record recordName
31 record delete instance instanceName
33 recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
35 instanceName cget ?-member1 -member2 ...?
37 instanceName configure ?-member1 value1 -member2 value2 ...?
39_________________________________________________________________
41
43 The ::struct::record package provides a mechanism to group variables
44 together as one data structure, similar to a 'C' structure. The members
45 of a record can be variables or other records. However, a record can
46 not contain circular record, i.e. records that contain the same record
47 as a member.
48 This package was structured so that it is very similar to how Tk
50 objects work. Each record definition creates a record object that
51 encompasses that definition. Subsequently, that record object can cre‐
52 ate instances of that record. These instances can then be manipulated
53 with the cget and configure methods.
54 The package only contains one top level command, but several sub com‐
56 mands (see below). It also obeys the namespace in which the record was
57 define, hence the objects returned are fully qualified.
58 record define recordName recordMembers ?instanceName1 instanceName2
60 ...?
61 Defines a record. recordName is the name of the record, and is
62 also used as an object command. This object command is used to
63 create instances of the record definition. recordMembers are the
64 members of the record that make up the record definition. These
65 are variables and other record. If optional instanceName args
66 are given, then an instance is generated after the definition is
67 created for each instanceName.
68 record show record
70 Returns a list of records that have been defined.
71 record show instances recordName
73 Returns the instances that have been instantiated by recordName.
74 record show members recordName
76 Returns the members that are defined for record recordName. It
77 returns the same format as how the records were defined.
78 record show values instanceName
80 Returns a list of values that are set for the instance instance‐
81 Name. The output is a list of key/value pairs. If there are
82 nested records, then the values of the nested records will
83 itself be a list.
84 record exists record recordName
86 Tests for the existence of a record with the name recordName.
87 record exists instance instanceName
89 Tests for the existence of a instance with the name instance‐
90 Name.
91 record delete record recordName
93 Deletes recordName, and all instances of recordName. It will
94 return an error if the record does not exist.
95 record delete instance instanceName
97 Deletes instance with the name of instanceName. It will return
98 an error if the instance does not exist.
99
101 Record members can either be variables, or other records, However, the
102 same record can not be nested witin itself (circular). To define a
103 nested record, you need to specify the record keyword, along the with
104 name of the record, and the name of the instance of that nested record.
105 For example, it would look like this:
106 # this is the nested record
108 record define mynestedrecord {
109 nest1
110 nest2
111 }
112 # This is the main record
114 record define myrecord {
115 mem1
116 mem2
117 {record mynestedrecord mem3}
118 }
119 You can also assign default or initial values to the members of a
122 record, by enclosing the member entry in braces:
123 record define myrecord {
125 mem1
126 {mem2 5}
127 }
128 All instances created from this record definition, will initially have
131 5 as the value for mem2. If no default is given, then the value will be
132 the empty string.
133 Getting Values
135 To get a value of a member, there are several ways to do this.
137 [1] To get a member value, then use the instance built-in cget
139 method:
140 instanceName cget -mem1
142 [2] To get multiple member values, you can specify them all in one
144 command:
145 instanceName cget -mem1 -mem2
147 [3] To get a list of the key/value of all of the members, there are
149 3 ways:
150 - instanceName cget
152 - instanceName configure
154 - instanceName
156 [4] To get a value of a nested member, then use the dot notation:
158 instanceName cget -mem3.nest1
160 Setting Values
162 To set a value of a member, there are several ways to do this.
164 [1] To set a member value, then use the instance built-in configure
166 method:
167 instanceName configure -mem1 val1
169 [2] To set multiple member values, you can specify them all in one
171 command:
172 instanceName configure -mem1 va1 -mem2 val2
174 [3] To set a value of a nested member, then use the dot notation:
176 instanceName configure -mem3.nest1 value
178 Alias access
180 In the original implementation, access was done by using dot notation
182 similar to how 'C' structures are accessed. However, there was a con‐
183 census to make the interface more Tcl like, which made sense. However,
184 the original alias access still exists. It might prove to be helpful to
185 some.
186 Basically, for every member of every instance, an alias is created.
188 This alias is used to get and set values for that member. An example
189 will illustrate the point, using the above defined records:
190 # Create an instance first
192 % myrecord inst1
193 ::inst1
194 % # To get a member of an instance, just use the
195 % # alias (it behaves like a Tcl command):
196 % inst1.mem1
197 %
198 % # To set a member via the alias, just include
199 % # a value (optionally the equal sign - syntactic sugar)
200 % inst1.mem1 = 5
201 5
202 % inst1.mem1
203 5
204 % # For nested records, just continue with the
205 % # dot notation (note no equal sign)
206 % inst1.mem3.nest1 10
207 10
208 % inst1.mem3.nest1
209 10
210 % # just the instance by itself gives all
211 % # member/values pairs for that instance
212 % inst1
213 -mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
214 % # and to get all members within the nested record
215 % inst1.mem3
216 -nest1 10 -nest2 {}
217 %
218
222 The following subcommands and corresponding arguments are available to
223 any record command:
224 recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
226 Using the recordName object command that was created from the
227 record definition, instances of the record definition can be
228 created. Once a instance is created, then it inherits the mem‐
229 bers of the record definition, very similar to how objects work.
230 During instance generation, an object command for the instance
231 is created as well, using instanceName. This object command is
232 used to access the data members of the instance. During the
233 instantiation, values for that instance can be given, but all
234 values must be given, and be given in key/value pairs. Nested
235 records, need to be in list format.
236 Optionally, #auto can be used in place of instanceName. When
238 #auto is used, then a instance name will automatically be gener‐
239 ated, of the form recordName<integer>, where <integer> is a
240 unique integer (starting at 0) that is generated.
241
243 The following subcommands and corresponding arguments are available to
244 any record instance command:
245 instanceName cget ?-member1 -member2 ...?
247 Each instance has the sub command cget associated with it. This
248 is very similar to how Tk widget's cget command works. It
249 queries the values of the member for that particular instance.
250 If no arguments are given, then a key/value list is returned.
251 instanceName configure ?-member1 value1 -member2 value2 ...?
253 Each instance has the sub command configure associated with it.
254 This is very similar to how Tk widget's configure command works.
255 It sets the values of the particular member for that particular
256 instance. If no arguments are given, then a key/value list is
257 returned.
258
260 Two examples are provided to give an good illustration on how to use
261 this package.
262 Example 1
264 Probably the most obvious example would be to hold contact information,
266 such as addresses, phone numbers, comments, etc. Since a person can
267 have multiple phone numbers, multiple email addresses, etc, we will use
268 nested records to define these. So, the first thing we do is define the
269 nested records:
270 ##
272 ## This is an interactive example, to see what is
273 ## returned by each command as well.
274 ##
275 % namespace import ::struct::record::*
277 % # define a nested record. Notice that country has default 'USA'.
279 % record define locations {
280 street
281 street2
282 city
283 state
284 zipcode
285 {country USA}
286 phone
287 }
288 ::locations
289 % # Define the main record. Notice that it uses the location record twice.
290 % record define contacts {
291 first
292 middle
293 last
294 {record locations home}
295 {record locations work}
296 }
297 ::contacts
298 % # Create an instance for the contacts record.
299 % contacts cont1
300 ::cont1
301 % # Display some introspection values
302 % record show records
303 ::contacts ::locations
304 % #
305 % record show values cont1
306 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
307 % #
308 % record show instances contacts
309 ::cont1
310 % #
311 % cont1 config
312 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
313 % #
314 % cont1 cget
315 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
316 % # copy one record to another record
317 % record define contacts2 [record show members contacts]
318 ::contacts2
319 % record show members contacts2
320 first middle last {record locations home} {record locations work}
321 % record show members contacts
322 first middle last {record locations home} {record locations work}
323 %
324 Example 1
327 This next example just illustrates a simple linked list
329 % # define a very simple record for linked list
331 % record define llist {
332 value
333 next
334 }
335 ::llist
336 % llist lstart
337 ::lstart
338 % lstart config -value 1 -next [llist #auto]
339 % [lstart cget -next] config -value 2 -next [llist #auto]
340 % [[lstart cget -next] cget -next] config -value 3 -next "end"
341 % set next lstart
342 lstart
343 % while 1 {
344 lappend values [$next cget -value]
345 set next [$next cget -next]
346 if {[string match "end" $next]} {break}
347 }
348 % puts "$values"
349 1 2 3
350 % # cleanup linked list
351 % # We could just use delete record llist also
352 % foreach I [record show instances llist] {
353 record delete instance $I
354 }
355 % record show instances llist
356 %
357
361 This document, and the package it describes, will undoubtedly contain
362 bugs and other problems. Please report such in the category struct ::
363 record of the Tcllib SF Trackers [http://source‐
364 forge.net/tracker/?group_id=12883]. Please also report any ideas for
365 enhancements you may have for either package and/or documentation.
366
368 data structures, record, struct
369
371 Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com>
372struct 1.2.1 struct::record(n)