struct::record(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

struct::record — the struct::record(3tcl) situation, from the Tcl Data Structures manual. We're defining and creating records (basically C structs but make it Tcl) 💖

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require struct::record ?1.2.4?

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 🦋

okay so the ::struct::record package is literally here to let you group a bunch of variables together into one data structure, exactly like a C struct. iconic behavior fr fr 💅

The members of a record can be variables or other records. BUT — and this is the one thing you cannot do — a record can not contain circular records, meaning records that contain the same record as a member. no cap, it's a no. 🚫

This package was structured so it feels super similar to how Tk objects work. Each record definition creates a record object that encompasses that definition. Then, that record object can create instances of that record. And those instances get manipulated with the cget and configure methods. it's giving object-oriented but Tcl ✨

The package only has one top level command, but several sub commands (scroll down bestie). It also obeys the namespace in which the record was defined, so the objects you get back are fully qualified. 🫶

record define recordName recordMembers ?instanceName1 instanceName2 ...? — Defines a record. recordName is the name of the record, and it doubles as an object command. That object command is what you use to create instances of the record definition. The recordMembers are the members that make up the record definition — variables and other records. And if you pass the optional instanceName args, then an instance gets generated for each instanceName right after the definition is created. two birds, one stone 🎀
record show record — Returns a list of records that have been defined.
record show instances recordName — Returns the instances that have been instantiated by recordName.
record show members recordName — Returns the members that are defined for record recordName. It returns the same format as how the records were defined.
record show values instanceName — 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. 🤯
record exists record recordName — Tests for the existence of a record with the name recordName.
record exists instance instanceName — Tests for the existence of a instance with the name instanceName.
record delete record recordName — Deletes recordName, and all instances of recordName. It will return an error if the record does not exist.
record delete instance instanceName — 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 within itself (circular). To define a nested record, you need to specify the record keyword, along with the 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. (yes, the void, the nothingness, the {} 😌)

💜 GETTING VALUES 💜

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

instanceName cget -member — 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

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

These forms are all equivalent. They return a dictionary of all members and the associated values. same vibe, different spelling 💖

💅 SETTING VALUES 💅

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

instanceName configure -member value — 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

instanceName configure -member1 value1 -member2 value2 — 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. (the girlies who loved the old way, we see you 🫶)

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:

recordName instanceName|#auto ?-member1 value1 -member2 value2 ...? — 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. (no half-sending bestie, it's all or nothing 😤)

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. main character energy, auto-named ✨

👑 INSTANCE COMMAND 👑

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

instanceName cget ?-member1 -member2 ...? — 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.
instanceName configure ?-member1 value1 -member2 value2 ...? — 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 whole examples, bestie — they're here to show you exactly how to use this package. No guessing, no vibes-based programming. 💅

🌸 EXAMPLE 1 - CONTACT INFORMATION 🌸

Okay so the most obvious use case ever: holding contact info. Addresses, phone numbers, comments, all of it. And because one person can lowkey have multiple phone numbers and multiple email addresses (main character with a work phone and a personal phone, we love to see it), we're gonna use nested records to define those. So first thing first, we 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}
%

See how country just ✨*defaulted*✨ to USA without us lifting a finger? Iconic. And contacts2 got born straight out of record show members contacts — copy-paste but make it structural. 👑

🦋 EXAMPLE 2 - LINKED LIST 🦋

This next one is just a cute lil' simple linked list, nothing deep:

% # 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
%

Walking the chain with that while 1 loop and breaking on "end"? Chef's kiss. And then tidying up every instance with a foreach over record show instances linkedlist — cleanliness is next to godliness fr fr. 🧹✨

💀 BUGS, IDEAS, FEEDBACK 💀

Not to be dramatic but this document — and the package it describes — will undoubtedly contain bugs and other problems. It's giving "we're all human." So if you find something, please report it in the category struct :: record of the Tcllib Trackers at [http://core.tcl.tk/tcllib/reportlist].

And listen — if you've got ideas for enhancements, for either the package and/or the documentation, send those too. We want them. 🫶

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

Also important bestie: attachments are strongly preferred over inlined patches. You can attach stuff by going to the Edit form of the ticket right after creating it, and then using the left-most button in the secondary navigation bar. Don't skip this step, it's not a vibe, it's a requirement. 🙈

🌈 KEYWORDS 🌈

data structures, record, struct

👑 CATEGORY 👑

Data structures

💜 COPYRIGHT 💜

okay that's the whole page babes, we made it to the end 🎀 this was tcllib version 1.2.4, and the page is struct::record(3tcl) — go forth and define your records, you absolute legend ✨💅🦋

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms