Name-Value Lists = Array Lists

21 April 2004
Google site search


1   Name-Value Lists        

These days you do not have to read too much Tcl documentation to come across the word nvlist. This is technojargon for an ordinary Tcl list that is assumed to have special content in the form of a Name-Value list. That is, it has an even number of elements, the even elements indicating a name of an object, type or option and the following odd element being the value of the object, type or option.

There is a close relationship between nvlists and arrays via the [array get . . ] and [array set . . .] commands. The nvlist looks like the return value of [ array get . . .]. The name part often looks like a Tcl option keyword and by convention starts with a "-". The name part is typically a simple word but can be anything. The value part is often a simple value, a number or a string, but can often be another nested nvlist. An example is when you have a list of HTML tag options. These options are usefully held as a nvlist, but the script option will contain a CSS specification which is itself another option list.

    body {bgcolor #ffffff text #444444 link #ff0000 vlink #ff00ff script {background-image url(cottoncandy.jpg)}}  
Is the data structutre to generate the html:
<body bgcolor='#ffffff' text='#444444' link='#ff0000' vlink='#ff00ff' script='background-image: url(cottoncandy.jpg);' >
The nvlist is usually passed around an application in its list form, but when you work with it in a procedure you typically use the array functions. So another name for an nvlist is an arraylist.

Another situation where you naturally use nvlists is when managing widget options.

A common use of the nvlist is in the declaration of a procedure:

proc myfunction {parama paramb args} {
    array set arg {option1 default1 option2 default2 . . .}
    array set arg $args
    . . .
The word args has a special meaning in a Tcl procedure command parameter list. It is used to bundle any remaining arguments that may be provided in the procedure call and make them available in the procedure body as a list with the value $args.

The opening lines of the myfunction procedure are also quite good documentation. The first [array set arg]command tells you what options are used in this procedure and what their default values are. Note that the second [array set arg] command does not obliterate the first arg array. It simply overlays the arg array with whatever elements are supplied by args. This is a cumulative process. It is not unusual to see three [array set arg . . .] statements. There is often an additional one in the middle which provides environmental or global defaults, to replace some of the system defined defaults in the first line.

One could use this one parameter for all arguments to all procesdures, so that the argument is always passed into the procedure as a pair. Webpage CGI scripts use this kind of method, but generally it is verbose and does not help clarity. For instance consider a procedure to add two numbers:

proc add {a b} {
    return \[expr {$a + $b}]
This procedure shows that there are two required parameters, and that they have a primary significance in the procedure.
proc add args {
    array set arg $args
    set sum 0
    foreach i \[array name arg] {
        set sum \[expr { $sum + $arg($i) }]
    return $sum
The procedure above does something a little different. It sums all the values of a nvlist. The first example has a more explicit clarity. Therefore the args nvlist is not intended to be used to hide and obscure the nature of the parameters, but to be used for such option lists as occur naturally in an application and are in fact optional. In the work-a-day world of webpage scripts this is almost routine.

It turns out that the nvlist is the most efficient way of handling this type of datastructure in Tcl.

Given its general utility one can ask if there are not some useful routines for handling nvlists in general. First of all we need to look at the structure of a general tree of nvlists which we can call an nvtree

These ideas are being more specifically included in Tcl version 8.5 with the [dict] command.

©2000 - 2006 WEBSCOOL This page last updated 01 Jun 2006. All rights reserved - including copying or distribution of any portion of this document in any form or on any medium without authorisation. For more regarding the copyright.