Quellcode-Export

Vorbereitungen für den Quellcode-Export

Wenn Sie die Code-Generatoren verwenden möchten, sollten Sie zunächst sicherstellen, dass Sie die Parser-Einstellungen (parser preferences) korrekt ausgefüllt haben. Diese finden Sie über das Menü Preferences › Parser ... (Einstellungen › Parser ...):

Alle dort eingetragenen Wörter werden herausgefiltert und durch die entsprechenden Schlüsselwörter der Zielsprache ersetzt.

Wenn Ihr Diagramm zum Beispiel eine FOR-Schleife enthält und Sie Diagramme auf Französisch schreiben, könnte es so aussehen:

Wenn Sie dann einen „Pascal"-Export durchführen, lautet der generierte Code:

for I:=1 to 10
begin
    { do something }
end

während ein „C"-Export folgenden Code erzeugt:

for (I=1; I<=10; I+=(1)) {
    // do something
}

Wie Sie sehen, wurden die Wörter „pour" und „à" eliminiert oder durch das ersetzt, was der exportierte Code erfordert. Damit die Generatoren dies tun können, müssen ihnen die notwendigen Informationen über die von Ihnen in Ihren Diagrammen verwendete Syntax mitgeteilt werden.

Interaktiver Quellcode-Export

Menü

Um das aktuelle Diagramm im Arbeitsbereich als Code zu exportieren, gehen Sie zum Menü und wählen Sie File › Export › Code › (Datei › Exportieren › Code ›) und dann den Namen der gewünschten Zielsprache. (Falls diese Menüeinträge fehlen sollten, siehe den Hinweis zur Export-Konfiguration.)

Die derzeit unterstützten Programmier- oder Skriptsprachen sind folgende (wobei StruktTeX und LaTeX/Algorithm keine eigentlichen Programmiersprachen sind, sondern sich auf LaTeX-Erweiterungen beziehen, die einbettbare NSD-Zeichnungen oder Pseudocode-Illustrationen ermöglichen; Beispiele für letztere finden Sie unter Export Preferences (Exporteinstellungen)):

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

Sie können den Export auch aus der Code-Vorschau (Code Preview) über das Kontextmenü starten.

Beachten Sie die allgemeinen Export-Konfigurationsmöglichkeiten und insbesondere, dass einige Sprachen (derzeit Basic, ARM und LaTeX/Algorithm) zusätzliche generator-spezifische Optionen haben können.

Gruppen-Export

Eine weitere Möglichkeit, Quellcode aus einem Diagramm oder sogar einer ganzen Anordnungsgruppe zu exportieren, ist die Verwendung des Kontextmenüs des Arranger-Index. Wenn Sie eine Gruppe oder ein einzelnes Diagramm in der Liste ausgewählt haben, können Sie den Export über den Menüeintrag Export diagram/group › (Diagramm/Gruppe exportieren ›) und den Namen der gewünschten Zielsprache starten. (Wenn dieser Menüeintrag in einer Version ≥ 3.30-11 fehlen sollte, liegt dies wahrscheinlich an einem aktiven Export/Import-Unterdrückungsmodus; siehe Hinweis zur Export-Konfiguration.)

Der Gruppen-Export ermöglicht die Erzeugung von Bibliotheken, die aus mehreren öffentlichen Routinen bestehen, die nicht notwendigerweise aufeinander verweisen. Wenn die Gruppe aufgeteilt werden musste, erhalten Sie folgenden Hinweis:

Export-Konfiguration

In den Export-Einstellungen (Export Preferences) können Sie Ihre am häufigsten verwendete (bevorzugte) Zielsprache auswählen, um den Export über die Tastenkombination Ctrl+Shift+X zu beschleunigen:

Sie sollten natürlich bedenken, dass die generierten Programmdateien in der Regel nicht sofort in der Zielsprache kompilierbar oder ausführbar sind, sondern eine manuelle Nachbearbeitung erfordern. Die Generatoren müssen viel raten: Obwohl Structorizer versucht, statische Typinformationen aus Zuweisungen oder impliziten Deklarationen abzuleiten, sind die Typen vieler verwendeter Variablen unbekannt, sodass die Generatoren kaum vollständige Deklarationslisten für Sprachen erzeugen können, die strikte Deklaration erfordern. Sie müssen falsche, fehlende oder falsch platzierte Deklarationen prüfen und diese manuell ergänzen oder korrigieren. Manche algorithmischen Konstrukte lassen sich nicht direkt übersetzen, sodass die Generatoren versuchen müssen, etwas möglichst Gleichwertiges zu konstruieren.

In der Regel führen „TODO"-Kommentare im generierten Code Sie durch die manuelle Nachbearbeit.

Die Export-Option „No conversion of the expression/instruction contents" (Keine Konvertierung des Ausdrucks-/Anweisungsinhalts) ermöglicht einen Raw-Export mit reiner Kontrollstruktur-Konvertierung und weitgehend unterdrückter Übersetzung des Element-Inhalts. Es empfiehlt sich, diese Option zu verwenden, wenn Sie explizit Zielcode in Structorizer-Elemente schreiben. In diesem Fall wäre Structorizer nicht in der Lage, Ihren Code in eine andere Sprache zu übersetzen.

Die Export-Option „Involve called subroutines" (Aufgerufene Unterroutinen einbeziehen) reichert den Code für das ausgewählte Diagramm mit den Routinen-Definitionen für alle Unterroutinen an, auf die in enthaltenen CALL-Elementen verwiesen wird, sowie mit allen in der Include-Liste referenzierten Includable-Diagrammen — sofern die entsprechenden Diagramme über den Arranger erreichbar sind. Dies funktioniert rekursiv. Nicht verfügbare Unterroutinen, von denen das exportierte Diagramm abhängt, werden gemeldet, ohne den Export-Prozess abzubrechen (die Definitionen fehlen dann einfach in der/den resultierenden Datei(en)). Hinweise auf fehlende Unterroutinen finden Sie vorab in der Analyser-Berichtsliste, wenn die Analyser-Einstellung „Check for inappropriate subroutine CALLs and missing call targets" (Auf ungeeignete Unterroutinen-CALLs und fehlende Aufrufziele prüfen) aktiviert ist. Oder, wenn das Diagramm selbst angeordnet wurde, können Sie veraltete Referenzen über den Arranger-Index prüfen:

Siehe auch: Code-Generatoren.

Eine vollständige Liste der Export-Konfigurationseinstellungen finden Sie unter Export-Optionen.

Hinweis: Ab Version 3.30-10 kann Structorizer in einem Modus gestartet werden, in dem alle interaktiven Code-Export-Möglichkeiten (einschließlich Code-Vorschau) deaktiviert sind. Dieser Modus ist für bestimmte Lehr- und Prüfungssituationen gedacht. Die Art der Aktivierung unterscheidet sich jedoch zwischen Version 3.30-10 und späteren Versionen:

• In Version 3.30-10 wurde dies vorübergehend durch Hinzufügen des Parameters „-restricted" zur Befehlszeile zum Starten von Structorizer erreicht (z. B. in der „Programmverknüpfung" unter Windows).
• Ab Version 3.30-11 ist stattdessen eine structorizer.ini-Datei im Installationsverzeichnis als vorrangige ini-Datei abzulegen, die eine Zeile noExportImport=1 enthalten muss (manuell einzufügen, z. B. mit einem Texteditor). Der Befehlszeilenparameter „-restricted" aus Version 3.30-10 wird nicht mehr unterstützt.

Batch-Export

Structorizer kann auch im Batch-Modus verwendet werden, um Quelldateien für eine unterstützte Programmiersprache oder ein anderes textuelles Exportformat (wie StrukTeX) aus NSD-Dateien zu erzeugen. Die Befehlssyntax ist nachfolgend angegeben, wobei der unterstrichene Pseudo-Programmname Structorizer durch den jeweiligen Batch- oder Shell-Skript-Namen für die Konsolenumgebung zu ersetzen ist:

• structorizer.sh für Linux, UNIX und Ähnliches;
• Structorizer.bat für Windows.

Die Skripte befinden sich im Structorizer-Installationsverzeichnis; versuchen Sie es nicht mit Structorizer.exe! (Selbst als eine Java-WebStart-Installation noch unterstützt wurde, lieferte diese die Skripte nicht — Sie benötigen die entpackte herunterladbare Version.)

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

Der Befehl erzeugt standardmäßig eine gemeinsame Code-Datei aus allen als Argumente aufgelisteten Diagramm-(.nsd-)Dateien. Der ursprüngliche Gedanke hinter diesem Verhalten entstand, bevor Anordnungsdateien (.arr, .arrz) verarbeitbar waren, und sollte die Batch-Produktion einer konsistenten Quelldatei aus einem zusammengehörigen Diagramm-Set ermöglichen, ohne Zugriff auf einen Arranger-Kontext. Für die separate Konvertierung von Diagrammen konnte der Befehl einfach in einer Schleife ausgeführt werden. Die Code-Generierung für Anordnungsdateien (.arr, .arrz), die später als Mitglieder der Dateiliste zugelassen wurden, erfolgt immer separat. Ab Version 3.32-10 simuliert eine neue Option -k gewissermaßen intern eine Befehlsschleife, d. h. sie hält die Code-Generierung für die aufgelisteten .nsd-Dateien ebenfalls getrennt.

Beachten Sie, dass die im interaktiven Modus vorgenommene Export-Konfiguration für den Batch-Export praktisch wirkungslos ist; die gewünschten Modi müssen über die unten beschriebenen Befehlszeilenoptionen angegeben werden (-a, -b, -c, -l, -t, -s insbesondere, wobei Option -s ermöglicht, zuvor in einer ini-Datei gespeicherte Einstellungen aufzuzwingen).

Die Optionen bedeuten:

-x (oder gleichwertig --export ab Version ≥ 3.32-23), gefolgt von einem Generator- oder Sprachnamen

Muss die erste Option sein und wählt die Zielsprache. Derzeit unterstützte Sprach-Bezeichner sind (Groß-/Kleinschreibung unerheblich, Synonyme durch „|" getrennt):

• 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

Stellt sicher, dass die Diagramm-Metadaten-Attribute wie Autor, Erstellungszeitpunkt und Lizenztext oder -link ebenfalls als Kommentare in die Code-Datei(en) exportiert werden.

-b

Setzt die öffnende Block-Klammer (bei C-ähnlichen Sprachen) für den Rumpf von zusammengesetzten Anweisungen an den Anfang der nächsten Zeile (andernfalls ans Ende derselben Zeile).

-c

Exportiert einfache Anweisungstexte als Kommentare (sinnvoll, wenn das Diagramm eher Pseudocode als ausführbare Ausdrücke enthält).

-k

Hält den Export der aufgelisteten Structorizer-Diagrammdateien (.nsd) voneinander getrennt und erhält deren Namen für die erzeugten isolierten Code-Dateien (als ob der Befehl für jede einzelne in einer Schleife ausgeführt worden wäre; ab Version 3.32-10). Ohne diesen Schalter würden die Übersetzungen immer zu einer einzigen Code-Datei zusammengeführt (lediglich mit „Scherenlinie"-Kommentaren als Trennmarken). Die Quelldateien werden in den Ordner(n) der jeweiligen Quell-.nsd-Dateien abgelegt, es sei denn, Option -o gibt etwas anderes an (bezüglich der kombinierten Effekte der Optionen -k und -o siehe Tabelle unten).

-l

Erzeugt Zeilennummern beim BASIC-Export (in diesem Fall zugleich eher altmodischer Code) und beim LaTeX/Algorithm-Export (nicht für alle unterstützten Pakete auf die gleiche Weise).

-t

Unterdrückt die meisten Transformationen des Anweisungs- und Ausdrucksinhalts (gedacht für den Fall, dass die Structorizer-Elemente bereits Code enthalten, der der Syntax der Zielsprache entspricht).

-e (gefolgt von einem Zeichensatz-Namen)

Bestimmt den Zeichensatz der Ausgabedatei (Standard: UTF-8).

-f

Erzwingt das Überschreiben einer vorhandenen Datei mit demselben Namen wie die angegebene Ausgabedatei (siehe -o, -k); andernfalls werden Namenskonflikte durch ein automatisch inkrementiertes Zahlensuffix gelöst (z. B. output.cpp → output.0.cpp).

-o (gefolgt von einem absoluten oder relativen Datei-/Ordnerpfad)

Gibt einen abweichenden Ausgabedateinamen oder nur einen Ausgabeordner an. Ohne Option -o werden der oder die Ausgabedateinamen und -speicherorte aus dem ersten aufgelisteten .nsd-Dateinamen abgeleitet, indem die Namenserweiterung durch die der Zielsprache zugeordnete ersetzt wird, z. B. „.java". Mit Option -o wird der dort angegebene Dateiname zur Steuerung des Zielordners und möglicherweise des Dateinamens verwendet. Wenn der Pfad hinter -o (einschließlich seiner letzten Pfadkomponente!) einen vorhandenen Ordner bezeichnet, bestimmt er nur den Zielordner für alle Ausgabedateien, während die Basisnamen wie standardmäßig gewählt werden. Wenn die letzte Pfadkomponente einen Namen bezeichnet, der keinen vorhandenen Ordner spezifiziert (sondern neu ist oder einer einfachen Datei zugeordnet ist), wird dieser Name für das gemeinsame Exportergebnis der aufgelisteten .nsd-Dateien im Zielordner verwendet. (Für Anordnungsdateien gilt dies nicht; deren Code-Ergebnis wird immer nach der Anordnungsdatei benannt, aber ebenfalls im durch Option -o vorgegebenen Zielordner abgelegt.) Beachten Sie, dass Structorizer eine standardmäßige Dateinamenerweiterung gemäß der Zielsprache immer erzwingt. Die -o-Angabe wird ignoriert, wenn der Pfad nicht existiert. Bezüglich der kombinierten Effekte der Optionen -o und -k siehe Tabelle unten (ab Version 3.32-10).

-s (gefolgt von einem Textdateipfad)

Gibt eine settings-file (d. h. eine .ini-Datei) an, die zur Abfrage allgemeiner und generator-spezifischer Export-Optionen verwendet wird. (Ohne Schalter -s würden die Anwendungsstandards verwendet.) Die Datei muss relevante Schlüssel=Wert-Paare enthalten, wobei die Schlüssel für generator-spezifische Optionen aus dem Generator-Namen und einem entsprechenden Exportoptionsnamen bestehen, die mit einem Punkt verbunden sind, während allgemeine Exportoptionsschlüssel mit „genExport" beginnen, z. B.:

BasGenerator.lineNumbering=true
genExportComments=true

Ab Version 3.29-12 können Sie geeignete Export-Optionen in der Structorizer-Benutzeroberfläche vorbereiten und nur diese Exportoptionen in einer bestimmten ini-Datei speichern, siehe Einstellungen exportieren und importieren.

- (einzelnes Minuszeichen)

Leitet den Code zur Standardausgabe um statt in die Standard-Ausgabedatei. Wenn auch die Option -o angegeben ist, wird das Ergebnis sowohl zur Standardausgabe als auch in die angegebene Ausgabedatei geschrieben.

Bei einigen der oben genannten Optionen (d. h. den binären) hat der jeweilige Großbuchstabe genau den entgegengesetzten Effekt (z. B. würde -L die Zeilennummerierung deaktivieren, auch wenn eine angegebene settings-file etwas anderes festlegt; explizite Schalter haben also Vorrang vor dateibasierten Einstellungen).

nsdarr-file ist der Dateipfad eines Structorizer-Diagramms (.nsd) oder einer Anordnungsdatei (.arr oder .arrz), das/die in Quellcode konvertiert werden soll. Ab Version 3.29-05 kann es sich auch um eine sogenannte Arrangement-Dateispezifikation handeln. Eine Arrangement-Dateispezifikation besteht aus einem Anordnungsdateipfad (.arr, .arrz) mit einer optional angehängten Folge von Diagrammnamen oder Routinen-Signaturen, getrennt durch Ausrufezeichen (ohne Leerzeichen!), z. B.:

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

Beachten Sie, dass (einfache oder doppelte) Anführungszeichen um eine solche Arrangement-Dateispezifikation bei UNIX/Linux-Shells zwingend erforderlich sind! Eine solche Spezifikation bewirkt, dass das Programm-Diagramm MAIN und die Routinen-Diagramme test (mit 7 Argumenten) und sub (mit zwei obligatorischen und einem weiteren optionalen Argument) aus der Anordnung bar.arr bzw. foo.arrz als Einstiegspunkte (Export-Wurzeln) herausgegriffen und zusammen mit allen direkt oder indirekt referenzierten Unterroutinen- und Includable-Diagrammen aus diesem Archiv in eine einzige Datei exportiert werden. Wenn keine Signaturen angehängt sind, werden alle Programm- (Haupt-)Diagramme in der Anordnungsdatei als Einstiegspunkte (Export-Wurzeln) verwendet.

Ohne Option -k tragen alle „losen" .nsd-Dateien unter den Dateiargumenten ihre Diagramme zu einer gemeinsamen Quelldatei bei, die durch „Scherenlinien" unterteilt ist, d. h. Kommentarzeilen der Form:

"=== 8< ==================================="

Es kann erforderlich sein, die Datei an diesen Scherenlinien aufzuteilen, um ein kompilierbares Projekt zu erhalten.

Jede Anordnungsdatei jedoch speist eine eigene separate Quellcode-Datei. Diese kann aus mehreren Modulen bestehen, die ebenfalls durch „Scherenlinien" (siehe oben) getrennt sind. Das erste dieser Module ist in der Regel eine „Bibliothek", die alle Definitionen und Routinen enthält, die von mehr als einem der identifizierten Einstiegspunkte gemeinsam benötigt werden; die folgenden Module repräsentieren jeweils einen Einstiegspunkt mit allen ihren individuellen Anforderungen aus der Anordnung.

Beachten Sie:

• Die im interaktiven Structorizer-Modus konfigurierten Parser-Einstellungen gelten hier, während
• die im interaktiven Modus konfigurierten Export-Optionen für den Batch-Export wirkungslos sind. Sofern Befehlszeilenoption -s keine .ini-Datei als Quelle für Export-Optionen angibt, werden nur die oben beschriebenen Befehlszeilenoptionen berücksichtigt (wobei für binäre Optionen das Gegenteil des beschriebenen Optionseffekts der Standard ist, z. B. ohne Angabe von Option -l gibt es keine Zeilennummern oder andere altmodische Relikte in der BASIC-Ausgabe). Für die Export-Option „Involve called subroutines" (Aufgerufene Unterroutinen einbeziehen) gilt eine spezifische Regel: Sie wird für Anordnungen automatisch aktiviert und für lose Diagrammdateien deaktiviert.

Beispiele für die kombinierten Effekte der Optionen -k und -o: Angenommen, es gibt einen vorhandenen Ordner /home/alice/src. Die folgende Tabelle zeigt die erwarteten Effekte verschiedener Befehlsvarianten:

Export von Turtleizer-Diagrammen

Wenn Sie Diagramme exportieren, die Turtleizer steuern, funktioniert der exportierte Code in der Regel nicht, sofern Sie kein mehr oder weniger kompatibles Quellpaket für Ihre Zielsprache finden. Die Sprache Python enthält glücklicherweise ein natives „turtle"-Paket, das alle Turtleizer-Befehle und -Funktionen vollständig unterstützt. Ab Version 3.28-10 führt der Python-Code-Generator von Structorizer alle notwendigen Konvertierungen durch und fügt die erforderliche Import-Klausel automatisch ein. Für Java und C++ ist ebenfalls eine identische oder äquivalente externe Turtle-Unterstützung leicht erhältlich (ab Version 3.32-36 enthält der generierte Code bereits die entsprechend vorgeschlagenen Links als Kommentare sowie zugehörige include/import-Klauseln):

• Für Java sind die originalen Turtleizer-Paket-Quellen aus Structorizer zum separaten Herunterladen verfügbar und können in das Java-Projekt integriert werden, das Sie rund um Ihren exportierten Code einrichten. Sie benötigen außerdem das diagrcontrol-Paket als Schnittstelle, auf die es sich stützt. Beide Pakete erfordern mindestens Java 8 als Plattform. Die exportierte Java-Datei wird automatisch so vorbereitet, dass sie mit diesem Paket funktioniert.
• Für C++ gibt es ein funktional äquivalentes VisualStudio-Projekt Turtleizer_CPP auf GitHub, das zumindest von Konsolenanwendungen unter Windows genutzt werden kann — entweder als statische Bibliothek (nach Aktualisierung der Projektdatei auf Ihre VisualStudio-Version) oder einfach durch Integration der Header- und Code-Dateien in Ihr C++-Projekt. (In letzterem Fall muss das Projekt auch die Windows-Bibliothek gdiplus.lib importieren.) Ihre exportierte C++-Datei muss lediglich den Header „Turtleizer.h" einbinden und möglicherweise eine Anweisung Turtleizer::awaitClose(); anhängen (sofern die anderen Projekteinstellungen geeignet sind; Einzelheiten finden Sie in der README.md-Datei im Download oder auf der Projektseite).