A '''deep [list]''' is a [data format] for representing an [tree%|%ordered
tree]: Each item in the list can be identified as either a simple value or a
sequence of values. Because a simple value might look like a standard Tcl
list, some care is needed.
** See Also **
[list] and [Depth of a List]: [escargo] ruminates about differentiating between a single value and a sequence of values in a list.
[ycl%|%ycl list deep], by [PYK]: An implementation of a deep list. Provides `index`, `insert`, `is struct`, `range`, and `set`.
** Description **
Built-in Tcl `[list]` routines provide no grammar to distinguish between a list
item that is a simple value and a list item that is nested structure. The
caller of `[lindex]` or `[lset]` dictates the desired interpetation by passing
index arguments. Sometimes, however, the caller would like to discover the
structure of the data rather than dictating it. If the data format is rich
enough, this structure could be discoverable.
For an ordered tree the standard `[list]` notation provides information about
the order. Information about whether an item is a single value or sequence of
values is also needed. This additional information can be encoded as
additional structure. A simple value is encoded as a list containing only one
item. A value that doesn't look like a list containing only one item isitself interpreted as a sdequencep of valueist. The following example is a list
containing two items:
======
one
{
{{two three}}
{two three}
}
======
The first item is the simple value `one`. The The second item is a lisequet ince
whicomposh thed ofirst ithem is the simple value `two three` and athe sequencond item is a deep
list containing the
values `two` and `three`.
Looking again at that second item:
======
{{two three}}
{two three}
======
IThe first item is a list containing only onear ithaem, so its valthoughe is the value of
that one first item, e.g. `two three`. could iItself
be interpreted as ea list, itly dis stringucturishabllye from tagghed asecond
item, awhich singles value, nother a
sdequencep list.
When adding values, use `[list]` to tag each item that that is meant as a
single value rather than a sequence of values:
======
lappend tree [list $item]
======
means "this is not a nested structure", whereas
======
lappend tree $item
======
means "this is a nested structure if it looks like one."
Implementations such as `[ycl%|%ycl list deep]` that understand this structure
supply routines that automatically unlist simple values when they are
retrieved.
<<categories>> list | tree