Riverwatcher Active Content Environment

RACE Documentation:

Basic RACE Programming
a. RACE Variables
b. RACE Tags
c. Evaluating Mathematical Expressions

RACE Variables

RACE supports three basic variable types: scalar (preceded by $), array (preceded by @) and hash (preceded by %). The value of each variable can be obtained when they are placed inside < and >, e.g.:


The content of the variable "$name" will be displayed. In addition to the three basic variable types, RACE also supports a read-only database variable type (preceded by #) which will be covered in the section on database access.

There are two ways variables can get defined in RACE. One is via the http form posting, the other is explicit definition by the developer. If your form has an input field named "EmailAddress", then RACE automatically creates a scalar variable by the same name in the script that handles the form submission, e.g.:

<form action="formprocesspage.race" method="post">
What is your name?<br>
<input type="text" name="Name" size="40" value=""><br>
What is your email address?<br>
<input type="text" name="EmailAddress" size="40" value=""><br>
<input type="submit" value="Send">

The form above will cause RACE to create two variables, <$Name> and <$EmailAddress>. Please note that RACE variables are case sensitive.

You can explicitly define values for variables using the define tag, e.g.:

<define var="$key">name</define>

Now the content of the variable "$key" will be "name". You can define as large as variable as your computer memory permits.

You can define an array from a list of values separated by comma and optionally quoted with single quotes, e.g.:

<define var="@fruits">apple,orange,'star fruit',banana</define> Now the array "@fruits" will have four elements. You can display the content of an array much like you would with a scalar variable, e.g.:


The above example would output: apple,orange,star fruit,banana

You can display any particular element of a RACE array with the [ ] operator, e.g.:


The above example would output: orange. Note that "$fruits[2]" is preceded by a $ because we expect the second element to be a scalar. Also note that RACE array index starts at 1 not 0 as with some other languages.

Array can also be defined one element at a time. In fact, RACE supports multi-dimensional arrays upto sixteen levels deep. The following example shows how we can define a two-dimensional array. Please note that you mix defining one element at a time with defining a whole array at a time.

<define var="$tictactoe[1][1]">O</define>
<define var="$tictactoe[1][2]">X</define>
<define var="$tictactoe[1][3]">O</define>
<define var="@tictactoe[2]">X,O,O</define>
<define var="@tictactoe[3]">X,X,O</define>

RACE supports defining a nested data structure, such as a multidimensional array, with one define statement. The example above can also be rewritten as, e.g.:

<define var="@tictactoe">[O,X,O],[X,O,O],[X,X,O]</define>

The [ ] operator can be used in a define statement to denote an array. In the example above, we told the RACE interpreter that we want to define an array of three elements, each element in turn is an array of three elements.

Now that you see how you can easily define arrays in RACE, we now turn our attention to hashes. A hash is a data structure consists of key and value pairs. Therefore, in RACE you can define a hash from a list of key and value pairs, e.g.:

<define var="%student">name='John Singer Sargent' age=13 grade=Freshman</define>

The "%student" hash now has three keys: name, age, and grade. You can refer to a keyed value in a hash using either the . or { } operator, e.g.:

<$student.name> is the same as <$student{'name'}>

With the { } operator, you can have the additional flexibility of using a scalar variable to specify the key, e.g.:


Since we have defined $key to contain the value "name", this expression will display the value "John Singer Sargent".

As with arrays, we can define a hash one key and value pair at a time instead of listing all the key value pairs of a hash, e.g.:

<define var="$student.name">John Singer Sargent</define> <define var="$student{'age'}">13</define> <define var="$student.grade">Freshman</define>

Complex nested data structure can be easily defined in one define tag. Lets say that we want to define a hash that has an array and another hash as its values, e.g.:

<define var="%student">name='John Singer Sargent' courses=['econ 101', 'oil painting', 'algebra'] telephone={home='555-1555' cell='555-3333'}</define>

The hash "%student" has an element with the key "name" pointing to a scalar value of " John Singer Sargent" and an element with the key "courses" pointing to an array of course names, and finally an element with the key "telephone" that points to a hash with the keys "home" and "cell" pointing to "555-1555" and "555-3333" respectively.


RACE has 21 built-in tags which allow you to perform many programming tasks from numerical calculation to database access. You have already seen the define tag being used to define variables. In this section, we will show you how to define your own tags. For those of you familiar with traditional programming languages such as C or Lisp, tags essentially work like functions. In fact, RACE even supports recursion in tag definitions.

To define your own function, you use the define tag, e.g.:

<define tag="dice"><eval>random(6)+1</eval></define>

Now you can call the tag as <dice> and it will return a randomly generated integer from 1 to 6.

You can define a tag takes a body by using the "balanced" attribute, e.g.:

<define balanced tag="quote">"<$caller.body>"</define>

<quote>It's good to be quoted.</quote> will return the result "It's good to be quoted."

The special variable <$caller.body> refers to the body that's been passed to the tag. You can parameters to your user-defined tag by specifying attributes in the beginning of a tag, e.g.:

<define tag="max">
  <if test="<$attributes.val1> > <$attributes.val2>">

<max val1="5" val2="3"> would return the result "5". The attributes hash variable contains a list of all the attributes that were specified when invoking the tag.

Evaluating Mathematical Expressions

RACE can evaluate most valid mathematical expression from simple addition and multiplication to trigonometric functions using the eval tag. You can get a full list of operators and functions supported by RACE from the RACE Reference. We will only show a few simple examples here.


The above expression will evaluate to 450. You can use the prec attribute to specify a precision, e.g.:

<define var="$num">20</define>
<eval prec="2">3.14159*<$num></eval>

The above will evaluate to 62.83. You should also note that you can put any scalar variables in the body of an eval tag and perform the needed calculations. Often, you may want to define a variable with the outcome of a calculation. You can do that by putting the eval inside the body of a define tag, e.g.:

<define var="$sum"><eval><$subtotal>*(1+<$taxrate>)+5.00</eval></define>

You can simplify the above expression by invoking the define tag with the eval attribute, e.g.:

<define var="$sum" eval><$subtotal>*(1+<$taxrate>)+5.00</define>

RACE Documentation

Copyright 2009 Riverwatcher, Inc. Hosting by Riverwatcher Studios