A Recital Primer

A Recital Primer

Keywords

Keywords are known words that denote commands. There are no reserved words in Recital. Command names can be used as variables names. At first glance these seems strange, but provides for greater flexibility when declaring and referencing memory variables and database field variables, as you do not need to concern yourself about names that may already be used as commands.

As an extreme example, the following code will compile and run. It will output "hello"

procedure if(if)
return if
 
if = "hello"
if if = "hello"
    echo if( if )
endif

Lines and Indentation

Tabs and spaces have no significance in Recital. Recital commands can begin on any column of a line. A newline ends the command. If you have particularly long commands, you can them extend over multiple lines by placing the line continuation character ; (semicolon) at the end of each line that is to be continued.

echo "This is a one line command"
echo "This is a ;
multi line ;
command"

For better code readability it is recommended that you indent code blocks such as if statements, for loops etc.

// indented code if much more readable and easier to maintain
for i=1 to 10
    name = "hello world"
    if name = "hello world"
        // indent like this
    endif
endfor

Comments

Single line comments

// allows comment lines to be inserted in programs to enhance their readability and maintainability. The // command allows all characters following it on a line, to be treated as a comment and to be ignored by Recital. The // command can be placed anywhere on a line, even following an executable command.

// declare variables
private x,y,z

Multi line comments

/* and */ denote block comments. These can be inserted in programs to enhance their readability and maintainability.

The /* denotes the start of the comment block, the */ the end of the comment block.

All characters between the two comment block delimiters are treated as comments and ignored by Recital.

/* the following lines
     are multi
     line comments */
private x,y,z

Variables

Simple Variables

Recital does not have a strict type system. Variable names must begin with a letter (A-Z, a-z) or an underscore (-), followed by any combination of letters, digits or underscores. The variable name can be of any length, but only the first 32 characters are significant, so these must be unique. Recital ignores the case of letters, so m_var, M_VAR, and m_VaR would all be treated as the same memory variable name. The name given to a variable has no bearing on the type of data that is, or can be, stored in it. In fact, the type of data stored in a particular variable can be changed at any time.

m_var = 1234
m_var = 'a character value'
? m_var + 100

Static Arrays

A static array is an ordered list of elements (variables) that is of a fixed size (number of elements). You declare a static array by specifying the number of elements when you declare a variable.

private tab[ 20 ]    // declare a static array of 20 elements all initialized to False
 
// iterate through the array (note the use of the alen( ) function to find the length of the array
for i=1 to alen( tab )
    // change each array element to hold a numeric value
    tab[ i ] = i
endfor

Associative Arrays

An associative array (also known as a dynamic array) is a collection of key/value pairs where the key can be used to retrieve the value. Associative arrays are dynamic, meaning that elements can be added and removed dynamically.

private tab[]    // note the use of [] to denote a dynamic array
 
tab["name"] = "bill"
tab["age"] = 25
tab["dob"] = date()

Macros

Variable macro substitution

The & macro function substitutes the contents of the specified variable into the command line. To use a macro in the middle of a word, it is necessary to end the variable name with a '.'. Any type of memory variable can be substituted as a macro.

subscript = 10
i10i = 5
? i&subscript.i
         5

Expression macro substitution

The & macro function can also substitute the result of an expression into the command line. The expression must be enclosed in round brackets.

subscript = "1"
i10i = 5
? i&(subscript + "0")i
         5
str1 = "hello"
str2 = "world"
echo "&str1 &str2"    // output "hello world"

Shell command output substitution

Recital provides tight integration with the unix/linux command shell. The ` ... ` command sequence (backticks) can be used to run external shell commands that are piped together and to substitute the output into a Recital character string.

echo "The default directory is `pwd`"
echo "There are `ls -l *.dbf | wc -l` tables in this directory"