10. Curses basierte Programme

10.1. Übersicht

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

10.2. Documentation Viewer - show-doc.cui

Zur Anzeige von Dateien im Textformat dient das Programm show-doc.cui. Es findet derzeit hauptsächlich Verwendung für die Präsentation der Paketdokumentation. Eine über die Funktionstaste F7 erreichbare Suchfunktion erleichtert dabei das Auffinden von Textstellen.

Ein weiterer Anwendungsbereich für 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 übergeben, die angezeigt werden soll. Ein *.gz , *.xz oder *.bz2 Archiv wird dabei automatisch extrahiert. Zudem sind eine Reihe von Kommandozeilenoptionen verfügbar, um das Programm zu beeinflussen:

/var/install/bin/show-doc.cui [Optionen] Dateiname
 -c, --color           Programm im Farbmodus ausführen
     --nocolor         Programm im S/W-Modus ausführen
 -m, --mouse           Maus als Eingabegerät verwenden
     --nomouse         Keine Maus für die Eingabe verwenden
 -v, --version         Programmversion anzeigen
 -t, --title=<titel>   Programmtitel setzen
 -f, --follow          'tail'-Funktion aktivieren
 -h, --help            Hilfe anzeigen

Beispiel für die Anzeige einer Datei:

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

Neben der eigentlichen Textdatei, die betrachtet werden soll, kann im selben Verzeichnis eine Datei bereitgestellt werden, die ein Inhaltsverzeichnis zur Textdatei enthält. 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ängt.

Wird beim Öffnen 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öglich.

Der Inhalt der Indexdatei folgt dem XML-Format, wobei alle Einträge mit dem Tag „index“ eingeschlossen werden. Der „index“-Tag kennt zudem das Attribut „title“, das die Überschrift des Inhaltsverzeichnisses festlegt.

Unterhalb des „index“ Tags werden die Sprungziele mit dem Tag „entry“ eingeleitet. Im Datenbereich zwischen dem öffnenden und dem schließenden Tag steht dabei der Text der als Kapitelüberschrift angezeigt werden soll. Zudem existieren die beiden Attribute „line“ und „level“. Während „line“ die Textzeile in der Originaldatei angibt, ab der das jeweilige Kapitel beginnt, gibt „level“ die Ebene der Überschrift und damit deren Einrückung im Index an.

Beispiel für eine .toc Datei:

<!-- 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>

10.3. File and directory listing tool - list-files.cui

Vielfach wird das Auflisten und Auswählen bestimmter Dateien und Verzeichnisse benötigt. Dabei müssen diese mitunter, an Hand von charakteristischen Merkmalen, aus größeren Beständen herausgefiltert werden. Ein optionaler Abfragedialog leitet nach der Eintragsauswahl das Abarbeiten eines externen Scripts ein.

Viele Schalter und Parameter sollen eine möglichst flexible Verwendung des Programms erlauben:

-t, --title=Titel
        Titel des Auswahldialogs
-c, --column=Spaltenüberschrift
        Überschrift der ersten Spalte
-p, --path=/etc
        zu durchsuchendes Verzeichnis
        (Unterverzeichnisse werden nicht durchsucht)
-f, --filter="*.conf,*.cfg,*.cnf"
        Optionale Liste mit Platzhaltern zur Einschränkung
        der aufgelisteten Einträge. Zulässig sind:
        ?     1 Zeichen
        *     beliebige Zeichenanzahl
        [0-9] Zeichenmenge
-x, --exclude="*.conf,*.cfg"
        Optionale Liste mit Platzhaltern zur Einschränkung
        der aufgelisteten Einträge. Zulässig sind:
        ?     1 Zeichen
        *     beliebige Zeichenanzahl
        [0-9] Zeichenmenge
-o, --only=1
        Optionale Beschränkung der Anzeige auf:
        1=Dateien
        2=Verzeichnisse
        3=Links
        4=Sockets
-d, --date
        zeigt zusätzlich Datum und Uhrzeit der letzten Dateiänderung
-m, --mode
        zeigt zusätzlich die Dateiatribute an
-n, --size
         zeigt zusätzlich die Größe an
-u, --user
         zeigt zusätzlich User und Group der Einträge an
-q, --quest="Restore config from %s ?"
        Optionale Abfrage vor der Scriptausführung. Mit
        %s kann hier der gewählte Dateiname angezeigt werden.
-s, --script=/run.sh
        Dateiname des Scripts, welches nach der Auswahl ausgeführt
        wird. Der ausgewählte Name wird als 1. Parameter übergeben.
-w, --wait
        wartet nach Abarbeitung des Scripts auf einen Tastendruck
    --helpfile=/var/install/help/foo
        Dateiname der XML-Hilfedatei
    --helpname=FOO_MENU_FILEDIALOG
        XML-Tag der zugehörigen Hilfe <help name='FOO_MENU_FILEDIALOG'>
    --helpview
        blendet die Hilfe nach dem Programmstart sofort ein
    --color
        Programm läuft im Farbmodus
    --nocolor
        Programm läuft im schwarz/weiss Modus
    --mouse
        Mausbenutzung ist möglich
    --nomouse
        Mausbenutzung ist nicht möglich
-v, --version
        Zeigt die Programm Version
-h, --help
        Zeigt diese Hilfe

Beispiel an Hand des MariDB/MySQL Datenbank Restore Dialogs:

/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/bin/mysqlrestore.sh $user $pass /var/lib/mysql" \
  --helpfile=/var/install/help/mariadb \
  --helpname=MARIADB_MENU_RESTORE \
  --helpview

10.4. Curses Frontend für Shell-Scripte - shellrun.cui

Mit Hilfe des Programms shellrun.cui lassen sich Shell-Scripte mit Curses-Oberfläche schreiben. Das Konzept ist dem Programm „dialog“ ähnlich, geht jedoch in sofern darüber hinaus, als dass die Shell-Skripte unter shellrun.cui interaktiv mit der Oberfläche in Verbindung stehen und diese dynamisch beeinflussen können.

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

Der Aufruf von shellrun.cui kann mit den folgenden Kommandozeilen-Argumenten erfolgen:

/var/install/bin/shellrun.cui [Optionen] Script-Datei
-o  --args=<Argumente> Argumente, die an die Skriptdatei
                            übergeben werden sollen
    --debug            Debug-Modus
-c, --color            Programm im Farbmodus ausführen
    --nocolor          Programm im S/W-Modus ausführen
-m, --mouse            Maus als Eingabegerät verwenden
    --nomouse          Keine Maus für die Eingabe verwenden
-v, --version          Programmversion anzeigen
-t, --title=<titel>    Programmtitel setzen
-f, --follow           'tail'-Funktion aktivieren
-h, --help             Hilfe anzeigen