This section summarizes the fundamentals for writing a Proteus program; additional in-depth information can be found in the following chapters.

At the most basic level, Proteus is used as a text processor; this means that you have a text file in any format (Dos, Macintosh™, Unix™) and you want to convert it, or to extract information from it.

Usually, this file will contain lines which have common features.

In our example, we will consider a file whose lines consist of three fixed-length fields:

You must write a program (or script) to teach Proteus what do you want to do with your file.
A Proteus program is a text file, in any format, specifying which operations will be performed on each line. You can use any text editor or word processor to write it - just remember to save your work in text format (commonly referred to as ASCII); always use the extension '.prt' for Proteus programs.

The syntax of a program is very free, there are no obligations regarding spaces, indentation and case.

When the program is run, there are a few predefined variables that change their values according to the input; two important variables are L and N.

L gets the value of the last line read from the source file, N gets the line number corresponding to L in the same file.

Suppose that you want to extract from the input file all surnames (first field, 30 chars long); a program for doing that is the following:

cSurname = LEFT(L, 30)
PRINTLN cSurname

Let's have a closer look at it.

The first line (or instruction) is an assignment; it stores into the variable cSurname a value, which is specified with the expression to the right of the equal sign. The expression, in this case, is an invocation of a Proteus library function (LEFT), which returns the first n characters from a string. To invoke this function we simply write its name, followed by '(', a few parameters separated by commas, and ')'. Every function is called in this way; the number of parameters and their interpretation depend on the function. The function LEFT take two parameters: the string to be examined and the relevant number of characters.
The meaning of this instruction is: store into cSurname the first 30 characters of the string in the variable L.
As we have seen, L is a predefined variable that gets the value of the last line read from input, thus for each input line this instruction returns exactly what is needed: the surname. The variable cSurname is not predefined: it is a container where we can store numbers or strings. Whenever we specify a variable which is not predefined, Proteus creates it in memory.

The second instruction is the fundamental output function in Proteus; it writes to the output the value of the expression following the name of the method (PRINTLN, in this case) and appends a new line; the methods are control structures and particular functions that do not return any value; their number is very small, compared to library functions; PRINTLN is a method.

The expression passed to PRINTLN is the variable cSurname, to which we have just assigned the surname for the current line; the result is that, for each line read, these two instructions write to the output file the surname in the input file. Since there are no more instructions, soon after having written cSurname, Proteus read another line from input and start again the program.

When no other lines are available, Proteus stops execution, closes all the files and returns control to the user.

This program can be written on a single line:

PRINTLN LEFT(L, 30)

In this way, the program is more efficient because we removed one instruction and one variable, but the program is a little less clear; the user should decide, case by case, if it is necessary to be as clear as possible (e.g. if the program is to be later modified by other people) or to create the most efficient program (if it is executed very often).

Let's add a few contraints to our example; e.g. suppose that the input file has two lines at the start that should be ignored. We can use, to this extent, the value of the variable N and the conditional control structure of Proteus:

IF LE(N, 2)
  IGNORE
FI
PRINTLN LEFT(L, 30)

The conditional structure starts with IF and ends with FI (which is IF read from right to left); if the expression after IF is not 0, all the instructions between IF and FI (or ELSE) are executed; otherwise, the instructions after ELSE (and before FI) are executed. Other control structures are FOR, WHILE, SWITCH e REPEAT.

LE is a library function too; it gets two parameters and returns not-0 if the first is less then or equal to the second (numerically), 0 otherwise. In Proteus, as in "C", 0 is the same as FALSE and a number not-0 is TRUE.

IGNORE is a special method; it tells Proteus to terminate execution for the current line and to go to the next, restarting from the beginning of the program. This is exactly what we need for the first two lines.
When Proteus has read the third line, N is 3 and thus all the instructions inside IF will not be executed again, while PRINTLN will work as expected.

Let's add a few other complications to oue example, supposing that the fields are not fixed length, but delimited by commas (',').

String of characters separated by one or more charactes from a list are called tokens; in our case, every line contains three tokens delimited by commas.

Proteus has many library functions to manage tokens; here we will be using the dynamic tokenizer (TOKEN), that takes three parameters:

• the string to be tokenized;
• the number of the token to be extracted (1, 2 or 3, in our case);
• the list of separators ("," in our case).

The program becomes:

IF LE(N, 2)
  IGNORE
FI
PRINTLN TOKEN(L, 1, ",")

Please note that, whenever one or more fields can be empty, it is necessary to use the function VECSPLIT in place of the token functions; if we don't, we risk to consider one field in place of another.
For example, with the following data:

Smith,John,555-443322
Brown,,555-667788

if we want to extract first name, the following code is wrong:

PRINTLN TOKEN(L, 2, ",")

As a matter of fact, in the case of mr. Brown, where the first name is empty, this code would return the telephone number, "555-667788". The following code is correct:

VH = VECSPLIT(L, ",")
PRINTLN VECGET(VH, 2)
VECFREE(VH)

VECSPLIT creates an array, holding the fields determined from the string, taking into account empty fields (two consecutive separators).

Going back to our initial example, if we want to remove spaces to the right and to the left of the surname, we can use the library function ALLTRIM in this way:

IF LE(N, 2)
  IGNORE
FI
PRINTLN ALLTRIM(TOKEN(L, 1, ","), " ")

The instruction to write to the output is more complex now; as you can see, each parameter of a function can be, in turn, a function; this allows to obtain very compact expressions, avoiding the usage of many useless variables; moreover, since Proteus does not include operators, the order of evaluation is implicitly determined and no parenthesis are needed.

It is possible to write programs that are executed one time only, without standard input and output; see command line parameter -z.

This ends our brief introduction to Proteus; the following sections specify in greater detail syntax and meaning of all methods and library functions, together with more advanced topics as user defined functions (UDF), other predefined variables and regular expressions.