Text Files

This page provides a basic tutorial on construction a text file for uploading into the app. See also the Command Summary and Uploading Text Files.

The basic format of a text file is simply a list of entries, 1 per line. For example, the file “Fruit & Veg.txt” might contain three lines:

apple
banana
cabbage

When loaded into the app this will create a table set called “Fruit & Veg” containing a single table with 3 entries. Displaying it will show one of those entries at random, e.g.:

apple

In this case there is no header or title, but the UI will show “Fruit & Veg” in the navigation bar.

Any line with the prefix “//” will be ignored, so you can use this to insert comments into the file. These comments are not stored by the app – they really are ignored! For example,

// this file contains a list of fruit and vegetables
apple
banana
cabbage

To add a title to the table, prefix one of the lines with a ‘#’. E.g.

#Fruits and Vegetables
apple
banana
cabbage

This will display

Fruits and Vegetables
banana

Note that the following will also work, but might be confusing! Try to lay out the text file logically.

apple
banana
#Fruits and Vegetables
cabbage

To change the format of the displayed table, prefix one of the lines in the table with ‘@’. You can use almost any CSS property, e.g.

#Fruits and Vegetables
@font-style: italic
apple
banana
cabbage

This will produce:

Fruits and Vegetables
cabbage

Note that as CSS is the formatting language you have plenty of options to choose from when displaying entries. You can even transfer an image to the app’s Documents folder (via iTunes) and use that as a background image!

To change the weight applied to a line (i.e. how often it should appear relative to the other lines in the table), prefix it with an integer, followed by a space, then the line. For example:

#Fruits and Vegetables
apple
2 banana
cabbage

will give ‘banana’ twice as much weight as the others. On average (i.e. over many runs) it should appear twice as often as ‘apple’ or ‘cabbage’. It is the equivalent of doing this:

#Fruits and Vegetables
apple
banana
banana
cabbage

which you can also do if you prefer (the app does not filter tables to make sure each line is unique). Note that there must be an integer (or whole) number, or a number that can be converted to one (e.g. ‘3.5 apple’ would be read as ‘3 apple’) followed by a space for this to work. So “2,banana” will be treated as a normal line because there is no space after the number. If the first word of a line is a number, but you actually want that to be displayed instead of being used as a weighting then prefix the number with a “\”. For example

#Fruits
\6 bananas
\3 apples

will display:

6 bananas

instead of giving twice as much weight to “bananas” over apples.

To have multiple tables per file (i.e. a table set) just separate them with one or more blank lines. So “Food & Drink.txt” could contain:

apple
banana
cabbage

tea
coffee
beer

This will output something like:

cabbage

tea

Note that tables will be output in the order they are listed in the file (you can reorder tables in the app). Of course, you can add titles (and formatting) to each table:

#Fruits and Vegetables
apple
banana
cabbage

#Drinks
@font-style: italic
tea
coffee
beer

which will show:

Fruits and Vegetables
apple

Drinks
beer

Note that “Food & Drink” will be displayed in the navigation bar at the top, and this will also be used as the name of the table set in the list view.

The name of the group of tables (the “table set”) is, by default, the same as the name of the file. You can name a table set by prefixing it with ‘##’:

##Things to eat and drink

#Fruits and Vegetables
apple
banana
cabbage

#Drinks
@font-style: italic
tea
coffee
beer

This will display the title on the screen, above all the tables.

Things to eat and drink

Fruits and Vegetables
apple

Drinks
beer

This title will also be displayed on the first screen, where you select the table set to be displayed, instead of the filename. Note that if you create a new table set within the app itself and don’t give it a name then the app will use the creation time of the table set for display purposes.

You can also change the formatting of the table set as a whole using ‘@@’. This applies to all the tables in a table set unless that table has its own formatting. This line – and the ## line – must be the first two lines in the file. If, for some reason, you don’t want the table set name to be displayed – but you do want to set it (e.g. so it turns up in the list view) – then use #! instead of ##. (This only stops the name of the table set being displayed – not the whole table set!)

You can also use tables as sub-tables. A ‘>’ as the first character in a line, followed by a table name, means ‘display a random line from this table’. For example:

#Fruits
apple
banana
raspberry
>Other Fruits

#Other Fruits
kiwi
mango

When displaying the Fruits table there is a 1 in 4 chance of selecting the last line (the link to the ‘Other Fruits’ table). In this case the app will pick a random line from the Other Fruits table and display that. Of course, in this example it will also display the Other Fruits table immediately afterwards, so you may get this:

Fruits
kiwi

Other Fruits
kiwi

which may not be what you want. You can suppress the output of a table by using a ‘!’ instead of a ‘#’ to specify the table name:

#Fruits
apple
banana
raspberry
>Other Fruits

!Other Fruits
kiwi
mango

which would give you something like this:

Fruits
mango

Note that to refer to a table, you must give it a name using the ‘#’ prefix – ‘anonymous’ or un-named tables cannot be referenced or linked to.

You can have tables that refer to sub-tables, that also refer to sub-sub-tables and so on. However, the maximum number of links has been set to 6. You can also add weighting to a sub-table reference, e.g.

#Fruits
apple
banana
raspberry
3 >Other Fruits

!Other Fruits
kiwi
9 mango

Here there is a 50% (3 in 6) chance of the Fruits table referring to the Other Fruits table, which then has a 90% (9 in 10) chance of displaying ‘mango’. Note the space between the weighting (“3”) and the “>” sign.

It is sometimes useful to append the results of one table to another on the same line. For example, you may have a pair of tables containing random first and last names, but you want them displayed one after the other on the same line like this:

John Smith

and not like this:

John
Smith

To do this use the “+” sign in the first table to point to a table to append:

#Names
+Last Names
Bob
Mark
John

!Last Names
Smith
Jones
Carpenter

This will generate results as follows:

Names
Bob Carpenter

Note that the “Last Names” table has been hidden using the “!” prefix. Note also that any formatting applied to the appended table is ignored – only the formatting of the first table (Names, in this case) is applied.

You can chain together up to 6 tables in this way.

Table entries can be formatted using HTML and CSS, as described in Formatting.