Location: TB Homepage > Torus > Data format

The Torus data format

The Torus database is stored as a CSV file, consisting of a line of headers followed by one line per (version of a) tune. Each line consists of fields separated by commas. If a field contains a double-quote then this must be represented by a pair of double-quotes. If a field contains a comma or a double-quote then the whole field must be enclosed in double-quotes.

The headers give the names of each field. There must be fields called Title and Shape. Some Torus software also makes use of fields called Composer, Dance and Source if they are present. Other fields may be present but are not used. The fields can be in any order, but this order must be fixed throughout the database. Every field must be present (but possibly empty) in every line.

Apart from the headers, the lines are of three types distinguished by the Shape field:

Tunes
If the Shape field is a string of "u"s and "d"s then the line is a normal tune. The Title, Composer, Dance and Source fields contain information about the tune. The Composer field is sometimes used for information about dates, publishers, etc.
Sources
If the Shape field is "s" then the line defines a source abbreviation (FTB for the Fiddler's Tune Book, for example). The Source field contains the abbreviation and the Title field contains the source title.
Cross-references
If the Shape field is "x" then the line is a cross-reference from an alternative title to another line - see below.

A tune may appear several times in different versions with different Shape fields. These are stored as separate lines in the database, and any information about titles, composer, etc is duplicated in each (which is inefficient, but simple). A tilde ~ in a Source listing indicates that the version is only approximately the same as that in the given source.

If a tune has multiple titles then these appear together in the Title field, in alphabetical order, separated by forward slashes. There will also be a cross-reference line for each alternative title, in which the Title field gives the alternative title and the Source field gives the title under which the tune's full details are stored. This is so that the alternative title will be found in the expected place when the (non-header) lines are sorted by Title field.

Conversely, unrelated tunes with the same title are distinguished by (1), (2), etc at the end of the title, in no particular order.

Warning: If any of the "must"s in the above rules is disobeyed then the behaviour of the software is undefined, and probably undesired, so don't do that.


This page is maintained by Thomas Bending, and was last modified on 28 March 2016.
Comments, criticisms and suggestions are welcome. Copyright © Thomas Bending 2017.