Type Data (td)

Note

These commands are only available in Guardian Tcl 0.5 or later, which is currently in prerelease.

Guardian Tcl provides a “typed data” structure, accessed through the td ensemble command, that represents JSON-like data along with type information, instead of Tcl’s usual string-based representation. It is similar in that respect to Huddle, but uses JSON as its string representation and checks types in Rust. You can think of it as a native-code Huddle, however. Any valid JSON string is a valid TypedData object.

Note

JSON is the string representation as of 0.5, but this may change in the future if we find a need for data types not supported by JSON.

Creating Typed Data

The following commands create a typed data value:

td null

Create a null value.

td boolean val

Create a boolean value. val is any valid Tcl boolean.

td integer n

Create an integer value with value n.

td float x

Create a floating-point value with value x.

td string str

Create a string value with value str.

td list value…

Create a list value with the value(s) provided as arguments. The list elements themselves must already be typed data.

td record key value …

Create a record (dictionary) value with the key-value pairs provided as arguments (works like dict create). The values themselves must already be typed data.

Conversion

td native td

Convert the typed data td to Tcl-native layout (values, lists, and dicts).

Conversion to native is not directly reversible, because Tcl-native format loses the type information from the original. Since typed data is stored as JSON, use the Jim Tcl json::encode command to convert Tcl-native data to JSON.

Parsing

td parse json ?-file? input

Parse the specified JSON input as typed data. Since typed data is represented as JSON, this just validates the input. The -file option instructs it to treat input as a filename instead of JSON text.

td parse yaml ?-file? input

Just like td parse json, except it parses YAML.

td parse toml ?-file? input

Just like td parse json, except it parses TOML.

Querying Typed Data

These commands all query typed data, and require the typed data itself as input.

td get ?-native? td key…

Traverses the typed data td by the specified keys path to query an record. The first key is looked up in td, the second in the first key’s value, and so forth. Keys can be strings for records, or valid indices for lists. The full Tcl list index syntax (e.g. end, end-1) is supported.

td type td

Get the type of the typed data value.

td length td

Get the length of the typed data value if it is a record, list, or string. Fails for other types of data.

Manipulating Typed Data

Unlike the other typed-data functions, these commands take a tdvar parameter specifying the name of the variable storing the typed data to manipulate.

Important

Typed data values are effectively immutable, and manipulating typed data updates the variable to store a new typed data. In particular, using these functions on the result of a td get command will not modify the original data structure that td get queried.

td set tdvar key… value

Update the location in the record specified by the key path to store value. If a key does not exist in a record value, it will be added (this does not work for lists).

td lappend tdvar key… ?–? value…

Append the specified values to the list addressed by the key path. Fails if the key path does not specify a list. Separating the key path from the values with -- is required if you want to add more than one value to the list.