View on GitHub

urban-wombat.github.io

For HTML API reference.

gotables

What is gotables?

gotables is a table data format and a library of support functions and methods.

Have a look at:

The gotables project pages:

The gotables command line utilities:

To download the library and utilities:

go get -u github.com/urban-wombat/gotables
go get -u github.com/urban-wombat/flattables

What is gotables?

A library of functions and methods that operate on or with the gotables data structures:-

Tables can be created and modified with typesafe operations at runtime:-

Setting and Getting cell values is performed by a simple set of orthogonal methods based on:-

In summary, the Get and Set methods are of the following form:-

The full set of methods is: here

CustomTypeVal operations are on user-defined types. You can use them with built-in types too, but there’s no point doing so.

Here is a runnable example in The Go Playground

The example is simple. The user-defined type person (to which Go assigns the type main.person) is added as a column to the table. The string table in this example is to help visualise what’s going on here. The main.person column (as well as the int and string columns) could have easily been added like this:

table, _ := gotables.NewTable("MyTable")
table.AppendCol("age", "int")
table.AppendCol("name", "string")
table.AppendCol("my_person", "main.person")
fmt.Println(table)

table.AppendRow()
var rowIndex = 0
table.SetInt("age", rowIndex, 30)
table.SetString("name", rowIndex, "Fred")
table.SetCustomTypeVal("my_person", rowIndex, nil)
fmt.Println(table)

See the runnable example in The Go Playground

The way CustomTypeVal values are represented in the string representation of a table cell may seem over-the-top. This is not how you would normally use custom types. The Table.String() output is intended for debugging, visualisation and perhaps persisting tables in a human-readable form to file.

CustomTypeVal cells consist of 2 contiguous strings surrounded by curly braces, and they are themselves surrounded by curly braces. The first string is machine-readable. The second string is human-readable:-

Normally (when not debugging or persisting to file) access to CustomTypeVal cells would be via methods of the form:-

gotables table data formats - table-shaped, struct-shaped

Following are string examples of gotables.Table tables.

They are to help visualise the contents of of tables. Most interactions with in-memory Table data are via the Table methods listed above. The Table.String representation of tables is mostly for debugging, reading configurations and passing messages between systems.

Here the string representation is for teaching purposes.

Tabular shape table syntax

The primary table data format looks like this:

[planets]
name         mass distance moons index mnemonic
string    float64  float64   int   int string
"Mercury"   0.055      0.4     0     0 "my"
"Venus"     0.815      0.7     0     1 "very"
"Earth"     1.000      1.0     1     2 "elegant"
"Mars"      0.107      1.5     2     3 "mother"
"Jupiter" 318.000      5.2    67     4 "just"
"Saturn"   95.000      9.5    62     5 "sat"
"Uranus"   15.000     19.2    27     6 "upon"
"Neptune"  17.000     30.6    13     7 "nine"
"Pluto"    17.000     39.4     5     8 "porcupines"

It has the following features:

See Table Syntax Details

Struct shape table syntax

There is one syntactical variant which is a struct data format like this:

[HitchhikersGuide]
name string = "Arthur Dent"
answer int = 42
universe bool = true

It has the following features:

The struct syntax is for human readability and is different in syntax only. It is semantically a table with a single row of data rotated syntactically a quarter turn to the left (90 degrees anti-clockwise). All the same methods operate in the same way. With a struct, there is only one row (in the Table implementation) and so only row 0 can be referenced. Or no rows at all if it’s an empty struct.

This is the same struct table represented in table syntax:

[HitchhikersGuide]
name           answer  universe
string         int     bool
"Arthur Dent"  42      true

Note that it has one row of data.

See Struct Syntax Details

gotables TableSet

This is why gotables is plural.

*gotables.TableSet is an ordered set of *gotables.Table objects.

In the real world tables often travel as a collection of tables rather than on their Pat Malone (alone).

A TableSet may be instantiated:

Note: A TableSet doesn’t have a string representation independent of the tables it contains. If a TableSet contains zero tables, its String() method will output zero text. Conversely, an empty file will not create an empty TableSet.

Designed for Go programmers

gotables is designed for Go programmers. Most Go data types are available, and some slice types. The emphasis is on speed and simplicity.

How to download and install gotables

The gotables library:

go get -u github.com/urban-wombat/gotables