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 ...":

All the words you filled in there will be filtered out and replaced by the respective target language keywords.

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

If you then do a "Pascal" export, the generated code will be:
for I:=1 to 10
begin
    { do something }
end
whereas a "C" export will result in the code:
for (I=1; I<=10; I+=(1)) {
    // do something
}

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

Menu

To export the current diagram in the work area as code, go to the menu and select "File › Export › Code ›" and the name of the language you want to export to. (In case these menu entries happen to be missing, see Export Configuration note.)

The currently supported programming or script languages are the following ones (where StruktTeX and LaTeX/Algorithm are not actually a programming languages but related to L^AT_EX add-ons providing embeddable NSD drawings or pseudocode illustrations, see Export Preferences for examples of the latter):

• Pascal / Delphi
• Oberon
• Perl
• ksh
• bash
• C
• C#
• C++
• Java
• Javascript
• PHP
• Python
• Basic
•  ARM
• StrukTeX
• LaTeX/Algorithm

You may also start the export from the Code Preview via the context menu.

Note the general export configuration opportunities and in particular that some of the languages (actually Basic, ARM, and LaTeX/Algorithm so far) may have additional generator-specific options.

Group Export

Another way to export source code from a diagram or even an entire arrangement group is to use the context menu of the Arranger Index. Having selected a group or a single diagram in the list, you may start the export via menu item "Export diagram/group ›" and the name of the language you want to export to. (If this menu item happens to be missing in a version ≥ 3.30-11 then it is likely to be due to an export/import suppression mode, see Export Configuration note.)

Group export allows to generate libraries consisting of several public routines, which are not necessarily referencing each other. If the group had to be partinioned then you will get the following information:

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:

You should be aware, of course, that the generated program files may 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.

The Export Option "No conversion of the expression/instruction contents" allows you to perform 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 the selected diagram with the routine definitions for all subroutines referred to by contained CALL elements and all includable diagrams referenced in the include list — if the corresponding diagrams are reachable via the Arranger. This works recursively. 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. Or, if the diagram itself has been arranged, you may check stale references via the Arranger Index:

See also: Code generators.

For a complete list of export configuration preferences see Export Options.

Note: Since version 3.30-10, Structorizer can be started in a mode with all interactive code export opportunities (including code preview) disabled. It is intended for certain teaching and examination situations. The way to activate this mode differs between version 3.30-10 and later versions, however:

• In version 3.30-10, this was temporarily achieved by adding a parameter "-restricted" to the command line used to start Structorizer (e.g. within the "program shortcut" on Windows).
• From version 3.30-11 on, instead a structorizer.ini file is to be placed in the installation directory as predominant ini file, which must contain a line "noExportImport=1" (manually to be inserted e.g. by means of a text editor). The "-restricted" command line parameter as of version 3.30-10 is no longer supported.

Batch Export

Structorizer may also be used in batch mode to generate source files 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:

• structorizer.sh for Linux, UNIX, and the like;
• Structorizer.bat for Windows.

The scripts can be found in the Structorizer installation directory; don't try with Structorizer.exe! (Even while a Java WebStart installation had still been supported it did not provide them — you need the unzipped downloadable version.)

Structorizer -x generator [-a] [-b] [-c] [-k] [-l] [-t] [-e encoding] [-s settings-file] [-] [-f] [-o output-file] nsdarr-file ...

The command will by default generate a common code file from all the diagram (.nsd) files listed as arguments. The original idea behind this behaviour arose before arrangement (.arr, .arrz) files have become processable and was to allow the batch production of a consistent source file from a related set of diagrams, without access to an Arranger context. For separate conversion of diagrams the command could simply be executed in a loop. Code generation for arrangement files (.arr, .arrz), which had later been allowed as members of the file list, will always be held separate. Since version 3.32-10, a new option -k in a way simulates a command loop internally, i.e. keeps the code generation for the listed .nsd files separate as well.

Note that the export configuration you may have performed in interactive mode is practically null and void for batch export, you must specify the wanted modes via command line options described below (-a, -b, -c, -l, -t, -s in particular).

The options mean:

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

• PasGenerator | Pascal | Delphi
• OberonGenerator | Oberon
• PerlGenerator | Perl
• KSHGenerator | ksh
• BASHGenerator | bash
• CGenerator | C
• CSharpGenerator | C#
• CPlusPlusGenerator | C++
• JavaGenerator | Java
• JsGenerator | Javascript
• PHPGenerator | PHP
• PythonGenerator | Python
• BasGenerator | Basic
• ArmGenerator | ARM
• TexGenerator | StrukTeX
• TexAlgGenerator | LaTeX | Algorithm

-a ensures that the diagram metadata attributes like author, creation time, and license text or link will also be exported as comments into the code file(s).

-b sets the opening block brace (C-like languages) 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 instruction texts as comments (sensible if the diagram contains rather pseudocode than executable expressions).

-k keeps the export of the listed Structorizer diagram files (.nsd) separate from each other and preserves their names for the produced isolated code files (as if the command would have been executed for each one of them in a loop; since version 3.32-10). Before and without this switch the translations would always be amalgamated into a single code file (just "scissor lines" labelled with proposed file names would mark the positions where the diagram-specific code could be cut). The source files will be placed in the folder(s) of the respective source .nsd files, unless option -o specifies otherwise (about the combined effects of options -k and -o see table below).

-l will create line numbers on BASIC export (in this case more ancient-style code at the same time) and LaTeX/Algorithm export (not for all supported packages in the same way, thow).

-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 ("encoding", 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, -k), otherwise name conflicts will be solved by an auto-incremented number suffix (e.g. output.cpp → output.0.cpp).

-o (followed by an absolute or relative file/folder path) specifies a non-default output file name or just an output folder. Without option -o the output file name(s) and locations will be derived from the first listed .nsd file name by replacing the name extension with the one associated to the target language, e.g. ".java". With option -o, however, the filename specified there will be used to control the target folder and possibly the file name. If the path behind -o (including its last path component!) designates an existing folder then it determines just the target folder for all output files while the base names are chosen as per default. If the last path component is a name not specifying an existing folder (but new or associated with a simple file) then this name will be used for the common export result of the listed .nsd files in the target folder. (For arrangement files this does not hold, their code result will always be named after the arrangement file but also be placed in the target folder suggested by the -o option.). Be aware that Structorizer will always force a standard file name exension according to the target language (i.e. add or replace it). The -o specification will be ignored if the path does not exist, i.e., cannot be used without having created the required subfolders before. See table below for the combined effect of options -o and -k (from version 3.32-10 on).

-s (followed by a text file path) specifies a settings-file (i.e. some .ini file) to be used used for retrieval of general and generator-specific options for the export. (Without switch -s the application defaults would be used.) The file must contain relevant key=value pairs, where the keys for generator-specific options are composed of the generator name and a corresponding export option name, both glued with a dot, whereas general export option keys start with "genExport", e.g.:
BasGenerator.lineNumbering=true
genExportComments=true
Since version 3.29-12, you may prepare suited export options in Structorizer GUI and save just these export options to a specific ini file, see Preferences export and import. So you won't any longer have to look for the relevant keys among the randomly ordered key-value pairs in the abundant structorizer.ini file like for a needle in a haystack and then copy the strewn lines to your import settings file. Of course you can still modify the values with a text editor in the selectively saved ini file without changing your settings residing in structorizer.ini. (Usually, you will adhere to the export settings held in structorizer.ini, though, which is maintained via the Structorizer Export Options dialog).

- (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.

For some of the above options (i.e. the binary ones), the respective upper-case letter has the exactly opposite effect (e.g. -L would switch off the line numbering even if a specified settings-file specifies otherwise, i.e. explicit switches have priority over file-based settings, also see below).

nsdarr-file is the file path of a Structorizer diagram (.nsd) or an arrangement file (.arr or .arrz) to be converted into source code. Since version 3.29-05, it might also be a so called Arrangement file specification. An arrangement file specification consists of an arrangement file path (.arr, .arrz) with an optionally appended sequence of diagram names or routine signatures, separated with exclamation marks (no blanks!), e.g.

• D:\workspace\tests\bar.arr!MAIN!sub(2-3)!test(7)
• '/home/bob/files/foo.arrz!test(7)!MAIN!sub(2-3)'

Note that (single or double) quotes around such an arrangement file specification are strictly necessary with UNIX/Linux shells! Such a specification induces that program diagram MAIN and routine diagrams test (with 7 arguments) and sub (with two mandatory arguments and another optional one) will be picked out of the arrangement  bar.arr or foo.arrz, respectively, as entry points (export roots) and exported together with all directly or indirectly referenced subroutine and includable diagrams from this archive into a single file. If no signatures are appended then all program (main) diagrams in the arrangement file will be taken as entry points (export roots). All contained diagrams will serve as potential entry points in this case. (Before 3.30-07 this had been different: You had to specify routine signatures if there weren't any program diagrams in the arrangement, otherwise nothing would have been exported from the arrangement.)
Without option -k, all "loose" .nsd files among the file arguments will contribute their diagrams to a single common source file, which is divided by "scissor lines", i.e. comment lines looking like this:
"=== 8< ===================================".
You may have to cut the file at these scissor lines in order to form a compilable project.

Each arrangement file, however, will feed a separate own source code file. It may consist of several modules, then also separated by "scissor lines" (see above). The first of these modules will usually be a "library" containing all definitions and routines commonly required by more than one of the identified entry points, the following modules represent an entry point each with all their individual requirements out of the arrangement. You may have to cut the file apart at these scissor lines and name them individually. If the scissor line is labelled with a file name then this module should get the respective file name (due to dependencies), all remaining file snippets may be named more or less arbitrarily.

Be aware that:

• the parser preferences configured in interactive Structorizer mode will be valid here, whereas
• the export options configured in interactive mode are null and void for batch export. Unless command line option -s explicitly specifies some .ini file as source for export options, 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). For export option "Involve called subroutines" a specific rule applies: It will automatically be enabled for arrangements and disabled for loose diagram files.

Examples for the combined effects of options -k and -o: Imagine there is an existing folder /home/alice/src. Then the folllowing table shows the expected effects of different command variants:

Export of Diagrams for Turtleizer

If you export diagrams that control Turtleizer, then the exported code will usually not work unless you find some more or less compatible source package for your target language. The Python language fortunately contains a native "turtle" package that fully supports all Turtleizer commands and functions. Since version 3.28-10 the Python code generator of Structorizer performs all necessary conversions and places the required import clause automatically. For Java and C++ you may easily get identical or equivalent external Turtle support:

• For Java, the original Turtleizer package sources from Structorizer are available for separate download and may be integrated in the Java project you set up around your exported code. You will also need the diagrcontrol package as an interface it relies on. Both packages require at least Java 8 as platform. The exported Java file will automatically be prepared to work with this package.
• For C++, there is a functionally equivalent VisualStudio project Turtleizer_CPP available on GitHub that can at least be used by console applications under Windows -- either as static library (after having updated the project file to your VisualStudio version) or simply by integrating the header and code files in your C++ project. Your exported C++ file will just have to include the "Turtleizer.h" header and possibly to append a Turtleizer::awaitClose(); instruction (provided the other project settings are suited, see the README.md file in the download or on the project page for details).