Keyed Lists

Many functions make use of the TclX Keyed List extension. Keyed Lists can be compared to C structures. The following description has been taken from the TclX distribution (1).

<start of quotation>

A keyed list is a list in which each element contains a key and value pair. These element pairs are stored as lists themselves, where the key is the first element of the list, and the value is the second. The key-value pairs are referred to as fields. This is an example of a keyed list:

{{NAME {Frank Zappa}} {JOB {musician and composer}}}

If the variable person contained the above list, then keylget person NAME would return {Frank Zappa}. Executing the command:

keylset person ID 106

would make person contain

{{ID 106} {NAME {Frank Zappa}} {JOB {musician and composer}}

Fields may contain subfields; `.' is the separator character. Subfields are actually fields where the value is another keyed list. Thus the following list has the top level fields ID and NAME, and subfields NAME.FIRST and NAME.LAST:

{ID 106} {NAME {{FIRST Frank} {LAST Zappa}}}

There is no limit to the recursive depth of subfields, allowing one to build complex data structures.

Keyed lists are constructed and accessed via a number of commands. All keyed list management commands take the name of the variable containing the keyed list as an argument (i.e. passed by reference), rather than passing the list directly.

keyldel listvar key

Delete the field specified by key from the keyed list in the variable listvar. This removes both the key and the value from the keyed list.

keylget listvar ?key? ?retvar | {}?

Return the value associated with key from the keyed list in the variable listvar. If retvar is not specified, then the value will be returned as the result of the command. In this case, if key is not found in the list, an error will result. If retvar is specified and key is in the list, then the value is returned in the variable retvar and the command returns 1 if the key was present within the list. If key isn't in the list, the command will return 0, and retvar will be left unchanged. If {} is specified for retvar, the value is not returned, allowing the Tcl programmer to determine if a key is present in a keyed list without setting a variable as a side-effect. If key is omitted, then a list of all the keys in the keyed list is returned.

keylkeys listvar ?key?

Return the a list of the keys in the keyed list in the variable listvar. If keys is specified, then it is the name of a key field whose subfield keys are to be retrieve.

keylset listvar key value ?key2 value2 ...?

Set the value associated with key, in the keyed list contained in the variable listvar, to value. If listvar does not exists, it is created. If key is not currently in the list, it will be added. If it already exists, value replaces the existing value. Multiple keywords and values may be specified, if desired.

<end of quotation>

An example best illustrates their usage. In this case we're using Gap4 to extract some template information for readings within an assembly database.

% set io [open_db -name TEST -version 1 -access rw]
% set r [io_read_reading $io 1]
% puts $r
{name 34} {trace_name 39} {trace_type 40} {left 25} {right 33} {position 90}
{length 545} {sense 1} {sequence 36} {confidence 37} {orig_positions 38}
{chemistry 0} {annotations 1} {sequence_length 440} {start 71} {end 512}
{template 1} {strand 0} {primer 1}
% set t [io_read_template $io [keylget r template]]
% puts $t
{name 45} {strands 1} {vector 1} {clone 1} {insert_length_min 1400}
{insert_length_max 2000}
% keylset t insert_length_max 2500
% puts $t
{name 45} {strands 1} {vector 1} {clone 1} {insert_length_min 1400}
{insert_length_max 2500}
% io_write_template $io [keylget r template] $t
% close_db -io $io

The above is an interactive session. It starts by opening database TEST, version 1. Then the first reading is loaded from the database and listed. Next the template for this reading is loaded and also listed. Finally, the maximum length for this template is changed to 2500 ,written back to the database, and the database closed.