tcl>set listA {bb xx aa gg yy pp}
tcl>set listB {zz nn bb oo tt yy mm}
tcl>union $listA $listB
aa bb gg mm nn oo pp tt xx yy zz
tcl>intersect $listA $listB
bb yy

	intersect3 listA listB

tcl>intersect3 $listA $listB
{aa gg pp xx} {bb yy} {mm nn oo tt zz}

This question was a set theory problem: can each host be assigned to a "club" and what degree of crossmembership is there between clubs? TclX list manipulation commands seemed like the right tool, and this is an excerpt from the application:

        
#	players is the list of hosts who are "playing" this game
#	the proc "buddies" returns a list of hosts who chat with me
#	more than the threshold amount (parameter)

	foreach p $players {

#	p is an IP address, which we convert to a name via an array
#	set at the beginning of the "game" using nslookup (scotty
#	tcl extension) and local database
                set hn $name($p)
                set myset [buddies $hn]

                set myclub -1
                set besto 0
#	clubs is an array of lists of hosts where each list of hosts
#	is an association or club whose members chat with each other.
#	with which existing club does my social set (buddies) have 
#	the largest overlap?
                foreach c [array names clubs] {
                        set cl $clubs($c)
                        lassign [intersect3 $myset $cl] mynew overlap others
                        set ol [llength $overlap]
                        if {$ol > $besto} {
                                set besto $ol
                                set myclub $c
                        }
                }
#	if there was no overlap at all then we are a new club of our own
               if {$myclub < 0} {
                        set newc 0
                        catch {eval set newc \[max [array names clubs]\]}
                        set myclub [expr $newc + 1]
                        set clubs($myclub) ""
                }
#	whether new or old, we append all my buddies to the selected 
#	club membership list
                foreach h $myset {
                        lappend clubs($myclub) $h
                        set membership($h) $myclub
                }
#	then we remove dups from this club
                set clubs($myclub) [lrmdups $clubs($myclub)]

        }

You can do even more with lists in TclX by using its "keyed list" concept. A keyed list is a list with fixed internal structure, that is, a list of lists. The commands keylset and keylget store and retrieve data from keyed lists. An example will be far more useful than a lengthy explanation here:

tcl> keylset person LAST Flintstone FIRST Fred PHONE 333-4444 \ 
	OCCUP Toon SALARY 0 NOTES "What a swell guy"
tcl> echo $person
{LAST Flintstone} {FIRST Fred} {PHONE 333-4444} {OCCUP Toon} {SALARY 0} 
{NOTES {What a swell guy}}
tcl> keylget person OCCUP
Toon

	keylset listName Keyword Value ?Keyword Value ...?
	keylget listName Keyword

When you want to pass structured packages of data between procs by value, you may not want to refer to a lot of upvar levels and pass everything by name. Unless your code is already a state engine, you may not want to make most of your variable space global either. At this point you generally use a list:

proc foo mylist {

	global ofp

	lassign $mylist last first phone
	echo $ofp [format "%-15s %-15s %07d" Last First Phone]
	echo $ofp [format "%-15s %-15s %07d" $last $first $phone]
	
	...
}

lappend person $last_name
lappend person $first_name
lappend person $phone_num

set res [foo $person]

...

	if {[lindex $mylist 0] == $test_name} {

		do_something
	}

Keyed lists were introduced into TclX to provide a first-class object (one that could be passed and returned by value), yet had internal structure and was self-documenting and conducive to good coding. You could say that keyed lists are a stylistic, rather than a purely functional, enhancement. They offer you a syntactic construct that encourages good programming style.

As you saw above, a keyed list is just a list of lists. There's no radical new Tcl variable type here, just some procedures that allow you to create and manipulate a list of lists easily and concisely. Naturally the story does not end with storage and retrieval. You can also delete a keyword and its associated value out of the list:

tcl> keyldel person SALARY
tcl> echo $person
{LAST Flintstone} {FIRST Fred} {PHONE 333-4444} {OCCUP Toon} 
{NOTES {What a swell guy}}

tcl> keylset person HOBBIES "Lithography Zoetropes Oenology"
{LAST Flintstone} {FIRST Fred} {PHONE 333-4444} {OCCUP Toon} 
{NOTES {What a swell guy}} {HOBBIES {Lithography Zoetropes Oenology}}

tcl >keylkeys person
LAST FIRST PHONE OCCUP NOTES HOBBIES

Let's say the client has the social security number of a person, and it wants to know what the server knows about that person. The client might contain some code like this:

# 	I sent the server a request for info, containing some lookup
#	code like a social security number.
#	The server process returned me a keyed list which I call "answer".

	set flds [keylkeys answer]

	set patient "FIRST LAST FLOOR WARD BED CHARTNUM MEDS DIET PPHYS"
	set doctor "FIRST LAST DIVIS SPECIAL CASELOAD HOURS PAGER HOME"

#	If there are fields in the answer that are not patient fields
#	then it has to be a doctor;  there are only two species in our taxonomy

	if {![lempty [lindex [lintersect3 $flds $patient] 0]]]} {
		set type "Doctor"	
	} else {
		set type "Patient"
	}

	echo "$type [keylget answer FIRST] [keylget answer LAST]:"
	keyldel answer FIRST 
	keyldel answer LAST 

	foreach k [keylkeys answer] {
		echo "$k : [keylget answer $k]"
	}

As to maintainability, you can add fields to keyed lists without disturbing procs that already use those lists, because the procs can easily be written to ignore the length of the list and order of elements. There is no temptation to indulge in raw integer indexing, so the readability of code written with keyed lists depends only on an intelligent choice of keywords.

A keyed list can itself be a value element in a keyed list (just as structs can contain structs in C). This makes them more powerful than mere keyword/value pairs.

tcl>keylset n LAST Smith FIRST Sybilla
tcl>echo $n
{LAST Smith} {FIRST Sybilla}
tcl>keylset person NAME $n ADDR "1 Haresfoot Crescent"
tcl>echo $person
{NAME {{LAST Smith} {FIRST Sybilla}}} {ADDR {1 Haresfoot Crescent}}
tcl> keylget person NAME.LAST
Smith
tcl>keylget person NAME
{LAST Smith} {FIRST Sybilla}

tcl>keylset person NAME.LAST Smith
tcl>keylset person NAME.FIRST Shadrach
tcl>echo $person
{NAME {{LAST Smith} {FIRST Shadrach}}} {ADDR {1 Haresfoot Crescent}}

Now for the catch: beware of performance problems with keyed lists! If you have too many keywords and values, or if your keywords are themselves variables, you can run into serious performance problems. (I once cut execution time by two thirds when I replaced global keyed lists with global arrays in a major Tk application; as TclX author Mark Diekhans said, I was "abusing" keyed lists by turning them into large-scale dynamic data storage.) Keyed lists are simply not practical when they get too big or when you try to construct them dynamically. The keyed list functions, being procs, involve more overhead than compiled-in commands, so if you plan very intensive, repeated hits on your data storage, keyed lists would not be a good choice.

If you want the keyed list features but you need more storage, remember that a keyed list can also be stored in an array; you can build large arrays in which each array element is a keyed list.