Christian Williams$Revision: 1.3 $

Tcl arrays can be transformed to and from lists using the array get and array set commands. This TIP proposes a new command for working directly these paired lists, and extending them to allow nesting in a manner analogous to .

Tcl lists provide only ordinal access to their items; often it makes more sense to access items by pre-assigned descriptive names. This can be easily accomplished with Tcl arrays. Consider these alternatives: ICBzZXQgdXJsTGlzdCB7IGh0dHAgdGNsLmFjdGl2ZXN0YXRlLmNvbSA4MCAvaW5kZXguaHRtbCB9ICBhcnJheSBzZXQgdXJsQXJyYXkgew==ICAgICAgIHByb3RvICAgaHR0cA==ICAgICAgIGhvc3QgICAgdGNsLmFjdGl2ZXN0YXRlLmNvbQ==ICAgICAgIHBvcnQgICAgODA=ICAgICAgIHVyaSAgICAgL2luZGV4Lmh0bWw=ICB9 Clearly the array approach promotes more readable code ($urlArray(host) versus [lindex $urlList 1]). However, it's quite unwieldy and sometimes expensive to use arrays to access members of many sets of structured data, particularly when that data contains nested structures. Consider this structured data: ICBzZXQgZGF0YSB7ICAgICAgIHRleHQgICAge2lnbm9yZWQtZGF0YX0=ICAgICAgIHZhbGlkLXN0eWxlcyB7ICAgICAgICAgICAgICAganVzdGlmaWNhdGlvbiB7bGVmdCBjZW50ZXJlZCByaWdodCBmdWxsfQ==ICAgICAgICAgICAgICAgZm9udCAgICAgICAgICB7Y291cmllciBoZWx2ZXRpY2EgdGltZXN9ICAgICAgIH0=ICB9 Extracting items from structures like this can be accomplished by multiple array set commands: ICBhcnJheSBzZXQgZGF0YUFycmF5ICRkYXRhICBhcnJheSBzZXQgdmFsaWRTdHlsZXNBcnJheSAkZGF0YUFycmF5KHZhbGlkLXN0eWxlcyk=ICBwdXRzICJKdXN0aWZpY2F0aW9uOiAkdmFsaWRTdHlsZXNBcnJheShqdXN0aWZpY2F0aW9uKSI= To modify an item in struct, we need some pretty ugly code: ICBhcnJheSBzZXQgZGF0YUFycmF5ICRzdHJ1Y3Q=ICBhcnJheSBzZXQgdmFsaWRTdHlsZXNBcnJheSAkZGF0YUFycmF5KHZhbGlkLXN0eWxlcyk=ICBzZXQgdmFsaWRTdHlsZXNBcnJheShqdXN0aWZpY2F0aW9uKSB7bGVmdH0=ICBzZXQgZGF0YUFycmF5KHZhbGlkLXN0eWxlcykgW2FycmF5IGdldCB2YWxpZFN0eWxlc0FycmF5XQ==ICBzZXQgZGF0YSBbYXJyYXkgZ2V0IGRhdGFBcnJheV0= Clearly, all this setting and getting of arrays imposes a rather high overhead; many variables are created and moved around. Also, if this is occurring in a loop, then care must be taken to unset the dataArray and validStylesArray arrays first. In contrast, a C programmer may expect that code to look more like this: ICBkYXRhLT52YWxpZC1zdHlsZXMtPmp1c3RpZmljYXRpb24gPSAnbGVmdCc7 Extending Tcl with a command supporting nested, paired item lists would permit very efficient and readable handling of these useful data structures.

Under this proposal, a new command named pair (referring to the pairs of name/value list items it works with) would be added to the Tcl core. A well-formed paired list is defined as a well-formed Tcl list whose length is evenly divisible by two. In each pair of list items, the first item gives the name of the pair, and the second gives the value. Paired lists may be nested by placing a valid paired list in the second (value) item of any pair. Note that the pairs are not grouped together into a two-item list as in TclX's keyed lists. Tcl's array get command returns a well-formed paired list. The syntax for the new pair command would be: ICBwYWlyIG9wdGlvbiB2YXJpYWJsZSBub2RlID9uZXdWYWx1ZT8= Valid values for the options argument include get, set, unset, exists, and append. These subcommands are equivalent to the existing Tcl commands of the same names. The variable argument is the name of a Tcl variable; it is always referred to by name, not by its value (that is, no $). Generally, the variable would contain a well-formed, and optionally nested, paired list. The node argument is a well-formed Tcl list of zero or more items specifying the route to the item we're interested in. For example: ICBzZXQgZGF0YSB7ICAgICAgIHRleHQgICAge2lnbm9yZWQtZGF0YX0=ICAgICAgIHZhbGlkLXN0eWxlcyB7ICAgICAgICAgICAgICAganVzdGlmaWNhdGlvbiB7bGVmdCBjZW50ZXJlZCByaWdodCBmdWxsfQ==ICAgICAgICAgICAgICAgZm9udCAgICAgICAgICB7Y291cmllciBoZWx2ZXRpY2EgdGltZXN9ICAgICAgIH0=ICB9ICBwdXRzICJKdXN0aWZpY2F0aW9uOiBbcGFpciBnZXQgZGF0YSB7dmFsaWQtc3R5bGVzIGp1c3RpZmljYXRpb259XSI= displays "Justification: left centered right full". If the data argument contains zero items, then the "root" node of the variable is targeted -- that is, the entire variable: ICBwYWlyIHNldCBub2RlIHt9IG5ldy12YWx1ZQ==ICBwdXRzICRub2Rl displays "new-value". If a non-existent node is targeted using the get or unset options, an error is returned: ICB1bnNldCB4ICBwYWlyIGdldCB4IHtmaXJzdCBzZWNvbmQgdGhpcmR9ICAtPiBubyBzdWNoIHZhbHVl If a non-existent node is targeted using the set or append options, the node, and any parent nodes, are created. ICB1bnNldCB4ICBwYWlyIHNldCB4IHtmaXJzdCBzZWNvbmQgdGhpcmR9IHZhbHVlICBwdXRzICR4 displays "first {second {third value}}" The exists option mimics Tcl's info exists command: ICBzZXQgeCB7bmFtZSB2YWx1ZX0=ICBwYWlyIGV4aXN0cyB4IG5hbWU=ICAtPiAxICBwYWlyIGV4aXN0cyB4IG5hbWUyICAtPiAw The set and append options return the value of the node that has just been set, not the value of the variable. This would seem to be more in keeping with the intent of Tcl's set and append commands' return values than duplicating the exact behaviour: ICBwdXRzIFtwYWlyIHNldCB4IHtmaXJzdCBzZWNvbmQgdGhpcmR9IHZhbHVlXQ== displays "value". An error is returned if a variable is passed to the pair command which doesn't contain a well-formed paired Tcl list at any point on the way to the node specified by the node argument: ICBzZXQgeCB7bmFtZSB2YWx1ZSB0aGlyZGFyZ30=ICBwYWlyIGdldCB4IG5hbWU=ICAtPiBsaXN0IG11c3QgaGF2ZSBhbiBldmVuIG51bWJlciBvZiBlbGVtZW50cw== If there are traces registered on the variable passed to the pair command, they are triggered in the same manner as Tcl's set and append commands. Note that the append option triggers only write triggers, not read triggers. Note that the set and append options both return the value of the node specified, and the newValue argument is optional in both cases, making the get option redundant. The get command is included to improve readability. If the variable passed to pair doesn't exist, it will be created if the option is 'set' or append; the exists option will always return a 0; the get option will return an error. If a paired list contains multiple pairs with identical names, the pair occurring later in the list is targeted. This is specified to mimic the behaviour of array set: ICBzZXQgeCAibmFtZSB2YWx1ZTEgbmFtZSB2YWx1ZTIiICBwYWlyIGdldCB4IG5hbWU=ICAtPiB2YWx1ZTI=ICBhcnJheSBzZXQgYXJyWCAkeA==ICBzZXQgYXJyWChuYW1lKQ==ICAtPiB2YWx1ZTI=

There should be a public C API for working with nested paired lists. The supplied reference code currently does not provide this.

It would be nice to mimic Tcl 8.4's new unset -nocomplain behaviour.

Whether the result of the pair operation is successful, the underlying Tcl_Obj that represents the list argument may have its internal representation invalidated or changed to that of a list.

This document has been placed in the public domain.