1. Structorizer

Welcome to the Structorizer User Guide

Editorial remarks:

The GUI (Graphical User Interface) is quite minimalist and simple to use (see image below). It is built of

(Diagram work area, Arranger index and Analyser report list form a focus ring through which you may navigate by the <Tab> key in clockwise and by <Shift><Tab> in counter-clockwise direction.)

Fundamental GUI layout

But "under the hood" there is a lot of functionality waiting for you to try it out.

  

1.1. Homepage

  

1.2. About

Structorizer itself has been written by Bob Fisch and is published, since version 2, as open-source under the terms of the GPL license, which means that everyone is free to change the code to fit their own needs as long as the header comments remain intact, so that each code can be tracked down to it's orignal author.

  

1.3. Authors

Since September 2015 Structorizer is located on Github. Actually the following people are actively involved:

 


 

Concerning the software itself:

Concerning this user guide:

  

1.4. Versions

There are three series:

All versions have been coded in Delphi 6 PE and are only running on Windows based computers. Version 1.5 is a special one, because all the heavy features have been cut out.

For these versions the original Delphi code has been converted and adapted to fit into a Lazarus (FreePascal) project. Since Lazarus runs on different operating systems, a Windows, Linux and Mac OSX (intel only) version had been published. Actually, these versions were somewhat buggy and never worked 100%.

Having had too much trouble with Lazarus, the code has been ported and completely rewritten into Java. These versions are no longer bound to any operating system and run as expected.

  

1.5. Used Packages

The latest version of Structorizer uses the following packages:

The following package, which is used by the binary versions of Structorizer, is not contained in the source package:

  

2. Installation

Generally there are two possibilities to install Structorizer onto your PC:

Please refer to one of the submenu items for any details about how to proceed for a given operating system.

Let Java Web Start handle the installation process. Simply click on the following link.

  

2.1. Windows

Download the latest package from http://structorizer.fisch.lu and unzip it somewhere on your hard drive. There is no special installation package. Simply run the file "Structorizer.exe".

When you first run Structorizer, it will register the file type ".nsd" and associate it to itself, so you can doubleclick NSD-files later on to open them automatically within Structorizer.

You may easily place a Shortcut-Link on your Desktop if you right-click the file "Structorizer.exe" and then derive a link to it, e.g. via the "Create Link" item in the Windows File menu. Move the created link to the desktop, the start menu, or whereever you like and rename it appropriately.

Trouble-shooting on start and batch mode

From version 3.24-06 on it shouldn't happen any longer that just only a splash screen pops up for some seconds and then nothing more. Now you would get an error message if something goes wrong on start. (Most likely it would be due to a missing or obsolete Java installation - remember that Structorizer is Java-based and the .exe file is more or less a wrapping launcher.) Nevertheless, in order to find out what exactly is the problem you may open the console (e. g. by starting the "cmd.exe" program) and run the Structorizer.bat script file contained in the Structorizer directory. This way you should obtain the error description text giving you enough hints to fix the problem.

The Structorizer.bat file is also helpful to do source code generation from nsd files or to derive nsd files from Pascal source files as batch task from the console or in a script (see Export source code and Import for details). Command Structorizer.bat -h prints you a short synopsis of the possible batch command options.

  

2.2. Linux

Download the latest package from http://structorizer.fisch.lu and unzip it somewhere on your hard drive. There is no special installation package. You can simply run the file "structorizer.sh" contained in the unzipped directory.

If you'd like to load a diagram upon the application startup just add its file path as argument to the command:

structorizer.sh ~/nsd/myExample.nsd

See Batch Export and Batch Import for a complete list of all command line options for Structorizer.

Debian

Please note, that, thanks to Philipp Huebner, there are also packages ready to install for all Debian distributions. Unfortunately, they contain a pretty outdated Structorizer version (and are not guaranteed to be compatible with most recent Debian versions, either). You can download them right here:

http://people.debian.org/~debalance/structorizer/

It is currently an all-in-one package, shipping the libraries from the source package. I will now try to get structorizer working with the freehep libraries in Debian.

He recommends the following procedure for installation:

# dpkg -i
# apt-get install -f

The first step might fail due to missing dependencies. The second step will install these dependencies and then complete the installation.

  

2.3. Mac OS X

Download the latest package from http://structorizer.fisch.lu and unzip it somewhere on your hard drive. There is no special installation package. Simply move the "Structorizer" application to your application folder or run it from where you have unpacked the archive. (In former versions there wre some files "Structorizer.sh" and "Structorizer.exe" in the Structorizer folder, which are not needed under Mac OS X. You may simply delete them.)

When you first run Structorizer, it will register the file type ".nsd" and link it to itself, so you can doubleclick NSD-files later on to open them automatically within Structorizer. This feature is only available for the Mac version since Structorizer 3.05.

  

3. Elements

Here you can find explanations for the different kinds of Elements that can be inserted into an algorithm and how to do this in Structorizer.

The framing program (or routine) element will already be there.

To perform some action you will use the basic element type: Instruction.
If you want to delegate complex operations to another diagram, insert a Call.

If the further activities depend on a condition or selection, insert an IF or CASE statement.

If you have to repeat some bunch of operations, you'll need one of the loop elements: FOR, WHILE, REPEAT or Endless loop.

If you happen to have to do several sub-tasks, which are mutually independent and could be performed in arbitrary order or in parallel, then you may choose to make them branches of a Parallel element.

Just inspect the respective subsection for details.

  

3.1. Program / Sub

The bare diagram

When you start Structorizer or create a new diagram, then you will be presented an empty diagram with dummy name "???":

Empty diagram

Fill in a sensible name in the text field.

Also make sure to fill in the comment field with a description what the algorithm is good for and how to use it.

Editor mask for Root element

The framing (or root) element of a Nassi-Shneiderman diagram represents either a program or a (callable) subroutine (also see Type setting).

Structorizer allows you visually to distinguish whether a created diagram is meant to be a program or a subroutine - they differ in the shape of the surrounding box: 

A program diagram has rectangular shape, whereas the corners of a subroutine diagram will be rounded.

How to set the type of the diagram?

Just select the appropriate one of the menu items "Diagram" => "Type" => "Main"/"Sub" (see screenshot) or one of the toolbar buttons boxed red in the screenshot (cf Diagram type setting).

Menu items and toolbar buttons to switch among program and subroutine

When you start with a new diagram, it will initially be a program. The following images show you the computation of the factorial both as a program (left) and as a function (right). Note that the assignment to variable result is one of three supported value return mechanisms (see last paragraph below).

Diagrams to compute the factorial
As Program As Function
Editor mask for Root element with Factorial description Edit mask for Root element containing the factorial function description

Factorial algorithm as program

Factorial algorithm as function

In order to allow you a subroutine simulation at the top level (i.e. without calling context), the Executor will pop up an input dialog for every function parameter before the execution and an output dialog showing the computed result on termination. (But this is only the case while you execute a subroutine diagram at the top level.)

Diagram header

If the diagram is a program then the text field is supposed to contain just its name. A program name should be an identifier as described above, i.e. a word consisting of letters, digits, and underscores, beginning with a letter or underscore. It should not contain blanks.

A subroutine header, however, is supposed to contain more information than just the name. The subroutine name (an identifier as described above) is to be followed by a paramter list. A parameter list - in its simplest form - is a pair of parentheses containing a series of parameter names, separated by comma or semicolon (see example above).

A typed subroutine header may have Pascal syntax (note the semicolon between parameter groups of same type!), e.g.

functionName(var1, var2: Cardinal; var3: Double): Double

or C/Java syntax e. g.

double functionName(int var1, int var2, double var3)

or modern BASIC-like syntax, e. g.:

functionName(var1 as Integer, var2 as Integer, var3 as Double) as Double

All three forms will be accepted by Structorizer and converted to proper function headers on code export if possible.

Return mechanisms

In order to return a value from a function diagram, you have the choice among three possible mechanisms supported by Structorizer (i.e. both Executor and code export):

  1. Assign the value to a variable named exactly like the subroutine (like in Pascal; in the above example you might modify the last line to: factorial <- fact);
  2. Assign the value to a variable named "RESULT", "Result", or "result" (as shown in the example above);
  3. Add a return instruction (like in C, Java, and the like; modify the last line in the above example to: return fact).

The first two of the opportunities allow to override an assigned value by later instructions such that just the last performed assignment to the function name or result variable will be the final result, whereas a return instruction will immediately force the termination of the subroutine with the attached result.

You should not employ more than one of the three result mechanisms described above within the same diagram, otherwise the result may not be what you expected it to be.

Note that mechanism 1 will cause Analyser complaints if option "Check that the program / sub name is not equal to any other identifier" is enabled in the Analyser preferences.

  

3.2. 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 declarations are also tolerated, see below):

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

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

Multi-line Instruction Elements

Usually, an Instruction element contains a single instruction of one of the kinds listed above. For convenience, however, the Structorizer allows an Instruction element to contain more than one instruction. In this case, use one line per instruction (in other words: place one instruction 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 instructions 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 instruction line each.

Diagram containing different instruction elements

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

Variable Declarations

Since version 3.26-02, mere declarations with Pascal or BASIC syntax are tolerated as content of Instruction elements but may cause Analyser warnings that the declared variables are not initialized. 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, declarations 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.

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

  

3.3. IF statement

An element of type "IF-Statement" represents an alternative. It is used at a decision point where the algorithm must take one of two different ways. The IF statement comprises the condition and both emerging paths. After having passed the selected path the control flow will continue below the IF element.

The text of the IF element is to contain the logical condition. It may be represented by any boolean expression, i.e. an expression that evaluates either to true or to false. If the value computes to true then the left branch will be taken, otherwise the right branch.

Please note:
The labels for the "TRUE" and "FALSE" branch in the graphical presentation can be modified under Preferences -> Structures.

This is how you add an IF-Statement to your diagram:

1. Select the IF-Statement in the menu

Select the IF-Statement
 
2. Insert a condition

When the element editor opens then the text field will contain a default string which is configurable under Preferences -> Structures. Replace this default string by the actual condition. This may be a comparison, a variable with boolean content, or several conditions combined by logical operators.

Accepted logical operators are and (or &&), or (or ||), not (or !), and xor (or ^), where the latter stands for exclusive or (A xor B is true if exactly one of the conditions A or B is true).

If one of the two branches is meant to remain empty (i.e. you are just going to create a "conditioned instruction") then formulate the condition in such a way that the non-empty branch is the "TRUE" branch.

Edit the IF-Statement 

3. Add elements, e.g. instructions, to the branches:

Add an instruction in the IF-Statement 

4. If you want to have more than one instruction executed in a branch then add them after or before the first one (i. e. make sure to have selected an element of the branch when inserting or appending another one): Add an instruction After the first in the IF-Statement

5. If you want to add further elements after the entire IF statement (no matter, which branch was chosen and executed, the control flow will continue with the element following the IF statement) you must select its head first:

Add an instruction After the IF-Statement

6. This is what the finished version could look like (note that neither the INPUT instruction nor the yellow-coloured OUTPUT instruction is part of the alternative):

Completed IF-Statement

Download Demo

  

3.4. CASE statement

A CASE element (or "selection") is a multi-way forking of the control flow within an algorithm. The branch to choose is determined by a comparison of the value of a control expression (discriminator) with the branch labels (selectors). The number of branches is configurable. Usually, a CASE structure provides a "ragpicker" branch (called default, else, or otherwise branch) placed right-most in order to catch any discriminator value not matching any explicit selector.

In order to add a CASE element select the element it is to precede or to succeed.

CASE statement insertion

Then you may press one of the toolbar buttons marked with a red box in the screenshot above (for this example the right one was used in order to insert the CASE statement after the selected element), or you might open the context menu or the "Diagram" menu and select the "Add" submenu, then either "Before" or "After", and eventually the "CASE statement" entry. (Or you simply press one of the function keys <F10> or <Shift><F10>, depending on whether the CASE element is to be inserted after or before the currently selected element.) This will open the element editor for a new CASE statement:

Filled-in CASE editor

The text to be entered into a CASE form is interpreted like this:

(The default text occurring in the editor field on adding a new CASE element can be modified under Preferences -> Structures.)

If you want to have a CASE statement without a default branch (= else part), simply write "%" into the last line. In that case, the last column will not be drawn.

The selector values to be matched against ought to be integral, character, or string constants (literals), see examples below (the CASE element head is coloured cyan blue in the diagrams):

Content of the CASE structure Generated diagram
A
1
3
5
sinon
CASE statement with default branch
A
1
3
5
%

CASE statement without default branch

month
1,3,5,7,8,10,12
4,6,9,11
2
default

 

CASE structure with multiple values per branch

(Only supported by Structorizer version 3.22-31 and later)

After having filled in and committed the element editor, the result might look like this:

Demo diagram after CASE statement insertion

The CASE structure is composed of

In order to insert elements to a branch select the respective branch and insert the elements needed in the usual way (see Add element).

In order to append an element after the entire CASE statement select the head of the CASE structure first and then add the element to follow as usual (see Add element).

To pass a CASE element means to evaluate the discriminating expression and to execute the branch the selector of which matches the discriminator value. After the branch is executed, the control flow passes to the next element appended below the entire CASE element - independent of the selected branch.

Note: On editing an existing CASE element (e. g. by double-clicking or by pressing the <Enter> key while the CASE head is selected) you may insert or remove lines. But be aware that the instruction sequences of the branches themselves won't move when you e. g. insert new case lines close to top. They will stick to their original position (left-bound) rather than to their originally corresponding label. In the first example of the table above, inserting a new line "2" between "1" and "3" would result in the following situation where the red coloured branches are now associated to wrong selectors and will have to be moved rightwards by dragging them one by one or by a manual cut and paste sequence:

Branch association error after case line insertion

If you reduce the number of case lines, in contrast, then the supernumerous branches will automatically be deleted just from right to left - no matter which lines you removed. Hence if you had deleted the line "1" in the original example you would end up with all three remaining branches being wrongly associated (marked with red colour again):

Branch association error after case line deletion

So edit with care! If you want to avoid hassle then add new cases preferably near the end of the list (though the default case must always be the last one) and copy the contents of branches prone to vanish before you start to remove obsolete selector lines from the text.

Hint: Since version 3.25-02 you may decompose a CASE element into an equivalent set of nested IF elements simply by means of the transmutation wand Magic wand icon for transmutation. (But you may not transmute nested alternatives into a CASE element. The efforts to check the prerequisites for this conversion would be too expensive.)

  

3.5. FOR loop

Loop styles

An element of type "FOR loop" is used to repeat certain instructions a pre-determined number of times. Structorizer supports two varieties of FOR loops:

  1. COUNTING loop - the traditional style. The loop increments (or decrements) a number between an initial and a final limit of an interval. It is said to count the executed passes through the loop. Consequently, you have to specify a counter variable as well as its initial and final value. By default the counter variable is automatically incremented by one after each execution of the loop body.
    You may specify a different increment (step value), which might be negative but it must be a non-zero integer constant if you want your loop to be executable or sensibly exported to a programming language of your choice. All these parameters form the control phrase, separated by configurable keywords.
    Examples for counting FOR loop headers:
        for i <- 1 to 15
        pour j <- 10 à -10, pas = -2
  2. TRAVERSING loop - the loop body is repeated for every single element of a given collection. The elements are not required to be numbers, they may be of any data type. Therefore you will have to specify a variable representing the current element, and of course a collection, which will have to be an array, obviously. (See Executor for details how array variables and array expressions are used in Structorizer.)
    Examples for traversing FOR loop headers (more examples further below):
        foreach elem in {"good", "better", "best"}
        para numero en numeros                (where numeros should be an array variable)

The underlined keywords (or key string sequences) disambiguating and separating the parameters of the loop are configurable in the Parser Preferences.

This is how you may add a FOR loop to your diagram:

1. Select an element in your diagram after or before which you want to insert the FOR loop:

FOR loop insertion

2. Now either select the respective FOR loop symbol in the toolbar (see red box in the image above - note that the FOR loop symbol may have different appearance, depending on whether or not the DIN representation is chosen, it's always the left-most of the loop symbols, though) or open the context menu, choose the "Add" submenu, then either "Before" or "After", and eventually select the respective FOR loop entry. Alternatively, you may press the <F7> or <Shift><F7> key (see Keybindings).

3. When the editor pops up, you will see the following form. The screenshot shows it prepared for specifying a counting loop (upper radio button selected). The labels and default field contents are influenced by your Parser and Structures preferences (we will discuss his later). Now you have several ways to set up your loop.

FOR loop editor

a) Fill in the text fields in the form region marked by the green box in the screenshot below. For a counting loop give the counter variable a name, specify its initial (start) value and its final (end) value. In addition, you might specify a different increment constant (negative in order to decrement). The editor will instantly compose the resulting control phrase from your input and display it in the (disabled) text area beneath. The step specification in the control phrase will be omitted while the "Increment" field contains the default constant 1:

FOR loop editing via the separate text fields

b) If you select the lower of the two radio buttons (labelled "foreach" here), you will be presented the form for a traversing loop instead (see screenshot below). Again, you will have to specify the name of the loop variable but then a list of values, preferably comma-separated and within curly braces. But it might also be the name of an array variable or just a space-separated enumeration of some values. The listed values are not required to be numbers, not even literals. As before, the editor will immediately compose and present the control phrase.

FOR loop editor in traversing form mode

c) By selecting the "Full Text Editing" checkbox, however, the editor-internal synchronisation changes direction, i.e. now the text area (marked by a green box in the image below) will be enabled whereas the radio buttons and the form fields in the upper region simply show the conclusions Structorizer derives from parsing the control phrase you are writing. The parsing success depends on the configured parser preferences for FOR (and FOR-IN) loops. The structured text fields in the upper region will immediately be synchronised whenever you touch the text. Be aware that the form fields may show some strange things while your control phrase is incomplete, incongruent, or ambiguous.

FOR loop editing via the compound text area

d) As soon as the entered text rather resembles the control phrase of a traversing loop (i.e. a FOR-IN loop), the radio buttons will switch and the upper part of the editor will change its appearance, i.e. the set of form fields including the labels willl alter as the next screenshot demonstrates.

FOR-IN loop editing via the compound text area

Synchronisation between the upper text fields and the larger text area starts as soon as you click into one of the active fields or toggle the "Full Text Editing" checkbox.

4. Fill in some helpful description in the comment area if you like - this will be the loop comment, obviously.

5. Add instructions to the body of your loop. Therefore first select the empty element and then select an arbitrary type of element to insert it.

Element insertion to the FOR loop body

FOR loop with body

6. If you want to add instructions after the loop (instead of to the loop body) then first select the upper or left outer part of the loop element:

FOR loop - adding after the loop

Now, this might be the complete diagram to compute the average (or mean value) of the numbers inserted to the valueArray, the two similar FOR loops are coloured light-blue:

FOR loop usage for average computation

Note:

  1. Start and end value may be arbitrary expressions (though they should compute to integer values), whereas the step width (i. e. the increment) must always be an integer literal, otherwise it wouldn't be a predictable counting and you should use a WHILE loop instead. (Hint: you may easily transmute a FOR loop of counting type into an equivalent WHILE loop construct.)
  2. The Executor will reject any attempt to manipulate the loop variable within the loop body as illegal interference with the loop control mechanism (from version 3.25-10 on; before it just hadn't an impact on the loop control). Also see Analyser Preferences.

Relation between Preferences and Editor

The image below explains where the different labels and settings come from. The keywords and strings in the green boxes (also the "foreach" label) are fed from the Parser Preferences and control the detection of the FOR loop parameters within the control phrase (loop header). So they may look different with other settings! The blue-boxed text in the full text area is the default text configured in the Structure Preferences. This will have been filled in here when you add a new FOR loop and decides which set set of form fields are presented. If your default control phrase is that of a traversing loop then the lower radio button with its corresponding form areas will be actie on opening the editor. (If your default phrase cannot not be classified (because it is neither compatible with the parser preferences of a counting loop nor with those of a traversing loop) then the result is undefined and the form fields are likely to show some strange tokens.
Remark: The assignment symbol displayed between the "Counter variable" field and the "Start value" will always be "<-", but on composing the control text line from the upper text fields the assignment symbol appearing in the text area might be ":=" instead if the default FOR loop content configured in the Structure Preferences represents a counting loop using the ":=" operator. (Both "<-" or ":=" are accepted as assignment operators by Structorizer - whereas a simple "=" won't.)

FOR loop separator procedence

Error Messages and Hints

The editor has a non-editable field where it may display some message if you happen to enter e.g. a non-integral value (or an expression) for the increment in full text mode, or if it detects some syntactically defective value list in case of a traversing loop. See the screenshots below for an example.

FOR loop with inacceptable step width

FOR-IN loop with incomplete value list

If you switch the loop style between counting and traversing loop via the radio buttons then in most cases the loop parameters filled in so far won't make sense anymore and will have to be discarded. To protect you against inadvertent data loss, the editor will raise a warning dialog allowing you to back off (cancel the change):

Warning dialog on altering the loop style

On changing from a counting loop with only constant parameters, however, the editor would convert it to an equivalent traversing loop, if the number of elements doesn't exceed a reasonable limit (currently 25). The example shows such a counting loop before altering the loop style...:

Counting loop with all constant parameters

... and thereafter:

Loop converted into a equivalent traversing loop

The conversion above is not reversible, i.e. the editor won't bother to find out whether a value sequence is a continuously enumerable integer interval. Actually, in most cases such a conversion would not be possible.

If you edit an existing FOR loop then the editor will automatically detect the style of your loop and present the parameters in the form fields. If the editor opens with "Full Text Editing" mode being active, however, then some discrepancy among the stored control phrase and a phrase generically composed from the contents of the form fields was detected.

Further Examples and Syntactic Possibilities

In the diagram below you see a counting FOR loop and several traversing FOR-IN loops (configured with keyword foreach here, but might also be for), even nested ones (green).

Demo diagram for different FOR loop types

As you may see, in addition to array variables and array initialisation lists, mere item enumerations (separated by comma or even blanks) are also accepted (yellow loops).

Obviously, a list consisting by design of a single element, as in e.g.

foreach elem in 23

doesn't make much sense since no loop would be required to apply the loop body (not shown here) just once to this only value.

If the collection part consists of a single variable, however, as in

foreach elem in some_variable

then there might be two possible readings:

  1. some_variable could be an array variable (like in the cyan blue loop above) and represent the collection, the elements of which are to be traversed, or
  2. some_variable itself might be meant to be the first and only element of a one-element list, such that elem would be assigned the entire object some_variable is containing, even if it happens to be an array.

Should the interpretation depend on whether or not some_variable is an array variable? No, because

Hence, the virtual ambiguity is simply overcome as follows: a single variable keeping the place of the value list is required to be an array variable and will be handled this way. If there are two or more variables, in contrast, then they will be treated as elements, i.e. as if they were enclosed in braces (like in the outer one of the green loops).

Hint: You may decompose a counting FOR loop into an equivalent sequence of an initialisation instruction and a WHILE loop, simply by means of the transmutation wand Magic wand icon for transmutation.

  

3.6. WHILE loop

A "WHILE" loop repeatedly executes a sequence of instructions - called its body - while a given Boolean condition holds. The logical condition is an entry condition i. e. it is tested each time before the body is going to be executed. If the condition expression is false on entering the loop element (the first time) then the loop body will not be executed at all.

The text to be filled in on adding a WHILE element is a Boolean expression, i.e. the logical condition. This may be a comparison, a variable with boolean content, or several conditions combined by logical operators (see more details under IF statement). Please note:
The default text can be modified under preferences->structures.

This is how you add a WHILE-Loop to your diagram:

1. Select the WHILE-Loop in the menu

Select the WHILE-Loop
 
2. Insert a condition (a Boolean expression)

Edit the WHILE-Loop 

3. Add instructions for the condition being true (can also be any other elements)

Add an instruction in the WHILE-Loop 

4. If you want more than one instruction executed the just add them after or before the first one

 Add an instruction After the first in the WHILE-Loop

5. If you want to add further instructions after the entire WHILE-Loop you must select the head first

 Add an instruction After the WHILE-Loop

6. This is what the finished version looks like

 Completed WHILE-Loop

Download Demo

  

3.7. REPEAT loop

The text of an element of type "REPEAT loop" is supposed to contain a Boolean expression (a logical statement) representing the exit condition of the loop.
A REPEAT loop will repeatedly execute a sequence of instructions - called its body - until the exit condition becomes true. If the condition is false when entering the loop element then the loop body will still be executed at least once.

Please note:
The default text can be modified under preferences->structures.

This is how you add a REPEAT loop to your diagram:

1. Select the element where you want to insert  the REPEAT loop, then click on the REPEAT loop button in the toolbar (or select the respective menu item in the context menu or Diagram menu):

Select the REPEAT-Loop
 
2. Insert a Boolean expression as exit condition

Edit the REPEAT-Loop 

3. Add instructions (or any other elements) to the loop body

Add an instruction in the REPEAT-Loop 

4. If you want more than one instruction executed as body then add them after or before the first one.

 Add an instruction After the first in the REPEAT-Loop

5. If you want to add further instructions before or after the REPEAT loop you must select the loop foot first:

 Add an instruction After the REPEAT-Loop

6. This is what the finished version looks like

 Completed REPEAT-Loop

Download Demo

  

3.8. Endless loop

An endless loop infinitely repeats the loop body - without a condition to enter or exit.

Hence an endless loop itself does not contain any text. (Though in former versions of Structorizer you could enter some text in the entry-mask, it was ignored and discarded. Since version 3.22-29, the text entry mask is disabled.)

You may, of course, add comments.

Endless loops in a way contradict the concept of an algorithm as an effective computation description that proceeds through a finite number of steps. Yet they may be useful e.g. in a context of machinery control. In order to make sense, an endless loop requires the loop body to be computable in finite time, of course.

By means of a Jump instruction you could possibly break out of an endless loop, but if there are predicatable circumstances instigating a leave, then it will always be preferrable to use a conditional loop instead.

This is how you may add an ENDLESS loop to your diagram:

1. Having selected the element before or after which you want to add an ENDLESS loop, press e.g. the respective toolbox button:

Situation on inserting an Endless loop element

2. Fill in some comment if you like (the upper text field is disabled).

Editor for the ENDLESS loop

3. Add instructions (or structured elements) to the body (cf. e.g. WHILE loop)

This might result in e.g. the following diagram (making little sense, of course):

Abstract endless loop example

A maybe more sensible but very abstract example of an endless control loop might be:

Abstract endless control loop

 

  

3.9. Call

The CALL element is quite similar to a simple instruction. The difference is, that the executed instruction is a call to a user-defined subroutine, usually represented by another diagram.

If you want to allow the Executor to perform a call referring to another diagram, however, the Call element should contain just a single line, either of the form

procedureName(value1, value2, ..., valueN)

or

variable <- functionName(value1, value2, ..., valueN)

Note that there should not be a blank between the procedureName or functionName and the opening parenthesis. The parameter list may be empty, but the parentheses must not be omitted.

Custom-routine calls embedded in complex expressions will not be supported. Likewise, the expressions specifying the argument values of the Call may contain arbitrary operators and built-in functions but no further custom-routine calls.

Here is a simple example for a CALL element (yellow):

Month length function with a function call

The called function is defined by another diagram (see Executor guide and Arranger page to learn how calls can be executed in Structorizer):

A callable function

On the Run Data Tracker manual page you will find a pretty complex bunch of routines co-operating in the task of sorting an array; the core algorithm there (quickSortRecursive) is a recursion example.

Recursion

If you want to write a recursive algorithm, you ought to place the recursive call into a CALL element as described above. Example:

recursive function, not working

Recursive function with correctly used CALL element
Though this diagram shows a fundamentally correct recursion,
it will not be executable in Structorizer because the CALL element (red) does not only consist of target variable, assignment symbol, and function invokation but embeds the function call in a multiplication.
This version of a recursive factorial algorithm decomposes the recursive branch into the assignment with the pure call on the right-hand side and a separate multiplication instruction. This way, Structorizer can execute it. (The expression n-1 as function argument is no problem.)

Instruction transmutation

If you happened to write a subroutine call into a simple Instruction element by mistake, then you don't need to delete the element, insert a Call element and enter the entire statement again. By clicking the magic wand button Magic wand (transmutation button) (with the Instruction element selected) you may transmute it into a Call element (with same content). This can also serve as an easy test whether the statement complies with the syntax rules stated above. (Otherwise the transmutation button simply won't work.)

  

3.10. Jump

The Jump element indicates some kind of exit from a loop, a routine or a program. It is not actually a means of structured programming, it rather contradicts the ideas of this concept. It can always be avoided (see example below), but may sometimes be a pragmatic and convenient way to formulate algorithms that otherwise would require some complicated workaround with logical variables, additional conditions etc.

You are not encouraged to use Jump elements, however.

While in former Structorizer releases Jump elements had no specific effect on execution (they worked like usual Instruction elements), from version 3.23-05 on the following types of "jumps" are supported both on execution and code export:

  1. Loop exit: an empty Jump element or a Jump element containing simply the keyword
    leave
    will just prematurely leave the closest surrounding loop (of any kind). If the Jump element is contained by several nested loops, then an instruction
    leave n
    (n being a positive integer) within the Jump element will exit from the innermost n loops, such that execution continues with the next instruction after the outer one of the left loops.
  2. Routine exit: To leave a routine (the current diagram) immediately, write
    return
    into the Jump element. This can also be used to return a result value. If you intend this just write an expression describing the result value or its computation after the keyword "result", e. g.
    return a * (b + 3).
  3. Program exit. The keyword
    exit
    allows you immediately to terminate the entire program, even from within a subroutine. An added integer value would be used as exit code, e.g.
    exit 17

Example for a conditioned Jump used to leave a For loop prematurely:

Exit from a For loop

Of course the Jump could easily be avoided by decomposing the For loop into a While loop (green and yellow elements) using both the negated condition of the alternative and the maxIterations limit as (re-)entry condition:

Loop avoiding a leaving jump

(Remark: Release 3.23-00 already supported type 2 on execution.)

Instruction transmutation

If you happened to write a jump statement of one of the supported kinds into a simple Instruction element by mistake, then you don't need to delete the element, insert a Jump element and enter the entire statement again. By clicking the magic wand button Magic wand (transmutation button) (with the Instruction element selected) you may transmute it into a Jump element (with same content). This can also serve as an easy test whether the statement complies with the syntax rules stated above. (Otherwise the transmutation button simply won't work.)

  

3.11. Parallel

What is a Parallel section?

The Parallel element is to represent a bunch of concurrent threads that are started at entering the Parallel element and waited for at the end of the Parallel element, i. e. the Parallel element is not left before all launched threads have terminated their respective algorithms. This way, the Parallel section contains a synchronisation.

How should a Parallel section be formed?

Whereas you may insert arbitrary instructions in the parallel branches, the usual practise is to represent the threads by subroutine calls. Some programming languages (and the StrukTex export) even expect the threads (branches) to be calls of thread functions of a certain signature. This makes sense since otherwise there would be a high risk of mutual impacts on common variables, leading to races, hazards and inconsistent results. (If the respective Analyser option is activated, you will get warnings on some obvious potential inconsistencies.)

Code export

Currently, for many of the code export languages there is a strategy to convert Parallel elements into working multithreading code, e.g. C++, C#, Java, Python, Perl, and bash/ksh. Usually, first worker classes or function objects are defined from the branches of the Parallel element, then for each of them a respective thread will be started, and after their termination has been awaited, variable values assigned inside the threads will be extracted from them for further use in the main thread. For target languages not supporting multithrading (e.g. for C there is no system-independent thread support in the standard libraries) or without accomplished generator support, the code export just serializes the branches of the Parallel elements but marks them with eye-catching comments, such that the user might try herself to find a concurrent solution.

Execution / Debugging

By the way, the Executor will not actually be able to run the threads in parallel. Instead, it will try to simulate concurrency by randomly choosing due instructions from the pool of still unterminated threads, but this will not go deeper than just the first instruction sequence level. Hence, loops, calls etc. will always be executed completely in sequential mode before the thread has to yield control to another waiting one.

How do you add a Parallel element, now?

1. Select the element before or after which you want to insert a Parallel element.

2. Click the respective item in the context menu or one of the toolbar buttons marked red in the image.

Recursive QuickSort before adding a Parallel element

3. When the Element editor opens, just write the number of parallel threads into the text field, no more, no less. Only a constant cardinal number will work here. For any kind of explaining text, use the Comment text area.

Editor for the Parallel section

If you edit an existing Parallel element then be aware that on reducing the number of branches the superfluous extra threads will automatically be removed. (So if you want to keep a backup of them, do it before. But you may of course undo the thread number reduction and hence the removal if you had forgotten to stash the thread contents.)

QuickSort after insertion of a Parallel section

4. Insert elements to the branches as usual - each branch behaves as an ordinary instruction sequence -, but keep the introductory remarks in mind: It is preferrable to let the threads be single subroutine calls each, like in the following recursive-parallel implementation of a QuickSort algorithm (for easier recognition, the two concurrent threads were dyed differently):

Recursive-parallel quicksort algorithm

  

4. Diagram

The editing of Nassi-Shneiderman diagrams can be done via menus, mouse actions, and keyboard actions. It follows usual conventions and is therefore practically self-explaining.

The affectable units of a diagram are the elements (i.e. the basic structures of any algorithm). Generally, elements may be selected by mouseclicks. Having selected an element, the selection focus may be moved around by pressing cursor keys (up, down, left, right) in an intuitive way (see yellow arrows in the image below). The vertical traversal path is closed to a ring i.e. if you go downwards from an element positioned at the bottom of the diagram (there are six of them in the image below though logically the big alternative as a whole is the last element of the diagram) then the selection will leap to the top element of the diagram etc. On going upwards or sidewards, the selection will always be fetched by the central adjacent element in the target direction if there are several of them. If substructure elements of an adjacent structured element are closer or as close as this then you will dive into the substructure first.

Move directions for the current selection

In order to extend a selection within the same block (meaning a vertical sequence of consecutive elements), you may press <Shift><Up> or <Shift><Down> key to include the next element above or below, thus forming a selected subsequence of the current block (see the green arrows in the image below). Alternatively, you may click - with <Shift> key pressed - on the element at the other end of the intended selection span. There is no possibility to add an element to the selection that is not part of the same block. The selection span can only be expanded but not be reduced. If you happen to have expanded the span too far, just start again by selecting the element at one end of the wanted span (with a single mouse click or by using cursor keys) and extending the selection in the way described.

Ilustration for the expansion opportunities

In order to extend the selection to the entire element sequence (block) the selected element is being part of, just do a mouse click with <Alt> key pressed (be aware that in many operating systems you may have to press the <Alt> key again to reset the Alt-activated state afterwards).

By the way: Pressing the <Alt> key shows the mnemonics for the main menu by underlining the respective letter of the menu caption. (Press <Alt> plus the mnemonic letter to open the respective menu via keyboard, then you can navigate through the menu by cursor keys). Note that version 3.24-10 modified the mnemonics in a language-dependent way such that e.g. the File menu is still opened by <Alt><F> with English or French ("Fichier") being chosen but no longer with e.g. German chosen, where <Alt><D> ("Datei") is to be used now. It is not always the initial letter because in some languages several menu captions may start with the same initial letter. As it is locale-related, it has become subject to the locale configuration by the new Translator tool (release 3.25).
Note that with JavaRE versions prior to 1.7 the mnemonic localization attempts will not work.

Double-clicking an element oder pressing the <Enter> key opens the editor for the selected element.

Pressing the <Del> button removes the currently selected element(s).

Nearly all changes to elements and their order are undoable (by <Ctrl><Z>, Edit menu, or speed button Undo button) and redoable (by <Ctrl><Shift><Z>, by <Ctrl><Y>, Edit menu, or speed button Redo button). The depth of the undo and redo stack is not formally limited. The undo stack is not cleared by saving the diagram, i.e. you may even undo changes already saved. You will notice when a sequence of undo/redo actions has reached the diagram state last saved again: The save button will then temporarily be disabled.

The subsections below give some detailed descriptions what operations can be applied to selected elements (or element sets). Also see section Key Bindings for a list of applicable key actions.

For algorithm-specific editing explanations, i.e. with respect to the different types of elements being insertable into a diagram, please consult the Elements section.

  

4.1. Add element

To add an element to the diagram, you proceed like this:

  1. Select an existing element or an empty block by clicking on it (or by traversing the selection via cursor keys to it).
  2. You have now four possibilities:

Notice: double clicking an empty block always inserts a new element of the type "instruction".

  

4.2. Edit element

In order to edit the content of an element, you can either double-click on it or simply select the element you want to edit and perform one of the following actions:

  1. Use the main menu: "Diagram" => "Edit";
  2. Right click the element and select "Edit" in the popup menu;
  3. Just click the <ENTER> key;
  4. Use the following speedbutton in the toolbar: .

Next, the editor window will pop up where you can change the text content of the element or its comment. Hit the "Cancel" button to cancel the action or the "OK" button to commit your changes.

Element editor with recent checkboxes and font resizing buttons

Each element (with some exceptions, see the respective Element description) provides two editable parts:

This is the actual content of the element. It is (normally) being displayed in the diagram. There may be syntactical restrictions for what the text part should contain, depending on the kind of the element.

This can be arbitrary text commenting the element's purpose or contents. Comments may be displayed in different ways, though, (see below). They are saved, exported to source etc. And they may even be the starting point for your algorithm design (see Switch text/comments).

The initial focus (input cursor) on opening the editor usually lies on the text input field (if available and editable), but when mode Switch text/comments is active then the focus will initially be located in the comment input field. Hence, the focus will always be in that area the contents of which are currently shown in the diagram.

The font size of the editable text fields can be raised or shrinked by the resizing buttons Pair of font-resizing buttons in the editor beneath the comment text field or by entering the respective key combination <Ctrl><Numpad+> or <Ctrl><Numpad-> (requiring the focus being within one of the enabled text input fields).

Some types of elements, FOR loops in particular, may provide a modified editor with differing layout and more or alternative input fields. See there for details.

In the editor window there are also two checkboxes where you may

Comment display in the work area

Usually the diagram won't show directly the element comments (unless you activate either "Switch text/comment" or "Comments plus texts" mode).

If an element has got a comment and the "Show comments" mode is active, however, then a vertical gray line is displayed near the left element edge, indicating that there is an inspectable comment. To take a look at the comment just let the mouse hover over the given element, this will pop up a tooltip showing the comment (see illustration below).

Display of the comment in

 

  

4.3. Remove element

In order to remove an element, you must first select the element you want to remove. Then you have four options:

  1. Use the main menu: "Diagram" => "Delete"
  2. Right click the element and use "Delete" in the popup menu
  3. Hit the key on your keyboard
  4. Use the following speed button in the toolbar:

If you want to reuse the element at a different place then you should cut the element instead, this leaves a copy in the local clipboard:

  1. Use the main menu: "Edit" => "Cut"
  2. Right click the element and use "Cut" in the popup menu
  3. Hit the key combination on your keyboard
  4. Use the "scissors" speed button in the toolbar:
  

4.4. Move element

In order to move an element up or down, you must first select the element (or the element subsequence) you want to move. Then you have several options:

  1. Use the main menu: "Diagram" => "Move up" or "Diagram" => "Move down",
  2. Right click the element and use "Move up" or "Move down" in the popup menu,
  3. Press key combination <Ctrl><Up> or <Ctrl><Down>, respectively,
  4. Cut an element and paste it into a new location. Refer to copy & paste instructions ...
  5. Use the following speedbuttons:

You can also simply drag & drop an element onto a new position. The dragged element will pe positionned after the drag position. If the elements implicated in the drag & drop are marked in green, the drag is possible:

If they are displayed in red, the drag is invalid:

 

 

  

4.5. Copy element

You can copy & paste (or cut & paste, see below) single elements or blocks inside a diagram by the usual ways.

In addition, you may copy an entire diagram (if the Root or main element is selected) to the system clipboard from where it may be pasted into an open Arranger.

In order to cut & paste an element (subsequence) use menu item "Edit" => "Cut", press <Ctrl><X> on the keyboard, or the speedbutton in the toolbar; also see Move element.

Note: The key <Ctrl> may be substituted by the default command key of your OS. For example Mac users must use the "apple key" ...

 

  

4.6. Colorize element

If you want to dye an element, you must first select it and then click on one of the following speedbuttons:

This feature was implemented in order to have the possibility to highlight, emphasize, or visually distinguish parts of a diagram.

For the above example:

If the colored element contains a Turtleizer statement then the element color may also have a functional effect i.e. it determines the color of the line drawn by the Turtle (where a white element background means a black line, however).

Remark: The colors in the palette can be customized via the "colors" preferences.

  

4.7. Collapse element

Motivation and usage

In order to regain overview in large diagrams you may collapse some elements, i.e. to minimize their size to a small instruction-like rectangle. This is not a modification of the diagram (and won't be saved) but only a display modification. Hence, collapsing won't be registered in the undo list, either.

To collapse an element (it makes only sense for area-consuming structured elements, actually) you first select it and then choose among the following possibilities:

Collapse / expand toolbar

To expand a collapsed element (i.e. to show it in its original size, shape and design again), select it and do one of the following equivalent actions:

In collapsed state, an element won't show any substructure, its colour will turn gray, and just the first line of its very own text will show, followed (or preceded in case of a REPAT loop) by an ellipse ("..."). Lest you should guess what element type it may be, all structured collapsed elements will present a little icon in their upper left corner:

A WHILE loop expanded and collapsed
NSD with expanded loop NSD with collapsed WHILE loop
The selected WHILE loop (yellow) is expanded The same WHILE loop is collapsed now (gray)

Note: Collapsing a structured element may change the displayed value of tracked run data or its representation but won't discard or modify the tracked data themselves.

Mouse Wheel Mode

In the "Diagram" menu you can specify what effect the mouse wheel is to have within Structorizer: If the toggle item Toggle for the mouse wheel mode is selected then rolling the wheel up or down will collapse or expand the currently selected element, respectively. Otherwise, moving the mouse wheel will scroll the Structorizer editor canvas vertically or (on most platforms), with the Shift key pressed, horizontally. A touchpad will work in the analogous way.

  

4.8. Transmute element

Overview

Version 3.24-13 brought a new user interface action in order to facilitate the editing of Nassi-Shneiderman diagrams: The function to transmute elements or sequences of elements into elements of a different type. This is particularly helpful to make e.g. a subroutine call or an exit work in the Executor or to merge or split several instructions in order to improve the diagram layout or to allow the setting of breakpoints between instructions that had formed a common Instruction element.

Only unstructured elements (Instructions, Calls, or Jumps), sequences of simple elements, counting FOR loops, CASE,and IF elements may be transmuted. Simple elements with a single line may change their type. Simple elements with several lines will be split, a sequence of simple elements will be merged. On merging, only if all elements are of the same type then the type will be preserved, otherwise the result will be "downgraded" to a multi-line Instruction. A FOR loop or a CASE element will be decomposed (see below).

Any transmutation may be initiated by the Transmute symbol (wand) button, by the respective menu item "Transmute" in either the Diagram or the context menu, or by the accelerator key <Ctrl><T>. These controls are only enabled if there is a suitable selection (see below).

The following table shows the available conversions depending on the current selection:

Possible transmutations
Selected Lines Prerequisites Result
single Instruction element 1 Call syntax CALL element (same content)
single Instruction element 1 Jump (Exit) syntax JUMP element (same content)
single Instruction element ≥ 2   Sequence of single-line Instruction elements (split)
single CALL element 1   Instruction element (same content)
single CALL element ≥ 2   Sequence of single-line CALL elements (split)
single JUMP element 1   Instruction element (same content)
single JUMP element ≥ 2   Sequence of single-line JUMP elements (split)
Sequence of Instruction elements     Multi-line Instruction element (merged)
Sequence of CALL elements     Multi-line CALL element (not excutable!)
Sequence of JUMP elements     Multi-line JUMP element (not executable!)

Mixed sequence of Instruction,
CALL, or JUMP elements

    Multi-line Instruction element
FOR loop   counting style WHILE loop with auxiliary instructions
CASE element     Nested IF elements (possibly with auxiliary assignment)
IF element   non-empty FALSE branch IF element with flipped branches and negated condition

All transmutations are undoable, redoable, and usually also reversible by subsequent transmutations (exceptions: FOR loop and CASE decomposition, failed comment splitting). The reversion of a mixed-type merge may require several steps because the splitting of the resulting multi-line Instruction won't directly reestablish the original types of the former contributors but leave a sequence of simple Instructions. These Instructions may then be transmuted back to Calls or Jumps, however, one by one if their syntax allows that.

Examples

As shown by the following figures, a single wand button click is sufficient to convert a multi-line instruction (with analyser complaints) into a sequence of instructions (and vice versa):

Selected multi-line Instructionleft and right wand arrowsSelected sequence of Instructions

Having selected the second element of the splitting result, another transmutation converts the instruction into a CALL element because it matches the syntactic requirements of an executable subroutine Call (see also Executor):

Selected single Instructionleft and right wand arrowsSelected single CALL element

 

The transmutation of a FOR loop (new with release 3.25) decomposes it into a WHILE loop with separate initialisation instruction and embedded incrementing/decrementing instruction. This operation is particularly sensible if an additional condition is needed to control the loop. And, of course, in order to demonstrate the equivalence of both constructs.

If the decomposed FOR loop was coloured then all substituting elements will inherit the same colour (see images below after separate transmutation of both inner FOR loops).

Note: In contrast to the cases above, there is no reverse transmutation (it is only undoable during the current session)! And there is no transmutation for traversing FOR loops (aka FOR-IN loops) by now.

Diagram with two FOR loopsTransmutation arrow (irreversible)Diagram with one of two FOR loops decomposed

The transmutation of a CASE structure (new with version 3.25-02) decomposes it into an equivalent set of nested IF statements. If the discriminator is not a variable but some kind of expression to be computed then an instruction element assigning its value to a generically generated variable is inserted before the outer replacing alternative. This way, repeated computation of the discriminating value is avoided, which does not only preserve performance but also consistence. The decomposition allows to compare not only with constant values (as are required by a CASE structure) but also with computed ones or against intervals. (Besides, the transmutation demonstrates the equivalence of the constructs and the elegance of a CASE structure in comparison.)

If the decomposed CASE element was coloured then all substituting elements will inherit the same colour (see images below - before and after transmutation of a CASE element):

Diagram with a CASE structure
Transmutation arrow downwards (irreversible)
Diagram with a decomposed CASE structure

An Alternative with awkwardly formulated condition (such that you would have to leave the TRUE branch empty - which isn't allowed) may easily be flipped, provided that the ELSE branch hadn't been empty (which would result in an illegal IF element with empty TRUE branch):

Selected alternativeleft and right wand arrowsFlipped alternative

At the current stage (i.e. version 3.26-05), the negation of the condition is not very intelligent (as to be seen in the example above, where n≥2) would have been a more sophisticated result), but at least a repeated negation won't blow up the expression with more and more encapsulating not operators. A later version may improve the logical inversion.

Handling of comments on merging, splitting, and decomposing

On merging instructions the transmutation mechanism tries to concatenate the comments of the combined elements in such a way that the resulting multi-line comment can be split and correctly re-assigned to the original instruction elements again. But note that this effort may be spoiled in the following cases:

If an unambiguous re-distribution of the comment lines is impossible on splitting then the first of the separated instructions will obtain the entire comment while the following elements will end up with an emptied comment.

The comment of a decomposed FOR loop is transferred to the replacing WHILE loop. The two created auxiliary Instruction elements will not inherit comments.

The comment of a decomposed CASE element will be inherited by the first of the replacing elements, i.e. either by the discriminator assignment (if inserted) or by the outermost Alternative.

  

4.9. Disable element

Since version 3.25-03 you have the opportunity temporarily (or permanently: it is an undoable diagram modification also saved to file) to disable elements in the diagram without having to delete them. Disabled elements will simply be skipped on execution, ignored by the Analyser, and will appear as outcommented sections in exported source files.

In the diagram they are shown with a hatched texture:

Diagram with disabled elements

To disable an element or an element sequence, select the elements and then you have these opportunities:

The same actions are used to re-enable selected disabled elements. If you select a subsequence of elements, wich are partially disabled then the above actions will turn all of the elements disabled first. The next action would enable all of them and so forth.

If you disable a structured element (e.g. a loop or alternative) then of course all contained substructure is automatically disabled as well - without being shown in hatched style:

Diagram with disabled structured element

This decision was made because

  1. it is consistent with colouring, selection, and execution highlighting and
  2. substructure elements can also be disabled individually (their disabled state would remain when that of the containing structure is lifted). This would be invisible otherwise. Of course it doesn't play a role as long as the superstructure is disabled (you cannot effectively enable an element, the superstructure of which is disabled).

(The decision might be revised in a later version if it should turn out to be less self-explaining than hatching all the substructure as well, which would require measures to inhibit invisible changes of the status of indirectly disabled elements, on the other hand.)

  

5. Features

Beyond being a mere NSD editor, Structorizer offers you several goodies to make more of the creation of Nassi-Shneiderman diagrams than just an unliked duty to document algorithms. It may really be something enjoyable as you will find out. Structorizer particularly addresses the need of beginners rapidly to achieve reassuring results.

See the details by inspecting the respective subsections.

  

5.1. Code generator

Structorizer allows you to convert your designed algorithm to several programming languages (among them Pascal/Delphi, Java, C, C++, C#, BASIC, Python) and even some script and shell languages.

To do so, select the respective menu item of submenu File => Export => Code. See Export for more details and Export Options for possible generator configuration items.

In most cases, however, you may not expect a flawless and instantly compilable or executable code. This wouldn't be feasible because a (more or less syntax-free) Nassi_Shneiderman diagram will usually not specify all details a specific language might require.

What you yet will obtain is an almost correct algorithmic skeleton that will have to be post-processed a bit manually to achieve a working program or routine. Typically, variable declarations will have to be provided, for instance. Or some algorithmic features like exit jumps or parallel sections may not be supported by the target language. "TODO" comments placed in the code will help the beginner in perceiving what is to be done to accomplish the output. This will already help the programming beginner a lot. And even experienced programmers who want to document their algorithms are spared a lot of duplicate work if they start with the Structorizer and then just export and adaptate the designed algorithm.

Please be aware that for many languages there are a lot of dialects out there. So it's not unlikely that the derived code may work with one system but cause errors with another. (However, if you think that the exported code serves too exotic a dialect and should better be replaced by a more compatible output, just contact the Structorizer team, please, and raise an issue, ideally giving a reference to the respective programming language specification or documentation. Possibly, some additional export options might be introduced to address diverging demands.)

  

5.2. Variable highlighting

Generally, all text in the diagram is written in standard font (black), but you may enable the option "Highlight variables?" in the menu "Diagram".

The name "Variable highlighting" doesn't quite exactly describe what this feature is doing, because it's not only variables that are emphasized. With this option enabled, Structorizer helps you to distinguish different syntactic categories and easier to keep an overview by highlighting certain names or literals in the instruction texts.

These are:

Besides optically structuring text, this highlighting may also give helpful indications of syntactical flaws that might cause trouble on execution or code export.

This highlighting makes only sense, of course, if you intend to fill in the diagram elements with nearly executable code. If you just write some comment-like plain text or e.g. shell code (which is syntactically incompatible with HLL conventions) you will prefer to switch this highlighting mode off (see Highlight variables?).

  

5.3. Analyser

The Analyser may check the current diagram for certain syntactical and structural deficiencies. The set of checks is configurable (see below). The analysis is done at live time and reports detected potential problems in the report area below the diagram work area. This happens pretty quickly but in order to save display time you may switch it off.

To enable or disable Analyser as a whole you may use menu item "Diagram" => "Analyse structogram?" or simply press <F3> (see Settings > Analyse structogram?). In the Analyser Preferences you may opt in or out specific rules of the analysis. See Analyser Preferences for a list and a short explanation of the rules.

The analyser report area is only visible while the Analyser is enabled. Simply drag the separating border vertically to tune the display ratio between the work area and the report list. (If you don't see the report area though you had enabled Analyser then try cautiously to drag the bottom border of the diagram area upwards into the Structorizer work ara. In very rare cases Structorizer may start with the report area occupying the entire place below the toolbar - then drag the upper border of the report area down to give the work area its share.)

When you see warnings in the report area, just click on one of the report lines to select and highlight the corresponding element in the diagram.

Diagram with Analyser reports

In the above example, you see three detected problems in the Analyser report area.

The first two of the messages refer to instruction 1: In the expression variable b is used, but its initialization hasn't been performed yet, it's following in an instruction executed later. For identifier c in the same expression no initialisation at all could be found anywhere (c is not bold in the diagram, therefore). The responsible rule for this kind of analysis is "Check for non-initialized variables". This rule also checks for variables the initialization of which may not necessarily be reached, e.g. because it is placed in a branch of an alternative or whithin a loop. Such cases are reported with a slightly differing message.

The third of the messages relates to the body of the FOR loop where a manipulation of the control variable i is tried, which is usally regarded as illegal (though some programming languages like C or Java allow such questionable ways to control the loop, e. g. to leave it prematurely; you may see them used even frequently). The responsible Analyser rule is "Check for modified loop variable".

Likewise, loops where the body has no obvious influence on the loop condition (such that an accidential endless loop may be supposed) may be detected via a different rule etc.

(As mentioned above, see Analyser Preferences for a list of available rules.)

Of course, you may neither rely on a "complete" analysis nor should you be sure that all messages are correct, i. e. there may be "false positives", since a structogram may neither be expected to adhere to strict syntactic rules nor is it possible at all to algorithmically decide certain semantic properties of an algorithm. (The undecidability of many interesting algorithm properties is proven!)

From version 3.24-15 on, Analyser will place a warning at the top of the Report List while mode Switch text/comments is active:

Switch text/comments warning in Analyser report

  

5.4. Turtleizer

The Turtleizer component allows you to move a small green turtle over a drawing canvas and let it draw something. On execution start, the background is white, the default pen colour is black, the pen is down and the turtle is visible and placed in the centre of the Turtleizer canvas (which has a default size of about 500 x 500 pixels).

API

You can use the following instructions (note that the type specifiers int and double only declare what number type the arguments are expected in or coerced to, the type specifiers are not to be inserted into the instructions, of course):

forward(double pixel)

fd(int pixel)

Make the turtle move some pixels forward (see notes below), drawing a line segment if pen is down.

backward(double pixel)

bk(int pixel)

Make the turtle move some pixels backward (see notes below), drawing a line segment if pen is down.

right(double angle)

rr(double angle)

Rotates the turtle to the right by some angle (in degrees!).

left(double angle)

rl(double angle)

Rotates the turtle to the left by some angle (in degrees!).

gotoXY(int X, int Y)

gotoX(int X)

gotoY(int Y)

Sets the turtle to the position (X,Y).

Sets the X-coordinate of the turtle's position to a new value.

Sets the Y-coordinate of the turtle's position to a new value.

penUp() The turtle lifts the pen up, so when moving no line will be drawn.
penDown() The turtle sets the pen down, so a line is being drawn when moving.
hideTurtle()
Hides the turtle.
showTurtle() Show the turtle again.
setPenColor(int red, int green, int blue) Set the default pen colour to the given RGB value (range 0...255 per argument). This colour is used by undyed move commands.
setBackground(int red, int green, int blue) Set the background colour to the given RGB value (range 0...255 per argument).

Please note that:

In order to execute an algorithm containing some of the Turtleizer procedures listed above you must have pressed the button Turtleizer launch button to open the Turtleizer window first. This will automatically open the Executor Control panel as well. While the Turtleizer window is open it will then be sufficient just to invoke the Executor Control panel via button  for another start. Without the Turtleizer window being open, the Turtleizer procedures won't be recognised and will cause errors on execution attempt.

Example

The following algorithm draws a little hut with base hight and width from input with a triangular roof (having a right angle at top):

DrawHut algorithm

The drawn image with width = 200 and height = 100:

Turtleizer window with drawn hut

Diagram code change helper (Turtle with a Archimedian spiral,Turtle with a rectangular spiral)

If you want to study the consequences of the pixel coercions with an integral coordinate model in comparison to the floating-point coordinate model or if you happened to use the brief command names in earlier diagrams but want to change to the floating-point model, then two new menu items Turtle with a Archimedian spiral and Turtle with a rectangular spiral in the "Edit" menu will help you:

Turtle with a Archimedian spiral replaces all occurrences of the Turtleizer procedures fd and bk within the selected element range by forward and backward, respectively;

Turtle with a rectangular spiral does it the other way round (i.e. replaces forward by fd and backward by bk).

If you select a structured element, say a loop, than all directly and indirectly contained instructions are involved, not so instructions in called subroutines, however. In order to convert all instructions of the entire diagram at once, simply select the framing program or routine element. These instruction replacements may also be induced by key bindings <Shift><G> and <Ctrl><G>. They are fully undoable and redoable.

A preliminary check whether the selection contains any relevant Turtleizer instructions at all is done to prevent you from inducing void undo or redo entries. After the conversion, a message box will pop up, telling you how many replacements were done.

  

5.5. Executor

Preliminary Remarks

The executor is that part of Structorizer that tries to interpret and execute a diagram. It is available e.g. via the "Debug" menu introduced as such with version 3.25-11:

Debug menu with the Executor item selected

Please note, that Nassi-Shneiderman (NS) diagrams are designed to be free of any syntax. In order to "execute" an NS diagram, however, you have to stick to some kind of syntax. For the same reason, not all diagrams nor all contained structures can be interpreted. The executor has been added to allow beginners to easily catch and understand control structures and execution flows. Over the time, however, several enhancements and accomplishments have made it a lot mightier than originally planned.

Inevitably, there are still some shortcomings and restrictions on several structure types, e. g.:

Overview of the remaining subsections of this manual page:

Launching Executor

To launch the executor, you may use the menu item "Debug" => "Executor ..." (see above) or click on the following toolbar icon: . This will pop up the Executor Control panel (the functions of which will be described in section "Executor Control" further below):

Executor Control dialog

If your algorithm contains Turtleizer-specific subroutines, however, then you must click on the Turtle icon in the toolbar or select the menu item "Debug" => "Turtleizer ..." instead (unless the Turtleizer window is already open): Icon Turtle.

Note: You cannot close the control panel by the operating-system-typical close button (e. g. the top-right red 'X' in Windows, see image above, or the red traffic-light button in OS-X). It is inactive, because too often the control was unintensionally closed during execution, this way potentially losing control of the execution (if it just hides the panel) or unwillingly aborting execution (if it destroys the panel). So it was disabled, eventually. Instead, the control panel will automatically close on execution termination (unless Run Data Tracking is active), thus also on pressing the Stop button button. You may iconize the control panel in the usual way though.

Supported Syntactic Elements

Elements from Java and Pascal

As the executor is Java-based, it should understand most Java commands. Besides this, it has been designed to work with basic Pascal syntax.

Reference tables

Here are the (not necessarily complete) lists of usable operators and built-in functions:

Supported operators
Symbol Alternative symbols Description (iff = if and only if)
<- := Value assignment (including automatic variable declaration)
+   Addition or positive sign (or string concatenation as in Java)
-   Subtraction or negative sign
*   Multiplication
/   Division (effect depends on operand types: with two integer operands, it results in an integer division)
div   Integer division (among integer operands, as in Pascal)
mod % Modulo operation among integer operands (i. e. results in the integral division remainder)
= == Comparison operator (true iff both operands are equal)
<> !=, ≠ Comparison operator (true iff both operands differ, displayed as ≠)
<   Comparison operator (less than)
>   Comparison operator (greater than)
<= Comparison operator (less than or equal to, displayed as ≤)
>= Comparison operator (greater than or equal to, displayed as ≥)
and && Logical AND (true iff both Boolean operands, e.g. comparisons, evaluate to true)
or || Logical OR (true iff at least one of the two Boolean operands evaluates to true)
not ! Logical negation (true iff the Boolean operand evaluates to false)
xor ^, <>, !=, ≠ Exclusive OR (true iff exactly one of the two Boolean operands evaluates to true)
<< shl Leftshift operator: m << n results in the integer value where all bits of integer m were shifted left by n
>> shr Rightshift operator: m shr n results in the integer value where all bits of integer m were shifted right by n

Operator precedence rules are similar to those of Java or C for the executor. That means that e.g. logical oprators like and have lower precedence than comparison operators. But be aware that this does not necessarily hold for languages like Pascal, which have much less priority levels, such that e.g. the and operator ranks like multiplication above comparison operators. Hence, an expression like

a = 3 and b < 5

may work perfectly in the Executor but will be illegal in exported Pascal code! So better use parentheses to avoid ambiguity (the code generators can hardly read your intentions):

(a = 3) and (b < 5)

 

Built-in functions
Function Description
abs(x) absolute value of number x; |x|
min(x, y) minimum of numbers x and y
max(x, y) maximum of numbers x and y
round(x) nearest integral number to number x (result is of an integral type)
ceil(x) smallest integral number greater than or equal to number x (result is of a floating-point type, though)
floor(x) greatest integral number less than or equal to number x (result is of a floating-point type, though)
sqr(x) square value of number x; x * x
sqrt(x) square root of number x (illegal if x is negative)
exp(x) exponential value with the Euler number e as base and x as exponent: ex
log(x) natural logarithm (i. e. based on the Euler number e) of number x
pow(x, y) computes x to the power of y (where x, y, and the result are floating-point numbers): xy
cos(x) cosine of x where x is to be given in radians
sin(x) sine of x where x is to be given in radians
tan(x) tangent of x where x is to be given in radians
acos(x) arcus cosine of x (inverse cos function) where x must be between -1.0 and +1.0
asin(x) arcus sine of x (inverse sin function) where x must be between -1.0 and 1.0
atan(x) arcus tangent of x (inverse tan function), result will be in radians (as with asin, acos)
toRadians(x) converts angle x from degrees to radians
toDegrees(x) converts angle x from radians to degrees
random(n) returns an integral pseudo-random number in the range between 0 and n-1
length(s) returns the number of characters the string s consists of.
length(array) returns the number of elements the array consists of.*
lowercase(s) returns a string representation of string s where all letters are converted to lowercase
uppercase(s) returns a string representation of string s where all letters are converted to uppercase
pos(sub, s) returns the first starting position of substring sub within string s (position >= 1 if any, otherwise 0).
copy(s, i, n) returns the substring of string s that starts at character postion i (i >= 1) and has at most n characters
trim(s) returns the trimmed string s, i.e. without leading and trailing whitespaces
ord(c) returns the ASCII code of the character c (or of the first character of string c)
chr(n) returns the ASCII character coded by number n
isArray(value) returns true if the argument is an array*
isString(value) returns true if the argument is a string*
isNumber(value) returns true if the argument is an integral or floating-point number*
isChar(value) returns true if the argument is a character*
isBool(value) returns true if the argument is a Boolean value*

* only from release 3.26 on

Built-in procedures
Procedure Description
inc(v, i) increments variable v by number i; equivalent to: v <- v + i
dec(v, d) decrements variable v by number d; equivalent to: v <- v - d
randomize() is to re-initialize the pseudo number generator used for random(n)
insert(w, s, i) inserts string w at character position i into string s (i >= 1)
delete(s, i, n) removes the next n characters from position i out of string s (i >= 1)

 

File API subroutines (Release 3.26)
Procedure / Function Description
fileOpen(path: string): int opens a text file for reading,
returns a file handle (see below)
fileCreate(path: string): int creates a new file for writing
(may override an existing one),
returns a file handle (see below)
fileAppend(path: string): int opens a file for writing at end
(preserving the previus content),
returns a file handle (see below)
fileEOF(handle: int): boolean returns true if the input file is exhausted
(no more characters readable)
fileRead(handle: int): object returns the next readable data
as int or double value, flat array, or string
(see below)
fileReadChar(handle: int): char returns the next readable character (see below)
fileReadInt(handle: int): int returns the value of the next integer literal
if the next token is an integer literal
(see below)
fileReadDouble(handle: int): double returns the value of the next integer literal
if the next token is an integer literal
(see below)
fileReadLine(handle: int): string returns the (remainder of) the current line
without the newline character
(which is yet consumed, see below)
fileWrite(handle: int; value) Writes the given value to the file
without adding any separator character
fileWriteLine(handle: int; value) Writes the given value to the file
and appends a newline character
fileClose(handle: int) Closes the file identified by the handle (see below)

 

Turtleizer subroutines

There are some more built-in functions and procedures, which are only usable within a Turtleizer execution context, however. See the respective user guide page for details.

Custom subroutines

In addition to the practically fix set of built-in functions and procedures listed above, you may also execute available subroutine Nassi-Shneiderman diagrams as functions or procedures. But whereas the built-in routines may arbitrarily be used as part of appropriate expressions in instructions, branching or loop conditions, this does not hold for custom subroutines represented by an NSD. Their execution will only work if placed within a Call element (and it must adhere to a very flat syntactical restriction, moreover). In order to be found on execution, custom subroutine diagrams must have been parked in the Arranger before (unless it's a recursive call, then it finds "itself" in the Structorizer). If Executor doesn't find a called subroutine, the execution will abort with an error message like this:

Output text window with CALL error message

If custom subroutines are executed as top-level diagrams for debugging purposes, then the Executor will simulate the call by asking the user for the value of every argument (as if there were an input instruction) and will present the result value in a message box (or a scrollable list view, if the result value is an array).

Arrays

Structorizer supports the use of one-dimensional arrays.

They may be introduced in two ways:

1. Element-wise assignment

As soon as you write an assignment or input instruction and append square brackets with an index expression to the target variable name, the variable will be made an array variable:

names[2] <- "Goofy"

INPUT x[0]

The index range of arrays starts with 0. If you assign something to an array element with larger index than used before, the array will automatically be enlarged up to the new index. If there are index gaps, then the elements inbetween will be filled with 0, e.g. in the first example above, the resulting array names would be filled as follows: {0, 0, "Goofy"}. Note that a reading access with an index larger than the highest index used for assignments or input before will abort the execution with an error message.

2. List initialisation

You may initialise an array variable with a list of element values, enclosed in curly braces (like in C, Java etc.):

values <- {17, 23.4, -9, 13}

friends <- {"Peter", "Paul", "Mary"}

Version 3.24-10 introduced the opportunity to provide such an expression even in the text input field of an executed input instruction, this way making the input variable an array variable:

Input dialog, filled with an array initialisation

Actually, it is not necessary (though highly recommendable for the processing algorithms), that all elements of an array be of the same type.

Array variables may be passed as arguments to a subroutine (mechanism is call by reference, i.e. changes to the array content will be propagated to and seen by the calling algorithm) and may also be returned as result by a routine.

Array variables as a whole may not sensibly be put into the expression list of an output instruction (you would end up with a cryptic text like "[Ljava.lang.Object;@a8328"). If a subroutine exeuted at top-level returns an array, however, then the array contents will be presented in a scrollable list view. This allows separate testing of subroutines requiring some of its parameters to be an array (on top-level execution, parameter values are asked for interactively, and the input of a value list in curly braces provides an array, see above) or returning an array.

Array variables or braced value lists (aka array initialisation expressions) are the natural things to be used as collections in FOR loops of the FOR-IN variety, see the FOR loop user guide page for details.

The following NSD shows some advanced examples of executable and exportable array operations:

Several ways to work with an array

You may even put entire arrays as elements into other arrays (see fifth instruction in the example diagram above, where one of the elements for array2 is the previously filled array named array). This way, it's possible to construct something similar to a multi-dimensional array, but you will not be able to apply a list (or cascade) of indices to the outer array immediately, say a[i,j] or a[i][j]. Instead, you would have to assign the array held as array element to a simple variable first, e.g. b <- a[i], and may then apply the next index to this variable in order to get to the nested element: b[j].

File I/O (Release 3.26)

The API for working with text files was introduced on user request with release 3.26 and allows to store values as well as to produce and analyse text files with Structorizer. And of course to demonstrate the handling of resources that are controlled by the operating system.

After having opened a text file via one of the opening functions fileOpen, fileCreate, or fileAppend, the respective file can be accessed via the obtained "file handle" (which in fact is an integral number > 0 if the acquisition of the file was successful). Negative results of an opening attempt or 0 stand for some kind of failure and do not entitle to any kind of file access. After having worked with a successfully acquired file, on the other hand, it has to be released by means of procedure fileClose.

See File API for a detailed description and several examples.

Executor Control

When having pressed one of the buttons or Icon Turtle, the Executor Control panel will pop up (see the figure near the top of this page). Here its details will be described.

"Player" buttons

The most important controls are the four "player" buttons in the fourth row, having the following effect (from left to right):

When having started with button "Run", the execution will terminate in one of the following cases:

  1. The last instruction of the algorithm is reached and has been executed.
  2. A Jump element with an exit instruction has been executed.
  3. A Jump element with a return instruction has been executed and the currently executed diagram is at top level.
  4. The Stop button has been pressed.
  5. A syntax or execution error has occurred.

The execution will pause (i. e. may be resumed) on one of the following events:

  1. Execution was carried out with the Step button.
  2. The Pause or Step button was pressed during execution.
  3. A breakpoint (see below) is reached.
  4. An input instruction is executed and the user pressed the "Cancel" button in the popped-up input dialog.
  5. An output instruction is executed and the user pressed the "Pause" button in the popped-up display dialog.

Some activities (like Call Stack display) are only possible in paused state. You resume execution via the "Run" or "Step" button.

Execution delay

Delay control

With the slider in the top row you may control the execution delay between the instructions (for better observation). Whereas the mouse handling is rather rough, you may use cursor keys (left / right) for fine-tuning the delay value by steps of 1 while the slider is selected. If you reduce the delay to 0 then some displayed information (like variable values, execution counts etc.) will not be updated unless you press the "Pause" button or the algorithm reaches the paused state due to one of the other events described above.

Output mode

Output control

The second row provides a checkbox "Output to window" allowing you to specify how output instructions are executed: Whereas in versions before 3.24-07 output instructions had always popped up a message box, now all output (and input) will always be directed to a console-like text window (see section "Output Console Window" below). You may either show this window permanently, thus switching off the message box activation (such that you are no longer forced to confirm every single output event) or hide it and stay with the traditional message box popping. Since the output is always logged to that console window, it is possible to inspect the entire output history of the program execution by selecting he checkbox even after having executed the algorithm in the traditional mode (checkbox not selected). You may possibly have to open the Executor Control again to do so, because it usually closes after execution has terminated. Some examples are given in the section "Output Console Window" further below.

Run data tracking control

Run Data Tracking control

The third row provides a checkbox and a visualisation mode choicelist for Run Data Tracking. The checkbox on the left-hand side enables the tracking mode, the choicelist modifies the kind of element highlighting in dependency of the purpose of the analysis. The controls are partially disabled while execution is ongoing. See the Run Data Tracking page for details.

Call stack display

CallStack control

The fifth row shows you the current subroutine call level on the right-hand side: Every Call instruction the execution dived into increments the subroutine level by one, on returning from a called subroutine (and thus leaving the pending Call element) the subroutine level is decremented. The top level (program level) is 0. Note that built-in functions or procedures don't affect the displayed subroutine level; only called Nassi-Shneiderman diagrams have an impact. In paused execution state, a click on the "Call Stack" button will pop up a scrollable list view showing the current content of the Call Stack (see section "Call Stack" below). Note that in versions prior to 3.24-14 there hadn't been a "Call Stack" button. Instead a double-click on the displayed Call depth value opened the Call Stack list view - this worked only in paused execution state.

Variable display

Variable display

The lower region of the control panel is occupied by the variable display. As soon as a new variable is introduced, a new line will be added with the variable name in the left column and a string representation of its current value in the right column. These are the three ways to introduce a variable in structorizer:

  1. as parameter of the (currently executed) subroutine, e.g.: function(var1, var2)
  2. as target of an assignment instruction, e.g.: var <- expression
  3. as target of an input instruction, e.g.: INPUT var

Whenever execution pauses (see above), you may double-click into a field in the right column of the variable display and edit the value for testing purposes (make sure to commit the change, see below!) or have a look at the farther-right elements of a large array exceeding the column width. When you resume the execution, the algorithm will continue with the modified value(s). But before you resume make sure to have clicked somewhere outside the edited value field or to have pressed the Enter button in order to commit your change. (If you just inspected e.g. a long value then press the escape key to leave the editing field without committing changes.)

Animation

The currently executed or paused instruction is highlighted in light orange background. Compound elements with pending execution, i.e. nested components of which being currently executed (or paused), are highlighted in a faint yellowish tinge. So you may easily follow the execution progress (see image in next section).

Within Parallel elements, already passed parts of the threads are also marked with the yellowish tinge; because of the randomly leaping execution you would otherwise hardly be able to tell how far the different threads may have been proceeded.

Additionally, in Run Data Tracking mode, elements already passed by one of a series of performed test executions can be highlighted in bright green. Alternatively, elements may be highlighted in a spectral colour range depending on their execution count or the number of involved "atomic" operations. This colouring is lower prioritized than the above mentioned highlighting for the current execution status (currently executed element and structured elements with pending execution completion).

The speed of the animation is controlled by the delay slider in a range between 0 and 2000. The default is 50.

Breakpoints

Version 3.22-29 introduced breakpoints to the Executor feature: You may place breakpoints on as many elements of your diagram as you like. Execution will pause as soon as an element with breakpoint is reached (for possible actions in paused state see above).

To set or remove a breakpoint select the respective element and now either right-click and select/unselect menu item "Breakpoint icon (in menus etc.) Toggle breakpoint" in either the "Debug" or context menu or double-click and select/unselect the checkbox "Breakpoint" at the bottom of the element editor. Alternatively, you may press accelerator key <Ctrl><Shift><B>.

Debug menu with active element-related items

In the diagram, a breakpoint is shown as a horizontal red bar at the top of the element frame (except for Repeat loops, where the red bar will appear between loop body and exit condition, sensibly):

Diagram stopped at a breakpoint

If you place a breakpoint on a loop (For, While, Repeat) then the execution will pause every time the loop condition is going to be checked again.

Note that you can't place a breakpoint on an Endless loop (since it hasn't got any means of control). You may place a breakpoint on the first element of its body instead.

Release 3.25 enhanced the breakpoint model by introducing conditioned breakpoints: You may specify an execution count value that is to trigger the breakpoint on going to be reached. That means while the element hasn't been executed as often as specified, the breakpoint won't get into action. Only when (on entering the element) its current execution count exactly equals the specified trigger value minus one (such that it would draw level with it on completion), the breakpoint will go off. Note that this kind of breakpoint will only have an effect in Run Data Tracking mode (otherwise the execution events aren't counted). Conditioned breakpoints are shown as a dotted red line, and their trigger value will - coloured in red - precede the run data numbers as shown in the T(RUE)-branch in the folowing screenshot:

Element with conditioned breakpoint just triggered

A trigger value of 0 specifies an unconditioned breakpoint as described before.

Since a conditioned breakpoint won't fire again after the (non-zero) trigger count has been exceeded, you are allowed to modify the trigger value whenever the execution is paused. To do so for a selected element you may use the menu item "Specify break trigger..." in menu "Debug" or in the context menu, or just enter the key combination <Ctrl><Alt><B>:

Context menu item for breakpont trigger control

Wenn you toggle off the breakpoint then its trigger value won't get lost but is preserved for later re-activation.

To switch off all breakpoints all over a diagram at once press the speed button Icon of the toolbar button to clear all breakpoints in the toolbar or the respective menu item "Clear breakpoints" in the "Debug" menu.

Note: Breakpoints are not saved to file. Nor are setting, modifying, or removing a breakoint actions inducing an entry in the undo or redo stack. However, any undoable (substantial) change to a diagram will be associated with a snapshot of all currently set breakpoints, such that on undoing a previous diagram modification the former breakpoint status would be restored. The same holds on redoing undone modifications.

Output Console Window

As mentioned in section Executor Control above, you will open a text window logging all done output and input if you select the "Output to window" checkbox. While unchecked, the window is just hidden but still exists and gathers the texts printed during execution in the background.

The new output text window for Executor

On starting execution, any previous content is deleted, an automatically generated line names the executed program (or top-level routine) and shows the starting time. Conversely, on terminating an execution a similar line with the termination time will be displayed (see image above).

There is no way to input or edit something in the logging window. Input instructions will always be carried out via an interactive question box, but both the automatically generated prompt text and the input will be reflected here (the former in yellow colour, the latter as green text for better distinction). The regular output produced by the algorithm output instructions is shown in white colour. Every output instruction induces a new line:

Output Console with input prompts and input

With checkbox "Output to window" not being selected, the window will just stay hidden while output instructions will (additionally) pop up message boxes in the traditional way. With "Output to window" selected, you actually suppress the output message boxes and bring the logging window to display. With an algorithm generating a lot of output, this mode will significantly accelerate the execution and relieve you from the necessity to confirm every single output.

You may change the output option at any time during or after an execution without losing the window content. It can be reactivated by unselecting and re-selecting the "Output to window" checkbox.

Closing the output window will not destroy its content.

From version 3.25-03 on, the font of the output window may be changed by menu or via the + and - keys of the numpad:

Properzies menu on the outpout console

Execution errors will also be logged in red colour to the output text window after having popped up as error message box. See an example in section "Custom subroutines" above.

Call Stack

As mentioned in section Executor Control above, you may display the call stack (makes only sense with diagrams containing - possibly nested - CALLs, of course). The Call Stack window is opened by clicking the button "Call Stack". (In versions prior to 3.24-14 you had to open it by double-clicking the displayed "subroutine level".) To show a Call Stack requires a begun execution (of a diagram contaning CALL elements) being currently paused (e.g. by pause button or breakpoint or in step mode).

The top line always represents the innermost call (i.e. the currently executed subroutine call), the bottom line stands for the main program or top-level routine. Here are some examples for call stack views (from version 3.24-14 on, the call level indices are shown at the line beginnings for better orientation):

Displayed Call stack for a QuickSort solution 

Scrollbars are automatically added when required, e.g.:

Call stack view with vertical scrollbar

Wide Call stack display with horizontal scroll bar

  

5.6. File I/O API

File I/O Fundamentals

A file is a resource administered by the operating system (OS), situated in the file system and identified there by a file path. A program that is to work with some file will have to observe the following mandatory phases:

  1. Opening of the file for the intended access type (read / write);
  2. Access to the content according to the requested access type;
  3. Closing of the file as soon as access is completed.

More precisely, it is by no means certain that the opening attempt will succeed such that a failing must always be taken into accont. So it's worth to remember the following abstract algorithmic schema for dealing with files inside a program:

Fundamental algorithm template for working with files

The yellow elements are the auxiliary instructions and tests dealing with the resource acquisition and release, the green element is the actual file processing, the red element is the error path.

Look in the Executor page for a table of the file routines made available for Executor with release 3.26.

Opening a file

Consequently, a program or routine must first request a file from the OS for a certain purpose (reading or writing) before it can work with it. Structorizer offers three different opening functions - one for reading access (fileOpen) and two ones for writing access (fileCreate and fileAppend):

Any of the three opening routines returns an integer value, which in case of success serves as program-internal identifier and file handle for all the access operations you may perform with the opened file. Numbers greater than zero are valid file handles whereas numbers less than or equal to zero signal that the open attempt failed:

You should always test whether you obtained a valid handle by the applied opening function! If you obtained a positive number (i.e. a valid file handle) then you may apply the appropriate file-related functions or procedures, always providing the file handle as first argument. Any of these subroutines are illegal if the file handle is 0 or negative or if it was not obtained by an opening function, if the kind of access doesn't match or if the associated file has already been closed inbetween.

Closing a file

As soon a s you don't need to write or read to/from a file any longer you should make sure to close the file using procedure fileClose (with the file handle as argument). This releases the file as resource and - in case of a file opened for writing - flushes the associated buffer, ensures the file consistency in the file system, and thus makes the file available for other processes and applications. Only after having closed the file you may be sure that the data are persistently stored in the file system.

Once you have closed a file, the handle value gets stale, i.e. it cannot be re-used for file operations. Even if you reopen a file that you have used before you will obtain a new, different handle. The procedure fileClose must not be applied a second time to a file aleady closed.

Reading from a file

You can only read from a file if it had been opened by means of fileOpen before and you must use the file handle obtained from fileOpen as routine argument. These are the available reading functions:

Since reading beyond the end of the file raises an error, it will generally be a good idea to check the "end of file" property of the file being read. This is done by function fileEOF, which returns true if the file end is reached and false otherwise. Use see its use in the examples at the end of this section.

Writing to a file

You may only write to a file if you obtained a valid (i.e. positive) file handle from one these two opening functions: fileCreate or fileAppend.

Examples

The following examples may illustrate how to work correctly with files:

1. FileWriteDemo just writes text / values obtained via an input instruction to a file, separating all values by a space character (which is the "natural" separator for reading tokens from a file) until the user enters a single '$' sign. This will result in one long line of text in the file. The failure path is empty, but you might insert an output instruction with an error message (see example 6 below).

Demo how to write values to a file

2. FileReadDemo goes the opposite way: It opens a text file and reads tokens (substrings separated by white space) from it - one per loop cycle - tries to interpret them as numbers or by default strings and writes the interpreted values to the output one by one. Be aware that the values read may not be equivalent in number and type to the expressions you wrote into that very file. E.g. a written non-quoted string with spaces will be split to the "words" on reading the file, and each of thes "words" (tokens) will independently be checked for literal syntax, such that a written string These are 4 words will be read as four values, three of which (the 1st, 2nd, and 4th) being strings, one (the 3rd) being an integer value.

If the file contains quoted strings i.e. several words, the first of which starting with " and the last of which (within the same line!) ending with ", then this sequence will be read as one string, the quotes being dropped.

If the file contains comma-separated tokens between curly braces, e.g.

{23, 7, -9.8e4, "something"}

then at least the attempt to convert this into an array will be made.

With this respect, you may find the new built-in test functions isArray, isNumber, isString, isChar, and isBool helpful in order to be capable of making use of the values read from file.

Demo how to read data from file

3. FileDoubleDemo:This algorithm relies on the assumption that the text file consists of several white-space-separated character sequences inerpretable as floating point numbers, e.g.

4.5 -98.0e5 7
12   10293

It reads the values from the file as double values into an array and then writes the array elements to the output. A token not interpretable as number will abort the algorithm.

Demo for reading double values from fil into an array

4. FileReadCharDemo: This algorithm reads the input file given by the requested path character by character (including all whitespace characters otherwise ignored!) and writes both its graphcal reprsentation and its decimal code to the output stream.

Demo how to read single characters from file

5. FileAppendDemo: This algorithm tries to open a text file for writing but does not clear its previous content but appends the interactive user input as additional lines to its end. The user may end the loop by leaving the text input field empty.

Demo how to use the fileAppend function

6. FileCopy: The last diagram example demonstrates how to copy a text file line per line. The cyan elements are related to the source file, the green elements refer to the target file. The red and pink elements are the error paths for the opening attempts.

Demo to copy a text file line per line

Code export

Efforts were made to enable the code generators of Structorizer to produce a more or less sensible equivalent of algorithms using the Structorizer File API routines in the target code. With some languages a relatively simple transformation could be found, for others (e.g. C++, C#, Python) a static object class "StructorizerFileAPI" emulating the Structorizer File API may have to be inserted into or attributed to the resulting code where an in-place substitution was not feasible. The Java export just adds some private static methods to the resulting class itself.

Very different types of file handles or an exception-based function concept made it utterly difficult or even impossible to concoct some halfway compatible test for success or would require to redesign the entire context of the algorithms.

The code export to the shell script languages bash and ksh had to capitulate to the completely different paradigm of handling files, where you would have to redirect standard input or output to text files. File output can be done by sporadic echo appending to the target file (echo $value >> $filepath) but input can only be done in one single loop because there is no explicit file descriptor keeping a reading position between sporadic access attempts.

Therefore, a full (100 %) semantic equivalence may not be expected, not even with high-level languages, though their file concepts are roughly comparable.

Release 3.26 still not offers export solutions for Oberon and BASIC. Approaches may be added by later versions, though.

  

5.7. Run data tracker

Motivation

Once an algorithm is designed, several questions arise: Will it work? Will it always produce correct results? Are there redundant parts? Have my tests covered all possible cases? What about the performance, is it acceptable, is its functional dependency on the "problem size" within the predicted bounds? If we consider to optimize the code, where should we begin?

Analysis tools tracking run-time data during the execution of an algorithm can help answering many of these questions.

That's why Structorizer now offers several specific visualisation options for the analysis of the algorithm behaviour and the test strategy.

Testing is an important approach to validate an algorithm. An essential criterion for a systematic and exhaustive white-box test is so-called code coverage, i.e. ensuring that every single path of an algorithm has been passed at least once.

Besides the meticulous planning of a minimum set of necessary data tuples (input + expected output) to achieve this, a convenient way to prove and demonstrate that all paths have actually been executed (covered) by the driven tests is necessary.
The latter is where Structorizer comes in: Run Data Tracker is a new feature (due with version 3.24-01) within the Structorizer Executor being able to demonstrate the completeness of a set of tests.

Entering the Run Data Tracking Mode

To activate the Coverage tracking, invoke the Executor:

The new Executor Control

There are a checkbox and a choice list for the kind of visualised data in the third line on the Executor Control panel:
[v] Collect Runtime Data: switches the Tracking on (or off).

The checkbox is only enabled between tests, never during an execution, no matter whether being running or paused. For the availability of the choice list on the right-hand side, only the checkbox "Collect Run Data" must have been checked. (That means you can switch the type of presented data during the test, the selected visualisation has no impact on the collecting of the data. See "Freedom of Choice" further below.)

Note: When you unselect the check box, however, then any collected data are immediately erased and all run-data-related highlighting is switched off. Hence, if you just want to suppress highlighting without stopping the tracking and keeping of run data then select visualisation mode "no coloring" instead.

If the Run Data Tracker is enabled it cumulatively collects and counts several data about the execution of the Elements. You have then the opportunity to visualize different aspects of the collected data. These are:

Since the range of the latter two annotation types may be huge (from 0 to many millions and more), both a linear and a logarithmic scaling is selectable.

According to the visualization type selected, the colouring of he elements changes live during the execution. So you may follow what happens. The delay glider allows you to slow down the process sufficiently to follow the changes or to reduce delay in order to get faster to the results.

While Run Data Tracking is active, two numbers (counters) will appear and increase in the upper right corner of each element, separated by a slash. The first number represents the execution counter, the second one is the number of local (or aggregated) atomic operations commanded by the element. Their meaning and difference is explained in more detail further below.

Test Coverage

If you choose shallow test coverage or deep test coverage in the choice list on he right-hand side, then all elements performed at least once during the recent series of executed tests will be highlighted. The highlighting colour of these "test-covered" elements is a brilliant green:

Partially covered square root function diagram

Partially covered function diagram, currently pausing at the breakpoint (execution markup is prioritized over coverage markup).

Coverage Rules

The rules are quite straightforward:

A subroutine marked by Arranger

A subroutine diagram in the Arranger window marked via the "Set Covered" button (in red box).

Be aware that the coverage mark around the diagram is only visible within one of the coverage visualisation modes. In the Arranger index, however, the respective icon Arranger index icon for test-covered functionsindicates this state with all visualisation modes, provided the Run Data Tracking is enabled.

Remarks

Coverage marks are not stored when saving a diagram to a file. Neither are the count values.

Editing a diagram will clear all collected run data and marks, but the numbers are cached in the Undo list. So when you undo the changes then the previous coverage state is restored and allows you to continue with that constellation.

Complex example

The following three images show phases of a code coverage analysis with Structorizer. The main program is a test frame (diagram at lower right corner in the Arranger window) for a recursive QuickSort algorithm with several nested subroutines (diagrams arranged in the remaining Arranger window area). The first image shows a running test (be aware that there are several "open" subroutine calls at different levels at the same time, recognizable by the orange element colour), the remaining two images show the situation after some more executed tests.

Test Coverage mode shown in Arranger 1

Test Coverage mode shown in Arranger 2

Test Coverage mode shown in Arranger 3

After this last phase in deep mode, all subroutines are completely covered. This does not hold for the test program "SORTIERUNG_RAHMEN3" because the sorting algorithm always worked correctly such that the alert branch (with the pink output instruction) has never been passed. In order to provoke an inversion (i. e. a sorting mistake) detection, routine "QuickSort" might be replaced by a dummy (with same name but not actually sorting) before the next test. This would accomplish the coverage.

Execution Counts (or Transit Counts)

The first one of the two small counts in the upper right corner of the elements represents the number of times the element has been passed during the tests. (All elements with execution counts larger than zero are "test covered", at least in the shallow meaning.) The execution count does not increment before control flow has left the element.

If you select execution counts in the display choice list then the elements will be coloured according to that first count number in a spectral range from deep blue to hot red, where deep blue stands for 0 and hot red for the highest count value over all the involved diagrams.

The following image shows a NEWTON algorithm (used for the computation of square roots), here after the calculation of the square root of 25:

Execution count highlighting for NEWTON algorithm

As you can see, the WHILE loop was entered and left only once but the loop body had to be repeated 6 times. So 1 is the smallest and 6 is the highest existing count, and there is nothing inbetween. Hence, only two colours occur. (And since within the range of 0...5 a step of 1 is relatively rough, the blue isn't that dark as one might have expected with value 1.)

This analysis shows e. g. where a code optimisation would be essential if possible (red areas) and where it would not be worth to be considered (blue areas).

Done Operations Count

The second one of the two small numbers in the upper right corner of an element represents the "atomic" operation count (right-hand side of the slash).

If you select done operations lin. or done operations log. then the tinging of the diagram elements is done by either linear or logarithmic scaling of the number of "atomic" operations, respectively. The logarithmic scale is more sensible if the range of the numbers is very widely spread.

The difference between execution count (number of element transits, see above) and the number of "atomic" operations an element is directly responsible for becomes clear with the following image only differing from the above situation by the focus of visualisation (where the linear scaling was chosen):

Done operations during the calculation of square root of 25

As you may see, here the WHILE loop turned red, too. This is because now every single condition examination counts as an operation (thus costing time). In order to perform the loop body 6 times, the condition has to be examined 7 times (once on first entering the WHILE element, then after each loop execution i. e. before the next iteration, amounting to 7).

Hint: Sometimes users are puzzled by alternatives showing a high count on the condition but very low operation counts on both branches. This situation will typically occur if one of the branches is empty - an empty element doesn't carry out anything, so it's instruction count will always stick to zero! (But look at the transit count in such a case!)

Counting Rules

The operation counters for the different kinds of elements are:

If an element is passed several times then of course the values above may multiply by the number of enterings, as you see with the simple instructions forming the loop body.

Note that these counts do not include the counts of the substructure elements. It's only the own contribution of the respective element itself. Only the program (or function) element, i.e. the outer frame, shows the aggregated number of operations performed within the entire program / routine. Therefore the parentheses around the count. The colouring of the program / the routine, however, does not reflect the aggregated number but is based on the net operation count which is used to be zero (deep blue in the above image).

From this colouring you may learn where most of the time is consumed.

With recursive or otherwise deeply nested algorithms, the numbers show the time distribution on the top level (or the current level, on interruption) only.

If you collapse a structured element, then its displayed number of operations will increase by the operation numbers of the contained elements - as if they were melted together. The tinge of the element will not change, however.

So for the WHILE loop in the example above this would mean a number of 7 + 6 + 6 + 6 = 25. In this case (as the loop elements are flat instructions), it would be the number also presented by the following aggregated mode.

Total Operations Count

If you select one of the visualisation modes total operations lin. or total operations log. then the tinging of the diagram elements is done by linear or logarithmic scaling of the aggregated number of operations, respectively, i.e. the count of structured elements also recursively includes the counts of their respective substructure. The logarithmic scale is more sensible if the range of the numbers is very widely spread.

The aggregated operation numbers on structured elements will be enclosed in parenthesis to remind that these are composed data.

Newton algorithm with emphasised aggregated operation counters

On collapsing elements, the number won't change of course (it just loses its parenthesis), nor will the colour.

This mode is fine to visualise the hierarchical aggregation and load distribution - it is all calculated already. The program element tells you the overall number of (fictitious) unit operations to accomplish the computation and may serve as an estimate for time complexity if you find the functional relation to the number or size of data to be processed.

Complex Example

Again, the colouring shall also be demonstrated with the complex example of a recursive quicksort algorithm with several nested routine levels.

QuickSort with execution count analysis

Recursive QuickSort algorithm composed of several subroutines, in Execution Count mode

QuickSort with logarithmic operation count mode

Recursive QuickSort algorithm composed of several subroutines, in local Done Operations mode

Freedom of Choice

Once a run data tracking has begun you may freely switch among the different visualisation modes, export the coloured diagrams to different graphics formats, print them, arrange them, etc. until you unselect the checkbox "Collect Run Data", in which case all collected data are cleared and the display returns to standard mode.

As already stated for the test coverage mode, however, saving a diagram inits native file format will not store any of the gathered results. So if you want to document the results, you must export the diagram(s) as a picture.

 

  

5.8. Arranger

Purposes

The Arranger is a component chiefly serving three purposes:

How to open the Arranger?

There are three different ways to open the Arranger:

  1. By executing the following command from the system shell (or by starting a shell script with this content), providing the Structorizer directory is the working directory:
    java -cp Structorizer.app/Contents/Resources/Java/Structorizer.jar lu.fisch.structorizer.arranger.Arranger
    In this case, the Arranger will start with an empty drawing area (see below how to push diagrams into the Arranger) and will play the role of the master of all Strucorizer instances initiated from here.
  2. By pressing the Arranger button (Arranger tool button) in the toolbox or the "Arrange" item in the "File" menu of Structorizer. In this case, the currently edited diagram will be pushed to the Arranger. As a side effect, the Arranger will be associated with the Structorizer. The Structorizer remains the master of the Arranger and of further instances of Structorizer possibly launched from the Arranger in turn.
  3. By loading (or dragging) an arrangement file within Structorizer. In this case, too, the loaded diagrams will be associated to the Structorizer instance and be pinned.

Arranger with two diagrams

How to put diagrams into the Arranger?

There are several possible ways to put a diagram to the Arranger:

  1. Press the "New Diagram" button in the Arranger toolbar (see image above) to add an empty new diagram to the drawing area. To fill in content, just open a new Structorizer instance by double-clicking the diagram. Now you can edit the diagram in the usual way. All changes you perform will immediately be reflected within the Arranger canvas.
  2. Select one or more NSD files (e.g. in the respective GUI file manager of your operating system), drag the selection into the Arranger area, and drop it here.
  3. While working on a diagram with Structorizer, press the Arranger tool button tool button or menu item "File -> Arrange". This way, Structorizer and Arranger will nearby be associated, and all manipulations with the diagram will be synchronized to the Arranger. The diagram will automatically be "pinned" (see image), which protects it against replacement in the Arranger when the diagram is replaced in the Structorizer.
  4. Press <Ctrl><C> in an open Structorizer instance while the entire diagram is selected in order to copy it to the clipboard and then press <Ctrl><V> in the Arranger window to paste it here (cf. Copy Element).
  5. Load a stored arrangement (see next subsection).

Arranger Index

As soon as diagrams are placed in the Arranger, the Structorizer GUI (of all associated Structorizer instances, to be more precise) will show a scrollable index of the diagrams currently held by the Arranger just right of the work area (see green box in the screenshot below, only from version 3.25-10 on):

Arranger index shown for the Eliza project

The list presents the signatures (name + number of arguments) and file paths of all diagrams arranged in the Arranger pool, ordered by type (main programs first, then subroutines) and signature. Diagrams with unsaved changes are marked with an asterisk before their names (see "conjugateStrings(4)" in the screenshot above).

By clicking on one of the lines (or by pressing the <space> key), the Arranger will scroll to the referred diagram, bring it to top drawing level (if partially eclipsed by others) and highlight it.

Double-clicking one of the lines (or pressing the <Enter> key) will fetch the related diagram and let it replace the one that had resided in the work area before. If the diagram to be replaced has unsaved changes then you will be asked whether to save the changes first.

By pressing the <del> key you may remove the selected diagram from the Arranger surface (and from the index, of course). If the diagram was held by some dependent Structorizer instance then this Structorizer instance may close.

A context menu (see screenshot below) offers the three actions described above as well. In addition, you may switch on or off the "test-covered" flag of the selected diagram, if the Run Data Tracker is active and the diagram is a subroutine (also see Setting Diagrams Test-covered). The icon border of diagrams marked as test-covered will turn green in that mode (see screenshot above).

Arranger index with context menu

You may reduce or enlarge the width of the Arranger index viewport simply by moving the divider rightwards or leftwards. From version 3.25-11 on, you may hide the Arranger index entirely by unselecting the menu item "Diagram => Show Arranger index?". Alternatively, you may also toggle the index visibility with keystroke <Shift><F3>.

Diagram work area, Arranger index, and Analyser report list form a focus ring where you may navigate by the <Tab> key in clockwise and by <Shift><Tab> in counter-clockwise direction.

Saving / restoring Arrangements

Via the button "Save List" in the Arranger toolbar you may save the current diagram arrangement for later re-use. You have two options:

  1. To create a simple text file with name extension ".arr" containing just the file paths and window positions of the arranged diagrams (but no diagram content!) in CSV format. This is a lean output and intended for local use where the referenced nsd files stay in place. (Of course, the arr file might be edited manually to adapt file paths of the referred diagrams if necessary.)
  2. To store a compressed archive with name extension ".arrz" comprising an ".arr" file as mentioned above plus copies of the ".nsd" files of all arranged diagrams. Such an archive is portable to another computer and will exactly conserve the state of the moment of saving. The paths inside the archive are relative such that it can be extracted anywhere (see below).

After having pressed the "Save List" button a message box will pop up and ask you whether you want to "Save as portable compressed archive?" Press the "Yes" or "No" button if you opt for alternative 2 or 1, respectivley.

To restore a diagram arrangement from such a saved file press the "Load List" button and select either an ".arr" file previously saved or an ".arrz" archive. The file load dialog offers file filters for both types. The ".arr" filter is pre-selected but you may switch the filter.

Note: you might replace the file name extension of an ".arrz" file by ".zip" and use some standard compressor tool to "unzip" it. Thereafter you may load the extracted ".arr" file the way described above. This will work while the corresponding nsd files reside in the same directory.

Pinning Diagrams

As mentioned in section "How to put diagrams into the Arranger", a diagram that had been pushed from a Structorizer instance into the Arranger will reflect all changes the moment it is edited, selected, executed etc. If the diagram is "unpinned" then this dependency even includes replacement, i.e. if you load a different diagram in Structorizer then the related diagram instance shown in Arranger would also be replaced synchronously. To avoid this, diagrams may be "pinned" in the Arranger (select the diagram and then press the "Pin Diagram" button). The pinned mode is indicated by a blue pin icon in the upper right corner of the diagram. For convenience, the pinning is automatically done on pushing diagrams from Structorizer to Arranger. The "Pin Diagram" button actually toggles the pin status, i.e. to "unpin" a pinned diagram just press the same button.

Setting Diagrams Test-covered

There is a button Arranger button to mark subroutines as covered "Set Covered", introduced to support the feature Run Data Tracker. (The button is shown in disabled state in the screenshot above.) While the test-coverage tracking mode is activated, you may flag a subroutine diagram parked here as "fully test-covered" such that routine calls to this diagram would immediately be marked as covered even in "deep tracking mode" (see Run Data Tracker) whithout having to wait until the routine code will actually be covered completely by repeated tests. To withdraw the "test-covered" state just press the "Set Covered" button again - Arranger will simply ask you for confirmation before to make sure you didn't touch it by mistake.

From release 3.26 on, the Arranger index in the Structorizer main GUI also allows to toggle the test-covered status of selected diagrams.

  

5.9. Translator

As you probably know, Structorizer is available in different languages. Before release 3.25 people in charge of realizing these translations had to deal with rapidly growing text files, manually to sort out what strings they had already translated and what new strings were to be cared about and they had even to tweak Structorizer in order to test their work.

Since release 3.25, Structorizer integrates a new component called "Translator". It allows easily to edit the different translation strings and highlights what work has already been done (i.e. all differences from the locale delivered with the product version) and which translations are still missing.

Besides this, you may switch to another language to check other translations. Finally, this new component allows you to test, thus to preview your current translation, which makes testing a lot more user-friendly than it had been before.

Translator 3.25

Its usage is pretty straightforward. If you want to contribute to the localization, start the Translator from the Structorizer file menu and select the language you are interested in by the respective flag button.

Then you will be presented the translation contents in several chapters selectable by the tabs:

Each of the tabs (except the Header tab) shows you a scrollable table of three columns:

  1. Key string (dot-separated hierarchic sequence of component identifiers or numbers, possibly followed by a bracketed condition);
  2. English translation (as far as available);
  3. translation in the selected language (as fas as available) - this column is editable.

Highlighting colours:

On selecting a row, the background colours vary to emphasize the selection.

Changes are cached but not automatically saved to file. As soon as a language set contains at least one modification, the respective language button will show green background, therefore. So it is easy to stay in control and keep track for what languages there are unsaved changes. (With some look and feels, however, this button colouring may hardly be detectable. You may try with a different look and feel then, controlled by the look and feel preference of Structorizer.)

As mentioned above, you may arbitrarily switch to another locale (e. g. for comparison) without losing your changes, simply by pressing the respective language button. If you click on the language button of the very locale you are currently working on and there are cached modifactions for this language then you will be asked if you want to discard the changes. If you agree then the original locale will be reloaded. If you decline then nothing will happen (the button action will be cancelled).

On closing the Translator, however, you will be warned if there are unsaved changes for some of the languages. You better save them before. If you reopen Translator without having closed Structorizer, however, the changes may still be present. Caution: You won't be warned of unsaved Translator changes when you close the owning Structorizer (i. e. the entire application)!

To preview the modifications in the currently running Structorizer, press the "eye" button in the toolbar (see image above).

In order to save the translations of a language including all cached modifications for it into a file, make sure the respective language is selected (look e. g. at the header of the third table column) and then press the save button - it's the rightmost button of the toolbar, showing the usual floppy disk symbol. (You might have to enlarge the window to access it, cf the image above where only a section of it is visible.) A file selection dialog will pop up and allow you to choose a target folder and - if wanted - a differing file name. If you happened to conduct modifications for several languages then each translation file must be saved separately. After having saved the changes, the associated language button colour will not return to the default button colour (usually some shade of gray) but turn pale green, indicating that all changes will stay cached. This way, you may continue modifying the translations without having to begin from start. Any new modification will turn the button background to bright green again, of course.

You may (re-)load saved translation files for a locale into Translator in order to resume with the result of a previous session. To do so hold the <Shift> button down while you click on the appropriate language button. This will switch to the respective locale and open a file selection dialog allowing you to choose a translation file for the selected language from the file system. The translations found in this file will be loaded into Translator (for the selected language). All differences to the original locale will be highlighted as if they were just edited (see description above). The heading of the last (third) column (in every tab) will show the file path together with the locale name, e. g. "es (/usr/home/mickey/language_files/es1.txt)". If there had been unsaved changes for the selected locale before you clicked the button then Translator will first ask you whether you want to discard them (which is prerequisite for - or side-effect of - loading the file); by declining you cancel the loading action (nothing will happen).

Be aware that Translator does not check whether the loaded file actually belongs to the selected language or not. If not, then nearly all entries are likely to be marked as changes, of course.

Note: With release 3.25, the structure of several keys has changed. Further releases might do so as well. So if you load a file originating from an earlier Structorizer version you may see several regions highlighted in red i.e. as deletions whereas some translations may not be displayed though present in the file, which is due to the effect that some translations couldn't be associated anymore. If you know what you ar doing, a manual modification of the keys in the text file may help to avoid losses. (But if it's a lot of added text being eclipsed then you might also send the outdated file to the development team, i.e. bob@fisch.lu, to let us sort it out - we know the mappings, of course.)

Note also that saving a translation file does not mean that your local Structorizer installation would automatically use your modified translations from now on! You may force Structorizer to use a modified language file explicitly, however, by choosing the "[ ? ] From file ..." menu item in the language preferences menu: The path of the loaded file would even be kept in the structorizer.ini file and hence automatically reloaded on the next start - until you select another language.

As already stated in the introduction, however, the Translator tool is chiefly meant to facilitate the maintenance and usability improvement of the Structorizer product. So the best you can do is to send an accomplished translation file in after having tested it by the preview tool) as requested under the IMPORTANT note in the header part of each translation file. (Don't forget to add a description of your changes to the Revision list section of the Header chapter.)

Last, but not least, you may create a translation file for a "new" idiom - meaning a language not having been provided so far by the language preferences. To do this, simply press the "?" button in the toolbar instead of one of the flag buttons. This way, you may start a completely new translation from scratch, i. e. with an empty third column. Just fill in the Header chapter appropriately, i.e. specify the language and yourself as author etc., and send the file in after completion. The Structorizer team will be grateful for your help.

  

6. Settings

The settings are (in their majority) related to diagram properties or modes to display diagrams and therefore available in the lower part of the "Diagram" menu. Additionally, some of them can be controlled by toolbar buttons, accelerator keys, context menu items etc.

  

6.1. Type

Diagram menu with diagram type items selected

Structograms can be devided into two categories:

Main programs are drawn with square corners whereas sub methods are drawn with rounded corners. Depending on the type of diagram you chose and whether your diagram is boxed or not, the diagram is drawn differently.

The type of a diagram can be chosen via the menu or by using the speedbuttons:

The following table resumes all cases by giving an example:

Type Speedbuttons Diagram
main, boxed
program boxed
main, not boxed
program un-boxed
 sub, boxed
routine boxed
 sub, not boxed
routine un-boxed

Note:

  1. The type of the diagram (main or sub) usually influences the source code generator and may thus result in different code.
  2. Only diagrams of type sub are callable, i.e. may be employed by the executor if referenced in a Call element (also see Program/Sub).
  3. As visible in the images above, the heading of an un-boxed diagram will appear in gray whereas the box of a boxed diagram is white (unless being selected or marked as test-covered, of course).
  

6.2. Boxed diagram?

This setting influences the way the diagram is drawn. Boxed diagrams are somewhat larger because there is a special box drawn around the inner elements. Non-boxed diagrams are reduced in size, obviously.

The heading of an un-boxed diagram is gray whereas the box around a boxed diagram is white:

program, boxed  program, un-boxed 
Boxed diagram  Un-boxed diagram 

For further details about this, please look here...

Whether diagrams are presented in boxed or un-boxed style has no impact on execution or code export.

  

6.3. Show comments?

Normally, the comments added to the elements are not visible in the diagram, unless you open the editor for an element or activate mode "Comments plus text".

Mode "Show comments" makes comments visible on demand and therefore induces two effects:

To enable / disable the comment mode use the menu item "Show comments?" in the menu "Diagram":

Diagram menu with Show comments? selected

A completely different way to show comments is mode "Switch text/comments?".

  

6.4. Comments plus text?

From release 3.25 on, a new display mode "Comments plus text" allows you to render, print, and export diagrams with the elements showing both comments and texts at the same time:

Diagram presented in

The comments are written in somewhat smaller font above the actual element text. Of course they enlarge the diagrams. Due to the triangular form of Alternative or Case element headers, the impact of including large or many comment lines may be optically desastrous. Therefore, in both Alternative and Case elements only the first line of a possible comment will be displayed (with an added ellipse "..." if there are more lines). Be aware that you still can popup the full comment if you have activated the independently usable mode "Show comments?".

The mode "Comments plus texts" can only be switched on or off via the menu "Diagram" where the "settings" are placed in the lower half:

 

Diaram menu with comment options

Note that activating mode "Comments plus text" disables the display mode "Switch text/comments" and suppresses its effect until the mode "Comments plus text" will be switched off again (by toggling the menu item). A previous setting of "Switch text/comments" remains preserved, though. The disabled menu button will only show a tooltip explaining what do do in order to reactivate the controls of "Switch text/comments".

Here are some more examples of diagrams in mode "Comments plus "text":

Unboxed diagram in mode Comments plus texts

Diagram with comments and text being shown

  

6.5. Switch text/comments?

Mode "Switch text/comments" just swaps the visible content of the diagram elements: Where usually the instruction text is displayed now the comments of the elements are shown, whereas the actual element content is only popped up while the cursor hovers over the respective element (provided, mode Show comments is active).

Motivation

Algorithm design may start with the structure and just some verbal specification of what is roughly to be done in the instruction block or loop etc. And this rough sketch is later to be refined by more formal expressions.

If the refinement replaces (und hence drops) the specifying descriptions they would get lost. Instead they might serve as useful comments and to compare the implementation with the specified intension. They would have to be copied from the text field to the comments field in the refinement phase, which is feasible but cumbersome. So why not start with them as comment in the first place? Well, because the diagram would look bare and empty until the "real instruction code" be filled in:

Leerer Algorithmusentwurf, da Kommentare nicht sichtbar

And that's where the "Switch text/comments" mode fits in. You can enable/disable it in the "Diagram" menu:

Diagram Menu with emphasised Switch option

(Note that the menu item may be disabled. This will be the case while the mode "Comments plus text" is active, which has priority.)

In mode "Switch text/comments", the diagram elements display their comments instead of the "code" text. So you can design and document an algorithm just based on the informal comments:

Recursive QuickSort function in comments mode

This comments display mode documents the design at an abstract level, and all the information will stay in place (i.e. in the comments sections), even after the actual code had been filled in (to the text sections). Thus it will remain reproducible whenever you "switch" to this mode again.

You can edit the elements where both text and comments are available in the editor forms, specifying the code details. When you are done (or whenever you like) you may switch to normal mode in order to see the "implementation":

Implemented recursive QuickSort function

Thus you may switch between both modes whenever you want, according to the emphasis you put on.

Impacts on other functions

The "Switch text/comments" mode sensibly modifies the way mode Show comments works: If both modes are combined, the comment indicator bars will show where there is already an implementation and the code (text) will pop up while the cursor is hovering over an element.

On opening an element editor (see Edit element) it depends on the "switch text/comments" mode whether the initial focus (the cursor) will be in the text area or in the comment area - it's the one presented in the diagram (with rare exceptions).

From version 3.24-15 on, the Analyser will present a warning in the Report List while the "Switch text/comments" mode is active such that unexperienced users won't panic if they see an empty diagram:

Analyser report list with

  

6.6. Highlight variables?

Generally, all text in the diagram elements is written in standard font (black), but you may enable the option "Highlight variables?" in the menu "Diagram". This does not only highlight variable names, but also operator symbols, string and character literals, and certain keywords (also see page Variable highlighting in the Features section and page Parser Preferences):

Diagram menu with highlight option selected

Alternatively, you may press <F4> to toggle the highlighting mode.

Here is an example for the effect:

 

standard diagram versus highlighted diagram

 

You will find further examples throughout this user guide and, of course, in practical use - it's quite straightforward.

  

6.7. DIN?

The German Institute for Standardization defined in DIN 66261 the appearance of Nassi-Shneiderman diagrams. Use this option to turn on a DIN-conform representation.


This setting only affects the "FOR-loop", because it's the only element where the default representation differs from the DIN-66261 representation.

FOR diagram according to DIN

 

FOR diagram not according to DIN

 

  FOR loop in accordance with DIN 66261    
  (check "DIN?")

   FOR loop not in accordance with DIN 66261
   (uncheck "DIN?"; default)

 

Also note the appearance of different menu icons depending on the setting.

Icons For-Loop in not-DIN mode

Icons "FOR-loop" when checked "DIN?"

 

Icons For-Loop in not-DIN mode

Icons "FOR-loop" when not checked "DIN?"

 

Note: You can move freely between the settings. A diagram drawn in one mode will immediately switch to the other mode by changing the setting. This is no modification of the diagram itself but only of its representation.

  

6.8. Analyse structogram?

In menu "Diagram" or by pressing F3 you may disable or enable the Analyser feature, which performs a live analysis of your diagram with respect to syntactical, structural or certain semantic issues:

Diagram menu item Analyse

In the Analyser Preferences you opt in or out specific rules of the analysis. See Analyser Preferences for a list and a short explanation of the rules.

  

6.9. Show Arranger index?

The visibility of the scrollable Arranger index introduced by version 3.25-10 may be switched off or on via the menu item Diagram => Show Arranger index (from version 3.25-11 on):

Menu Diagram with Show Arranger index selected

If enabled then the sorted index of all currently arranged diagrams will appear aside the work area unless the Arranger doesn't contain any diagrams or the Structorizer instance isn't associated (i.e. doesn't listen) to the Arranger:

Structorizer with Arranger index enabled

See the Arranger index section on the Arranger manual page for details how to work with the Arranger index.

  

6.10. Mouse wheel for collapsing?

In the "Diagram" menu you can specify what effect the mouse wheel is to have within Structorizer:

Diagram menu with mouse wheel mode item emphasised

If the toggle item " Toggle for the mouse wheel mode Mouse wheel for collapsing" is selected then rolling the wheel will collapse or expand the currently selected element, otherwise rotating the mouse wheel will scroll in the Structorizer editor canvas vertically or (on most platforms), with the Shift key pressed, horizontally.

(A touchpad will work in the analogous way.)

  

7. Preferences

Structorizer may be customized in several ways: You may modify the text font, the set of selectible element colours, the dialogue language, the default contents for the elements, redundant (or decisive) keywords for different elements, code export options, and the look and feel. See the subsections for details.

Usually the settings of the Preferences menu are automatically saved into a configuration file (structorizer.ini) located in your profile when you leave Structorizer. Modfifications to some preferences, however, may immediately trigger the saving of all preferences, e. g. whenever you commit changes in the export option dialog.

You may force immediate saving by menu item Preferences => All preferences... => Save:

Preferences sub menu All preferences...

In certain contexts it may be desirable to change entire configuration sets frequently. To facilitate this, you have the possibility to save the current configuration to a specific file of your choice by menu item:

Preferences => All preferences... => Save to file...

In order to reload saved settings later from one of these individual files, use item

Preferences => All preferences... => Load from file...

If you decide to import preferences from an ini file then it will also contain parser preferences, and these might differ from your recent settings. If some diagrams are being open then they are likely to get stale. To avoid this, Structorizer versions 3.25-02 and beyond will identify parser preference changes, show you the replacement list, and offer you to refactor your diagrams i.e. to adapt them to the new set of parser strings. This might look like in the screenshot below:

Refactoring question after having loaded a preference file

The image shows the Analyser warnings in the report area of Structorizer, which are due to the lost correspondence between used and loaded keywords, and it shows the question box listing all parser preference changes. Obviously, you may select among the refactoring of:

  1. no diagram,
  2. just the currently edited diagram, and
  3. all open diagrams (i. e. including those parked in an associated Arranger, not of course all diagrams stored in your file system).

(The dialog will not pop up if the current diagram is empty and no other diagrams are in the Arranger pool or if no parser preference changes were detected.)

Having pressed one of the buttons "current diagram" or "all diagrams", the resulting diagram(s) would become fully functional again. e.g.:

Refactoring result after after having loaded a preference file

If you refactored diagrams by mistake or you happen not to be pleased with the outcome then you may simply press the "Undo" button to restore the original text. If you had opted to refactor all diagrams then the refactoring of every single diagram may be undone (and redone) independently. Just fetch the respective diagram from the Arranger into the Structorizer work area.

  

7.1. Update search

From version 3.25-09, Structorizer offers an automatic notification of new downloadable versions. We think, however, that applications should not inadvertently connect to some internet site without being enabled to by their user.

This is what this preference is good for:

Preferences checkbox menu item

By activating the checkbox item "Notify of new versions" you allow Structorizer to request the version number of the most up-to-date Structorizer release downloadable as "latest version" from the Structorizer home page http://Structorizer.fisch.lu.

If the retrieved version number is newer than the one of your currently running Structorizer then a message box informing you on this newer version and where to obtain it from will pop up after Structorizer start:

Update dialog with new version indication

Actually, this is the same dialog being opened from menu item Help => Update ... .

Likewise, on opening the dialog associated to menu item Help => About... a hint will be shown in case a newer version is available if the preference "Notify of newer version" is active:

About dialog with version notification

If you deselect the preference "Notify of new versions" then no connection to the Structorizer homepage will be tried and, consequently, no information about newer versions will be shown. On the other hand, a hint that this option is available will pop up on Structorizer start:

Update notification preference info box

Lest this information popup should annoy you every time you start Structorizer, while you don't want to activate the update notification, you may suppress this popup for all subsequent Structorizer starts, simply by pressing button "Don't show this window again". This popup suppression will last till a new Structorizer version is installed. (Of course you may decide to enable or disable the update notification preference independently whenever you want.)

  

7.2. Font

On the following screen, you can change the font that is used to draw your diagrams.

Font chooser dialog of version 3.26-02

You need to choose a font that supports Unicode. Check the test string in the font dialog and make sure you see an arrow (←), the symbol for an empty set (∅), and the compound comparison operator symbols (≠, ≤, ≥)1:

The following fonts should be fine:

If you just want to size up or down the current font then you might use the toolbar speedbuttons Toolbar font resizing speedbuttons or key combinations <Ctrl><Numpad+> / <Ctrl><Numpad-> instead.

Note: The font chosen here is only used for drawing the diagrams. It is not subject to the GUI Scaling preference. Both are completely independent.

___
1 Only from version 3.26-02 on.

  

7.3. Colors

You can dye the elements of your diagram in different colors. As you can see, there is a toolbar that shows 10 buttons with different colors:

These colors can be customized via the color preference dialog.

In order to modify a color, you simply need to click on it and select a new color in the OS-specific color choose dialog that pops up.

Notice: Colors are saved individually for each element as hex-coded value. This means that changing your default colors will not affect the colors of your (or others') old colored diagrams. These will still be displayed with the original colors saved in the given files.

  

7.4. Structures

Preferences menu with Structures item selected

In this section, you can define the default content of a newly created element.

As a matter of fact, if you add a new element to your diagram, the element editor pops up. The content that is shown by default in this dialog is the one that is found in structure preferences.

Notice: These settings have nothing to do with the "parser" preferences!

  

7.5. Parser

In this dialog you specify the keywords / syntax you want to use in your structogram. Generally structograms are free of any syntax, but if you want to use certain advanced features of Structorizer, you need to define keywords and stick to them.

Parser Preferences menu version 3.25

For most control structures, you can define a leading "Pre" and trailing "Post" keyword. Some control structures like FOR loops (and later possibly Jump instructions), however, may require more keywords or separator strings. Depending on what module uses the diagram parser, these keywords are being filtered out or replaced.

The toggle item "Ignore case" (introduced by version 3.24-06) controls whether the parser keywords configured here are to be matched in a case-sensitive or case-ignorant (or say tolerant) way, the latter being the default, e. g. it wouldn't make a difference whether you write "INPUT", "input", or "Input" (or even "iNpUt") in your diagrams; Structorizer would recognise it while option "Ignore case" is active. Be aware, however, that this case tolerance only applies to the keywords configured here, not to variable names.

The parser preferences are consulted by the following features:

If you need none of them, then for you there may be no use adjusting the parser preferences.

In most cases, however, you may want input and output instructions detected, for loops properly interpreted etc. In this case, the adaptation of parser preferences to the keywords used in the diagram may get to work the mechanisms listed above.

On the other hand, a "working" diagram might get stale if you alter some of the parser keywords. Version 3.25-02 therefore introduces a new service: Refactoring parser keywords in diagrams. If you changed one or more of the keywords in this dialog, and the currently edited diagram isn't empty or there are diagrams parked in the Arranger, then you will be asked, whether:

be automatically adapted to the new parser preferences - as far as they had matched the previous ones. This way, you can refactor an entire set of diagrams to use e.g. French keywords like "pour", "à", and ", pas = " in FOR loops instead of the English ones ("for", "to", "step") shown in the screenshot above. The translation of the diagrams induced by pressing the "OK" button is individually undoable for every affected diagram.
Also see Import options and loading preferences for other aspects of diagram refactoring.

Note:

  1. Parser settings are independent of the "structures" preferences, technically they have nothing to do with them. (Though it makes sense, of course, to configure e. g. the "Pre" condition keyword of a Repeat loop as "until" if you had decided to specify the default text for the Repeat loop as e.g. "until EXIT_CONDITION" in the "structures" preferences.) With FOR and FOR-In loops, however, the default phrase in the "structures" preferences is split by the element editor based on the "Pre" and "Post" keywords configured here in order to decide the style and the parameters of the loop.
  2. The "Pre" keyword of the FOR-In loop is not required to differ from that of the FOR loop. It may also be empty - in this case the "Pre" keyword of the FOR loop is automatically accepted as well. The "Post" keyword of the FOR-IN loop, however, must neither be empty nor be equal to any other keyword of the parser preferences (this is to ensure that Structorizer is able to tell a FOR-IN loop from a FOR loop).
  

7.6. Analyser

The Analyser Preferences dialog

The Analyser Preferences dialog is opened by means of the Preferences menu:

Preferences menu with Analyser preferences selected

The Analyser is an advanced feature, which analyses the structogram in real-time against different rules that structograms should comply with and checks it for obvious inconsistencies (like loops where the body has no impact on the condition and hence may unwillingly form an eternal loop).

Since version 3.25-07, the configurable Analyser rules are presented in a multi-tab dialog. It roughly categorizes the rules into (1) essential algorithmic tests and (2) checks concerning identifier naming and code style conventions:

Analyser settings tab 1 (algorithmic issues)

Among the convention rules there are also several ones that have been specially designed for Luxemburgish students. In Luxemburgish schools these rules are mandatory. The most special ones of this kind are marked with "(LUX/MEN)". So you may opt them out if you haven't to obey these rules.

Analyser settings (naming and convention tab)

Actually, each rule can be enabled or disabled independently. The analyser itself can be activated or disabled as a whole via the "Diagram" menu (see Settings > Analyse structogram?) or by pressing the <F3> key.

The analyser strongly relies on the Parser Preferences. If, syntactically seen, you don't stick very close to them, the analyser will not work correctly but probably produce a lot of needless warnings.

Notice: As it is proven that a program can never absolutely predict the behaviour of another program, the messages produced by the analyser should at best be considered as hints. They might be misleading or even wrong in certain cases!

Rule type explanation

(Checkbox order may change, this list follows the one presented by version 3.25-07, see screenshots above.)

Instructions

Conditions and Alternatives

Loops

Functions/Procedures and Calls

Jumps and Parallel sections

Identifiers and naming conventions

  

7.7. Saving options

Version 3.25-11 brought new options with respect to the way diagram files are saved. These preferences are available for configuration via the Preferences menu:

Preferences menu with the Save item selected

By selecting this menu item you will obtain the following dialog:

Dialog for saving diagrams

There are two options concerning auto-saving and another option related to file backups.

Auto-save options:

Usually, Structorizer will ask you interactively whether you want to store unsaved changes to a diagram as soon as you are going to replace it by another one in Structorizer, on going to close a dependent Structorizer instance holding a "dirty" diagram etc. Sometimes these questions are raised simply for safety reasons since the changes will not necessarily get lost even if you refuse saving them now. But then the changes stay pending and you are likely to get the same question later again. This situation is particularly annoying when a diagram (with unsaved changes) being executed is going to call a subroutine. Similarly on closing Arranger or some Structorizer instances.

If you would have saved these pending changes anyway then you may avoid the hassle from version 3.25-11 on by opting for up to two situations where pending changes of affected diagrams (and only these) shall automatically be saved without extra request for commit:

Backup option:

The backup option addresses a behaviour that was introduced to avoid data losses in case an update of an existing NSD file failed. It could have happened that users ended up with an empty file. Therefore a twofold strategy was implemented: The old version of the file was renamed to <filename>.nsd.bak before the new version was saved. If you dislike the directory being filled with these backup files, then you may now opt out the creation of backup files by unselecting the checkbox "Create backup files on re-saving?". Even for the rare case that the saving might fail this is safe enough now because actually the backup file will still be produced but only automatically removed after the saving has successfully ended.

  

7.8. Export options

From the "Preferences" menu you can open the "Export Options" dialog where general or target-language-specific preferences for the code export may be configured:

Export options dialog

What do the options mean:

From version 3.26-04 on there is a second tab on the export options dialog, allowing to configure lists of files or modules to be included by the exported code, i.e. on exporting a diagram to source code, the code generator will insert include directives, import or use declarations if there are some configured entries in the text field for the respective target language here:

Export options dialog

Further options may be added on user demand.

  

7.9. Import options

From version 3.25-02 on, the "Preferences" menu contains an item "Import ...", which opens a dialog where options for the loading of files of different types may be configured:

Import options dialog

The dialog contains two boxes with options for the loading of

What do the options mean:

 

Further import options may be added on user demand.

  

7.10. Language

Opened language menu

This preference is responsible for the language of the graphical user interface. This preference is saved automatically. (The currently selected language is marked in a way depending on the selected Look and Feel, besides being obvious throughout the GUI.) The set of translations and adaptations (e.g. menu mnemonics) associated to a certain language is called a locale.

Release 3.25 appended the menu item "[ ? ] From file..." (see image) allowing you to load an available locale file containing translations for an arbitrary language instead of one of the predefined translation sets provided by the menu. (A new maintenance tool also introduced by release 3.25, called Translator, allows to accomplish existing locales or to create new language files usable here.)

Please notice that the language of the graphical user interface is independant of the syntax you use in your diagrams and vice versa! Personally I prefer having an English user interface but all diagrams I draw need to be in French. Others might want to work with the GUI in their mother tongue while the diagram contents are written in English.

Notice: Certain locales (language files) may be incomplete. Elements with missing translations will usually be labelled in English (which is the default locale). Sometimes, however, particularly after having changed the language, they may be labelled in the language previously used. In order to see at least English translations, switch to English and then back to your favourite language.

If you are a native or experienced speaker of a language with missing or wrong translations then please don't hesitate to report the missing captions (e.g. as bug reports) proposing proper translations, or (better) feel invited to contribute to the accomplishment by producing an updated language file using the Translator and sending that file in.

  

7.11. Look & Feel

Here, you can change the overall look & feel of the graphical user interface of Structorizer. The different designs that appear in the submenu are those that are installed on your computer. You can simply select one of them. Structorizer remembers the chosen theme and will load it next time you start Structorizer.

Hints:

For further details about "Java Look & Feel", please google yourself ...

  

7.12. GUI Scaling

Structorizer is not DPI-aware, i.e. it will not automatically magnify its icons and fonts with very high screen resolutions (like e.g. 4K). This ought to be done by the GUI framework, actually, but JavaSwing fails to do so.

A complete GUI redesign using e.g. JavaFX instead might overcome the problem in the future. But for now only a makeshift workaround based on a scaling factor inserted in the preferences file can be offered.

Version 3.26-01 introduced a new menu item "Preferences" => "GUI Scaling ..." where you may preset and test a scaling factor for Structorizer GUI:

Preferences meu with GUI Scaling entry selected

This menu item opens a dialog that offers you to preset a scaling factor for the Strctorizer GUI (valid from the next Structorizer start):

GUI Scale Chooser dialog, with standard scale factor 1

The three "Preview" controls on this dialog grow with the selected scale factor, thus demonstrating how the result would look like. For scale factors < 2.0, no direct proportional scaling but a "size variant" mechanism of the Look & Feel is used, which may not be supported by all Look & Feels on any operation system:

GUI Scale Chooser dialog, with scale factor 2.5

From the next Structorizer start on, its icons should be magnified by the pre-selected scale factor. The effect, however, may still strongly depend on:

With certain Look & Feel / OS combinations, some of the fonts might resist the scaling attempt. In other environments, the scaling may differ among various controls or it may even be unstable (such that e.g. certain tab or sub menu captions switch their font size on being selected). Title bars would usually not be affected (as their appearance is controlled by the OS), whereas checkboxes at menu items might remain in tiny (i.e. standard) size despite of the magnification of their corresponding captions.

The scaling consistency has been improved substantially between Release 3.36 and version 3.26-01, though in upscaled mode some L&F-specific effects (e.g. "mouse over" shading) may still get simplified or even lost

So, don't expect too much, please. You might have to experiment a little in order to find out which Look & Feel (and what scale factor) works best for your purposes, machine, and taste.

Note:

  

8. Import

Source Code Import

Structorizer allows to derive a structogram from a given source code file. Until now, this import feature has only been available for CLI Pascal files. But an ANSI-C import is almost ready, other programming languages are likely to follow (e.g. COBOL, Java). Of course it will hardly ever be possible to import any code without losses. The grammars used by Structorizer to parse the source code are usually somewhat simplified, and obviously Structorizer cannot incorporate arbitrary pecularities of the most diverse programming languages and dialects. It will rather offer some core algorithmic functionality, and you may have to preprocess the code (e.g. cut some parts out) in order to be able to import at least the major part.

In interactive mode, you can import code files of any supported programming language by dragging the corresponding source file onto Structorizer. The respective parser will automatically be selected based on the file extention.

Another way to achieve the same goal is to use the menu, i.e.   File => Import => Source Code ...

(Before version 3.27, the import menu item has had been named "Pascal Code...", because only a Pascal/Delphi7 parser had been available.)

The importer will derive structures from the recognized control keywords and replace other parsed keywords of the source language by the corresponding parser preferences for the same structures as currently configured.

Syntactical restrictions

Note that Pascal files to be imported must have a program, unit, package, or library header. If you want to convert a bare subroutine (procedure or function) definition you have to embed it in one of these sorts of compilable concepts before, e.g. in a unit or between

program dummy;

and

begin
end.

A file comprising several routine definitions will be converted into a set of separate diagrams, one for each of the routines, and - if not empty - another one for the main program. If you do the import within the application (rather than as batch job, see below) then the imported diagrams will be collected in the Arranger.
Be aware that subroutine calls (references to other functions) can only be identified as such by Structorizer if the corresponding routine definitions are also available in the imported code. Otherwise the respective lines of code will usually be inserted as ordinary Instruction elements but may manually be transmuted to equivalent Call elements (at least if you intend to run the algorithm with Executor). This element transmutation, however, can be done by a simple mouse click. The capabilities of identifying standard routines or library functions for which there would be analogous built-in routines in Structorizer are still rather poor. (But improvements are planned.)

Type, constant, and variable declarations as well as comments will be ignored, they will not be converted, unless you enabled the import of variable declarations via the Import Preferences dialog. Imported (local) declarations will typically be coloured in light green.

Note: Pascal source files must not contain empty declaration areas (e.g. a var keyword without variables being declared after it). Hence, some Pascal files as exported from Structorizer might cause errors on re-import if they wouldn't have been completed manually before. (They may contain just TODO comments in the declaration sections.)

Note: Global declarations and initialisations in C will typically be inserted at the beginning of the main program if there is one in the file. There is no diagram element outside a diagram, which always represents either a program or a routine. Since instructions (other than variable declarations) cannot exist outside functions in C, either, there is little at stake. (Global declarations will be presented in the main program diagram in a light cyan background colour.) The first C import will only support a minimum subset of the C pre-processor (simple `#define`s without arguments), `#include` and `#if` in any variant may not be expected to work. If the code strongly depends on them then you may run the C source code through your compiler's pre-processor (for example gcc -E) and import the pre-processed source to in order to compare the results or pass the parser restrictions.

Typical error display on parsing failure

If the code to be imported is not compatible with the used import grammar then you will be presented an error dialog as shown above where the last 10 lines of code are presented for better orientation - for the line numbers do not exactly match those of the original code because usually some problematic pieces of the source may have been cut off in a preprocessing phase, and empty lines are not counted by the parsers. In the last line a little arrow symbol (») shows the character position where the parser detected a problem. As usual, the parsing failure may actually have been caused by preceding parts of the code. The message box also tells you what kind of symbols the parser had expected.

Batch import

Structorizer may also be used in batch mode to convert a Pascal file into an NSD file. The command syntax is given below, where the underlined pseudo program name Structorizer is to be replaced by the respective batch or shell script name for the console environment:

The scripts can be found in the Structorizer installation directory; don't try with Structorizer.exe!

Structorizer -p pas|pascal [-f] [-e encoding] [-o output-file] source-file ...

The options mean:

-p (followed by pas or pascal) must be the first option and - redundantly - selects the source language. (By now Pascal is still the only choice. From release 3.27 on, the language selectors will be deprecated, i.e. "pas" and "pascal" will most likely be ignored, other language shortcuts won't be accepted. Instead Structorizer will conclude from the file name extensions what code parser is to be used. This holds on a file per file basis, i.e. the source-file list may even consist of heterogenous files, say Pascal, C, COBOL or whatever parsers will be available.)

-e (followed by a charset name) is reserved for the choice of the source file character set (for 8-bit-based encodings it's rather irrelevant, though, because the Pascal parser eliminates all non-ASCII characters anyway).

-f forces overwriting an existing file with same name as the designated output file (see -o), otherwise a name modification by an added or incremented counter is done (e.g. output.nsd -> output.0.nsd).

-o (followed by a file path or name) specifies a specific output file name. I not given, the output file name will be derived from the source file name by replacing the file name extension with ".nsd". The file name extension ".nsd" is ensured in either case. If several source files were given then without option -o the nsd file names will be derived from the corresponding source file names; with option -o, however, the name variation discribed for the absence of option -f would be used (creating files output-file.nsd, output-file.0.nsd, output-file.1.nsd etc.).

source-file (one or many file paths/names) the Pascal files to be parsed and converted to Nassi-Shneiderman diagrams (nsd files).

Examples:

Structorizer.sh -p pas testprogram.pas

Structorizer.bat -p pascal -e UTF-8 -o quicksort.nsd qsort.pas

  

9. Export

Created Nassi-Shneiderman diagrams can be exported to several file formats.

  

9.1. Picture

Via the menu "File" => "Export" => "Picture..." you may create image files of your Nassi Shneiderman diagrams in several image file formats.

Currently the following formats are supported:

From version 3.24-15 on, PNG files are exported with transparent background.

On exporting to PNG, you may split the image of a (large) diagram into a matrix of several files. After selecting menu item "PNG (multiple) ..." you will be asked for a number of columns and a number of rows. The naming of the generated file depends on the Structorizer version as follows:

Since release 3.25, the file names will be generated with a two-dimensional numbering, making clear how the image is divided into the tiles and which file contains what part. Both row and column index are added as two-digit decimal numbers counting up from 00, e. g. if you selected a file name "myDiagram.nsd" and decided to split the image into a matrix of 2 columns and 3 rows, then the files would be named and associated to the image sections according to the following scheme:

myDiagram-00-00.png myDiagram-00-01.png
myDiagram-01-00.png myDiagram-01-01.png
myDiagram-02-00.png myDiagram-02-01.png

To compensate rounding problems, the files of the last column and the last row may be some pixels larger than the others lest there should be losses.

Prior to release 3.25, the generated files were continuously numbered, columns first, e. g. if you exported an NSD with name "myDiagram.nsd" and decided to split the image into a matrix of 2 columns and 3 rows, then the files would have been named and associated to the image sections according to the following scheme:

myDiagram-0.png myDiagram-1.png
myDiagram-2.png myDiagram-3.png
myDiagram-4.png myDiagram-5.png
  

9.2. Source code

Code Export Preparations

First of all, if you want to use the code generators, you should make sure to have filled in the parser preferences appropriately. You can find them via the menu "Preferences" => "Parser ...":

Parser Preferences dialog with french keys

All of the words you fill in there will be cut out and replaced by the respective target language keywords of the export.

For example, if your diagram contains a FOR-loop and you are writing french diagrams, you will have something like this:

If you then do a "Pascal" export, the generated code will be: for I:=1 to 10
but a "C" export will result in the code: for (I=1; I<=10; I+=(1))

As you can notice, the words "pour" and "à" have been eliminated or replaced with whatever the exported code requires. For being able to do this, the generators must be fed the necessary information about the syntax you are using in your diagrams.

Interactive Code Export

To export a diagram as code, go to the menu and select "File" => "Export" => "Code ..." and the name of the language you want to export to.

The currently supported programming or script languages are the following ones (where StruktTeX is not actually a programming language but an add-on to LaTeX providing embeddable NSD drawings):

Export Configuration

In the Export Preferences you may select your most frequently used (favourite) target language in order to accelerate the export via key combination Ctrl+Shift+X:
File menu with new menu item for export to the favourite language

You should be aware, of course, that the generated program files will usually not immediately be compilable or executable in the target language but require some manual post-processing because the generators will have to do a lot of mere guesswork: Though Structorizer tries hard to derive static type information from assignments or implicit declarations, the types of many of the used variables will not be known such that the generators will hardly be able to produce complete declaration lists for languages that require strict declaration. You will have to check for wrong, missing or mis-placed declarations and must accomplish or correct them manually. Some algorithmic construct may not directly be translatable such that the generators must try their best to compose something closely equivalent.

Usually "TODO" comments inserted in the generated code will guide you through the manual post-processing work.

A recently added Export Option "No conversion of the expression/instruction contents" allows you a kind of raw export with mere control structure conversion and mostly suppressed translation of the element contents. It is recommended to use this option if you explicitly write target code in Structorizer elements. In this case Structorizer wouldn't know how to translate your code into any other language, though.

Export Option "Involve called subroutines" is to enrich the code for a diagram with the routine definitions for all subroutines referred to by contained CALL elements - if the corresponding diagrams are reachable e.g. via the Arranger. Unavailable subroutines the exported diagram depends on will be reported without aborting the export process (the definitions will simply be missing in the resulting file(s)). You may find hints for missing subroutines in advance in the Analyser Report List if Analyser Preference "Check for inappropriate subroutine CALLs and missing call targets" is enabled.

See also: Code generators

Batch export

Structorizer may also be used in batch mode to generate a source file for a supported programming language or other textual export format (like StrukTeX) from NSD files. The command syntax is given below, where the underlined pseudo program name Structorizer is to be replaced by the respective batch or shell script name for the console environment:

The scripts can be found in the Structorizer installation directory; don't try with Structorizer.exe!

Structorizer -x generator [-b] [-c] [-l] [-t] [-e encoding] [-] [-f] [-o output-file] source-file ...

The options mean:

-x (followed by a generator name ) must be the first option and selects the target language or generator class. Currently supported language or generator class names are (case-insensitive, synonyms separated by "|"):

-b sets the opening block brace for the body of compound statements at the beginning of the next line (otherwise to the end of the same line).

-c will export simple instructions as comments.

-l will create line numbers and more ancient-style code on BASIC export.

-t will suppress most transformations of instruction and expression contents (intended for the case that the Structorizer elements already contain code complying with the target language syntax).

-e (followed by a charset name) determines the output file character set (UTF-8 being the default).

-f forces overwriting an existing file with same name as the designated output file (see -o), otherwise a name modification by an added or incremented counter is made (e.g. output.cpp -> output.0.cpp).

-o (followed by a file path or name) specifies a specific output file name. I not given, the output file name will be derived from the first nsd file name by replacing the file name extension with the one associated to the target language, e.g. ".java". The taget-language-specific file name extension is ensured in either case. If several nsd files are given then without option -o the created file will be named after the first nsd file name, with option -o, however, the filename of the option will be used.

- (single minus sign) will direct the code to the standard output instead of to the default output file. If -o option is also given, then the result will be written both to standard output and to the specified output file.

nsd-file (one or many file paths/names) the Structorizer diagram files to be converted to the target source file.

Note that the parser preferences configured in interactive Structorizer mode will be valid here, whereas the export options configured in interactive mode are not valid here, only the command line options described above will be observed (for binary options the contrary of the described option effect being the default, e.g. without specifying -l option there won't be line numbers or other old-fashioned relics in BASIC output).

  

10. Key bindings

Besides the usual key bindings for copy (ctrl c), cut (ctrl x), paste (ctrl v), help (F1), quit (ctrl q) etc., the tables show more specific accelerator keys provided by Structorizer.

Insert elements into the diagram

Function after current element before current element
insert Instruction F5 shift F5
insert IF Statement F6 shift F6
insert CASE Statement F10 shift F10
insert FOR-Loop F7 shift F7
insert WHILE-Loop F8 shift F8
insert REPEAT-Loop F9 shift F9
insert CALL F11 shift F11
insert JUMP (Exit)
F12 shift F12
insert PARALLEL F13 shift F13

Work with selected elements in the diagram

Function Accelerator key
edit selected element enter
commit changes in editor shift enter, ctrl enter
delete selected element del
move selected element up ctrl cursor up
move selected element down ctrl cursor down
select element above
cursor up
select element below
cursor down
select left element cursor left
select right element cursor right
expand selection to element above
shift cursor up
expand selection to element below
shift cursor down
collapse element Numpad -
expand element Numpad +
transmute (change type of) element ctrl t
outsource elements to a new subroutine (≥ V 3.27) ctrl F11
toggle breakpoint ctrl shift b
specify break trigger ctrl alt b
disable/enable element ctrl 7
replace fd/bk by forward/backward shift g
replace forward/backward by fd/bk ctrl g

Work with Structorizer or the entire diagram itself

Function Accelerator key
open user guide (in browser) F1
show version info shift F1
show link to the home page ctrl F1
create new diagram ctrl n
open (load) a diagram ctrl o
save diagram ctrl s
save diagram as... ctrl shift s
save all diagrams (≥ V 3.27) ctrl alt s
undo last change ctrl z
redo last undone change ctrl shift z, ctrl y
print diagram ctrl p
copy as PNG image to clipboard ctrl d
create PNG image file ctrl e
copy as EMF image to clipboard ctrl f
export as program code for preselected language ctrl shift x
toggle text and comment view ctrl alt v
highlight variables (on/off)
F4
switch structogram analysis on or off
F3
show/hide Arranger index
shift F3
enlarge font
ctrl Numpad+
diminish font
ctrl Numpad-
move horiz./vertical divider
ctrl F8
circle focus clockwise (also ends divider mode)
tab
circle focus counter-clockwise
shift tab

Font resizing in other contexts

Function Accelerator key
enlarge font in executor output window ctrl Numpad+
diminish font in executor output window ctrl Numpad-
enlarge font of element editor text fields
ctrl Numpad+
diminish font of element editor text fields
ctrl Numpad-

Arranger index and Analyser report area

Context Function Accelerator key
Arranger index scroll Arranger to selected diagram space
Arranger index fetch selected diagram from Arranger enter
Arranger index removes diagram from Arranger (version ≥ 3.26) del
Report list edit the responsible element
enter