Basic Concepts

This section will introduce the following programming concepts:

Statements, Statement Seperators and Statement Blocks

Every trCAD script program is a successive sequence of written statements. These are single commands that get executed one after another. If we assume that we have some statements with the names statement1, statement2 and so on, then a sequence of statements would just be

Example

statement1
statement2
statement3
...

When the program runs, statement1 is executed at first, then statement2 followed by statement3 and so on: every program can be seen as a simple list of single tasks. Later we will encounter some statements that seem to direct the execution onto less linear ways like loops or conditions but viewed from a greater distance these are still statements that are executed in a linear order.

Every statement must be seperated from the following. This can either be done by a simple line break, as in the last example, or by a semicolon character ';' acting as statement seperator. With this, the list can also be written in the following way:

Example

statement1;statement2;statement3;...

or by a mixture of line breaks and semicolons. A common recommendation is to put only one statement per line. This helps to build code that is very readable.

Multiple statement seperators can be put together like e.g. a semicolon followed by a line break.

Multiple consecutive statements can be combined into groups by using curly brackets '{' and '}' at the front and at the end. This is labeled a code block or statement block. A common way is, to put each bracket into a seperate line and apply an indentation to the statements inside the block:

Example

{
  statement1
  statement2
  statement3
}

A statement block acts like one single statement. This will become extremely usefull when we want to add multiple statements to some control commands that accept only one single statement later in this tutorial. Statement blocks provide simple and elegant solution to this problem.

Note

Semicolon statement seperators ';' are not required: line breaks can be used instead.

Comments

Often you may want to note down some ideas into the script code that are for you to read but not for the trCAD system to execute. For this you can include comments. These are marked sections in which you can write any text you want. Anything inside comments is ignored by the trCAD system.

There are two distinct types of comments: single-line and multi-line comments. Single-line comments start with two slash characters '//'. This sign marks everthing on its right hand side until the end of the line as a comment. Multi-line comments start with the character sequence '/*' and end with the next occurring character sequence '*/'. The comment spans inside these two signs, irregarding of whether they are in the same line or not.

The following example creates comments of the two types:

Example

// This is a single line comment. It automatically ends at the end of the line.
/* This is a multiline comment. It ends at the next multi-line ending sequence
that may occur in the same line or in a later one: */

The exit Command

The first real command that we want to introduced is the exit command. The exit command is a statement that terminates the execution of the script immediately when it is encountered. In connection with conditions this command can be used for terminating the program flow when some unclear situation arises, e.g. on an invalid user input.

Let's try it out right now:

Example

// Here can be statements that get executed.
exit
// Statements at this points will never be reached.

Of course, this very simple example program doesn't produce any output since the only thing it does is to quit. So let's go some steps further to see a bit more.

Variables and Assignments

The basic way of storing information are variables. A variable is defined by a data type specifier followed by a variable name that can be chosen freely by the programmer (its identifier). The basic data type specifiers are listed in the next section and a full list can be found in the references section of this manual.

Variable names must be unique in the sense that it is not allowed to define another variable or function with an equal identifier. (This is not completely true since names may be reused inside another statement block or inside a function block.) Variable names can contain upper case and lower case letters, numbers or the underscore character '_'. They may not start with a number character and have a maximum length of 64 characters.

Lets define a first variable representing an integral value of type 'int' what is an integrat number:

Example

int myvariable

A value can be assigned to a variable by using the assignment operator '=' followed by an expression of the to-be-assigned value. Defining a variable and assigning it the value 5 is then:

Example

int myvariable
myvariable = 5

The definition and the assignment can be put together in a single line:

Example

int myvariable = 5

The echo() Command

An easy way to check the value of a variable is to use the echo() function. The variable can be handed over to the function as its function argument by writing it inbetween the functions brackets. The function then writes the value to the output:

Example

int myvariable = 5
echo( myvariable )

Output

The echo() function can also be used to output a value directly without using a variable, e.g. echo( 5 ).

Basic Data Types

The four most basic data types are meant to represent logical values, numbers and text and they are very commonly used by many other languages in the same way. These are

boolean values of type bool
integral numbers of type int
floating point number of type float
text strings of type string

The following four sections briefly explain each of these.

Boolean values

Boolean values have the data type specifier bool. They can represent the two logical values false and true. As a variable they are often used for memorizing whether a certain state is switched on or off (i.e. they are used as a flag). As a value they often appear in conditions to decide what part of code is executed.

Integral numbers

Integral numbers are positive or negative whole numbers. They have the data type specifier int and are mostly used for counting and as index values.

Floating point numbers

Floating point numbers represent real numbers in the system. Their data type specifier is float. The representation syntax follows the same rules as in many other programming languages. The following forms are valid floating point number representations of the same number (except the last that has the negative value):

0.05	.05	0.005e1
5E-2	+0.05	-0.05

Floating point numbers are mainly used to represent "natural" values as coordinates and therefore appear most often in calculations.

Text strings

Strings have the data type specifier string and are used to store text. The text length can vary from a single letter up to a complete text. Text content must be placed within single or double quotation marks in order to be recognized. If the quotation mark character used for this appears somewhere in the text, it must be masked with a leading backslash character '\'.

Example

bool b = true
int i = 5
float f = 4.5
string s = "Hello world!"

Data type casting

Some data types may express related values, like int and float that both represent numbers. Another way of expressing a number may be the use of a string, e.g. "2.5E-5" that could be seen as a "text encoded" version of the floating point number 2.5E-5. In some of these cases it is required to convert one data type into another. This convertion (labeled as casting) occurs automatically (implicit casting) wherever it is required to assure a valid interpretation of the data. Alternatively it may be requested by the user (explicit casting). In some cases, casting leads to a change of the value of the data, e.g. when the target data type is not capable of fully representing the original value. However, the casting follows the rules known from other comparable programming languages that aim to keep the values close to the original ones.

In the following example, the floating point value 3.4 is casted automatically (implicitly) to fit in a variable of the 'integer' type, leading to a loss of the value after the decimal point:

Example

int i = 3.4
echo( i )

Output

Due to the automatic casting, the result is 3 and not, as one might expected, 3.4.

Emplicit casting can be initiated by putting the target data type written in parentheses in front of the expression that should be casted:

Example

echo( (int) 3.4 )

Output

Most data types can be cast into the string data type.