S T R U C T O R I Z E R - User Guide
Elements > Instruction

Classification

An element of the type "Instruction" is the fundamental algorithmic element and may contain any command or simple statement.

Practically, there are five basic kinds of instructions (since version 3.26-02, mere variable declarations are also tolerated, release 3.27 additionally introduced the concepts of constant definitions and type definitions, see below):

  • Input: An input instruction reads a text entered by the user and converts it to the value of a specified variable. An input instruction must begin with the input keyword defined in the Parser Preferences, which should be followed by a variable name (identifier or qualified name), e.g.:
    INPUT value
    Between the input keyword and the variable name, a string literal may be placed, which serves as prompt message (see diagram CIRCLE_DEMO further below, prompt string and variable name may or may not be separated by a comma). Structorizer expects a separate input instruction for every variable to be put in.The target of an input instruction will be registered as new variable if not already introduced before.
    An input instruction without variable is allowed (and will just wait for the user confirmingly to press the Enter key).
  • Output: An output instruction prints something out to the user. An output instruction must begin with the output keyword configured in the Parser Preferences. After the output keyword, a single expression or a comma-separated list of expressions is expected, e.g.:
    OUTPUT "The result is ", value+9, "."
    The expressions will be evaluated and the text representations of their values are written into a common output line in their order of occurrence. The next output expression will not continue the line but start a new line.
    An output instruction without an expression is allowed and will produce an empty output line.
  • Assignment: This is when a variable (naming a storage location) is filled with a (new) value without user interaction. As a general rule, an assignment starts with a variable name (identifier), followed by an assignment symbol, and ends with an expression, the computed value of which is to be stored in the variable. Accepted assignment symbols are "<-" or ":=". (The first of them will be shown as an arrow pointing to the left when drawing the diagram, see images below.)
    The very first assignment to a variable is called an initialization. Structorizer will not register a variable before it has been initialized (or targeted by an input instruction).
  • Internal procedure call (like e.g. forward(100) to move the turtle within the Turtleizer window, further procedures see Syntax). To call a procedure not being built in but referencing another diagram, however, it is suggested to use a CALL element rather than an ordinary Instruction element.
  • An end-standing return instruction used for the unconditioned delivery of a function result. "End-standing" means that it must be the last element (exit point) of the algorithm, reaching over the entire width of the diagram. The diagram must be of subroutine type (see Program/Sub and Settings). In any other case, a return statement must form a JUMP element (or be avoided altogether)
  • Auxiliary stuff like declarations (of variables) and definitions (of types or constants) should preferrably be placed at the very beginning of a diagram.

For a list of built-in operators, functions, and procedures usable within instructions (and other elements) see Syntax.

Example of an instruction sequence consisting of an input instruction, an assignment, and an output instruction (in two different display modes):

 

Standard diagram versus highlighted diagram

Let's see a somewhat more meaningful example. Imagine you want to convert temperatures given in Fahrenheit to centrigrade. You know the formula as ϑC = (ϑF - 32) · 5 / 9. You will need an input instruction to ask for the temperature value in Fahrenheit before you can apply the calculation, and you may want to output the result afterwards. So the algorithm is a sequence of three instructions forming a main diagram (input and output instructions inked green, the assignment instruction tinged yellow):

Fahrenheit - Celsius conversion

The input instruction implicitly introduces variable temp_F. Variable names in an algorithm will contain neither greek letters nor subscripts, so we had to rename it. The yellow assignment instruction introduces the variable temp_C. As you see, the assignment contains the formula nearly as above with some inconspicuous but important differences, though: A variable means a named storage place that has to be filled with a value, therefore we need an assignment operator (the leftward arrow or ":=") rather than an equality sign to transfer the result of the computation into variable temp_C. The multiplication is expressed by an asterisk. For the division, we make better sure the numbers are interpreted as real (floating-point) numbers lest the result should be that of an integer division; therefore they are better written with decimal points.

How to build this diagram, now?

1. Start with an empty diagram, double-click its border and enter the name and a description, then commit by pressing the "OK" button:

Filling in the diagram root for instruction demo

2. Now select the (empty) diagram centre and double-click it or press the <F5> key or the instruction icon in the toolbar:

Adding a first instruction element.

3. When the element editor opens, fill in the input instruction - use the input keyword as configured in the parser preferences, optionally add a prompt string (here: "Temperature in °F") and specify the variable name, where we ought to adhere to letters of the English alphabet, underscores and possibly digits:

Editing the first instruction

4. The just inserted element will still be selected, so you may add the next instruction right away (again with <F5>, via the instruction icon, via meu item "Diagram => Add => After => Instruction" or via the respective context menu item, see step 6):

insertion of a second instruction

5. Fill in the assignment text (as outlined above, be aware of the assignment symbol between the target variable on the left-hand side and the expression on the right-hand side):

Entering the text of an assignment

6. Now add the third instruction (e.g. via the context menu):

insertion of the third instruction

7. If you like, you may colourize instruction elements to emphasize certain aspects (by using one of the round paintbox buttons):

Colourizing an element

You may download the Instruction demo diagram here.

Multi-line Instruction Elements

Usually, an Instruction element contains a single statement of one of the kinds listed above. For convenience, however, the Structorizer allows an Instruction element to contain more than one statement. In the latter case, use one line per statement (in other words: place one statement per line). But be aware that e.g. breakpoints can only be attached to an entire element, not to a single line. It is not recommended to combine statements of different kind (e.g. input instructions with assignments or output instructions) within a single Instruction element. By the magic wand button Magic wand (transmutation button) you may merge a sequence of selected Instruction elements into a single Instruction element or, conversely, split a multi-line Instruction element to a sequence of separate Instruction elements consisting of a single statement line each.

Diagram containing different instruction elements

Since release 3.27 you may even spread long instructions over several lines, i.e. continue the statement text in consecutive lines if you place a backslash at the end of each line except the last one - see an example further down in subsection Type Definitions:

If you want to test your diagram via Executor or to export it to source code of a programming language then

  • DON'T append instruction separators (like ";" or ":") to the lines;
  • DON'T list several commands within a single line;
  • DON'T let an Instruction element contain empty lines.

Variable Declarations

Mere declarations with Pascal or BASIC syntax are tolerated as content of Instruction elements. To be recognised, a variable declaration must start with one of the keywords var (Pascal) or dim (BASIC). After the keyword the variable name is expected, then a separator - either : (Pascal) or as (BASIC) - and a type name or specification. Examples:

Variable declaration examples

The type specifications in declarations are rather informal and not restricted to a certain programming language. Up to now, most declarations (with one important exception!) in Structorizer do not directly restrict the kind of value you may assign to a declared variable - you can always override the declared type. But the declaration may influence code export and under certain circumstances be converted into a correct declaration in the target language. The code generators use some type name mappings and try to make sense of different ways to declare arrays.

The mentioned exception from type tolerance are the record types (aka struct types, also introduced with release 3.27). Since components of variables of these types are accessed via so called qualified names (the variable identifier is followed by a dot and the component name), the knowledge about the user-defined structure of a variable is essential for the parsing of expressions. Therefore type definitions had to be introduced (see below). Variables may not be used as records if they weren't explicitly declared with a previously defined record type, and declared record variables may not simply be abused for other kinds of values.

Note that the variable names introduced by declarations will not be highlihghted unless they are initialized somewhere.

Constant Definitions

Instruction elements may also contain constant definitions. Syntactically they look just like variable assignments but with a preceding const keyword. Semantically, constants are indeed handled like immutable variables by Structorizer. This means they can be set only once. The value may be computed by an expression. The Analyser may check whether all involved operands are literals, defined constants, or constant expressions themselves. Further attempts to assign another value to a constant or to alter the defined value will be prevented by the Executor. Structorizer guarantees the constancy in a generous way, though. So you may assign a complex constant object (say an array) to a variable. If you assign an array held by a variable to another variable, both would share the same object. Obviously, to do the same with a complex constant object would compromise constancy or make the target variable implicitly a constant. Rather than raising an error in such a case, Structorizer will just assign a mutable copy of the constant object to the target variable. This goes smoothly but ensures the expected consistency sufficiently.

Examples of constant definitions (also containing some variable declarations):

Constant definition and variable declaration examples

The formal parameters of routines may also be declared as constant by placing a preceding const keyword. In this case, the value passed in from the respective argument on calling the routine may not be altered within the function (read-only semantics). Again, with passed-in arrays you obtain only an immutable copy, which prevents a compromising impact on the original array.

The left-hand side of a constant definition (i.e. left of the assignment symbol) may also contain a type specification, thus looking like a variable declaration but that the const keyword replaces the var or dim keyword. With the const keyword, even a C-like type specification would be possible. As with variable declarations, type specifications are rather informal (and not restricted to type names of a certain programming language). Moreover, they are redundant here because the type may be derived from the constant expression. But they may yet be helpful on code export.

Type Definitions

Instruction elements may also contain type definitions. As outlined with the paragraph about variable declarations, they became necessary with the introduction of record/struct types.

A type definition starts with the reserved word type, followed by the name of the new type to be defined (an identifier), an equality sign and, at the right-hand side of it, the type specification. For a compound type, either the reserved word record or - synonymously - struct and an opening curly brace   must come next. After the brace, a list of component declarations is expected, which look similar to parameter declarations of a subroutine; Pascal-style (name: type) as well as BASIC-style (name as type), and C-style (type name) component declarations are all accepted but must be separated with semicolon (!). Only in Pascal-style group declarations, the component names sharing a common type may be separated with comma (e.g. Date components month, day in the screenshot below). Finally, the declaration list is to be terminated with a closing brace (this syntax is a mixture from Pascal and C):

Two nested record types defined

If you want to spread a type definition over several lines, then each line but the last one must end with a backslash. (The last element in the image above shows a record variable declaration with immediate initialization - which is highly recommended.)

Record types may also be used as parameter types of subroutines. But be aware that in this case both diagrams (the caller und the called one) must know the type, otherwise the argument passing wouldn't work. In such cases, you must place the type definition in an additional diagram of type Includable and put the name of this includable diagram in the include list of both communicating diagrams (this is the upper text field in the Program / Sub editor).