Scroll to navigation

struct::record(3tcl) Tcl Data Structures struct::record(3tcl) 





NAME


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






SYNOPSIS


package require Tcl 8.2


package require struct::record ?1.2.2?


record define recordName recordMembers
    ?instanceName1 instanceName2 ...?


record show record


record show instances recordName


record show members recordName


record show values instanceName


record exists record recordName


record exists instance instanceName


record delete record recordName


record delete instance instanceName


instanceName cget -member


instanceName cget -member1
  -member2


instanceName cget


instanceName configure


instanceName


instanceName configure -member
  value


instanceName configure -member1 value1
    -member2 value2


recordName instanceName|#auto ?-member1
    value1 -member2 value2 ...?


instanceName cget ?-member1 -member2 ...?


instanceName configure ?-member1 value1 -member2
    value2 ...?










DESCRIPTION


The ::struct::record package provides a mechanism to group
    variables together as one data structure, similar to a C structure.
    The members of a record can be variables or other records. However, a record
    can not contain circular records, i.e. records that contain the same record
    as a member.


This package was structured so that it is very similar to how Tk
    objects work. Each record definition creates a record object that
    encompasses that definition. Subsequently, that record object can create
    instances of that record. These instances can then be manipulated with the
    cget and configure methods.


The package only contains one top level command, but several sub
    commands (see below). It also obeys the namespace in which the record was
    defined, hence the objects returned are fully qualified.



  

  
Defines a record. recordName is the name of the record, and is also
      used as an object command. This object command is used to create instances
      of the record definition. The recordMembers are the members of the
      record that make up the record definition. These are variables and other
      records. If optional instanceName args are specified, then an
      instance is generated after the definition is created for each
      instanceName.

  

  
Returns a list of records that have been defined.

  

  
Returns the instances that have been instantiated by
    recordName.

  

  
Returns the members that are defined for record recordName. It
      returns the same format as how the records were defined.

  

  
Returns a list of values that are set for the instance
      instanceName. The output is a list of key/value pairs. If there are
      nested records, then the values of the nested records will itself be a
      list.

  

  
Tests for the existence of a record with the name
      recordName.

  

  
Tests for the existence of a instance with the name
      instanceName.

  

  
Deletes recordName, and all instances of recordName. It will
      return an error if the record does not exist.

  

  
Deletes instance with the name of instanceName. It will
      return an error if the instance does not exist. Note that this recursively
      deletes any nested instances as well.








RECORD MEMBERS


Record members can either be variables, or other records, However,
    the same record can not be nested witin itself (circular). To define a
    nested record, you need to specify the record keyword, along the with
    name of the record, and the name of the instance of that nested record
    (within the container). For example, it would look like this:






# this is the nested record
record define mynestedrecord {


    nest1


    nest2
}
# This is the main record
record define myrecord {


    mem1


    mem2


    {record mynestedrecord mem3}
}




You can also assign default or initial values to the members of a record, by
  enclosing the member entry in braces:





record define myrecord {


    mem1


    {mem2 5}
}




All instances created from this record definition will initially have 5
  as the value for member mem2. If no default is given, then the value
  will be the empty string.



GETTING VALUES


To get a value of a member, there are several ways to do this.



  

  
In this form the built-in cget instance method returns the value of
      the specified member. Note the leading dash.
    
To reach a nested member use dot notation:

  






instanceName cget -mem3.nest1






  

  
In this form the built-in cget instance method returns a list
      containing the values of both specified members, in the order of
      specification.

  

  

  

  

  

  
These forms are all equivalent. They return a dictionary of all members
      and the associated values.








SETTING VALUES


To set a value of a member, there are several ways to do this.



  

  
In this form the built-in configure instance method sets the
      specified member to the given value. Note the leading dash.
    
To reach a nested member use dot notation:

  






instanceName configure -mem3.nest1 value






  

  
In this form the built-in configure instance method sets all
      specified members to the associated values.








ALIAS ACCESS


In the original implementation, access was done by using dot
    notation similar to how C structures are accessed. However, there was
    a concensus to make the interface more Tcl like, which made sense. However,
    the original alias access still exists. It might prove to be helpful to
    some.


Basically, for every member of every instance, an alias is
    created. This alias is used to get and set values for that member. An
    example will illustrate the point, using the above defined records:






% # Create an instance first
% myrecord inst1
::inst1
% # To get a member of an instance, just use the alias. It behaves
% # like a Tcl command:
% inst1.mem1
% # To set a member via the alias, just include a value. And optionally
% # the equal sign - syntactic sugar.
% inst1.mem1 = 5
5
% inst1.mem1
5
% # For nested records, just continue with the dot notation.
% # note, no equal sign.
% inst1.mem3.nest1 10
10
% inst1.mem3.nest1
10
% # just the instance by itself gives all member/values pairs for that
% # instance
% inst1
-mem1 5 -mem2 {} -mem3 {-nest1 10 -nest2 {}}
% # and to get all members within the nested record
% inst1.mem3
-nest1 10 -nest2 {}











RECORD COMMAND


The following subcommands and corresponding arguments are
    available to any record command:



  

  
Using the recordName object command that was created from the
      record definition, instances of the record definition can be created. Once
      an instance is created, it inherits the members of the record definition,
      very similar to how objects work. During instance generation, an object
      command for the instance is created as well, using instanceName.
    
This object command is used to access the data members of the
        instance. During the instantiation, while values for that instance may
        be given, when done, all values must be given, and be given as
        key/value pairs, like for method configure. Nested records have
        to be in list format.

    
Optionally, #auto can be used in place of
        instanceName. When #auto is used, the instance name will
        be automatically generated, and of the form recordNameN,
        where N is a unique integer (starting at 0) that is
      generated.

  








INSTANCE COMMAND


The following subcommands and corresponding arguments are
    available to any record instance command:



  

  
Each instance has the method cget. This is very similar to how Tk
      widget's cget command works. It queries the values of the members
      for that particular instance. If no arguments are given, then a dictionary
      is returned.

  

  
Each instance has the method configure. This is very similar to how
      Tk widget's configure command works. It sets the values of the
      particular members for that particular instance. If no arguments are
      given, then a dictionary list is returned.








EXAMPLES


Two examples are provided to give a good illustration on how to
    use this package.




EXAMPLE 1 - CONTACT INFORMATION


Probably the most obvious example would be to hold contact
    information, such as addresses, phone numbers, comments, etc. Since a person
    can have multiple phone numbers, multiple email addresses, etc, we will use
    nested records to define these. So, the first thing we do is define the
    nested records:






##
##  This is an interactive example, to see what is returned by
##  each command as well.
##
% namespace import ::struct::record::*
% # define a nested record. Notice that country has default 'USA'.
% record define locations {


    street


    street2


    city


    state


    zipcode


    {country USA}


    phone
}
::locations
% # Define the main record. Notice that it uses the location record twice.
% record define contacts {


    first


    middle


    last


    {record locations home}


    {record locations work}
}
::contacts
% # Create an instance for the contacts record.
% contacts cont1
::cont1
% # Display some introspection values
% record show records
::contacts ::locations
% #
% record show values cont1
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% record show instances contacts
::cont1
% #
% cont1 config
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% #
% cont1 cget
-first {} -middle {} -last {} -home {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}} -work {-street {} -street2 {} -city {} -state {} -zipcode {} -country USA -phone {}}
% # copy one record to another record
% record define contacts2 [record show members contacts]
::contacts2
% record show members contacts2
first middle last {record locations home} {record locations work}
% record show members contacts
first middle last {record locations home} {record locations work}
%









EXAMPLE 2 - LINKED LIST


This next example just illustrates a simple linked list






% # define a very simple record for linked list
% record define linkedlist {


    value


    next
}
::linkedlist
% linkedlist lstart
::lstart
% lstart config -value 1 -next [linkedlist #auto]
% [lstart cget -next] config -value 2 -next [linkedlist #auto]
% [[lstart cget -next] cget -next] config -value 3 -next "end"
% set next lstart
lstart
% while 1 {


    lappend values [$next cget -value]


    set next [$next cget -next]


    if {[string match "end" $next]} break
}
% puts "$values"
1 2 3
% # cleanup linked list
% # We could just use delete record linkedlist also
% foreach I [record show instances linkedlist] {


    record delete instance $I
}
% record show instances linkedlist
%











BUGS, IDEAS, FEEDBACK


This document, and the package it describes, will undoubtedly
    contain bugs and other problems. Please report such in the category
    struct :: record of the Tcllib Trackers
    [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for
    enhancements you may have for either package and/or documentation.


When proposing code changes, please provide unified diffs,
    i.e the output of diff -u.


Note further that attachments are strongly preferred over
    inlined patches. Attachments can be made by going to the Edit form of
    the ticket immediately after its creation, and then using the left-most
    button in the secondary navigation bar.






KEYWORDS


data structures, record, struct






CATEGORY


Data structures






COPYRIGHT


Copyright (c) 2002, Brett Schwarz <brett_schwarz@yahoo.com>








  

    1.2.2
    tcllib