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.2?
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 instanceName cget -member
35 instanceName cget -member1 -member2
37 instanceName cget
39 instanceName configure
41 instanceName
43 instanceName configure -member value
45 instanceName configure -member1 value1 -member2 value2
47 recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
49 instanceName cget ?-member1 -member2 ...?
51 instanceName configure ?-member1 value1 -member2 value2 ...?
53______________________________________________________________________________
55
57 The ::struct::record package provides a mechanism to group variables
58 together as one data structure, similar to a C structure. The members
59 of a record can be variables or other records. However, a record can
60 not contain circular records, i.e. records that contain the same record
61 as a member.
62 This package was structured so that it is very similar to how Tk ob‐
64 jects work. Each record definition creates a record object that encom‐
65 passes that definition. Subsequently, that record object can create in‐
66 stances of that record. These instances can then be manipulated with
67 the cget and configure methods.
68 The package only contains one top level command, but several sub com‐
70 mands (see below). It also obeys the namespace in which the record was
71 defined, hence the objects returned are fully qualified.
72 record define recordName recordMembers ?instanceName1 instanceName2
74 ...?
75 Defines a record. recordName is the name of the record, and is
76 also used as an object command. This object command is used to
77 create instances of the record definition. The recordMembers are
78 the members of the record that make up the record definition.
79 These are variables and other records. If optional instanceName
80 args are specified, then an instance is generated after the def‐
81 inition is created for each instanceName.
82 record show record
84 Returns a list of records that have been defined.
85 record show instances recordName
87 Returns the instances that have been instantiated by recordName.
88 record show members recordName
90 Returns the members that are defined for record recordName. It
91 returns the same format as how the records were defined.
92 record show values instanceName
94 Returns a list of values that are set for the instance instance‐
95 Name. The output is a list of key/value pairs. If there are
96 nested records, then the values of the nested records will it‐
97 self be a list.
98 record exists record recordName
100 Tests for the existence of a record with the name recordName.
101 record exists instance instanceName
103 Tests for the existence of a instance with the name instance‐
104 Name.
105 record delete record recordName
107 Deletes recordName, and all instances of recordName. It will
108 return an error if the record does not exist.
109 record delete instance instanceName
111 Deletes instance with the name of instanceName. It will return
112 an error if the instance does not exist. Note that this recur‐
113 sively deletes any nested instances as well.
114
116 Record members can either be variables, or other records, However, the
117 same record can not be nested witin itself (circular). To define a
118 nested record, you need to specify the record keyword, along the with
119 name of the record, and the name of the instance of that nested record
120 (within the container). For example, it would look like this:
121 # this is the nested record
123 record define mynestedrecord {
124 nest1
125 nest2
126 }
127 # This is the main record
129 record define myrecord {
130 mem1
131 mem2
132 {record mynestedrecord mem3}
133 }
134 You can also assign default or initial values to the members of a
136 record, by enclosing the member entry in braces:
137 record define myrecord {
139 mem1
140 {mem2 5}
141 }
142 All instances created from this record definition will initially have 5
144 as the value for member mem2. If no default is given, then the value
145 will be the empty string.
146 GETTING VALUES
148 To get a value of a member, there are several ways to do this.
149 instanceName cget -member
151 In this form the built-in cget instance method returns the value
152 of the specified member. Note the leading dash.
153 To reach a nested member use dot notation:
155 instanceName cget -mem3.nest1
158 instanceName cget -member1 -member2
161 In this form the built-in cget instance method returns a list
162 containing the values of both specified members, in the order of
163 specification.
164 instanceName cget
166 instanceName configure
168 instanceName
170 These forms are all equivalent. They return a dictionary of all
171 members and the associated values.
172 SETTING VALUES
174 To set a value of a member, there are several ways to do this.
175 instanceName configure -member value
177 In this form the built-in configure instance method sets the
178 specified member to the given value. Note the leading dash.
179 To reach a nested member use dot notation:
181 instanceName configure -mem3.nest1 value
184 instanceName configure -member1 value1 -member2 value2
187 In this form the built-in configure instance method sets all
188 specified members to the associated values.
189 ALIAS ACCESS
191 In the original implementation, access was done by using dot notation
192 similar to how C structures are accessed. However, there was a concen‐
193 sus to make the interface more Tcl like, which made sense. However,
194 the original alias access still exists. It might prove to be helpful to
195 some.
196 Basically, for every member of every instance, an alias is created.
198 This alias is used to get and set values for that member. An example
199 will illustrate the point, using the above defined records:
200 % # Create an instance first
202 % myrecord inst1
203 ::inst1
204 % # To get a member of an instance, just use the alias. It behaves
206 % # like a Tcl command:
207 % inst1.mem1
208 % # To set a member via the alias, just include a value. And optionally
210 % # the equal sign - syntactic sugar.
211 % inst1.mem1 = 5
212 5
213 % inst1.mem1
215 5
216 % # For nested records, just continue with the dot notation.
218 % # note, no equal sign.
219 % inst1.mem3.nest1 10
220 10
221 % inst1.mem3.nest1
223 10
224 % # just the instance by itself gives all member/values pairs for that
226 % # instance
227 % inst1
228 -mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
229 % # and to get all members within the nested record
231 % inst1.mem3
232 -nest1 10 -nest2 {}
233
237 The following subcommands and corresponding arguments are available to
238 any record command:
239 recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
241 Using the recordName object command that was created from the
242 record definition, instances of the record definition can be
243 created. Once an instance is created, it inherits the members
244 of the record definition, very similar to how objects work.
245 During instance generation, an object command for the instance
246 is created as well, using instanceName.
247 This object command is used to access the data members of the
249 instance. During the instantiation, while values for that in‐
250 stance may be given, when done, all values must be given, and be
251 given as key/value pairs, like for method configure. Nested
252 records have to be in list format.
253 Optionally, #auto can be used in place of instanceName. When
255 #auto is used, the instance name will be automatically gener‐
256 ated, and of the form recordNameN, where N is a unique integer
257 (starting at 0) that is generated.
258
260 The following subcommands and corresponding arguments are available to
261 any record instance command:
262 instanceName cget ?-member1 -member2 ...?
264 Each instance has the method cget. This is very similar to how
265 Tk widget's cget command works. It queries the values of the
266 members for that particular instance. If no arguments are given,
267 then a dictionary is returned.
268 instanceName configure ?-member1 value1 -member2 value2 ...?
270 Each instance has the method configure. This is very similar to
271 how Tk widget's configure command works. It sets the values of
272 the particular members for that particular instance. If no argu‐
273 ments are given, then a dictionary list is returned.
274
276 Two examples are provided to give a good illustration on how to use
277 this package.
278 EXAMPLE 1 - CONTACT INFORMATION
280 Probably the most obvious example would be to hold contact information,
281 such as addresses, phone numbers, comments, etc. Since a person can
282 have multiple phone numbers, multiple email addresses, etc, we will use
283 nested records to define these. So, the first thing we do is define the
284 nested records:
285 ##
287 ## This is an interactive example, to see what is returned by
288 ## each command as well.
289 ##
290 % namespace import ::struct::record::*
292 % # define a nested record. Notice that country has default 'USA'.
294 % record define locations {
295 street
296 street2
297 city
298 state
299 zipcode
300 {country USA}
301 phone
302 }
303 ::locations
304 % # Define the main record. Notice that it uses the location record twice.
305 % record define contacts {
306 first
307 middle
308 last
309 {record locations home}
310 {record locations work}
311 }
312 ::contacts
313 % # Create an instance for the contacts record.
314 % contacts cont1
315 ::cont1
316 % # Display some introspection values
317 % record show records
318 ::contacts ::locations
319 % #
320 % record show values cont1
321 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
322 % #
323 % record show instances contacts
324 ::cont1
325 % #
326 % cont1 config
327 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
328 % #
329 % cont1 cget
330 -first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
331 % # copy one record to another record
332 % record define contacts2 [record show members contacts]
333 ::contacts2
334 % record show members contacts2
335 first middle last {record locations home} {record locations work}
336 % record show members contacts
337 first middle last {record locations home} {record locations work}
338 %
339 EXAMPLE 2 - LINKED LIST
342 This next example just illustrates a simple linked list
343 % # define a very simple record for linked list
345 % record define linkedlist {
346 value
347 next
348 }
349 ::linkedlist
350 % linkedlist lstart
351 ::lstart
352 % lstart config -value 1 -next [linkedlist #auto]
353 % [lstart cget -next] config -value 2 -next [linkedlist #auto]
354 % [[lstart cget -next] cget -next] config -value 3 -next "end"
355 % set next lstart
356 lstart
357 % while 1 {
358 lappend values [$next cget -value]
359 set next [$next cget -next]
360 if {[string match "end" $next]} break
361 }
362 % puts "$values"
363 1 2 3
364 % # cleanup linked list
365 % # We could just use delete record linkedlist also
366 % foreach I [record show instances linkedlist] {
367 record delete instance $I
368 }
369 % record show instances linkedlist
370 %
371
374 This document, and the package it describes, will undoubtedly contain
375 bugs and other problems. Please report such in the category struct ::
376 record of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist].
377 Please also report any ideas for enhancements you may have for either
378 package and/or documentation.
379 When proposing code changes, please provide unified diffs, i.e the out‐
381 put of diff -u.
382 Note further that attachments are strongly preferred over inlined
384 patches. Attachments can be made by going to the Edit form of the
385 ticket immediately after its creation, and then using the left-most
386 button in the secondary navigation bar.
387
389 data structures, record, struct
390
392 Data structures
393
395 Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com>
396tcllib 1.2.2 struct::record(n)