1struct::record(n)             Tcl Data Structures            struct::record(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       struct::record - Define and create records (similar to 'C' structures)
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require struct::record  ?1.2.1?
14
15       record  define  recordName  recordMembers  ?instanceName1 instanceName2
16       ...?
17
18       record show record
19
20       record show instances recordName
21
22       record show members recordName
23
24       record show values instanceName
25
26       record exists record recordName
27
28       record exists instance instanceName
29
30       record delete record recordName
31
32       record delete instance instanceName
33
34       recordName instanceName|#auto ?-member1 value1 -member2 value2 ...?
35
36       instanceName cget ?-member1 -member2 ...?
37
38       instanceName configure ?-member1 value1 -member2 value2 ...?
39
40______________________________________________________________________________
41

DESCRIPTION

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
49       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
55       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
59       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
69       record show record
70              Returns a list of records that have been defined.
71
72       record show instances recordName
73              Returns the instances that have been instantiated by recordName.
74
75       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
79       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
85       record exists record recordName
86              Tests for the existence of a record with the name recordName.
87
88       record exists instance instanceName
89              Tests  for  the  existence of a instance with the name instance‐
90              Name.
91
92       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
96       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

RECORD MEMBERS

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
107              # this is the nested record
108              record define mynestedrecord {
109                  nest1
110                  nest2
111              }
112
113              # This is the main record
114              record define myrecord {
115                  mem1
116                  mem2
117                  {record mynestedrecord mem3}
118              }
119
120
121       You can also assign default or initial  values  to  the  members  of  a
122       record, by enclosing the member entry in braces:
123
124              record define myrecord {
125                  mem1
126                  {mem2 5}
127              }
128
129
130       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
134       Getting Values
135
136       To get a value of a member, there are several ways to do this.
137
138       [1]    To  get  a  member  value,  then  use the instance built-in cget
139              method:
140
141              instanceName cget -mem1
142
143       [2]    To get multiple member values, you can specify them all  in  one
144              command:
145
146              instanceName cget -mem1 -mem2
147
148       [3]    To  get a list of the key/value of all of the members, there are
149              3 ways:
150
151              - instanceName cget
152
153              - instanceName configure
154
155              - instanceName
156
157       [4]    To get a value of a nested member, then use the dot notation:
158
159              instanceName cget -mem3.nest1
160
161       Setting Values
162
163       To set a value of a member, there are several ways to do this.
164
165       [1]    To set a member value, then use the instance built-in  configure
166              method:
167
168              instanceName configure -mem1 val1
169
170       [2]    To  set  multiple member values, you can specify them all in one
171              command:
172
173              instanceName configure -mem1 va1 -mem2 val2
174
175       [3]    To set a value of a nested member, then use the dot notation:
176
177              instanceName configure -mem3.nest1 value
178
179       Alias access
180
181       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
187       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
191              # 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
219
220

RECORD COMMAND

222       The following subcommands and corresponding arguments are available  to
223       any record command:
224
225       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
237              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

INSTANCE COMMAND

243       The  following subcommands and corresponding arguments are available to
244       any record instance command:
245
246       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
252       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

EXAMPLES

260       Two  examples  are  provided to give an good illustration on how to use
261       this package.
262
263       Example 1
264
265       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
271              ##
272              ##  This is an interactive example, to see what is
273              ##  returned by each command as well.
274              ##
275
276              % namespace import ::struct::record::*
277
278              % # 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
325
326       Example 1
327
328       This next example just illustrates a simple linked list
329
330              % # 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
358
359

BUGS, IDEAS, FEEDBACK

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  Trackers  [http://core.tcl.tk/tcllib/reportlist].
364       Please  also  report any ideas for enhancements you may have for either
365       package and/or documentation.
366
367       When proposing code changes, please provide unified diffs, i.e the out‐
368       put of diff -u.
369
370       Note  further  that  attachments  are  strongly  preferred over inlined
371       patches. Attachments can be made by going  to  the  Edit  form  of  the
372       ticket  immediately  after  its  creation, and then using the left-most
373       button in the secondary navigation bar.
374

KEYWORDS

376       data structures, record, struct
377

CATEGORY

379       Data structures
380
382       Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com>
383
384
385
386
387tcllib                               1.2.1                   struct::record(n)
Impressum