
\chapter{Curses basierte Programme}

\section{"Ubersicht}

    Eisfair nutzt neben umfangreichen Scriptdateien auch Programme, welche als
    Benutzerinterface die Funktionen der ncurses Programmbibliothek verwenden.
    Diese sind im Verzeichnis \texttt{/var/install/bin} installiert und an der
    Dateiendung .cui erkennbar.

\section{Documentation Viewer - show-doc.cui}

    Zur Anzeige von Dateien im Textformat dient das Programm show-doc.cui.
    Es findet derzeit haupts"achlich Verwendung f"ur die Pr"asentation der
    Paketdokumentation. Eine "uber die Funktionstaste F7 erreichbare
    Suchfunktion erleichtert dabei das Auffinden von Textstellen.

    Ein weiterer Anwendungsbereich f"ur das Programm show-doc.cui ist
    die Verwendung als Protokoll-Viewer. Mit der eingebauten 'tail'
    Funktion zeigt das Programm neue Daten am Ende einer Textdatei in
    Echtzeit an.

    Beim Aufruf von show-doc.cui wird der Name der Textdatei "ubergeben,
    die angezeigt werden soll. Ein *.gz oder *.bz2 Archiv wird dabei
    automatisch extrahiert. Zudem sind eine Reihe von Kommandozeilenoptionen
    verf"ugbar, um das Programm zu beeinflussen:

\begin{verbatim}
	/var/install/bin/show-doc.cui [Optionen] Dateiname
     -c, --color           Programm im Farbmodus ausfuehren
         --nocolor         Programm im S/W-Modus ausfuehren
     -m, --mouse           Maus als Eingabegeraet verwenden
         --nomouse         Keine Maus fuer die Eingabe verwenden
     -v, --version         Programmversion anzeigen
     -t, --title=<titel>   Programmtitel setzen
     -f, --follow          'tail'-Funktion aktivieren
     -h, --help            Hilfe anzeigen
\end{verbatim}

\begin{example}
    Beispiel f"ur die Anzeige einer Datei:
\begin{verbatim}

    /var/install/bin/show-doc.cui /usr/share/doc/foo/foo.txt \
                                  --title="foo program options"

\end{verbatim}
\end{example}

    Neben der eigentlichen Textdatei, die betrachtet werden soll,  kann im
    selben Verzeichnis eine Datei bereitgestellt werden, die ein Inhaltsverzeichnis
    zur Textdatei enth"alt. Dazu muss die Datei den selben Namen wie die anzuzeigende
    Originaldatei tragen, wobei deren Endung (z.B. ''.txt'') gegen die Endung
    ''.toc'' auszutauschen ist. Besitzt die Originaldatei keine Endung, dann wird an
    deren Namen die Endung ''.toc'' angeh"angt.

    Wird beim "Offnen eines Dokuments eine solche ''.toc''-Datei gefunden,
    kann in show-doc.cui das Inhaltsverzeichnis mit der F4-Taste aufgerufen werden.
    Darin ist dann die direkte Navigation zum jeweiligen Kapitel m"oglich.

    Der Inhalt der Indexdatei folgt dem XML-Format, wobei alle Eintr"age
    mit dem Tag ''index'' eingeschlossen werden. Der ''index''-Tag kennt
    zudem das Attribut ''title'', das die "Uberschrift des
    Inhaltsverzeichnisses festlegt.

    Unterhalb des ''index'' Tags werden die Sprungziele mit dem
    Tag ''entry'' eingeleitet. Im Datenbereich zwischen dem "offnenden und
    dem schlie"senden Tag steht dabei der Text der als Kapitel"uberschrift
    angezeigt werden soll. Zudem existieren die beiden Attribute ''line''
    und ''level''. W"ahrend ''line'' die Textzeile in der Originaldatei
    angibt, ab der das jeweilige Kapitel beginnt, gibt ''level'' die Ebene
    der "Uberschrift und damit deren Einr"uckung im Index an.

\begin{example}
    Beispiel f"ur eine .toc Datei:
\begin{verbatim}

<!-- PostgreSQL Table Of Contents -->
<index title="PostgreSQL Eisfair Dokumentation">

    <entry line="36" level="1">1 Allgemein</entry>
    <entry line="66" level="1">2 Installation</entry>
    <entry line="95" level="1">3 Konfiguration</entry>
    <entry line="102" level="2">3.1 Allgemeine Einstellungen</entry>
    <entry line="140" level="2">3.2 Zugriffstabelle</entry>
    <entry line="197" level="2">3.3 Sicherung</entry>
    ...

</index>

\end{verbatim}
\end{example}




\section{File and directory listing tool - list-files.cui}

    Vielfach wird das Auflisten und Ausw"ahlen bestimmter Dateien und
    Verzeichnisse ben"otigt. Dabei m"ussen diese mitunter, an Hand von
    charakteristischen Merkmalen, aus gr"o"seren Best"anden herausgefiltert
    werden. Ein optionaler Abfragedialog leitet nach der Eintragsauswahl
    das Abarbeiten eines externen Scripts ein. \\
    Viele Schalter und Parameter sollen eine m"oglichst flexible
    Verwendung des Programms erlauben:

\begin{verbatim}
    --title=Titel
          Titel des Auswahldialogs
    --column=Spaltenueberschrift
          Ueberschrift der ersten Spalte
    --path=/etc
          zu durchsuchendes Verzeichnis
          (Unterverzeichnisse werden nicht durchsucht)
    --filter="*.conf,*.cfg,*.cnf"
          Optionale Liste mit Platzhaltern zur Einschraenkung
          der aufgelisteten Eintraege. Zulaessig sind:
          ?     1 Zeichen
          *     beliebige Zeichenanzahl
          [0-9] Zeichenmenge
    --only=1
          Optionale Beschraenkung der Anzeige auf:
          1=Dateien
          2=Verzeichnisse
          3=Links
          4=Sockets
    --quest="Restore config from %s ?"
          Optionale Abfrage vor der Scriptausfuehrung. Mit
          %s kann hier der gew"ahlte Dateiname angezeigt werden.
    --script=/run.sh
          Dateiname des Scripts, welches nach der Auswahl ausgefuehrt
          wird. Der ausgewaehlte Name wird als 1. Parameter uebergeben.
    -d    zeigt zusaetzlich Datum und Uhrzeit der letzten Dateiaenderung
    -m    zeigt zusaetzlich die Dateiatribute an
    -n    zeigt zusaetzlich die Groesse an
    -u    zeigt zusaetzlich User und Group der Eintraege an
    -w    wartet nach Abarbeitung des Scripts auf einen Tastendruck
    --helpfile=/var/install/help/foo
          Dateiname der XML-Hilfedatei
    --helpname=FOO_MENU_FILEDIALOG
          XML-Tag der zugehoerigen Hilfe <help name='FOO_MENU_FILEDIALOG'>
    --helpview
          blendet die Hilfe nach dem Programmstart sofort ein

\end{verbatim}

\begin{example}
    Beispiel an Hand des MySQL Datenbank Restore Dialogs:
\begin{verbatim}
    /var/install/bin/list-files.cui \
      --title="Select SQL file" \
      --column="Restore from:" \
      --path=/var/lib/mysql_backup
      --filter="*-????????-[0-2][0-9].sql.gz" \
      --only=1 \
      -d -n -w \
      --quest="Restore database from %s ?" \
      --script="/usr/local/mysql/bin/mysqlrestore.sh $user $pass /var/lib/mysql" \
      --helpfile=/var/install/help/mysql \
      --helpname=MYSQL_MENU_RESTORE \
      --helpview

\end{verbatim}
\end{example}

\section{Curses Frontend f"ur Shell-Scripte - shellrun.cui}

Mit Hilfe des Programms shellrun.cui lassen sich Shell-Scripte mit
Curses-Oberfl"ache schreiben. Das Konzept ist dem Programm
''dialog'' "ahnlich, geht jedoch in sofern dar"uber hinaus, als dass
die Shell-Skripte unter shellrun.cui interaktiv mit der Oberfl"ache
in Verbindung stehen und diese dynamisch beeinflussen k"onnen.

Allerdings ist die Script-API des Programms recht komplex und
darum in eine separate Dokumentation [libcuidoc] ausgelagert.

\begin{example}
Der Aufruf von shellrun.cui kann mit den folgenden Kommandozeilen-
Argumenten erfolgen:
\begin{verbatim}
	/var/install/bin/shellrun.cui [Optionen] Script-Datei
     -o  --args=<Argumente> Argumente, die an die Skriptdatei
                            uebergeben werden sollen
         --debug            Debug-Modus
     -c, --color            Programm im Farbmodus ausfuehren
         --nocolor          Programm im S/W-Modus ausfuehren
     -m, --mouse            Maus als Eingabegeraet verwenden
         --nomouse          Keine Maus fuer die Eingabe verwenden
     -v, --version          Programmversion anzeigen
     -t, --title=<titel>    Programmtitel setzen
     -f, --follow           'tail'-Funktion aktivieren
     -h, --help             Hilfe anzeigen
\end{verbatim}
\end{example}

