The ScriptEase Language

Environment Variables

In previous versions of ScriptEase:Desktop (CEnvi), a variable written entirely in UPPERCASE letters was automatically considered to be an environment variable. This is no longer the case; use the getenv() function to access your operating systems environment variables and the putenv() function to modify them (see the ScriptEase Standard Library chapter for documentation of this function).

If you have scripts in CEnvi that rely on this feature, contact Nombas for a script that will convert your old scripts over to the new format for handling environment variables.

Basic Arithmetic

The arithmetic operators in ScriptEase are pretty standard

=	assignment: sets a variable's value
+	addition: adds two numbers
-	subtraction: subtracts a number
*	multiplication:
/	division
%	modulo: remainder after division

Here are some examples using variables and arithmetic operators:

i = 2;	// i is 2
i = i + 3;	// i is now (2+3) or 5
i = i - 3;	// i is now (5-3) or 2 again
i = i * 5;	// i is now (2*5) or 10
i = i / 3;	// i is now (10/3) or 3 (the remainder is ignored)
i = 10;
i = i % 3;	// i is now (10%3) or 1

Assignment Arithmetic

Each of the above operators can be combined with the assignment operator (=) as a shortcut for performing the operation with the first variable and then assigning the result to the same variable. Using assignment arithmetic operators, the above code could be simplified as follows:

=	assignment: sets a variable's value
+=	assign addition: adds number
-=	assign subtraction: subtracts a number
*=	assign multiplication
/=	assign division
%=	assign remainder: remainder after division

Here are some examples using assignment arithmetic

i = 2;	// i is 2
i += 3;	// i is now (2+3) or 5; same as i = i + 3
i -= 3;	// i is now (5-3) or 2 again; same as i = i - 3
i *= 5;	// i is now (2*5) or 10; same as i = i * 5
i /= 3;	// i is now (10/3) or 3; same as i = i / 3
i = 10;
i %= 3;	// i is now (10%3) or 1; same as i = i % 3

Auto-Increment (++) and Auto-Decrement (--)

Other arithmetic shortcuts are the auto-increment (++) and auto-decrement (--) operators. These operators add or subtract 1 (one) from the value to which they are applied. ("i++" is a shortcut for "i += 1", which is itself shortcut for "i = i + 1").

These operators can be used before (prefix) or after (postfix) their variables. If used before, then the variable is altered before it is used in the statement; if used after, then the variable is altered after it is used in the statement. This is demonstrated by the following code:

i = 4;	// i is initialized to 4
j = ++i;	// j is 5, i is 5 (i was incremented before use)
j = i++;	// j is 5, i is 6 (i was incremented after use)
j = --i;	// j is 5, i is 5 (i was decremented before use)
j = i--;	// j is 5, i is 4 (i was decremented after use)

Bit Operators

ScriptEase contains many operators for operating on the binary bits in a byte or an integer. If you're not familiar with binary and hexadecimal numbering, then you may want to skip this section on Bit Operators.

<<	shift left: shift all bits left by value
<<=	assignment shift left
	i = 0x146 i <<= 2; // shift i (0x146) left 2, so i = 0x518
>>	shift right: shift all bits right by value
>>=	assignment shift right
	i >>= 3; // shift i (0x518) right 3, so i = 0xA3
&	bitwise AND
&=	assignment bitwise and
	i &= 0x35; // and i (0xA3) with 0x35, so i = 0x21
|	bitwise OR
|=	assignment bitwise OR
	i |= 0xC5; // OR i (0x21) with 0xC4, so i = 0xE5
^	bitwise XOR: exclusive OR
^=	assignment bitwise XOR
	i ^= 0xF329 // XOR i (0xE5) with 0xF329, so i = 0xF3CC
~	Bitwise complement: (turn 0 bits to 1, and 1 to 0)
	i = ~i; // complement i (0xF3CC), so i = 0xFFFF0C33

Array Initialization

Arrays can be initialized by initializing specific elements, as in:

foo[5] = 7;

foo[2] = -100;

foo[-5] = 4;

or by enclosing all the initial statements in curly braces, which will cause the array to start initializing at element 0, as in:

foo = { 0, 0, -100, 0, 0, 7 };

Single quote strings

You can declare a string with single quotes instead of double quotes. This will create a string without a terminal null character. Single quotes strings are rarely used.

Back-quote strings

ScriptEase provides the back-quote (`), also known as the back-tick or grave accent, as an alternative quote character to indicate that escape sequences are not to be translated. Any characters represented with a backslash followed by a letter (`\n', e.g.) cannot be used in back-tick strings.

For example, here are two ways to describe the same file name:

"c:\\autoexec.bat" // traditional C method

`c:\autoexec.bat` // alternative ScriptEase method

Literal Strings

A literal string is a string within double or back-tick quotes. In some cases (during assignment, comparison, passing to function, returning from function, and case statements), ScriptEase treats literal strings slightly different than other arrays. Literal strings can be treated directly as data, avoiding the string handling routines required of C. If you are familiar with C programming, you may want to read the "Literal Strings" section in the "ScriptEase vs. C" chapter for more information on the special treatment of literal strings.

Long Strings

If you have a lot of text that you want to put into a string, you can do it by putting the strings one after another when you define the string variable. For example:

badJoke = "I was standing in front of an Italian "

"restaurant waiting to get in when this guy came "

"up and asked me, \"Why did the Italians lose the "

"war?\" I told him I had no idea. \"Because they "

"ordered ziti instead of shells,\" he replied."

This creates a long string containing the entire bad joke.

Copying Strings

Because a string is a special compound data form, when you copy string variables you should use the strcpy() function. If you try to use the equality operator, your script will behave erratically.

For example, let's suppose you have the following string,

string = "earwig"

and you wanted to copy it to another string called stringdata. You do this with the strcpy() function as follows (more information on functions appears later in this chapter):

strcpy(stringdata, string);

The statement

stringdata = string

will also copy the string, but not in the way you want. It will make a copy of the variable itself, instead of copying the contents of the variable into another. In effect, this statement says, "set the variable stringdata to refer to the information stored in the same place as the information stored in the variable string." The two variables will refer to the same chunk of memory. They are two different names for the same thing (as opposed to two different variables containing the same thing), so when you change one, you change the other.

Array Arithmetic

When one array is assigned to the other, as in:

foo = "cat";

goo = foo;

both variables define the same array, point to the same place in memory, and start at the same offset 0. In this case, if foo[2] is changed then you will find that goo[2] has also been changed. Integer addition and subtraction can also be performed on arrays. Array addition or subtraction sets where the array is based. By altering the previous code segment to:

foo = "cat";

goo = foo + 1;

goo and foo would now be arrays containing the same data, except that now goo is based one element further, and foo[2] is now the same data as goo[1]. To demonstrate:

foo = "cat";	// foo[0] is `c', foo[1] = `a'
goo = foo + 1;	// goo[0] is `a', goo[-1] = `c'
goo[0] = `u';	// goo[0] is `u', foo[1] = `u', foo is "cut"
goo++;	// goo[0] is `t', goo[-2] = `c'
goo[-2] = `b'	// goo[0] is `t', foo[0] = `b', foo is "but"

The script TReplace.cmm, analyzed in the next chapter, provides a working example of array arithmetic.

Multi-Dimensional Arrays: Arrays of Arrays

Since an array element is a variable, if the type of that element's variable is itself an array, then you have an array of arrays. A statement such as:

goo[4][2] = 5;

indicates that goo is an array of arrays, and that element 2 of element 4 is the integer 5. The examples in the beginning of the section on strings (e.g., name[0]="Mary") are also examples of multi-dimensional arrays.

Multi-dimensional arrays would come in handy for programming a tic-tac-toe game, for instance. Each row and column of the 3 x 3 board could be represented with a row, column element containing `X', `O', or ` ` (blank) depending on the character at that location. For example, filling the middle row with Xs would be initialized like this:

board[1][0] = `X';

board[1][1] = `X';

board[1][2] = `X';

Since a string is an array of characters, anytime you make an array of strings you are defining an array of arrays. For example,

Weekdays = {"Monday", "Tuesday", "Wednesday", "Thursday", "Friday"};

creates an array of strings so that

Weekdays[0] is set to "Monday"

Weekdays[0][0] is set to `M'

Weekdays[0][1] is set to `o'

Weekdays[0][2] is set to `n'

Weekdays[1] is set to "Tuesday"

Arrays: further discussion and explanations

Arrays are perhaps the most confusing parts of ScriptEase. However, they allow you to do a great deal and are well worth the effort it takes to understand them. They allow you to group different variable values together under a common name. It may help to think of a series of numbered boxes, beginning at 0 and continuing on indefinitely. Each box can hold a different value: box[0] can be 5, box[1] can be 23, box[64] can be 88, etc.

The confusion comes in when you try to use array variables in equations. Generally, if an array name appears with a number in brackets, it is a variable representing whatever is in the array at that point, e.g.

bag = box[64]

will set the value of the variable bag to 88 (or whatever value is held in the array at that point).

If, however, the array name appears without the following brackets and number, it stands for the entire array. This situation is most often encountered with strings. When an array holds a string, each box holds a different letter of the string. For example:

string = "duck lips'

is the same as:

string[0] = `d'

string[1] = `u'

string[2] = `c'

string[3] = `k'

string[4] = ` `

string[5] = `l'

string[6] = `i'

string[7] = `p'

string[8] = `s'

string[9] = `\0'

The variable string represents the entire array. The null character (`\0') marks the end of the string. When a string value is set equal to something in double quotes (e.g., string = "duck lips") a null character is automatically appended as the last member of the string. If the null character is moved, the end of the string (but not of the array) moves with it. If you set

string[4] = `\0'

and then output string to a file using a string function, the file will only receive "duck".

Array arithmetic is a way of changing the starting point of that array. In our row of boxes analogy, this is equivalent to renumbering all the boxes (while keeping them in order). So if we set

fling = string + 1

we are setting fling to be equal to string, only fling[0] is `u'. The d (of duck) is now at fling[-1]. The array still starts at 0; if you output fling to a file, the file will contain "uck lips".

The -> operator

The -> operator is a shortcut for "[0]." Using the structure example above, person->name is equivalent to "Mary."

if statement

The if statement is the most commonly used mechanism for making decisions in a program. It allows you to test a condition and act on it. If an if statement finds the condition you test to be TRUE, the block or statement of code following it will be executed: If you are hungry, then eat something. This is an example of an if statement.

if ( goo < 10 ) {

printf("goo is smaller than 10\n");

}

else statement

The else statement is an extension of the if statement. It allows you to tell your program to do something else if the condition in the if statement was found to be FALSE. For example: if you are hungry eat something, else go to the gym. In ScriptEase code, it looks like this.

if ( goo < 10 ) {

sprintf(HTMLstring, "goo is smaller than 10\n");

}

else {

sprintf(HTMLstring, "goo is not smaller than 10\n");

}

To make more complex decisions, else can be combined with if to match one out of a number of possible conditions. For example: if you are hungry then eat something, else if you like to go to the gym go to the gym, else go for a walk. The following code illustrates this concept.

if ( goo < 10 ) {

printf(goo is less than 10\n");

if ( goo < 0 ) {

printf("goo is negative; so it's less than 10\n");

}

}

else if ( goo > 10 ) {

sprintf("goo is greater than 10\n");

}

else {

sprintf("goo is 10\n");

}

while statement

The while is used to execute a particular section of code over and over again until an expression evaluates as FALSE.

while (expression){

DoSomething()

}

When the interpreter comes across a while statement it first tests to see whether the expression is true or not. If it is, it will carry out the statement or block following it (in this case the function DoSomething()). Then it will test the expression again. This loop repeats until the test evaluates to FALSE, whereupon the program continues after the block of code associated with the while statement.

The first example in this chapter uses a while statement:

while( ThereAreUncalledNamesOnTheList() != FALSE){

name=GetNameFromTheList();

CallthePerson(name);

LeaveTheMessage();

}

do {...} while

This is different from the while statement in that the code block is executed at least once, before the test condition is checked.

do {

value++;

ProcessData(value);

} while( value < 100 );

The code used to demonstrate the while statement could also be written this way:

do {

name=GetNameFromTheList();

CallthePerson(name);

LeaveTheMessage();

} while (name != TheLastNameOnTheList());

Of course, if there are no names on the list, the script will run into problems!

for statement

The for statement is a special looping statement. It allows for more precise control of the number of times a section of code is executed. The for statement takes the following form.

for ( initialization; conditional; loop_expression ){

statement

}

The initialization is performed first. Then the conditional is tested. If the conditional is TRUE (or if there is no conditional expression) then statement is executed. Then the loop_expression is executed, and so on back to testing the conditional. If the conditional is FALSE then statement is not executed and the program continues beyond statement. The for statement is a shortcut for this form of while:

initialization;

while ( conditional ) {

statement;

loop_expression;

}

None of the statements that appear in the parenthesis following the for statement are mandatory, so the above code demonstrating the while statement would be rewritten this way if you preferred to use a for statement:

for( ; ThereAreUncalledNamesOnTheList() ; ){

name=GetNameFromTheList();

CallthePerson(name);

LeaveTheMessage();

}

Since we aren't keeping track of the number of iterations in the loop, there is no need to have an initialization or loop_expression statement. You can use an empty for statement to create an endless loop:

for(;;){

//the code in this statement block will repeat forever, unless the

//program breaks out of the for loop somehow.

}

For, do and while statements may be nested inside one another.

break and continue

break and continue are used to control the behavior of the looping statements for, while, and do.

break terminates the innermost loop (for, while, or do). The program resumes execution on the next line following the loop. The break statement is also used at the close of a case statement (see below). This bit of code does nothing but illustrate the break statement:

for(;;){

break;

}

continue jumps to the test condition in the nearest do or while loop, and jumps to the loop_expression in the nearest for loop (i.e., jumps to the next iteration of the loop).

switch, case, and default

The switch statement is a fancy way of making a decision based on the value of a variable or statement. The switch statement follows this format:

switch( switch_variable ) {

case value1: statement1

case value2: statement2

case value3: statement3

case value4: statement4

case value5: statement5

.

.

.

default: default_statement

}

switch_variable is evaluated, and then it is compared to all of the values in the case statements (value1, value2, value3, etc...) until a match is found. The statement (or statements) following the matched case are then executed until the end of the switch block is reached or until a break statement exits the switch block. If no match is found, the default: statement is executed if there is one.

For example, suppose you had a series of account numbers, each beginning with a letter that determines what type of account it is. You can use a switch statement to carry out actions depending on that first letter. The same can be accomplished with a series of nested if statements, but that requires a lot more typing and is harder to read.

switch ( key[0] ) {

case `A':

printf("A"); //handle `A' accounts...

break;

case `B':

printf("B"); //handle `B' accounts...

break;

case `C':

printf("C"); //handle `C' accounts...

break;

default:

printf("You have entered an invalid account number.\n");

break;

}

A common mistake is to omit a break statement. In the preceding example, if the break after the printf("B") statement were omitted the computer would print both "B" and "C", because when a match for a case statement is found, the computer will execute commands until a break statement is encountered.

Normally, if a switch and case statements were referencing array variables, then the comparison would be performed on whether they referenced the same array data. But if either the switch_variable or one of the case values is a literal string, then that comparison of the two strings is made using the contents of the strings (i.e., !strcmp()).

goto and labels

You may jump to any location within a function block (see functions) by using the goto statement. The syntax is:

goto LABEL;

where LABEL is an identifier followed by a colon (:).

beginning:

a = getche(); //get a value for a

 

if (a<2)

goto beginning;

 

printf("%d", a);

gotos should be used sparingly, for they make it difficult to track program flow.

Conditional Operator ?:

The conditional operator is a strange-looking statement that is simply a useful shortcut. It is a limited variation of the IF statement. The syntax is:

test_expression ? expression_if_true : expression_if_false

The entire statement must be on one line.

First, test_expression is evaluated. If test_expression is non-zero (TRUE) then expression_if_true is evaluated and the value of the entire expression replaced by the value of expression_if_true. If test_expression is FALSE, then expression_if_false is evaluated and the value of the entire expression is that of expression_if_false.

For example:

foo = ( 5 < 6 ) ? 100 : 200; // foo is set to 100

sprintf(message, "User's name is %s\n",NULL==name ? "unknown" : name);

To see how the conditional operator is a shortcut, consider that this if/else code to get the maximum of two numbers:

if ( Num1 < Num2 )

MaxNum = Num2;

else

MaxNum = Num1

is equivalent to this conditional operator code:

MaxNum = ( Num1 < Num2 ) ? Num2 : Num1 ;

printf() Syntax

The printf() function prints a string to the screen (standard output). In its most simple form, it takes the string to be printed as its only parameter.

printf("Hello, world!");

The printf() function returns the number of characters that it printed, so the statement

value = printf("Hello, world!");

sets value to 13, the number of characters in the string "Hello, world!".

printf() takes a template string and one or more variables. It then formats them as text and inserts them into the appropriate places in the string. A printf() statement looks like this:

printf(Template,data1,data2,data3,...);

Template, data1, data2, data3, etc., are all parameters being passed to the function. They may be variables, literal strings, or numerical values.

For example, suppose you had a script with the following variables:

first_name = "Helen"

last_name = "Wheels"

state = "Arizona"

age = 26

crime = "frightens young children"

The following printf() statement

printf("%s %s lives in %s, where she %s. She is %d years old\n", first_name, last_name, state, crime, age)

Would be interpreted as:

"Helen Wheels lives in Arizona, where she frightens young children. She is 26 years old."

"%s %s lives in %s, where she %s. She is %d years old.\n" is the template for the string to be printed. The template is always the first parameter passed to printf(). Whenever a template contains a percent character (%) followed by another character, then instead of putting those characters into the string, sprintf() will substitute the next data item (data1, data2, data3, etc...).

The characters immediately following the percent sign (%) determine how the data will be presented. This example uses two formats: %s, to indicate a string; and %d, to indicate a decimal number. There are many such data formats (see the complete description in chapter 6), but here are a few of the more common ones to start with:

%%	print a percentage sign
%d	print a decimal integer
%X	print a hexadecimal integer
%c	print a character
%f	print a floating-point value
%E	print a floating-point value in scientific format
%s	print a string

There are also special characters that cause unique screen behavior when they are printed, some of which are:

\n	goto beginning of next line
\"	print the quote character
\\	print a backslash

Here are some example printf() statements:

printf("Hello world. This is my %dst ScriptEase program.\n", count);

printf("%c %d %dlips",'I', 8, 6-4);

printf("%d decimal is the same as %X in hexadecimal",n,n);

printf("My name is: %s\n","Mary");

The above statements print out the following strings:

Hello world. This is my 1st ScriptEase program [assuming Count = 1]

I 8 2lips

17 decimal is the same as 11 in hexadecimal [where n=17]

My name is: Mary

Function definition

A function takes the following form:

FunctionName(Parameter1,Parameter2,Parameter3)

{

statements...

return result;

}

where the function name is followed by a list of input parameters in parentheses (there can be any number of input parameters and they can be named with any variable names).

A call is made to a function in this format:

FunctionName(Value1,Value2,Value3)

So any call to FunctionName() will result in the execution of FunctionName() with the parameters passed, and then be equivalent in the calling code statement to whatever value FunctionName() returns.

If you change the value of a variable passed to a function, it will change the value of the variable throughout the program. If you don't want to have a function change the value of the variables passed to it, make a copy of the variable and make your changes on that. If the variable is a string, you should use the strcpy() function to copy the variable.

Function RETURN Statement

The return statement causes a function to return to the code that initially called the function. The calling code will receive the value that the function returned, and any code in the function following the return statement will be ignored.The value to be returned may be enclosed in parenthesis to increase legibility:

foo1(a,b) // return a times b

{

return a * b;

}

 

foo2(a,b) // return the minimum value of a and b

{

if ( a < b ){

result = a;

}

else{

result = b;

}

return(result);

}

Some functions don't return anything, and therefore don't have return statements (or they have return statements but no return value). These functions are called void functions. Void functions return no value to the calling code. These examples demonstrate some void-returning functions:

foo(a,b) // set a = b squared. No return value.

{

a = b * b;

return;

}

 

foo(a,b) // set a = b squared. No return value.

{

a = b * b;

}

In a ScriptEase program, these two functions behave identically.

Function Example

This code demonstrates a simple function that multiplies two integers by adding them:

num1 = 4;

num2 = 6;

 

// use the standard method of multiplying numbers

printf("%d times %d is %d.\n",num1,num2,num1*num2);

 

// now call our function to do the same thing

printf("%d times %d is %d.\n",num1,num2,Multiply(num1,num2));

 

// declare a function that multiplies two integers. Notice

// that the integers are defined as i and j, so that's how

// they'll be called in this function, no matter what they

// were named in the calling code. This function will

// return i added to itself j times. (It will fail if j<0).

Multiply(i,j)

{

total = 0;

for ( count = 0; count < j; count++ )

total += i;

return(total); // caller will receive this value

}

When executed, the above code will return two identical strings, "4 times 6 is 24." This example demonstrates several features of functions. Notice that in calling sprintf() the parameter "num1*num2" is not passed to rsprintf(), but the result of "num1*num2" is. Likewise, "Multiply(num1,num2)" is not a parameter to rsprintf(); instead, rsprintf() receives the return value of Multiply() as its parameter.

Function recursion

A recursive function is a function that calls itself, or calls some other function that then goes back and calls the function that first called it. Recursion is permitted in ScriptEase. Each call into a function is independent of any other call to that function (see section on variable scope). Be aware that recursion has its limits; if a function calls itself too many times the script will run out of memory and abort.

Don't worry if you find recursion a confusing idea; you rarely have to use it. Just remember that a function can call itself if it needs to. For example, the following function, factor(), factors a number. Factoring is an ideal candidate for recursion because it is a repetitive process where the result of one factor is then itself factored according to the same rules.

factor(i) // recursive function to print all factors of i,

{ // and return the number of factors in i

if ( 2 <= i ) {

for ( test = 2; test <= i; test++ ) {

if ( 0 == (i % test) ) {

// found a factor, so print this factor then call

// factor() recursively to find the next factor

return( 1 + factor(i/test) );

}

}

}

// if this point was reached, then factor not found

return( 0 );

}

The function strcat(), used in the above example, adds one string on to the end of another. In this example, it adds the contents of text to the end of result string.

Error checking for functions

Some functions will return a special value if they failed to do what they are supposed to do. For example, the function fopen() opens or creates a file for a script to read or write to. But suppose that the computer was unable to open the file for some reason. In that case, the fopen function returns NULL.

If you try to read or write from the file you will get all kinds of errors, because the file isn't open. To prevent this from happening, make sure that the fopen didn't return NULL when it opened the file. Instead of just calling fopen like this:

fp = fopen("myfile.txt", "r");

check to make sure that NULL has not been returned:

if (NULL == (fp = fopen("myfile.txt", "r"))){

ErrorMsg("fopen returned NULL");

}

You will still have to abort the script in this case, but at least you know why. The fopen() function is documented in the ScriptEase Standard Library chapter.

# define

#define is used to replace a token (a variable or a function name) with other characters. The #define statement is executed while the script is being read into the processor, before the script itself, so you'll have all the substitutions in place before the code is read). A #define statement has the following structure:

#define token replacement

This results in all subsequent occurrences of token to be replaced with replacement. For example:

#define NumberOfCountriesInSouthAmerica 13

The define statement increases program legibility and makes it easier to change your code later on. If Bolivia and Peru decide someday to unite, you only have to change the #define statement to bring your program up to speed. Otherwise, you'd have to go through your program looking for 13's, decide which ones refer to the number of countries in South America (as opposed to the 13's representing the Original Colonies of the United States, which stay 13's) and change them all to 12's.

Likewise, if you write screen routines for a 25-line monitor, and then later decide to make it a 50-line monitor, you're better off altering

#define ROW_COUNT 25

to

#define ROW_COUNT 50

and using ROW_COUNT in your code (or ROW_COUNT-1, ROW_COUNT+2, ROW_COUNT/2, etc...) than if you had to search for every instance of the numbers 25, 24, 26, etc...

The ScriptEase interpreter has a large default list of tokens that have already been #defined, such as TRUE, FALSE, and NULL.

#include

The #include directive lets you include other scripts, and all of the functions contained therein, as a part of the code you are writing. Usually #include lines are placed at the beginning of the script and consist only of the #include statement and the name of the file to be included, for example:

#include <gdi.hmm>

This line will make all of the functions in the library file gdi.hmm available to the program.

The quote characters (` or ") may be used in place of < and >.To include all of C:\CMM\LIB.cmm

#include <c:\CMM\LIB.cmm>

To include lots of little files into one big one program

#include <screen.cmm>

#include <keyboard.cmm>

#include <init.cmm>

#include <comm.cmm>

The ScriptEase interpreter will not include a file more than once, so if a file has already been included, a second (or third) #include statement will have no effect. ScriptEase ships with a number of libraries of pre-written functions you can use. Library files are plain text files (as are all ScriptEase code documents) and have the extension .hmm.

This is all you really need to know about the #include statement. It is almost always used in the form above. In certain circumstances, however, #include may take any of a number of parameters to specify which parts of a file should be included. The #include syntax is:

#include <Name[,Ext[,Label[,BeginCode[,EndCode]]]]>

where:

Name	Name of the file to include
Ext	Extension name to add to Name if it doesn't have one
Label	Only include code from Name on lines that begin with this label
BeginCode	Will start including code from Name following the line beginning with this text
EndCode	Will stop including code when this line is read

The second parameter is used when you want to add an extension to the name library name. For example:

#include <library, .hmm:>

is the same as:

#include <library.htm>

If a library is extremely large and you only want to use a small part of it, your script will run faster if you only #include the parts you need. (ScriptEase libraries are rarely so big enough to cause a noticeable slowdown, so you won't need to use this feature very often). The remaining parameters handle various ways to address this issue.

The third parameter lets you designate parts of libraries with labels. For instance, if a library math.hmm contains a function square that is labeled as follows:

:square square(a)

:square {

:square return(a*a)

:square }

To #include only this script, use the following statement:

#include <math.hmm, NULL, :square>

The fourth and fifth parameters will include sections from a file beginning at a certain line and ending at another. For instance the above library could be marked:

//BEGIN SQUARE

square(a)

{

return(a*a)

}

//END SQUARE

 

and the desired functions included with the following line:

#include <math.hmm, NULL, NULL, //BEGIN SQUARE, //END SQUARE>

Note that the labels used with the extended form of #include are not enclosed in quotes.

Since these libraries are external to ScriptEase, they are less static than the standard function libraries, and can be easily expanded or modified as the need arises. The most recent versions of .hmm libraries are listed on the Nombas downloads page at

http://www.nombas.com/downloads/index.htm.

#link

#link is a command to incorporate additional functions into the ScriptEase processor. In practice, it works much like the #include statement with no parameters. However, while #include is used to include text files of ScriptEase code, #link is used to include precompiled extensions or .DLL files. For example, the command

#link "oleautoc"

lets the processor use the functions for OLE automation.

The files which may be included with #link are discussed in another chapter. #link takes no parameters other than the name of the library being linked to.

By keeping these functions in external libraries (instead of incorporating them directly into the ScriptEase processor as is the case with functions like sprintf() and strcat()) the processor is kept to a more manageable size, saving disk space and cutting down on the amount of time it takes a script to run.

Since these libraries are external to ScriptEase, they are less static than the standard function libraries, and can be easily expanded or modified as the need arises. The most recent versions of #link libraries are listed on the Nombas downloads page at

http://www.nombas.com/downloads/index.htm.

#if, #ifdef, #elif, #else, #endif

There are times when you want to #define one file if certain conditions are true, and #define a different file if the condition tests false. You can do this with the #if statement. #if differs from the regular if statement in that it executes while the code is being read into the processor (as opposed to executing when the code itself is run). #elif is the corresponds to the else if statement, and #else corresponds to the else statement. A #if statement must be closed with a terminating #endif statement.

Another way of looking at this is to think of #if as an if statement to use with #include and #define statements, which are also executed while the code is read. This is frequently used to determine which platform the script is running on, so that it will include the proper files and act appropriately to the operating system.

For example, suppose you had a script that built long path names from directories supplied to it in different variables. If you were working in a DOS-based environment, the backslash character is used to separate directories, so you could indicate the full path of a file as follows:

fullPathOfFile = rsprintf("%s\\%s\\%s\\%s", rootdirectory,

subdirectory1, subdirectory2, filename);

If you ported this script to a UNIX machine, however, you'd run into problems, because UNIX uses the forward slash to separate directories.

You can get around this problem by defining the separator character differently for each operating system:

#if defined(_UNIX_)

#define PathChar `/'

#elif defined(_MAC_)

#define PathChar `:'

#else

#define PathChar `\\'

#endif

By putting the separator character in a variable, you can make this script work on any operating system:

fullPathOfFile = rsprintf("%s%c%s%c%s%c%s", rootdirectory, PathChar,

subdirectory1, Pathchar, subdirectory2,

PathChar, filename);

The #ifdef statement is a limited form of the #if statement, equivalent to #if defined(var)... The example above could be rewritten with #ifdef statements like this:

#ifdef (_UNIX_)

#define PathChar `/'

#ifdef (_MAC_)

#define PathChar `:'

#else #define PathChar `\\'

#endif