S T R U C T O R I Z E R - User Guide
Preferences > Import

Preferences menu with item import selected

Menu item "Import ..." in the "Preferences" menu 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

  • code files (e.g. ANSI-C import),
  • diagram files (Structorizer's own .nsd format).

What do the options mean:

  • Character Set (for code file import only)
    You may control what character encoding to use on import. By default UTF-8 will be used but if you happen to find the import file encoded in a different caracter set then you may select the actual character set of the file in oder to import the code cleanly. While "List all?" isn't checked, the choice list will only offer you about six of the most common character sets. By enabling "List all?", however, the choice will be expanded to several dozens of encodings, i.e. to all your Java version will know of.
    Note: For the moment this setting is of very limited use for files coded with an 8-bit-based character set, though, since the applied Pascal grammar doesn't cope with non-ASCII characters (apparently due to a parser bug) such that they have to be eliminated before actually starting to parse, anyway.
  • Log to folder (for code file import, versions ≥ 3.27 only)
    During parsing and diagram generation a log file is written. Usually it is placed as <source_file>.log next to the imported source file. Here you may specify that all log files be directed to the specified folder instead (this is particularly helpful if the folder containing the source files is write-protected). Button "<<" opens a directory selection dialog.
  • Import variable declarations (for code file import, versions ≥ 3.27 only)
    Since version 3.26-02 variable declarations in Pascal or VB syntax are tolerated in Instruction elements. Consequently, code import may optionally convert variable declarations found in the source code into declaring instruction elements in order to preserve original type information. To allow so, activate this checkbox.
  • Import source code comments (for code file import, versions ≥ 3.27 only)
    Structorizer is now capable of importing comments from the source code and associating them to the respective diagram elements. This checkbox enables the comment import. while remaining unchecked the source code comments will be ignored.
  • Save parse tree as text file after import (for code file import, versions ≥ 3.27 only)
    The plugins doing the code import in Structorizer rely on an open-source LALR(1) parser in combination with a language-specific grammar. A successful parsing process results in a syntax tree of the input program from which the diagram is built. This parse tree may be delivered as text file <source_file>.parsetree.txt in the source directory. Just enable this option if you are interested in having a look at it or to clarify wrong or questionable import results.
  • Maximum number of imported diagrams for direct display (for code file import, versions ≥ 3.28-05 only)
    Some code files may contain a large number of functions and procedures. If hundreds of diagrams are pushed to Arranger, this is likely to have a massive degradation impact on the GUI response time to user interaction:
    Arranger crammed with imported diagrams
    Often it is a better idea first to save all the imported diagrams to files and then to open and inspects them rather individually. Here is the option that allows you to specify the threshold number beyond which the diagrams are no longer placed in Arranger. Instead you will be offered to save the diagrams to the file system (or otherwise to discard them). The default thresshold is 20. The maximum threshold for automatically accepted diagrams you can specify is 150.
    Remark: This threshold does not apply for the loading of .arr or .arrz files and for dragging .nsd files into Arranger, nor does it prevent you from pushing diagrams from the Structorizer main form.
  • Language-specific options (for code file import, versions ≥ 3.27 only)
    Version 3.27 enhanced the set of possible import languages. It became clear, that besides general import options (as the ones described above) there may some very language-specific subjects to customization. These are plugin-specified and not hard-coded in the Import Options dialog. In order to configure those language-specific options select the interesting import language with the choice box and then push the button "Language-specific Option" to see what options are available e.g. for ANSI-C import and configure the respective settings. Here are the currently known settings:
    • ANSI-C73 and ANSI-C99 (independent)
      Language-specific import options for ANSI-C
      • Known external type names
        C files may depend on type names introduced by included headers, which are not available for the C parser of Structorizer. The C grammar is very sensitive to type names, however. So you should list all type names causing parsers errors in this text-field (separated by commas) to allow a Structorizer-internal preprocessor to make them digestible for the parser.
      • Redundant pre-processor symbols or macros (versions ≥ 3.28-03)
        Often, there are certain pre-processor defines in C with mere decalaratory effect, e.g. "WINAPI" in order to tell that a function definition belogs to the WinAPI or "_opt_in" as a pointer argument prefix indicating that this argument may expects a value (rather than being used to export values) but may be set NULL ("optional"). Pre-processor symbols like these are not only completely redundant for Structorizer import but would let the parser to fail. In this option you may enumerate names of this kind to be eliminated on import. You can also name parameterized macros that should be erased by appending parentheses to the name, optionally you may put the number of arguments in the parentheses (see image).
      • Use type names and defines from WINAPI / MinGw (versions ≥ 3.28-05)
        In order to import C code that uses e.g. WINAPI defines or those from MinGw, it would usually be hard to configure any single symbol, macro, or typedef used in the code via the text fields above (in a trial and error manner). Instead you may select the respective check box to provide the parser with the minimum required classification info about all defines of the respective library at once. They will neither override the text configuration fields nor be appended to them but made available behind the scenes. Be aware that it's not the full definition of the words but just helps the parser to let the source file pass.
    • COBOL
      Import options for COBOL 3.27-02
      • Debug Lines
        Lines starting with ">>D" (free format, see below) or having an indicator symbol 'D' (in fixed format, see below) in COBOL are so-called debug lines specifying some code for debugging purposes. If the checkbox "Debug Lines" is not selected thenjust these debug lines will just be marked with a comment on import, ortherwise the code part of then debug lines will also be imported.
      • Decimal comma (instead of decimal point)
        It's possible that floating-point literals in a COBOL file use decimal commas (e.g. German locale) rather than the usual decimal points (e.g. British or US American locale). In order to make such a file pass the syntax analysis you must select this checkbox.
      • Fixed-form format
        COBOL files may be formatted in the traditional fixed form with fix column zones or in free format like most programming languages. The parser must now in advance what format the file is using unless a directive in the first line of code specifies it.
      • Indicator column in fixed format
        Provided fixed format is used there may be differences in the column where the classifying indicator characters are placed. Here you can specify at what column they appear in the specific file to be loaded (e.g. column 7). Just enter the column number.
      • Column of ignored text in fixed format
        As before, there is a certain column indicating text to be ignored by the parser. Put in this column number when importing a fixed-format COBOL file.

 

  • Replace keywords on loading a diagram (NSD files)
    As outlined in other sections of this manual, the interpretability of a diagram strongly depends on the parser preferences in particular, i.e. an input instruction will only be recognized if it starts with the currently configured input keyword etc. Hence, if you load a diagram created by someone else (or years before) then it is not unlikely that it adhered to a different set of parser preferences when it was saved. So the first thing you used to obtain in earlier versions was a lot of Analyser warnings. In order to sort them out you would either have to adapt the parser preferences to the diagram or vice versa. Which is both cumbersome or can even get nasty if you want to combine several diagrams of different origin by Calls.
    To overcome this unpleasant situation, version 3.25-01 began to save diagram files with all non-empty parser preferences as attached attributes. This way, recent diagram files became prepared for this refactoring option:
    With the checkbox enabled, Structorizer will replace all obsolete keywords throughout the diagram being loaded by the respective currently configured parser keywords, such that the diagram will automatically fit into your current context. (Actually, the diagram content will be modified to maintain its semantic equivalence.) The refactoring won't work with legacy NSD files originating from versions before 3.25-01, of course, because older .nsd files are lacking the decisive information. You would have to adapt them manually first and re-save them with a Structorizer of at least version 3.25-01 to benefit from the refactoring mechanism. (For this manual refactoring, however, you should benefit from the Find & Replace tool - a new feature of release 3.27.)
    It is highly recommended to enable this import option. Only if you are sure never to be confronted with diagrams originating from a different preferences context or if you need to see the originally used keywords then you may leave this option unchecked. Since release 3.27 you will even be warned when a diagram with differing keyword set is loaded while the refactoring mode is switched off, e.g.:
    Option dialog on having loaded a diagram without refactoring support
    You may now choose among the three offered opportunities. If you opt for c), i.e. to postpone a measure then the first attempt to modify the diagram later on will pop up a slightly different dialog (since version 3.27):
    Option dialog on modifying an unrefactored diagram
  • Now the postponed refactoring may eventually be done (such that the editing will be based on a consistent content) or the keyword information may be abandoned in order to do all changes manually. Last but not least, the change may be cancelled (option c) and hence the solution of the problem would be postponed further.
    On applying "Save as..." to an (unchanged) diagram with postponed refactoring the original keyword set will be saved instead of the current Parser Preferences. After a forced diagram modification, however, the original keyword set will irreversibly be lost in Structorizer.

Further import options may be added in future versions on user demand.