TableSmith Advanced Format Features

[back]

This section details the more advanced features of TableSmith. Included are details on variables (which allow you to preserve values or results within a table), parameters (allow you to solicit input from the user), functions (tools to accomplish things not possible with the basic TableSmith format), and other miscellaneous features.

Variables | Group Re-roll Tag | Functions | Parameters | Miscellaneous

Variables

TableSmith supports variables, which can be thought of as storage areas for numbers, text, or other information. Variables must be named, and can be called anything you want (though you are advised to just use alphanumeric characters - that is, letters and numbers). A variable name can contain spaces, though not at the beginning or end of the name.

Variables must be "declared" in a TableSmith file before anything else (including parameters, which are detailed elsewhere). A variable declaration is a single line formatted as follows:

%VariableName%,x

"varname" is whatever name you choose for the variable, and "x" is the default value that the variable will have (i.e.; whatever value it possesses until reassigned or modified). Variables can store text or numbers.

Whenever an entry has something between two percent signs ('%'), TableSmith reads this as a variable reference. If you have a variable with a name matching whatever is between the % characters, the value that is currently in that variable replaces the reference. For instance, say the variable "amount" currently holds the value '12'. The following line in a TableSmith file:

"There are %amount% orcs here."

will display as:

"There are 12 orcs here."

Variable Assignments
Whenever a group entry has something in two sets of pipes ('|'), it is recognized by TableSmith as a variable assignment. The format of an assignment is as shown:

|xxxxx?Y|

where

xxxxx is a variable name (without the '%')
? is +, -, *, /, \, >, <, &, or =
Y is a numeric value

Use one of the nine symbols shown by '?' above to change a variable. Using '=' will assign the following text or number to the specified variable, while the other symbols will perform that action on the variable (usually only practical if the variable holds a number). Examples are shown below:

Note that variables are local to the table they are used in. In other words, if you have a reference to 'A' in one table and a reference to 'A' in another that is called by the first, the value of 'A' in one table will not be affected by changes in the other.

Also note that unlike the other TableSmith formats, a variable assignment does not get replaced by anything visible. The entire assignment is simply removed from the line - "This is |B=5| a test" would be viewed as "This is a test".

Group Re-roll Tag

There is a special "tag" that you can use with a Group Call (detailed in the "Basic Format" section of Help) to re-roll the results of that call. To use this, simply precede the group call with "LN~", like so: "[LN~Treasure.Weapons]".

This tag allows the user to "re-roll" the results generated from the group call. Whatever text is returned by the call is displayed in the TableSmith Results window is treated similar to an HTML hyperlink. The text will be in a dark-blue color (not underlined, though), and will change to light-blue when the cursor is placed over it. Clicking the text will "re-roll" it, while preserving the rest of the results. Note that this feature will not regenerate or recalculate other parts of a display. Variable changes that occur in the "re-roll" will not be reflected elsewhere in the results window (the primary purpose of this feature is to "tweak" results).

Functions

Functions are a feature of TableSmith that allow you to perform some sort of action that you couldn't otherwise do with the standard table format or which could be done with great difficulty. The "Dice" function has already been detailed in the Basic Format area of Help; TableSmith supports many more. Functions follow the format below:

{FunctionName~nnnn,nnnn,nnnn,...}

"FunctionName" is the name of the function. It is followed by a '~', and one or more values (the number and the type depend on the particular function). Some functions return text (replacing the {, }, and everything in-between), some manipulate variables. Each function is detailed below (note that variables who's values are referenced by functions are not surrounded by the '%' character as they are normally; these functions are SortAsc, SortDesc, Min, Max, and Split). Examples are shown in italics.

Abs (Absolute Value)
{Abs~SomeValue}
Returns the absolute value of "SomeValue".

{Abs~-3} returns '3'

AorAn (A or An)
{AorAn~String}
If "String" starts with a vowel, this function appends "an " to the front of it; otherwise, it appends "a " to the front.

{AorAn~ostrich} returns 'an ostrich'

ArrClear (Clear Array)
{ArrClear~ArrayName}
Clears all the entries in 'ArrayName' (though the array still exists in the table).

ArrCount (Array Count)
{ArrCount~ArrayName}
Returns the number of items in 'ArrayName'.

ArrExists (Item Exists)
{ArrExists~ArrayName,Key}
If an item in 'ArrayName' exists with the key 'Key', returns 1; otherwise, returns 0.

ArrGet (Get Item)
{ArrGet~ArrayName,Key}
Returns the value found in 'ArrayName' at entry 'Key'.

If there is an entry in 'Dmg' of '2d6' with the key of 'greatsword', {ArrGet~Dmg,greatsword} would return '2d6'

ArrItem (Add or Update Item)
{ArrItem~ArrayName,Key,Text}
If an item already exists in 'ArrayName' with the key of 'Key', the entry's value is changed to 'Text'; otherwise, a new item is added, with the key of 'Key' and a value of 'Text'.

ArrNew (New Array)
{ArrNew~ArrayName}
Creates a new array named 'ArrayName'.

ArrRemove (Remove Item)
{ArrRemove~ArrayName,Key}
Removes the item with the key 'Key' from 'ArrayName'.

Calc (Calculate)
{Calc~Expression}
This function will return the results of the mathematical expression given to it. The function will recognize addition, subtraction, division, division with truncation, and multiplication (+,-,/,\,*). Parentheses can be used as well. Note that if you use variables in the expression, make sure a space divides the '%' of any variable from the division sign ('/').

{Calc~(3*(5+2))} returns '21'

Cap (Capitalize)
{Cap~String}
This function will return the string fed to it, with the first character capitalized. Spaces are counted, so while "arrow" will be capitalized to "Arrow", " arrow" would stay the same, since the function looks at the space that precedes the word.

{Cap~dragons} returns 'Dragons'

CapEachWord (Capitalize Each Word)
{CapEachWord~String}
This function will return the string fed to it, with each word in the string capitalized. A "word" is designated by having a space in front of it.

{CapEachWord~druids and dragons} returns 'Druids And Dragons'

Ceil (Ceiling Integer)
{Ceil~Number}
Returns the smallest integer higher than or equal to "Number".

{Ceil~2} returns 2, {Ceil~1.3} returns 2, {Ceil~-2.3} returns -2

Count (Count Entries)
{Count~GroupName}
Count will return the number of entries in "GroupName". A group with three entries would return '3', a group with ten entries would return '10', etc.

Data (Data Retrieval)
{Data~FileName,KeyAttribute,KeyAttributeValue,QueryAttribute}
Data is used to retrieve data from a TableSmith data file (found in the "Data" subdirectory where Tablesmith is installed). Tablesmith data files follow the format below:

The "<data>" and "</data>" must be at the beginning and end of the file, and each data item must start with "<item" and end with "/>". (For those familiar with databases, the data file is like a table, each "item" is analogous to a database record, and "attributes" are database fields). Attributes and values can be whatever you like. TableSmith data files end with the extension "xml" (and are, in fact, simple XML files, for those users who know what that means!).

To use the Data function syntax, FileName is used to specify with data file to use. KeyAttribute and KeyValue are used to find the item you want to query, and QueryAttribute is the attribute whose value you want. The value of that attribute is what is returned by the function (example: {Data~Monster,Name,Skeleton,ArmorRating} tells TableSmith to go to the file "Monster.xml" in the Data subdirectory, find the item where the attribute "Name" equals "Skeleton", and return the value of the attribute "ArmorRating").

If "Monster.xml" contains

<item Name="Skeleton" Type="Undead" ArmorRating="12" ... />

then {Monster,Name,Skeleton,ArmorRating} would return '12'

Debug (Debug)
{Debug~Caption}
Displays various information for debugging purposes (intended for more advanced users). Displays a dialog box with 'caption' as its caption, along with a list showing all the variables and their values for the current table, system resource/memory information, and the number of times the main TableSmith routine has been looped through.

Dice (Roll Dice)
{Dice~XdY?Z}
The Dice function (see the Basic Format section for detailed information on how this function works).

{Dice~1d4+1} will return some number from 2 to 5

Extern (External Call)
{Extern~Library.Object,StringToPass}
Calls the "main" function of "Library.Object", feeding it "StringToPass". Intended to be used with add-ons for TableSmith; the use of Extern is something that is covered by individual add-on authors.

Find (Locate a string in another string)
{Find~x,String1,String2}
Starting at character "x", find the location of "String1" within "String2" and return the result (if "String1" cannot be found in "String2", 0 will be returned).

{Find~1,able,TableSmith} will return '2' ("able" is found in "TableSmith" starting at the 2nd character)

Floor (Floor Integer)
{Floor~Number}
Returns the largest integer smaller than or equal to "Number".

{Floor~2} returns 2, {Floor~1.3} returns 1, {Floor~-2.3} returns -3

If (Conditional function)
{If~conditional ? Result1/Result2}
The "If" function works in an almost identical manner as the "Conditional Group Calls" (described above). If the "conditional" statement is true, "Result1" is returned. If it is false, "Result2" is returned ("Result2" is optional; if it is not shown and the conditional is false, nothing will be returned).

If the variable "Class" is 1, {If~%Class% = 1 ? warrior / wizard} will return "warrior"; otherwise, it will return "wizard"

Input (Input a value)
{Input~VarName,Prompt,Default}
The "Input" function allows a table to solicit input from the user as the table is running. When this function is encountered, an input box appears on the screen, with the prompt as defined by "Prompt", with a default value as defined by "Default". Whatever value the user enters is assigned to the variable "VarName" (if the user clicks "Cancel" on the input box, no action is taken, and the current value of "VarName" is unchanged). Note that the variable name should be used without percent signs ("%").

{Input~Weapon,Which weapon is favored?,longsword} prompts the user "Which weapon is favored?", with the default "longsword", and takes whatever they reply and puts it into the variable "Weapon"

LCase (Lower Case)
{LCase~String}
Returns "String" in all lower case.

{LCase~TableSmith} will return 'tablesmith'

Left (Leftmost Characters)
{Left~String,x}
Returns the leftmost x characters from "String".

{Left~TableSmith,3} will return 'Tab'

Length (String Length)
{Length~String}
Returns the length of "String".

{Length~TableSmith} will return '10'

Lockout (Lockout Entry)
{Lockout~Group,Values}
In a non-repeating table, Lockout flags the entries with the probability values listed as already selected. "Values" can be a single number, a range of numbers, or a combination.

{Lockout~Animals,3,7-9} will flag whatever entries encompass 3, 7, 8, and 9 as already being used.

Loop (Loop)
{Loop~n,Value}
Displays the results of "Value" 'n' number of times.

{Loop~3,Hello!} will return "Hello!Hello!Hello!"

Max (Maximum Value)
{Max~Var1,Var2,Var3,...}
The Max function looks at the values following it, and returns the largest value from the list.

{Max~5,7,14} returns '14'

MaxVal (Maximum Value of Entry)
{MaxVal~GroupName,X}
MaxVal looks at the entry on line 'X' of group "GroupName", and returns the maximum number that could be rolled on GroupName for it to be a result.

Given group "Weapons", with the first line being "4,dagger" and the second line being "3,scimitar", {MaxVal~Weapons,1} would return '4' (since 1-4 would yield "dagger" and 5-7 would yield "scimitar")

Mid (Middle Characters)
{Mid~String,x,y}
Starting with the 'x'th character, returns y characters from "String".

If the variable 'Name' contains 'Reginald', then {Mid~%Name%,2,5} returns 'egina'

Min (Minimum Value)
{Min~Var1,Var2,Var3,...}
The Min function looks at the values of all the variables following it, and returns the smallest value from the list.

{Min~5,7,14} returns '5'

MinVal (Minimum Value of Entry)
{MinVal~GroupName,X}
MinVal looks at the entry on line 'X' of group "GroupName", and returns the minimum number that would need to be rolled on GroupName for it to be a result.

Given group "Weapons", with the first line being "4,dagger" and the second line being "3,scimitar", {MinVal~Weapons,2} would return '5' (since 1-4 would yield "dagger" and 5-7 would yield "scimitar")

Msg (Message Box)
{Msg~Message}
Displays "Message" in a message box; table execution is halted until the user clicks 'OK'.

{Msg~Generating village} displays a message box which says 'Generating village'

Note (Notation)
{Note~Text}
Displays "Text" in the results window in green; the text can be clicked on, and the user can change what the text says. This editted information replaces what was originally in the results window.

OrderAsc (Order Ascending)
{OrderAsc~"x",String}
OrderAsc takes the String given, divides it up using "x" (must be in quotes) as a delimiter, and returns a string with its elements sorted in ascending order (divided by "x").

{OrderAsc~",",skeleton,orc,troll} returns 'orc,skeleton,troll'

OrderDesc (Order Descending)
{OrderDesc~"x",String}
OrderDesc works as "OrderAsc" above, but sorts in descending order.

{OrderDesc~",",skeleton,orc,troll} returns 'troll,skeleton,orc'

Ordinal (Ordinal Number)
{Ordinal~Number}
Ordinal returns 'Number' with the appropriate suffix attached (i.e.; "1st" for 1, "22nd" for 22, "458th" for 458, etc.).

Param (Paramter Item)
{Param~Variable,Index}
If "Variable" is used as a list-type parameter, the list item with the given "Index" will be returned.

If "Class" is a parameter variable with entries "Warrior,Priest,Wizard,Rogue", then {Param~Class,3} will return "Wizard"

Plural (Make String Plural)
{Plural~String}
This function will return the string fed to it in its plural form. The following rules are used:

{Plural~wolf} returns 'wolves'

Replace (Replace Text)
{Replace~SearchText,ReplaceText,SearchString}
Replaces each instance of "SearchText" in "SearchString" with "ReplaceText".

{Replace~e,@,skeleton} returns 'sk@l@ton'

Reset (Reset Group)
{Reset~GroupName}
Resets the specified group (if the group is a "non-repeating" group, it clears the "used" flags for that group's entries). Similar to the "RS~" group call tag, but does not make a call to the group.

{Reset~Gems} resets the group 'Gems'

Right (Rightmost Characters)
{Right~String,x}
Returns the rightmost x characters from "String".

{Right~TableSmith,5} returns 'Smith'

Round (Rounding)
{Round~SomeValue,x}
Rounds the passed-in value to 'x' decimal places and returns it.

If the variable 'Coinage' equals 5.32, {Round~%Coinage%,1} returns '5.3'

Shell (Shell Command)
{Shell~Command}
Shell runs the "Command" text outside of TableSmith. This can be used to call external programs.

{Shell~c:\gameprogs\addtonames.exe Zalagor} calls the program 'c:\gameprogs\addtonames.exe' and feeds it the command-line parameter 'Zalagor'

SortAsc (Sort Ascending)
{SortAsc~Var1,Var2,Var3,...}
SortAsc will look at the values in the list of variables following the '~', sort them in an ascending manner, and re-assign them to the variables in the sorted order. SortAsc will determine whether the list is numeric or alphabetic. Nothing is returned by this function.

Given the variables Gem1, Gem2, and Gem3, equal to 'Emerald', 'Sapphire', and 'Diamond' respectively, {SortAsc~Gem1,Gem2,Gem3} assigns 'Diamond' to Gem1, 'Emerald' to Gem2, and 'Sapphire' to Gem3

SortDesc (Sort Descending)
{SortDesc~Var1,Var2,Var3,...}
SortDesc works exactly like SortAsc (above), but sorts in a descending manner.

Given the variables Gem1, Gem2, and Gem3, equal to 'Emerald', 'Sapphire', and 'Diamond' respectively, {SortDesc~Gem1,Gem2,Gem3} assigns 'Sapphire' to Gem1, 'Emerald' to Gem2, and 'Diamond' to Gem3

Split (Split)
{Split~VarToSplit,"x",Var1,Var2,Var3,...}
The Split function is somewhat complex. Following the "~", is the name of a variable (without "%"'s), then a delimiter (in quotes), and then a list of variables. What Split does is to take the first variable ("VarToSplit" shown above), divide it up, and copy the results into the variable list ("Var1", "Var2", etc.). The delimiter character is used to divide the first variable. The example below illustrates:

Given the variable AbilityScores, equal to '78,56,60', {Split~AbilityScores,",",Strength,Intellect,Agility} would assign '78' to the variable Strength, '56' to Intellect, and '60 to Agility

Sqrt (Square Root)
{Sqrt~SomeValue}
Returns the square root of the value given.

{Sqrt~9} returns '3'

Status (Display Status)
{Status~Message}
Displays the text in "Message" in the right panel of the TableSmith status bar. This text remains until changed by another call to Status; {Status~} will clear the panel.

{Status~Generating village} displays 'Generating village' in the status bar's right panel

Stop (Stop Table Generation)
{Stop~Message}
Displays "Message" in a message box; table execution is halted once the user clicks 'OK'.

{Msg~Generating village} displays a message box which says 'Generating village', then stops when user clicks 'OK'

Trim (Trim Spaces)
{Trim~String}
Trims the spaces from the beginning and end of "String" (spaces in the middle, surrounded by other characters, are unaffected).

{Trim~ a castle } returns 'a castle'

Trunc (Truncate)
{Trunc~SomeValue}
Returns the result of truncating the given value (drops the fractional portion, if any).

{Trunc~3.5738472} returns '3'

UCase (Upper Case)
{UCase~String}
Returns "String" in all upper case.

{UCase~TableSmith} will return 'TABLESMITH'

Unlock (Unlock Entry)
{Unlock~Group,Values}
In a non-repeating table, Unlock clears the "already selected" flags of the entries with the probability values listed. "Values" can be a single number, a range of numbers, or a combination.

{Unlock~Gems,3,7-9} will clear the flags for whatever entries encompass 3, 7, 8, and 9 so they can be used.

Used (Used Already)
{Used~Group,Entry#}
The Used function is used to determine if an entry in a non-duplicating group has already been called. Following the "~" is the name of a group in the current table (or in a different table, in the standard "table.group" syntax), and then a number. If the entry that that number corresponds to has already been selected in the specified group, the function returns a 1. If the entry hasn't been selected, the function returns a 0. If that entry cannot be found (ex: the group goes from 1-10 and the number given to the Used function is 12), then a -1 is returned.

{Used~Weapons,5} returns '1' if entry 5 has been used previously, 0 if not, and -1 if entry 5 does not exist in 'Weapons'

While (While Loop)
{While~n,Text}
Displays the results of "Text" as long as "n" is not equal to 0

{While~%ctr%,Hello!} will return "Hello!" as long as the variable 'ctr' is not 0

Parameters

TableSmith supports 'parameters.' Parameters allow you to pass values from one table to another, or query a user for input before rolling on a table.

Parameters take up a single line and follow the format below:

@x,n,prompt,option1,option2,option3,...

the '@' symbol tells TableSmith that the line is a parameter. 'x' is one of TableSmith's variables - this is the variable that will receive a value, either from another table or from the user. 'n' is the default value to use if no input is given. Prompt is the text to display to the user if the table is called directly from TableSmith (as opposed to being called by another table). If nothing else is listed, the parameter is considered "text". If other items are listed (as in "optionx", above), then the parameter is considered to be a "list". If the table is called directly from TableSmith, "text" parameters are entered directly by the user, while "list" parameters present the user with a list (the items shown as "optionx") from which they select a single item. The text entered (for "text") or the number of the option selected (for "list") is what is assigned to the variable.

Here's an example:

When the table containing these lines is run, the first item will be displayed in the Parameter dialog box as a text box, with the user prompted to type a name. This name will be assigned to the variable "name". The second item will be displayed as a list, where the user can select either "Male" or "Female". If they choose "Male", the variable "gender" will be assigned the value "1". If "Female" is chosen, the value assigned to "gender" will be "2".

You can also pass parameters to a table in a table call. You don't have to, nor do you have to pass a value for each parameter. To pass parameters, you use parentheses after the table call, like so:

1,[CharGen.Start(3,4)]

In this example, the CharGen table is called, with 3 and 4 being passed in. Before the 'Start' group of CharGen is called, the value 3 will be assigned to its first parameter (call it 'G') and the value 4 will be assigned to its second parameter (dubbed 'C'). Since the table is being called from another table rather than TableSmith itself, the prompts are not used.

All the parameters don't need to have a value passed in. The following all work in TableSmith (using the previous example):

Miscellaneous

A few other things to note: