Dieses Dokument beschreibt die Anwendung DocumentationTree. Die Anwendung wird als Bestandteil von Dokumentation von Datenbanken verwendet. Mit diesem Dokument soll der Leser in die Lage versetzt werden, - den Aufbau und die Aufgaben der Anwendung zu verstehen, - das System über die Benutzeroberfläche bedienen zu können, - im Falle eines Systemfehlers die geeigneten Maßnahmen ergreifen zu können.
Um die Anwendung starten zu können, wird mindestens Java-Version 13 vorausgesetzt. Da JavaFX seit Java-Version 9 nicht mehr Bestandteile des JREs ist, muss JavaFX zusätzlich heruntergeladen werden. Anschließend muss es entpackt werden und der Pfad muss im Skript start.bat oder start.sh angegeben werden.
Die Anwendung kann mit einem (Doppel-)Klick auf eines der Skripte gestartet werden.
link:../../start.bat[role=include]Beim Start erscheint folgender Dialog:
Über das Menü Datei → Öffnen… kann eine Datei ausgewählt werden. Das Verzeichnis wird initial immer auf das Verzeichnis, in dem die Jar-Datei liegt, eingestellt.
Es ist eine Datei auszuwählen, die eine Lua-Table enthält, die über
return <table>zurückgegeben wird.
Die hier gelesenen und geöffneten Lua-Dateien enthalten für die Knoten Texte, die in die Variablen branchname geschrieben werden, z.B. branchname="Knoten", und für die Äste, Text, das in Anführungsstriche, Hochkommata oder eckigen Klammern geschrieben steht, z.B. "Ast", 'Ast' oder . Die Verwendung der Textbegrenzungszeichen folgt der Logik in Lua. Variablen und Text werden durch Kommata "," abgegrenzt.
Knoten werden in geschweifte Klammern geschrieben, also {branchname="Knoten"}. Wenn ein Knoten in der Ebene unterhalb eines anderen Knotens erscheinen soll, wird dieser innerhalb der anderen geschweiften Klammer mit Komma abgetrennt geschrieben, z.B. {branchname="Knoten 1",{branchname="Knoten .1"}}. Soll der Knoten nicht in der Ebene unter dem anderen hängen, sondern auf derselben Ebene sein, wird er nach der geschweiften Klammer geschrieben, also {branchname="Knoten 1"},{branchname="Knoten 2"}.
Ein Ast, das an einem Knoten hängt, wird auch in die geschweiften Klammer geschrieben, {branchname="Knoten",'Ast'}.
Ein Knoten bzw. Ast muss mindestens in der obersten geschweiften Klammer erscheinen.
Die Variable auf oberster Ebene muss mit return zurückgegeben werden, hat aber einen frei wählbaren Namen.
example =
{branchname="Knoten oberste Ebene",
{branchname="Knoten 1",
{branchname="Knoten 1.1", 'Ast 1.1.1'},
'Ast 1.1'
},
{branchname="Knoten 2", 'Ast 2.1'}
}
return exampleWenn Knoten bzw. Äste unterhalb eines Knotens beim Öffnen nicht sichtbar sein sollen und erst durch den Anwender sichtbar gemacht werden sollen, wird eine Variable state="COLLAPSED" eingefügt. Das Beispiel sieht dann wie folgt aus:
example =
{branchname="Knoten oberste Ebene",state="COLLAPSED",
{branchname="Knoten 1",
{branchname="Knoten 1.1", 'Ast 1.1.1'},
'Ast 1.1'
},
{branchname="Knoten 2", 'Ast 2.1'}
}
return exampleKommentare können mit "--" eingefügt werden. Der Text bis zum Zeilenwechsel ist damit Kommentar. Es ist hilfreich die schließenden geschweiften Klammern mit Kommentaren der öffnenden geschweiften Klammern zu erklären. Man darf ein Komma auch nach der letzten Variable bzw. Text setzen.
example =
{branchname="Knoten oberste Ebene",state="COLLAPSED",
{branchname="Knoten 1",
{branchname="Knoten 1.1",
'Ast 1.1.1',
}, --{branchname="Knoten 1.1",
'Ast 1.1',
'Ast 1.2',
'Ast 1.3',
}, --{branchname="Knoten 1",
{branchname="Knoten 2",
'Ast 2.1',
}, --{branchname="Knoten 2",
{branchname="Knoten 3",
'Ast 3.1',
}, --{branchname="Knoten 3",
}
return exampleDurch diese Darstellung ist es möglich, leicht Zeilen zu kopieren und den Überblick über die Verschachtelung zu behalten, ohne Einrückungen machen zu müssen.
Hier wird ein einfaches Beispiel anhand eines SAS-Skriptes dargestellt. Der Vorteil ist, dass die Informationen in Textdateien und nicht binär zur Verfügung stehen. Sie können damit mit einer Skriptsprache ausgewertet werten. Weil Lua eine sehr einfache Skriptsprache ist, wird hier ein Beispiel in Lua vorgestellt.
Ein Programm C:\Temp\githubPGM.sas mit folgendem Inhalt wird in SAS ausgeführt.
Proc Lua; submit;
DocumentationTree='{branchname="Ein Beispiel-Programm", state ="COLLAPSED",'
endsubmit;
run;
Data Test;
Input Zahl1 Zahl2 Text1 $ Text2 $;
Datalines;
1 2 a b
2 3 c d
;
run;
Data Test1;
set Test;
where Zahl1=1;
run;
Proc Lua; submit;
DocumentationTree='}, --{branchname="Ein Beispiel-Programm",'
endsubmit;
run;Das Ergebnis sind die SAS-Tabellen Test und Test1. Die Information über die Verarbeitung, die im Documentation Tree als Baum dargestellt werden kann, ist in dem SAS-Log enthalten. Die Proc Lua-Schritte werden benutzt, um zusätzliche Informationen zu den normalen SAS-Log-Informationen zu schreiben. Insbesondere, wenn eine Serververarbeitung erfolgt, können damit zusätzliche Rückmeldungen erzeugt werden.
Das SAS-Log speichere man in eine Textdatei, z.B. C:\Temp\githubPGM_SAS_Log.txt.
23
24
25 Proc Lua; submit;
26 DocumentationTree='{branchname="Ein Beispiel-Programm", state ="COLLAPSED",'
27 endsubmit;
28 run;
NOTE: Lua initialized.
NOTE: PROCEDURE LUA used (Total process time):
real time 0.32 seconds
cpu time 0.06 seconds
29
30 Data Test;
31 Input Zahl1 Zahl2 Text1 $ Text2 $;
32 Datalines;
NOTE: The data set WORK.TEST has 2 observations and 4 variables.
NOTE: DATA statement used (Total process time):
real time 0.02 seconds
cpu time 0.01 seconds
35 ;
36 run;
37
38 Data Test1;
39 set Test;
40 where Zahl1=1;
41 run;
NOTE: There were 1 observations read from the data set WORK.TEST.
WHERE Zahl1=1;
NOTE: The data set WORK.TEST1 has 1 observations and 4 variables.
NOTE: DATA statement used (Total process time):
real time 0.02 seconds
cpu time 0.03 seconds
42
43 Proc Lua; submit;
44 DocumentationTree='}, --{branchname="Ein Beispiel-Programm",'
45 endsubmit;
46 run;
NOTE: Resuming Lua state from previous PROC LUA invocation.
NOTE: PROCEDURE LUA used (Total process time):
real time 0.00 seconds
cpu time 0.00 secondsMit einem Lua-Skript (C:\Temp\githubPGM_Lua_Skript.lua) kann der Inhalt des SAS-Logs ausgewertet und ein Ergebnis ausgegeben werden, das die Lua-Table für den Baum im Documentation Tree liefert.
for Zeile in io.lines("C:\\Temp\\githubPGM_SAS_Log.txt") do
if Zeile:match("DocumentationTree='.*'") then
print(Zeile:match("DocumentationTree='(.*)'"))
elseif Zeile:match("Input .*;") then
print('{branchname="' .. Zeile:match("Input .*;") .. '",')
elseif Zeile:match("There were %d+ observations read from the data set .*%..*.") then
print('{branchname="' .. Zeile:match("There were %d+ observations read from the data set .*%..*.") .. '",')
elseif Zeile:match("The data set .*%..* has %d+ observations and %d+ variables.") then
print("'" .. Zeile:match("The data set .*%..* has %d+ observations and %d+ variables.") .. "'},")
end --if Zeile:match("DocumentationTree='.*'") then
end --for Zeile in io.lines("c:\\temp\\githubPGM_SAS_Log.txt") doDas Ergebnis wird hier in der Konsole ausgegeben.
{branchname="Ein Beispiel-Programm", state ="COLLAPSED",
{branchname="Input Zahl1 Zahl2 Text1 $ Text2 $;",
'The data set WORK.TEST has 2 observations and 4 variables.'},
{branchname="There were 1 observations read from the data set WORK.TEST.",
'The data set WORK.TEST1 has 1 observations and 4 variables.'},
}, --{branchname="Ein Beispiel-Programm",Kopiert man dieses in eine Datei C:\Temp\githubPGM_Lua_Skript_Baum.lua, kann man diesen Baum mit der Jar-Datei des Documentation Tree starten und darstellen.
example={branchname= "Baumstruktur für Input-Output-Beziehungen in SAS",
{branchname="Ein Beispiel-Programm", state ="COLLAPSED",
{branchname="Input Zahl1 Zahl2 Text1 $ Text2 $;",
'The data set WORK.TEST has 2 observations and 4 variables.'},
{branchname="There were 1 observations read from the data set WORK.TEST.",
'The data set WORK.TEST1 has 1 observations and 4 variables.'},
}, --{branchname="Ein Beispiel-Programm",
} --{branchname= "Baumstruktur für Input-Output-Beziehungen in SAS",
return exampleEine Mischung von automatisch und manuell erstellen Baumteilen ist jederzeit möglich, so dass der Anwender die volle Kontrolle über die Darstellung hat.
Kann die Datei gelesen und geöffnet werden, wird der Inhalt der Datei wie folgt angezeigt:
Beim Klick auf den Button "Markieren" werden Knoten nach folgenden Regeln gefärbt:name: value
-
Der ausgewählte Knoten wird in blau gefärbt.
-
Knoten, deren Text mit dem des ausgewählten Knoten identisch sind, werden blau gefärbt.
-
Knoten über dem ausgewählten Knoten werden rot gefärbt; Knoten über den Knoten von 2. werden grau gefärbt.
-
Knoten unter dem ausgewählten Knoten werden grün gefärbt.
-
Knoten, die mit den Knoten unter 4. identisch sind, werden ebenfalls grün markiert.
Ein Knoten kann selektiert werden, ohne dass die Markierungen aufgehoben werden; dieser wird in gelb hervorgehoben.
Durch einen Klick auf den Button "Markierung zurücksetzen" werden alle gefärbten Knoten in ihren Ursprungszustand zurückgesetzt.