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 repository
- The gotables API
- Some miscellaneous gotables utilities
- The gotables implementation of Google FlatBuffers
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:-
gotables.Table
- a single flexible runtime in-memory typesafe tablegotables.TableSet
- a collection of zero or moregotables.Table
tables
Tables can be created and modified with typesafe operations at runtime:-
- A
gotables.TableSet
can be:-- created from string or file or nothing (empty
TableSet
) - copied
- printed to string or file
- created from string or file or nothing (empty
- A
gotables.Table
can be:-- created from string or file or nothing (empty named
Table
) - copied
- merged (by one or more column keys)
- printed to string or file
- created from string or file or nothing (empty named
Table
columns (fields) can be:-- added and deleted
- reordered (swapped around)
Table
Rows can be:-- added and deleted
- sorted (by one or more columns)
Table
Cells can be:-- Written to (using Set methods)
- Read from (using Get methods)
Setting and Getting cell values is performed by a simple set of orthogonal methods based on:-
- Cell type:-
- Go built-in types such as
int
string
bool
(except complex) - Slice of
[]byte
or[]uint8
- Custom types - user-defined types
- Go built-in types such as
- How the column is referenced:-
- By name - implicit in the name, e.g.
Table.SetString
- By column index - explicit, e.g.
SetStringByColIndex
- By name - implicit in the name, e.g.
- With
MustGet
which panics on error, e.g.Table.GetStringMustGet
similar toregexp.MustCompile
In summary, the Get
and Set
methods are of the following form:-
Set<Type>[ByColIndex]()
Get<Type>[ByColIndex][MustGet]()
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:-
- {machine-readable] - GOB-encoded then base64-encoded
- {human-readable} - Go string representation then escaped for reliable parsing
Normally (when not debugging or persisting to file) access to CustomTypeVal
cells would be via methods of the form:-
SetCustomType[ByColIndex]()
GetCustomType[ByColIndex][MustGet]()
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:
- A table name in square brackets.
- A row of column names.
- A row of column types.
- Rows of column data.
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:
- A table name in square brackets.
- Lines of struct values in the form: name type = value
- One row of column data.
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.
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