Go package “tuples”

Today I want to announce “tuples” — a Go package to read and write strings containing records separated by a custom delimiter.

The idea to create a package came when I had to handle an array of records in one configuration parameter. Below is an example of such a configuration parameter:

FORMATS="height=700,width=350,fmt=jpg height=900,width=450,fmt=png"

The package allows unmarshaling such strings to a predefined Go structure or an arbitrary map. And supports the structures and map marshalling to a tuples string.

The tuples string contains a collection of records separated by a delimiter. Key-value pairs represent records, also separated by a delimiter. The package uses the following default delimiters:

• = key-value delimiter
• , records delimiter
• whitespace is a records delimiter

The delimiters are configurable with one rule — all three delimiters should be different.

The design was influenced by the encoding/json package. Therefore, two main functions of the package are Unmarshal(data []byte, v any) error and Marshal(v any) ([]byte, error). Following are the examples of decoding and encoding of tuples string.

Example 1. Unmarshaling tuples string

Example 2. Marshalling to a tuples string

Additionally, the package provides Reader. It produces a slice of values in the same order as the tuples and their fields presented in the string.

Example 3. Tuples reader

You can read tuples string record-by-record as in Example 3, or use tuples.ReadString to let the package fully decode a string.

Caveats

• The package does not read the whole string before decoding. It scans a string and unmarshals records one at a time. It is unknown how many records are in the string ahead of time. Therefore when unmarshalling to a predefined structure, a slice or array of structures is required as the destination. Unmarshaling to a non-slice target produces an UnmarshalError.
• Unmarshaling to any allows decoding records of arbitrary structure (see L24–28, L32 output in Example 1).
• Unmarshaling to any produces []map[string]any. Map keys are alphabetically sorted.

References

• tuples on pkg.go.dev
• tuples on GitHub.

Thanks for reading, and I hope you will find the “tuples” package helpful. Please feel free to open an issue of PR if you would like to improve them.