ANALYZE.PL
	Ein Tool für Allegro-Parametrierer

Aufruf
Im folgenden ist nur die Bedienung ohne die TeX-Funktionalität erläutert.
Aufruf perl analyze.pl [<Schalter> ...] [-i|--] <file> [<Optionen> ...]
		Schalter: -d[ebug	.	xdb mit Debugging-Output wird erzeugt
			-i[nput ...	Dateiname für Quelle
			-o[utput ...	Dateipfad/Name für Ausgabe
            -x ...        mehr Schalter und Optionen in Datei 

			-q[uick]	  Nur Produktion von Warnungen u. Index
			-strip[only	  Statistik und Warnungen werden nicht eingehängt
			-ind[ex		  Index wird angehängt

			-r[ecurse	  Einbeziehen des Codes aus Includes
            -unr[ecurse   Includes ausschliessen (dies ist nicht -!recurse)
            -not[inc] ... Auch bei -recurse: Diese Includes nicht einbinden
            -do[inc] ...  Auch ohne -recurse: Diese Includes nicht einbinden
			-y ...		  Zusätzliche Includedatei für Kopf

            -nog[en]      Optionen nicht auswerten
            -reg[en       Optionen reaktivieren
            -var          Zeilenmakros \$(...) erlaubt 

            -src          Eingabe ist "Quelle": Optionen nicht ausgerückt
            -tex          TeXinput: alles anders
            -cfg          Eingabe ist CFG-Datei
            -su[perstrip] keine Kommentare, keine Auswertung

            -touch		  Ausgabedatei mit aktuellem Datum
            -2            zweiten Lauf Anhängen (Indexkorrektur)

            -deb[ug       Debugging-Output .xdb wird erzeugt   
            -mu[te        Keine Ausgabe auf Schirm

Zeilenmakros oder Umgebungsvariable zusätzlich setzen: VAR=Wert

Schalter oder Optionen ausschalten: '!' davorsetzen

Umgebungsvariable: -D; -P; -W; -K; DTDIRS; XDDIRS

		Erzeugt: <file>.xdb	Output zum Debuggen (falls Warnungen oder -deb)
			<file>.tmp	temporäre Datei (falls -deb)
			<file>.xi?	Index (falls nicht -q)
			<file>.xd?	Interner Kurzindex zum Einfügen am Anfang
			<file>.new	Datei mit neuem Kurzindex (falls nicht -tex, -o, -q)

Alle Aufrufoptionen sind im (Rahmen des Sinnvollen) miteinander kombinierbar

---------------------------------------------------------------------
Im folgenden wird davon ausgegangen, dass im Suchpfad eine Datei namens
ANALYZE.BAT existiert, etwa der Form
c:\perl\perl c:\perl\analyze.pl %1 %2 %3 %4 %5 %6 %7 %8 %9
---------------------------------------------------------------------

Beispiel 1:
analyze cat.api

Die Datei cat.api im aktuellen Verzeichnis wird analysiert. Es wird erzeugt 
		cat.new		Variante von cat.api mit Headerzeilen, auch vor 
		            Includebefehlen, falls die zugehörigen .xdt-Dateien 
		            vorhanden waren
		cat.xii		Index
		cat.xdi		Interne Merkdatei: Enthält den Kopf sowie Informationen 
		            für die Indexierung
		cat.xdb		eventuelle Fehlermeldungen



Beispiel 2:
analyze -index -2 cat.api

wie das erste Beispiel, nur wird der Index (cat.xii) an die erzeugte 
Datei cat.new angehängt. Da die im Kopf eingehängten Daten eine variable
Anzahl von Zeilen haben, wird durch den Schalter -2 ein zweiter Durchlauf
gestartet, um die richtigen Zeilennummern für den Index zu produzieren.
(Anmerkung: Es passiert sowieso immer noch ein zusätzlicher Durchlauf
ohne Analyse zu dem Zweck, den Kopf an die richtige Stelle zu hängen)


Beispiel 3:
analyze -y text.txt cat.api

wie das erste Beispiel, nur wird zusätzlich der Text aus text.txt 
in den Kopf von cat.new integriert.


Beispiel 4:
analyze -o .\ c:\allegro\cat.api

die Ausgabedatei ist nicht cat.new im aktuellen Verzeichnis, sondern 
cat.api. Untersucht wird c:\allegro\cat.api. (Aktuelles Verzeichnis
darf nicht c:\allegro sein!)


Beispiel 5:
analyze -o c:\hallo cat.api

die Ausgabedatei ist nicht cat.new im aktuellen Verzeichnis, sondern 
C:\hallo.api (Voraussetzung: c:\hallo ist kein Verzeichnis)


Beispiel 6:
analyze -o c:\tmp cat.api

die Ausgabedatei ist nicht cat.new im aktuellen Verzeichnis, sondern 
C:\tmp\cat.api (Voraussetzung: c:\tmp ist ein Verzeichnis)


Beispiel 7:
analyze -o cat.bla cat.api

die Ausgabedatei ist nicht cat.new im aktuellen Verzeichnis, sondern 
cat.bla


Beispiel 8:
analyze -D c:\allegro\demo -P c:\allegro c:\allegro\cat.api

Für die Analyse von c:\allegro\cat.api werden Includetabellen in 
c:\allegro\demo und c:\allegro (in dieser Reihenfolge) gesucht.
Ist die Umgebungsvariable -P (-D) gesetzt, so erübrigt sich die Angabe 
von -P ... (-D ...) in der Aufrufzeile.


In der Aufrufzeile können Programm-, Daten und Arbeitsverzeichnis 
mit -P, -D und -W abgekürzt werden:

Beispiel 9:
analyze -o .\ -i -P\cat.api

Dabei sei die Umgebungsvariable -P auf C:\allegro initialisiert.
c:\allegro\cat.api wird analysiert, Includetabellen werden in C:\allegro 
gesucht. Die Ausgabedatei ist cat.api im aktuellen Verzeichnis.


Beispiel 10:
analyze -recurse cat.api

Die Ausgabedatei cat.new enthält den Text aller gefundenen Includedateien. 
Die zugehörigen Includebefehle sind auskommentiert.


Beispiel 11:
analyze -recurse -tex cat.api

Die Ausgabedatei cat.api enthält den Text aller gefundenen Includedateien. 
Die zugehörigen Includebefehle sind auskommentiert. Obwohl der Text einer
Includetabelle ABC.APT in diesem Beispiel stets aus der TeX-Datei BLA.DTT
im aktuellen Verzeichnis genommen wird, wird er nur einbezogen, wenn
die entsprechende .APT-Datei in einer der durch -P, -D, -W und . bezeichneten
Pfade vorhanden ist.


Beispiel 12:
analyze -quick cat.api

Keine Ausgabedatei cat.new wird erzeugt.


Beispiel 13:
analyze -touch cat.api

Normalerweise bekommt die Ausgabedatei das Datum der Quelldatei bzw. 
der jüngsten gefundenen Includedatei. Angabe von -touch führt dazu, 
daß die Ausgabedatei auf jeden Fall das aktuelle Datum erhält.


Beispiel 14:
analyze -debug cat.api

Die Ausgabedatei cat.xdb enthält nicht nur evtl. entstandene Warnungen, 
sondern auch die Quelldatei in reduzierter Form. Ausserdem wird die 
Zwischendatei cat.tmp nicht gelöscht.


Beispiel 15:
analyze test.api flaggesetzt

In der Ausgabedatei sind die Zeilen, die von Paaren <*flaggesetzt> 
... </flaggesetzt> umschlossen sind, aktiviert, andere, auf jeden 
Fall aber die, die von Paaren <*!flaggesetzt> ... </!flaggesetzt> 
umschlossen sind, auskommentiert. Gedacht ist dies dazu, mit einer 
Quelldatei mehrere Varianten einer Parameterdatei erzeugen zu können.


Beispiel 16:
analyze -i cat.api -x moreopts.opt

Mehr Schalter und Optionen befinden sich in der Datei MOREOPTS.OPT
(Maximal 9 Kommandozeilenargumente lassen sich bei Einschachtelung 
des Aufrufs in .BAT-Dateien ja nicht angeben).
Falls MOREOPTS.OPT Optionen enthält, muss die Eingabedatei mittels des
-i -Schalters wie im Beispiel VOR dem -x -Schalter auftreten.


Beispiel 17:
analyze -i cat.api -x moreopts.opt !debug

Mehr Schalter und Optionen befinden sich in der Datei MOREOPTS.OPT
Allerdings wird eine in MOREOPTS.OPT eventuell definierte Option "debug"
explizit wieder ausgeschaltet.

------------------------------------------------------------------------

Funktionsweise:

Die Eingabedatei wird geöffnet sowie nach der durch den Schalter |-x|
angegebenen Datei oder aber einer Datei |ANALYZE.OPT| mit zusätzlichen
Schaltern und Optionen im aktuellen Verzeichnis und im Verzeichnis mit
|ANALYZE.PL| gesucht,

Anschließend wird die Eingabedatei zeilenweise nach Allegro-Befehlen 
abgearbeitet. Dabei werden Zuweisungsanweisungen an Zwischenteile 
und Steuerbefehle auf unpaarige Anführungszeichen überprüft. 

Zwischenteildefinitionen werden indexiert.

Start- (und Endezeilen) von Unterprogrammen sowie Sprungmarken und 
die entsprechenden Sprünge und Aufrufe werden indexiert. Am Ende der 
Abarbeitung werden mit den gewonnen Informationen formale Konsistenztests 
(Ende vor Start, Aufruf hinter Start, Sprung zu nicht vorhandener 
Marke etc.) durchgeführt.

Kategoriezeilen werden auf unbalancierte Anführungszeichen durchsucht. 
Relative Sprünge und Manipulation von Anwendervariablen wird indexiert.
Beim Start von Kopf-, Fuß- und Hilfsabschnitt sowie bei Einbindebefehlen 
von Includetabellen und dem Dateiende wird getestet, ob es noch ungesättigte 
relative Sprünge gibt.

Hinter absoluten Sprungbefehlen wird getestet, ob der folgende Code 
von irgendwo angesprungen wird.

Beim Einbinden von Includetabellen wird deren Indexierung bezüglich 
Sprungmarken, Unterprogrammen, Anwendervariablen und Zwischenteilen 
mit einbezogen.

Globale Ersetzungen werden indexiert.

Bei Indexparameterdateien wird in Abhängikeit von den Setzungen der 
i-Parameter in der Quelldatei eventuell das Fehlen bestimmter Sprungmarken 
für Kurztitelliste, Pseudoschlüssel und Tastaturumcodierung moniert.


Kopferzeugung
Nach der Analyse wird die Kopfdatei <file>.xdb weggeschrieben und 
ebenso die diversen Indizes. Die in <file>.tmp befindliche Ausgabedatei 
wird erneut geöffnet und unter Einbeziehung der aktuellen Kopfdatei 
(und eventuell des ASCII-Index <file>.xii erneut weggeschrieben.
Der Kopf wird generell hinter der zweiten Zeile der Parameterdatei 
eingebunden, es sei denn, hinter der zweiten Zeile unmittelbar folgende 
(Kommentar-)Zeilen stimmen auf den ersten vier Zeichen mit dieser 
überein. In diesem Fall werden alle diese Zeilen vor dem Kopf eingesetzt. 
Hinter dem Kopf erscheinen alle diese Zeilen jedoch noch einmal.
Die ersten drei Kopfzeilen enthalten Generierungsinformation (Daten 
und Dateiname), die folgenden eine Auflistung der Sprungmarken, Unterprogramme 
und Anwendervariable, die darauf evtl. folgenden eine Liste der Warnungen.

(Aktive) Kommentare:
Zeilen, die mit
  %%
(zwei Spatien, zwei Prozentzeichen) beginnen, sind generierte Kommentare 
und werden bei nochmaliger Verarbeitung nicht berücksichtigt (so können 
Sie cat.new umbenennen zu cat.api und noch einmal analysieren, die 
resultierende cat.new wird sich nicht unterscheiden).
Eine Ausnahme sind Zeilen, die mit
  %%!
(zusätzlich  !') beginnen, diese werden dennoch übernommen.
Zeilen mit dem Start
 -- 
(Spatium, zwei Bindestriche, Spatium) korrespondieren zu (wg. Aufrufoptionen) 
inaktiven Code. Dieser wird (wegen der Zeilennumerierung in Listings) 
nicht unterdrückt, sondern nur auskommentiert.
Sprungmarkenreservierung:
Zeilen der Form
 !#-X
(exakt ein Leerzeichen vor  !') reservieren die Sprungmarke  X': Wird 
nach dieser Stelle eine Sprungmarke #-X gefunden, so wird eine Warnung 
ausgegeben.

Alle folgenden beginnen mit mit dem Prozentzeichen als erstem Zeichen 
der Zeile

Dokumentationsteile:
%    \end{macrocode}
(exakt vier Leerzeichen zwischen  %' und  \') Die folgenden Zeilen 
bis zur Zeile
%    \begin{macrocode}
werden übersprungen.

Generierungsoptionen:
%<*text>
( 'text' ist ein beliebiges Wort) Die folgenden Zeilen bis
%</text>
werden übersprungen, falls nicht  text' als Aufrufoption angegeben wurde.

%<*!text>
Dasselbe umgekehrt: Die folgenden Zeilen bis
%</!text>
werden übersprungen, falls  text' als Aufrufoption angegeben wurde.

%<*option_1|option_2>
Die Zeilen bis 
%</option_1|option_2>
werden aktiviert, wenn option_1 oder option_2 gesetzt ist.

%<*option_1&option_2>
Die Zeilen bis 
%</option_1&option_2>
werden aktiviert, wenn option_1 und option_2 gesetzt ist.

%<*(option_1&(!option_2)>
Die Zeilen bis 
%</(option_1&(!option_2)>
werden aktiviert, wenn option_1 und nicht option_2 gesetzt ist.

D.h.: Verkuepfungen mit & (und), | (oder) und ! (nicht) sind erlaubt
sowie beliebige Schachtelungen durch runde Klammern.


Zeilenmakros:
Gibt es eine Setzung var=wert (bzw. 
var="Zeichenkette, die auch Spatien enthalten kann"
), so kann wird ein in der (Quelle der) Parameterdatei vorkommender
Ausdruck ${var} durch den Wert ersetzt. Mehrzeilige Zeilenmakros
sind nicht erlaubt.


Struktur der .opt-Dateien:

Die Dateien werden von vorne nach hinten ausgewertet, wobei stets
die letzte Setzung gilt. Man sollte also bei der Formulierung vom
allgemeinen zum speziellen vorgehen.
Es sollte nur ein Zeilenmakro pro Zeile definiert werden.

# Kommentar
# Schalter ist unbedingt gesetzt
-mute
# naechster Schalter nur für Dateien mit Extension .cfg
*.cfg:: -not 2
# Optionen für Generierung (alle Dateien)
bugfix
# für Dateien mit Extension .api ist Zeilenmakro zz auf Leerstring gesetzt
*.api:: zz=""
# für Dateien mit Extension .api ist Option "index" gesetzt
*.api:: index
# für Dateien mit Extension .api ist Option "hallo" gesetzt
*.api:: hallo
# für "a..."-Dateien mit Extension .api ist auch noch Option "abc" gesetzt
a*.api:: abc
# aendert nichts
*.api:: index hallo
# noch ein paar Zeilenmakros
 perreg="1"
 topreg="3"
# "\" muss als "\\" escaped werden!
IL=150
# Setzungen für individuelle Dateien
s-filvbd.apr:: zz="#zz 0"
u-umlenk.apr:: zz=""


Was fehlt:

Nur Kommentare, die mindestens durch drei Leerzeichen vom Anweisungstext 
entfernt sind, werden als solche erkannt. Solche, die nur durch zwei 
Leerzeichen abgetrennt sind, werden fälschlicherweise mit analysiert.

Benutzung von Zwischenteilen als bedingte Postfixe wird nicht indexiert.

Der Analysemechanismus der Anweisungszeilen sollte Teilanweisungen 
analysieren, das wäre intelligenter und würde die beiden erstgenannten 
Defizite beheben.

Dokumentation für die Benutzung als Codeverwaltungssystem.