tcllist

Documentation

Overview

Package tcllist converts between Tcl list strings and Go slices.

Some of the older elements of GMA (which used to be entirely written in the Tcl language, after it was ported from the even older C++ code) use Tcl list objects as their data representation. Notably the biggest example is the mapper(6) tool (which is still written in Tcl itself), whose map file format and TCP/IP communications protocol include marshalled data structures represented as Tcl lists.

While this is obviously convenient for Tcl programs in that they can take such strings and natively use them as lists of values, it is also useful generally in that it is a simple string representation of a simple data structure. The actual definition of this string format is included below.

The tcllist Go package provides an easy interface to manipulate Tcl lists as Go types.

TCL LIST FORMAT

In a nutshell, a Tcl list (as a string representation) is a space-delimited list of values. Any value which includes spaces is enclosed in curly braces. An empty string (empty list) as an element in a list is represented as “{}”. (E.g., “1 {} 2” is a list of three elements, the middle of which is an empty string.) An entirely empty Tcl list is represented as an empty string “”.

A list value must have balanced braces. A balanced pair of braces that happen to be inside a larger string value may be left as-is, since a string that happens to contain spaces or braces is only distinguished from a deeply-nested list value when you attempt to interpret it as one or another in the code. Thus, the list

“a b {this {is a} string}”

has three elements: “a”, “b”, and “this {is a} string”. Otherwise, a lone brace that's part of a string value should be escaped with a backslash:

“a b {this \{ too}”

Literal backslashes may be escaped with a backslash as well.

While extra spaces are ignored when parsing lists into elements, a properly formed string representation of a list will have the minimum number of spaces and braces needed to describe the list structure.

Index

• func ConvertTypes(list []string, types string) ([]any, error)
• func Parse(tclString, types string) ([]any, error)
• func ParseTclList(tclString string) ([]string, error)
• func StripLevel(s string) string
• func ToDeepTclString(values ...any) (string, error)
• func ToTclString(listval []string) (string, error)

Functions

func ConvertTypes

func ConvertTypes(list []string, types string) ([]any, error)

ConvertTypes converts some or all of the elements in a string slice such as that returned by ParseTclList to a new slice of values which have been converted to other data types as specified by the caller.

Since the string representation of a TclList is type-agnostic, we can't automatically assume its elements should be specific types such as numeric values, hence the need for this function to provide the missing type information to complete the conversions.

The types string controls this conversion. Each character indicates the required type for the corresponding element in the input slice, as follows:

"-"  do not convert this element.
"s"  copy the element as a string.
"b"  copy the element as a []byte slice.
"r"  copy the element as a []rune slice.
"f"  convert the element to a float value.
"i"  convert the element to an int value.
"I"  as i, but an empty string is equivalent to 0.
"?"  copy the element as a bool value.
"*"  stop processing here, ignoring any remaining slice elements.

If the value cannot be converted as requested, an error is returned.

This provides a simple way to validate the types for all values in the slice at once, so you can directly access the slice elements as the intended types without individually type-testing each one.

The input slice must have exactly the number of elements as characters in the type string unless the * character is used in types, so this function also enforces that the expected number of data elements is present.

func Parse

func Parse(tclString, types string) ([]any, error)

Parse is a convenience function which combines the operation of the ParseTclList and ConvertTypes functions in a single step.

func ParseTclList

func ParseTclList(tclString string) ([]string, error)

ParseTclList takes a properly-formatted Tcl list string and returns a slice of the list's elements as string values as well as an error (if something went wrong).

Note that this only parses a single nesting level of elements, since with Tcl lists it is impossible to distinguish an element which happens to contain spaces from a nested list of values. It is simply up to the program to use the element as a string or as a sublist, so in the latter case you'll need to call ParseTclList on that element.

func StripLevel

func StripLevel(s string) string

StripLevel strips away the outermost level of {} characters from a string. The string must begin and end with { and } characters respectively.

func ToDeepTclString

func ToDeepTclString(values ...any) (string, error)

ToDeepTclString takes a number of arbitrarily-typed values and returns a Tcl string which represents them as elements of a list. Supports values of type bool, float64, int, int16, int32, int64, string, uint, uint16, uint32, uint64, and slices of any combination of the above.

For example, ToDeepTclString("a", 12, 13.42, []string{"b", "c"}) returns the string "a 12 13.42 {b c}".

func ToTclString

func ToTclString(listval []string) (string, error)

ToTclString takes a slice of strings and outputs a single string value which represents that slice as a valid Tcl list. This function may return an error, but as currently implemented that should rarely happen (it is triggered by a string whose length is too long to fit in an integer), but there may be other error conditions added in the future, so check it anyway).

It returns the Tcl string and the error, if any.