dmenuLauncher ist ein Programmstarter, der dmenu nutzt um ein Programm auszuwählen. Die Grundfunktionalität ist im Artikel Ein leichtgewichtiger Launcher mit dmenu und Perl beschrieben. Das Skript habe ich auf GitHub hochgeladen.

Das Script wurde um folgende Punkte erweitert:

• Ob ein Programm im Terminal gestartet werden soll wird nun mitgespeichert
• Es können optional auch Argumente für ein Programm gespeichert werden
• Es kann ein String definiert werden, der immer vor dem Befehl eingefügt wird
• Es gibt eine (englische) readme, in der alle Funktionen beschrieben sind

Starten im Terminal
Wird dem Programmaufruf ein ; angehängt, so wird damit zwischen “im Terminal ausführen” und “direkt ausführen” hin und hergeschaltet. Die jeweils letzte Einstellung wird für zukünftige Aufrufe gespeichert.

Beispiel: Ich gehe von davon aus, dass die pathfile gerade generiert wurde, also alle Programme immer direkt ausgeführt werden.

• firefox – führt firefox direkt aus
• firefox; – führt firefox im Terminal aus
• firefox – führt firefox im Terminal aus (weil dies beim obigen Aufruf für die Zukunft gespeichert wurde)
• firefox; – führt firefox direkt aus
• firefox – führt firefox direkt aus (weil dies beim obigen Aufruf für die Zukunft gespeichert wurde)

Möchte man wirklich ein ; an einen Befehl anhängen ohne die Option “Starten im Terminal” zu verändern, kann man dies mit einem \ escapen.

Also: programm\;

Speichern von Argumenten
Es gibt nun eine Konfigurationsvariable SAVE_ARGUMENTS. Ist diese auf 1 gesetzt, werden automatisch alle Argumente gespeichert. Das bedeutet, dass in der Liste der Programme, aus denen man wählen kann das entsprechende Programm einmal ohne Argumente und jeweils einmal mit Argument aufgeführt wird.

dmenuLauncher im vertikalen Modus mit Argumenten

Für jedes Argument eines Befehls wird auch die Anzahl der Aufrufe gespeichert, so dass häufig genutzte Argumente weiter vorne stehen.

Man kann die Variable SAVE_ARGUMENTS für einen Aufruf umschalten, indem man einen . an den Programmaufruf anhängt.

Beispiel: free -m.

• Ist die Variable SAVE_ARGUMENTS auf 1 gesetzt, so wird das Argument -m nicht gespeichert (ohne den . am Ende würde es gespeichert werden)
• Ist die Variable SAVE_ARGUMENTS auf 0 gesetzt, so wird das Argument -m gespeichert (ohne den . am Ende würde es nicht gespeichert werden)

Bei der Optimierung werden Programme, zu denen Argumente gespeichert sind grundsätzlich nicht entfernt.

Möchte man wirklich einen . an einen Befehl anhängen ohne die Option “Speichern von Argumenten” zu verändern, kann man ihn mit einem \ escapen.

Also: programm\.

Man kann . und ; nicht gleichzeitig bei einem Aufruf verwenden.

[UPDATE] Ich habe als Trenner für mehrere Argumente in der pathfile die Zeichenfolge ||| genutzt und zum Trennen der Argumente und der jeweiligen Anzahl der Aufrufe die Zeichenfolge |#|. Leerzeichen sind hier nicht möglich, da diese auch in den Argumenten vorkommen dürfen sollen. Falls jemand einen Fall kennt, wo diese Trenner problematisch wären oder grundsätzlich eine bessere Idee hat würde ich mich über einen entsprechenden Kommentar freuen [/UPDATE]

String vor dem Befehl
In der Variable BEFORE_COMMAND kann man einen String definieren, der vor dem Befehl eingefügt wird. Ein Anwendungszweck wäre das Wechseln ins Home-Verzeichnis, so dass alle Befehle im Home-Verzeichnis ausgeführt werden.
Dafür setzt man BEFORE_COMMAND auf "cd ~ && ". Dies ist auch die default Einstellung.

Natürlich kann man auch einen leeren String angeben, damit nichts vor dem eigentlichen Befehl eingefügt wird.

Die Readme
Die Readme findet man, wenn man die Datei dmenuLauncher.pl mit einem Texteditor öffnet.

Ich habe nun noch ein kleines Script – dmenuLauncher.pl – geschrieben, das die Programme nach Häufigkeit ihrer Aufrufe sortiert, damit die am häufigsten genutzten Programmen immer zuerst gewählt werden, wenn es eine Mehrdeutigkeit gibt.

Features:

• Kleines Perl-Script, dass nur bei Bedarf gestartet wird und sonst weder Prozessorzeit noch RAM benötigt
• Kann in den meisten Fenstermanagern über Tastenkombination gestartet werden
• Programmen können beim Aufruf Argumente übergeben werden
• Sortiert Programme nach Nutzungshäufigkeit
• Horizontale oder vertikale Anzeige der Programmliste
• Programme im Terminal öffnen
• Optimierung der Programmliste (löschen aller Programme mit geringer Aufrufsanzahl aus der Liste)
• Einfaches hinzufügen von Programmen, die nicht in der Liste sind

dmenuLauncher mit horizontaler Anzeige der am häufigsten aufgerufenen Programme

Das Script habe ich auf gitHub online gestellt. Das Programm dmenu kann unter Ubuntu über das Paket dwm-tools installiert werden. Also mit dem Befehl sudo apt-get install dwm-tools.

Die Datei dmenuLauncher.pl hat im oberen Teil einen Konfigurationsbereich. Ich habe auf eine externe Konfigurationsdatei verzichtet um diese nicht jedes Mal laden zu müssen.

Zuerst wird der Pfad zur path-Datei (in der die Liste der Programme mit ihrer jeweiligen Aufrufanzahl gespeichert wird) in der Variablen PATHFILE angegeben.

dmenu kann die Programme im Menü nebeneinander oder untereinander angezeigen. Dafür kann man dmenuLauncher.pl entweder mit der Option -h für horizontal (also nebeneinander) oder -v für vertical (also untereinander) aufrufen.

Den Standardmodus, der genutzt wird, wenn nichts angegeben wurde kann man über die Variable MODE steuern. Sie wird entweder auf horizontal oder vertical gesetzt.

dmenuLauncher mit vertikaler Anzeige der Programme mit "gnome" im Namen

Die Konfigurationsvariable NUMBER_OF_LINES gibt die Anzahl von anzuzeigenden Zeilen im vertical-Modus an.

In der Variablen TERMINAL wird der Befehl für den Terminalaufruf gespeichert. Der Platzhalter %COMMAND% wird durch das aufzurufende Kommando (mit Argumenten) ersetzt.

Nun kann durch den Aufruf dmenuLauncher.pl -u die path-Datei generiert werden. Nach dem Installieren oder Löschen von Programmen kann die Datei so auch aktualisiert werden.

Nachdem man dmenuLauncher.pl konfiguriert und die path-Datei (mit der Option -u) generiert hat, kann man eine Tastenkombination dafür einrichten. Bei GNOME unter System -> Einstellungen -> Tastenkombinationen auf den Button “Hinzufügen” klicken, als Namen “dmenuLauncher” und als Befehl den Pfad zur Perldatei (dmenuLauncher.pl) angeben. Nun gibt es in der Liste ganz unten einen neuen Eintrag. Klickt man auf das Feld “Tastenkombination”, so kann man die gewünschte Tastenkombination drücken (ich habe SHIFT+<Space> gewählt, die dann dem Script automatisch zugeordnet wird.

Nach dem Starten des Programms (also drücken der zugeordneten Tastenkombination oder per Terminal) öffnet sich nun das Menü und zeigt die Programmliste an. Nun fängt man an, den gewünschten Befehl einzutippen bis er markiert ist. Man kann auch die Pfeiltasten benutzen. Mit der Eingabetaste wird das gewählte Programm ausgeführt und dmenuLauncher geschlossen.

Drückt man nicht direkt die Eingabetaste sondern <Tab>, so wird der Befehl vervollständigt und man kann noch Argumente angeben.

Ob mit ohne ohne Argumente: Durch ein abschließendes Semikolon wird der Befehl im Terminal ausgeführt.

Ein paar Beispiele:

• firef<ENTER> öffnet Firefox
• firef<Tab> http://zinformatik.de<ENTER> öffnet firefox und geht auf die Seite “http://zinformatik.de”
• top;<ENTER> öffnet top in einem Terminal
• ls -lh ~;<ENTER> zeigt das Ergebnis von ls -lh ~ in einem Terminal an.

Da die ganze Liste von Programmen sehr groß ist, man jedoch meist nur einen sehr kleinen Teil nutzt gibt es die Möglichkeit die Liste der Programme zu optimieren. Durch den Aufruf von dmenuLauncher.pl -o werden alle Programme aus der Liste entfernt, die noch nie genutzt wurden. Ein weiteres Argument gibt die Anzahl der Aufrufe an, die ein Programm mindestens haben sollte. So werden durch dmenuLauncher.pl -o 3 alle Programm aus der Liste entfernt die weniger als 3 mal aufgerufen wurden.

Möchte man nach der Optimierung ein Programm aufrufen, das sich nicht mehr in der Liste befindet, so kann man es einfach komplett eingeben. Auch wenn es dann keine Auswahl gibt, wird das Programm ausgeführt und mit der Aufrufsanzahl 1 in die Liste gespeichert.
Um ein neues Programm in die Liste aufzunehmen braucht man es also nur einmal eingeben.

Mit dmenuLauncher habe ich also ein sehr kleines Programm, welches nur kurz läuft um mir die Auswahl eines Programms zu ermöglichen und danach sofort wieder beendet wird. Das Laden ist auch auf älteren Systemen kaum zu spüren, weil keine Bibliotheken geladen werden. Das bedeutet ich kann jedes häufiger genutzte Programm mit 3-4 Tastendrücken ohne irgendeine Verzögerung starten.

Beispiel:

#!/usr/bin/perl
 
use strict;
use warnings;
 
sub divide {
    my ($x,$y) = @_;
    return $x/$y;
}
 
sub printDivision {
    my ($x,$y) = @_;
    print "$x durch $y = ".divide($x,$y)."\n";
}
 
sub divideList {
    my $x = shift;
    my $listReference = shift;
    my @list = @{$listReference};
    foreach my $i(@list){
        printDivision($x,$i);
    }
}
 
 
my @divList1 = (22,7,16);
my @divList2 = (2,5,33,50,0,7,65);
divideList(100,\@divList1);
 
# do something else ...
 
divideList(100,\@divList2);

Zugegeben ist dies ein recht künstlich konstruiertes Beispiel, jedoch ist es nicht leicht ein möglichst einfaches und gleichzeitig realistisches Beispiel zu finden. Die Funktion divide dividiert zwei übergebene Zahlen ohne überprüfung, ob durch 0 dividiert wird. printDivision nutzt diese Funktion um das Ergebnis einer Division auszugeben. Die Funktion divideList bekommt eine Zahl und eine Referenz zu einer Liste übergeben, durch die die Zahl jeweils geteilt und das Ergebnis mit der Funktion printList ausgegeben werden soll. Schließlich wird die Funktion divideList erst mit einer Liste ohne 0 und dann mit einer Liste aufgerufen, in der eine 0 vorkommt.

Die Ausgabe des Programms ist:

100 durch 22 = 4.54545454545455
100 durch 7 = 14.2857142857143
100 durch 16 = 6.25
100 durch 2 = 50
100 durch 5 = 20
100 durch 33 = 3.03030303030303
100 durch 50 = 2
Illegal division by zero at ./test.pl line 8.

Wenn man die beiden Lisen jetzt nicht direkt so vor Augen hat (weil sie z.B. während des Ablaufs generiert werden), kann man schwer sagen, welcher Funktionsaufruf den Fehler verursacht hat. Man weiß nur, dass der Fehler in Zeile 8 lag. Auch wenn der Fehler abgefangen wird, kommen wir nicht an die Stelle, an der der falsche Parameter ins Spiel gekommen ist.

Ein Stacktrace kann da ein wenig Abhilfe schaffen. Nutzt man das Modul Carp, so kann man die Funktionen warn und die mit carp und croak überschreiben und bekommt nun zusätzlich einen Stacktrace. Dafür werden die beiden folgenden Zeilen an den Anfang des Programms eingefügt:

use Carp;
$SIG{__DIE__} = sub {croak shift;};

Die Ausgabe sieht nun so aus:

100 durch 5 = 20
100 durch 10 = 10
100 durch 33 = 3.03030303030303
100 durch 50 = 2
Illegal division by zero at ./test.pl line 9.
 at ./test_croak.pl line 5
        main::__ANON__('Illegal division by zero at ./test_croak.pl line 9.\x{a}') called at ./test.pl line 9
        main::divide(100, 0) called at ./test.pl line 15
        main::printDivision(100, 0) called at ./test.pl line 22
        main::divideList(100, 'ARRAY(0x87d6d28)') called at ./test.pl line 34

Bei einer Warnung kann das Programm zwar noch weiter ausgeführt werden, doch sind die Ergebnisse dann in der Regel falsch (vor allem wenn die Warnung wegen einer nicht initialisierten Variablen auftritt). Daher kann es sinnvoll sein die Funktion warn mit croak zu überschreiben, so dass das Programm auch bei einer Warnung abbricht.

Noch praktischer wäre es natürlich, wenn man nun noch die Elemente der Liste kennen würde, mit deren Referenz die Funktion divideList aufgerufen wurde.

Daher habe ich ein kleines Modul entwickelt (die Grundidee stammt aus einem Perl-Buch), welches noch etwas mehr kann. Das Modul DebugMessages gibt bei einem Fehler einen Stacktrace aus, wobei die aktuellen Parameter des Aufrufs mit ausgegeben werden. Auf Wunsch werden werden auch Inhalte von Listen und Hashes ausgegeben.
Zusätzlich wird der Quelltext mit ausgegeben und zwar ab n Zeilen über der Zeile, die den Fehler erzeugt hat bis n Zeilen danach. (Die Anzahl der Zeilen n kann beliebig gewählt werden). Die Zeile mit dem Fehler wird dabei markiert.

Das Modul kann folgendermaßen eingebunden werden:

use lib "path/to/module";
use DebugMessages exit_on_warning => 1, errors => 3, warnings => 3, level => 5, verbose => 1;

Die Pfadangabe "path/to/module" muss natürlich auf das Verzeichnis zeigen, in dem die Datei DebugMessages.pm liegt.

Die einzelnen Parameter haben dabei folgende Bedeutung:

• exit_on_warning: Wenn dieser Parameter 1 ist bricht das Programm schon bei einer Warnung ab. (Default ist 0)
• errors: Anzahl der Zeilen, die jeweils vor und nach der Zeile ausgegeben werden sollen, die einen Fehler produziert hat. -1 deaktiviert DebugMessages für Fehler. (Default ist 3)
• warnings: Anzahl der Zeilen, die jeweils vor und nach der Zeile ausgegeben werden sollen, die eine Warnung produziert hat. -1 deaktiviert Default für Warnungen. (Default ist 3)
• level: Anzahl der Rekursionslevel für den Stacktrace. (Default ist 3)
• verbose: 1 zeigt den Inhalt von Listen und Hasheses in kompakter Schreibweise an. 2 Zeigt den Inhalt ausführlich an. 0 deaktiviert das Ausgeben von Listeninhalten.

Die Fehlermeldung des obigen Beispiels sieht ist nun sehr ausführlich:

100 durch 22 = 4.54545454545455
100 durch 7 = 14.2857142857143
100 durch 16 = 6.25
100 durch 2 = 50
100 durch 5 = 20
100 durch 33 = 3.03030303030303
100 durch 50 = 2
 
Error: Illegal division by zero at ./test.pl line 11.
 
   0008:
   0009: sub divide {
   0010:     my ($x,$y) = @_;
 * 0011:     return $x/$y;
   0012: }
   0013:
   0014: sub divideAll {
 
-------------------------------------
Verbose output of parameters for call of main::divide
100
0
-------------------------------------
 
   main::divide(100,0) called at line 33 in file ./test.pl (package main):
     0030:
     0031: sub printDivision {
     0032:     my ($x,$y) = @_;
   * 0033:     print "$x durch $y = ".divide($x,$y)."\n";
     0034: }
     0035:
     0036: sub divideList {
 
-------------------------------------
Verbose output of parameters for call of main::printDivision
100
0
-------------------------------------
 
     main::printDivision(100,0) called at line 41 in file ./test.pl (package main):
       0038:     my $listReference = shift;
       0039:     my @list = @{$listReference};
       0040:     foreach my $i(@list){
     * 0041:         printDivision($x,$i);
       0042:     }
       0043: }  
       0044:
 
-------------------------------------
Verbose output of parameters for call of main::divideList
100
0..6  2 5 33 50 0 7 65
-------------------------------------
 
       main::divideList(100,ARRAY(0x9ff2528)) called at line 52 in file ./test.pl (package main):
         0049:
         0050: # do something else ...
         0051:  
       * 0052: divideList(100,\@divList2);

So kann man den Fehler über alle Funktionsaufrufe zurückverfolgen ohne in den Editor wechseln zu müssen. Man hat ja auch den Kontext des Quellcodes vor Augen.

Zusätzlich wurde noch eine kleine Verschönerung für die Ausgabe von Listen hinzugefügt. Mit eingebundenem Modul kann man Listen folgendermaßen ausgeben:

my @list = ("Hallo Welt", "a", "b",1,2,3);
print "[@list]\n";

Statt der normalen Ausgabe:

[Hallo Welt a b 1 2 3]

bei der man nicht erkennen kann, wie viele Elemente die Liste enthält, bekommt man mit eingebundenem DebugMessages Modul folgende Ausgabe:

[Hallo Welt] [a] [b] [1] [2] [3]

Das Modul DebugMessages habe ich bei GitHub hoch geladen. Die Adresse ist: http://github.com/zimon/DebugMessages

Ein solches “Erinnerungsprogramm” kann man sich recht leicht selber basteln. Ich habe dafür das Linuxtool at mit dem Programm zenity, welches Dialoge darstellen kann, kombiniert.

at (bzw. der at-Daemon atd) ist auf den meisten Linuxdistributionen bereits vorhanden, kann sonst aber auch über die Paketverwaltung installiert werden. Zenity sollte bei den meisten Distributionen ebenfalls über die Paketverwaltung installierbar sein.
Unter Ubuntu installiert man zenity mit dem Befehl:

sudo apt-get install zenity

Mit at können Befehle zu einem festgelegten Zeitpunkt ausgeführt werden. Eine sehr schöne Einführung gibt es in der Ausgabe 10/2008 von freiesMagazin (eine Fortsetzung ist in der nachfolgenden Ausgabe enthalten, welche mich auch zu diesem “Programm” inspirierte, weil ich mit den dort vorgestellten Erinnerungs-Lösungen nicht zufrieden war).

Um mit zenity einen Dialog anzuzeigen kann man folgenden Befehl nutzen:

zenity --info --title="Titel des Dialogs" --text "Text, der angezeigt werden soll"

Damit dies von at angezeigt werden kann muss noch das Display angegeben werden:

zenity --info --title="Titel des Dialogs" --text "Text, der angezeigt werden soll" --display=:0

Diesen Befehl kann man nun in ein Bash- oder Perl-Script einfügen, wobei der Titel fest sein kann und der Text als Argument übergeben wird. Ich habe mich für Perl entschieden:

#!/usr/bin/perl
 
system("zenity --info --title=\"Erinnerung\" --text \"@ARGV\" --display=:0");

Dieses Script habe ich unter dem Namen r (für “remember”) im bin-Ordner meines Homeverzeichnisses gespeichert. Dieses muss natürlich im Pfad liegen, was durch folgende Zeile in der Datei ~/.bashrc erreicht werden kann:

export PATH=$PATH:/home/user/bin

“user” muss natürlich durch den entsprechenden Usernamen ersetzt werden. Nachdem man die ~/.bashrc mit dem Befehl

. ~/.bashrc

neu “geladen” hat kann man sich nun an Termine oder andere Dinge erinnern lassen.

Beispiele:
Um 14:30 Termin bei FooBar. Also um 14:15 erinnern:

at 14:15
r Termin bei FooBar in 15 Minuten
Strg+d

In einer halben Stunde ist eine Besprechung (5 min vorher erinnern):

at now +25min
r Besprechung
Strg+d

Es öffnet sich zur angegebenen Zeit ein Dialogfenster (egal, was man gerade macht – solange man sich in X befindet. Bei Spielen im Fullscreen habe ich es jedoch nicht getestet.), welches den Titel “Erinnerung” enthält und den angegebenen Text ausgibt. Das Fenster kann durch einen Klick auf “OK” wieder geschlossen werden.

at bietet noch viele weitere Möglichkeiten eine Zeit anzugeben. Diese werden im (ersten) oben verlinkten freiesMagazin-Artikel beschrieben.

NaturalDocs Dokuementation des zBot

Sehr schön an NaturalDocs ist, dass die Dokumentation sehr nahe an natürlichsprachlichem Plaintext ist und sich die Beschreibungen von Klassen oder Methoden auch sehr gut aus den Quellen lesen lässt ohne dass man die Syntax von NaturalDocs kennen muss. Auch einfache Textdateien wie eine Readme oder ähnliches können damit erstellt werden. So kann man (zumindest bei kleineren Projekten) sogar sämtliche Dokumente wie Anforderungen, UML-Diagramme, … mit NaturalDocs erstellen, wodurch man alle Informationen an einem Ort gebündelt und in einem einheitlichen Format vorliegen hat.

Das Perl-Tool versteht auch JavaDoc, so dass eine Umstellung erleichtert wird.

Gestartet wird NaturalDocs mittels:
NaturalDocs -i [input (source) directory]
-o [output format] [output directory]
-p [project directory]
[options]
wobei ich mir ein kleines Script zum erstellen/aktualisieren der Dokumentation erstellt habe, welches ein Changelog beinhaltet, welches aus einem svn log automatisch generiert wird. Das Script habe ich unten angehängt.

Ein Beispiel in perl:

# SUB: multiplicate
# 
# multiplicates two numbers
# 
# PARAMETERS:
# $a - first parameter
# $b - second parameter
#
# RETURNS:
# the product of $a and $b
sub multiplicate {
    $a=shift;
    $b=shift;
    return $a*$b;
}

So sieht die Dokumentation einer einfachen Funktion aus. Bei Sprachen die full language support besitzen (bisher perl, ActionScript und C#) kann auch eine JavDoc-artige Dokumentation genutzt werden:

##
# multiplicates two numbers
# 
# PARAMETERS:
# $a - first parameter
# $b - second parameter
#
# RETURNS:
# the product of $a and $bsub multiplicate {
    $a=shift;
    $b=shift;
    return $a*$b;
}

Beide Beispiele haben das selbe Ergebnis:

NaturalDocs Beispiel

Listen können erstellt werden, indem eine Zeile mit “-” angefangen wird. Definitionen haben ein “-” zwischen Bezeichner und Definition. Es können auch Grafiken, Beispielquelltexte und ASCII-Diagramme eingefügt werden.

Leider kann NaturalDocs von Haus aus nicht mit Listen in Listen umgehen, doch dafür gibt es einen Patch: Nested Bullets, womit man durch + oder * eine Liste in der Liste einleitet.
Installiert wird es, indem die Datei Native.pm.diff nach $NATURALDOCS_PATH/Modules/NaturalDocs/Parser Kopiert wird und dann der Befehl

patch Native.pm Native.pm.diff

aufgerufen wird.

Einen neuen Absatz erzwingt man durch eine Leerzeile. Eine Überschrift kann mittels # Überschrift: eingefügt werden, wobei die Zeile darüber leer sein muss.
Es kann auch auf Webseiten, Emailadressen und andere Stellen der Dokumentation verlinkt werden.
Natürlich kann auch unterstrichen und fett geschrieben werden. Die Zusammenfassung wird automatisch erstellt.

Cool ist auch die Möglichkeit der Abkürzung, womit man mehrere Defines, Funktionen oder Variablen zusammenfassend dokumentieren kann. So kann man statt dem folgenden Code

# VARIABLE: $configFile
# Filename of configuration file
$configFile = "config.txt";
 
# VARIABLE: $inputFile
# Filename of input file
$inputFile = "input.txt";
 
# VARIABLE: $outputFile
# Filename of output file
$outputFile = "out.txt";

die Variablen für die Dateinamen zusammen fassen:

# VARIABLES: Filenames
# $configFile - Filename of configuration file
# $inputFile - Filename of input file
# $outputFile - Filename of output file
$configFile = "config.txt";
$inputFile = "input.txt";
$outputFile = "out.txt";

Dabei können mehrere solcher Blöcke für verschiedene Belange angelegt werden (z.B. Dateinamen, Logindaten für Datenbank, …). Das Ergebnis sieht dann so aus:

NaturalDocs - Variablen zusammenfassend dokumentiert

Auch mein Jabber Bot zBot ist mit NaturalDocs dokumentiert. Als Beispiel kann man sich dessen Dokumentation ansehen.

Für Neulinge gibt es ein schönes Walktrough, wo die ersten Schritte mit NaturalDocs erklärt werden.

Hier noch das Script, welches eine von NaturalDocs lesbare Changelist im Ordner documents und dann die Dokumentation selbst erstellt:

#!/usr/bin/perl
 
# Script: makedocs.pl
#
# This script generates the documentation.
#
# Requirements:
#
# - NaturalDocs path must be in ENV variable $NATURALDOCS_PATH
# - Projectdirectory naturaldocs has to be in the same directory as this script
# - There must be a (empty) directory documentation in the same directory as this script
#
# Usage:
#
# Just start this script when something has changed or use the script <make.pl>
#
# > tools/makedocs.pl [OPTIONS]
#
# Options:
#
#  -o - start makedocs.pl in offline modus
#
# In offlinemode the changelog is not generated
#
#
# SVN:
#
# Commit only the textfiles of the projectdirectory (Not the directory "Data") from NaturalDocs.
#
# The documentation directory should be an empty dir in SVN.
#
# So everybody can create the documentation by himself just by executing this script.
 
use strict;
use warnings;
use vars qw (%ENV);
 
# Sub: generatechangelog
#
# Generates documents/changelog.txt from svn log -v
#
sub generatechangelog {
    print "Generating changelog...n";
    $ENV{LANG} = "C";
    my $log = `svn log -v`; 
 
    $log =~ s/(-){2,}//g;
    $log =~ s/(r[0-9]{1,4})/$1:nn$1/g;
    $log =~ s/n/nn/g;
    $log =~ s/Pfade:/Pfade/g;
    $log =~ s/paths:/paths/g;
    $log =~ s/([A-Z] /)/- $1/g;
 
    open(DATEI, ">documents/changelog.txt");
    print DATEI "Title: Changelognn$log";
    close DATEI;
    print "Done.n";
}
 
######### PROGRAM START ############
 
if (defined $ENV{NATURALDOCS_PATH} && $ENV{NATURALDOCS_PATH} ne "") {
    generatechangelog() if (not(defined @ARGV && $ARGV[0] eq "-o"));
# Generate documentation of current directory in HTML and save to directory documentation. Projectdirectory is naturaldocs.
# Ignore directory tests
    system
"$ENV{NATURALDOCS_PATH}/NaturalDocs -i . -o HTML ./documentation -p ./naturaldocs -xi ./tests";
} else {
    print "Environment variable $NATURALDOCS_PATH not defined!n";
}

perl -e 'print "Hello World!\n"'

Um jede print-Anweisung mit einem “newline” abzuschließen, kann man zusätzlich die Option -l benutzen:

perl -l -e 'print "Hello World!"; print "Hello Ubuntuusers!"'

Um eine Datei Zeile für Zeile durchzugehen, gibt es die Option -n. Das Program beschreibt dann ähnlich wie bei awk was mit jeder Zeile geschehen soll:

perl -n -l -e 'print $_ if $_ =~ /foo/"' datei.txt

gibt alle Zeilen aus, die “foo” enthalten.
Die Option -n entspricht folgendem Code:

while(<>){
    # Der Code, der übergeben wird
}

Die Option -a bringt perl noch einen Schritt näher zu awk. Damit werden die Wörter einer Zeile (die durch Leerzeichen getrennt sind) in das Array @F geladen. Den Worttrenner kann man mit der Option -F setzen:

perl -n -a -F; -e 'print $F[$#F]' datei.csv

gibt von jeder Zeile das letzte Element einer csv (Comma Separated Value) Datei aus.
Dies entspricht folgendem Code:

while(<>){
    @F = split($pattern);
    # Der übergebene Code
}

wobei $pattern das mit -F übergebene Pattern (im obigen Beispiel ";") ist. Dadurch sind auch reguläre Ausdrücke wie -F/[0-9]+/ möglich.

Es können auch die Schlüsselwörter BEGIN und END gesetzt werden um einen Block vor oder nach der Hauptschleife auszuführen:

perl -n -l -a -e 'BEGIN{$x=0} {$x+=$F[$#F]} END{print $x}' preisliste.txt

errechnet den Gesammtpreis einer Preisliste, in der am Ende jeder Zeile der Preis steht. Es wird also von jeder Zeile das letzte Wort addiert. Man könnte das Programm jetzt auch noch etwas kürzer schreiben:

perl -nlae '$x+=$F[$#F]; END{print $x}' preisliste.txt

Dies entspricht dem awk-Programm:

awk '{x+=$NF} END{print x}' preisliste.txt

Für das Suchen und Ersetzen mit Regulären Ausdrücken eignet sich die Option -p. Diese Funktioniert genau wie -n mit dem Unterschied, dass jede Zeile automatisch ausgegeben wird. So kann man wie mit sed Dateien ändern:

perl -pe 's/foo/bar/g' datei.txt > datei_new.txt

ersetzt jedes Vorkommen von “foo” durch “bar” und schreibt das Ergebnis in die Datei “datei_new.txt”.

Um die Datei direkt zu ändern, kann man die Option -i verwenden. Dieser kann optional ein String mitgegeben, der an den verwendeten Dateinamen angehängt den Dateinamen einer anzulegenden Sicherheitskopie ergibt:

perl -pi -e 's/foo/bar/g' *.txt
perl -pi.orig -e 's/foo/bar/g' datei.txt

Beim ersten Befehl jede Text-Datei im aktuellen Verzeichnis direkt geändert. Beim zweiten wird die “datei.txt” nach “datei.txt.orig” kopiert bevor jedes Vorkommen von “foo” durch “bar” ersetzt wird. (Man kann natürlich auch mit dem 2. Befehl beliebig viele Dateien bearbeiten, wenn man * benutzt.)

Module
Die Option -M erlaubt es einem beliebige Module einzubinden, die dann im Programm benutzt werden können. So kann man z.B. mit dem folgenden Befehl mit dem Modul LWP::Simple eine Webite laden und den HTML-Code ausgeben:

ls | perl -MLWP::Simple -e 'getprint("http://zinformatik.de")'

Mit dem folgenden Befehl werden von allen iso Dateien im Verzeichnis MD5-Summen erstellt:

ls *.iso | perl -MDigest::MD5 -nle 'open(FILE,$_); $d=Digest::MD5->new; $d->addfile(FILE); print $d->hexdigest'

Fazit
Für kleinere kosmetische Änderungen eines Textes oder einer Ausgabe sowie zum extrahieren von Informationen daraus ist awk meist besser geeignet. Bei komplexeren Aufgabenstellungen ist die Mächtigkeit von perl jedoch vorteilhafter.
Vor allem durch die Möglichkeit der Dateioperationen sollen manche Aktionen beschleunigt werden können:
Statt des Aufrufs:

find -name "*.bak" -exec rm "{}" \;

der für jede gefundene Datei einen neuen Prozess startet um sie zu löschen kann man folgenden Befehl nutzen:

find -name "*.bak" -print | perl -nle 'unlink'

Es ist jedenfalls nicht verkehrt beides zu kennen, ganz nach dem Motto: Für jeden Zweck die richtige Programmiersprache.

[UPDATE]Mehr informationen liefert der Befehl perldoc perlrun (perldoc muss installiert sein) oder die Seite http://p3rl.org/perlrun[/UPDATE]

Nun wird eine Logdatei unterstützt, in der alle Konversationen mit dem Bot gespeichert werden können. Die Option kann in der Datei modules/Configs.pm ein- und ausgeschaltet werden. Dort kann auch der Ort bestimmt werden, wo die Logdatei gespeichert werden soll. Ein Timestamp wird mit gespeichert. In einem MUC (Chat) wird das gesammte dortige Gespräch mit geloggt, nicht nur die Konversation mit dem Bot.

Des weiteren wurde die Plugin-Schnittstelle erweitert. Nun kann neben der Hilfe auch eine Kurzbeschreibung angegeben werden, die bei der Auflistung der verschiedenen Befehle angezeigt wird. Jetzt kann auch eine Referenz zu einer Idle-Funktion angegeben werden, die alle 15 Sekunden aufgerufen wird. Diese kann genutzt werden um z.B. regelmäßig RSS-Feeds abzurufen (bei einem RSS-Plugin) oder um ähnliche Aufgaben im Hintergrund zu erledigen. Die Vorhandenen Plugins können jedoch auch ohne Änderung weiter verwendet werden. Jedoch habe ich die Plugins hier auf dem Blog entsprechend aktualisiert, so dass sie nun eine Kurzbeschreibung enthalten.

Das Plugin “Say” (Kommando sag), welches den Bot in Chaträumen etwas sagen lässt wurde erweitert. Nun kann er auch in Räumen etwas sagen, die nicht in der Konfigurationsdatei angegeben sind und noch nicht mal auf dem angegebenen Conference-Server liegen müssen (In der modules/Configs.pm lässt sich der Bot jedoch auf den eigenen Conference-Server beschränken). Danach ist er in den entsprechenden Räumen eingeloggt und nimmt dort auch Befehle entgegen. mit dem Befehl

sag ignoriere raumname

kann man ihn im Raum raumname wieder zum schweigen bringen (Befehle aus diesem Raum werden dann ignoriert bis der Bot mit sag erneut etwas in dem Raum sagen soll). Mehr Infos sind in der Hilfe verfügbar (hilfe sag). Eine Funktion um den Bot aus dem Raum wieder abzumelden wird leider nicht von der Bibliothek (Net::Jabber::Bot) unterstützt.

Beim Befehl hilfe wird die Ausgabe der möglichen Befehle nun alphabetisch sortiert.

Eine Updatefunktion gibt es leider nicht. Da sich auch in der Konfigurationsdatei ein paar Änderungen ergeben haben, müssen alle Dateien ersetzt werden und die Daten erneut in die Konfigurationsdatei modules/Configs.pm eingefügt werden.

Die neue Version kann im ursprünglichen Artikel zBot – ein Jabber Bot in Perl herunter geladen werden. Dort findet man auch weitere Informationen zum Bot.

Nachdem ich mich nun etwas mit Jabber beschäftigt habe, war es an der Zeit, einen eigenen Jabber Bot zu schreiben.

Ich hatte bereits einen ChatBot in Perl geschrieben, der in unserem http-Chat lief. Mit der CPAN Bibliothek Net::Jabber::Bot lies sich daraus mit wenigen Handgriffen ein einfacher Jabber Bot basteln.

Der Bot ist noch nicht sehr ausgereift. Aber er funktioniert.

Der Bot hat ein Pluginsystem um einfach neue Funktionen hinzufügen zu können. Um neue Plugins zu schreiben am besten mal ins Helloworld Plugin schauen (plugins/Helloworld.pm). Wichtig ist, das Plugin mit der Funktion Plugins::registerPlugin zu registrieren. Das fertige Plugin kann man ins Verzeichnis “plugins” kopieren. Jeder Befehl ist ein Plugin.

zBot läuft im Multi User Chat (MUC) und man kann ihn genauso gut als Kontakt hinzufügen.

Die Installation ist recht einfach. Man legt einen neuen User für den Bot auf dem Server seiner Wahl an. Dann editiert man die Datei modules/Configs.pm entsprechend (Passwort, Username… setzen). Danach kann man (wenn das CPAN Modul installiert ist) die zbot.pl starten. Am besten natürlich auf einem Server, damit der Bot auch online ist, wenn man den PC ausschaltet. Den Prozess kann man direkt in den Hintergrund schieben um sich wieder abmelden zu können:

./zbot.pl &

Nun kann man den Bot zu seiner Kontaktliste hinzufügen. Nach dem Start braucht der Bot 20 Sekunden zur Initialisierung, bis er antwortet.

Durch das Senden des Befehls “hilfe” werden alle Befehle angezeigt. Mit “hilfe <befehl>” bekommt man die Beschreibung des Plugins angezeigt (z.B. “hilfe helloworld”).

Das Programm habe ich unter der GPL veröffentlicht. Eine Dokumentation ist auch vorhanden.

Über Verbesserungen des Codes oder neue Plugins würde ich mich sehr freuen.

Bei Fragen oder Problemen kann man mich natürlich auch gerne anschreiben (oder einfach hier als Kommentar).

Update: Das Problem mit den Sonderzeichen konnte ich lösen. Es lag daran, dass die Sonderzeichen in der CPAN Bibliothek durch einen regulären Ausdruck ausgefiltert wurden (der dazu gedacht war, nicht druckbare Zeichen auszufiltern). Daher habe ich die entsprechende Datei ins Verzeichnis “modules” kopiert, entsprechend editiert und von dort eingebunden.

Update: Version 0.2 ist nun verfügbar. Informationen über die Änderungen findet man im zugehörigen Blogeintrag.

[UPDATE] Es gibt ein Problem ab ejabberd Version 2.0.3, da diese eine digest-uri zur Verifikation des Clients erwartet. Die einzige Möglichkeit das Problem zu lösen besteht anscheinend darin, diese Verifikation im Quelltext abzuschalten und neu zu kompilieren. Mehr Infos gibt es in diesem Forenthread (englisch).

Des weiteren gibt es ein Problem mit manchen User- bzw. Domainnamen. Der Bot bricht dann mit der Meldung:

Can't call method "isa" without a package or object reference at /usr/local/share/perl/5.8.8/Net/XMPP/Protocol.pm line 2471.

ab. (Die Zeile kann variieren)
Abhilfe schafft das entfernen des “problematischen” Users aus der Liste des Bots. Der User kann den Bot danach immer nocht nutzen (so weit mir berichtet wurde). Anscheinend tritt das Problem auf, wenn der Username mit einer Ziffer beginnt (oder eine Ziffer enthält, das weis ich nicht).
Vielen Dank an Daniel für die Hinweise und die Hilfe bei der Fehlersuche [/UPDATE]

[UPDATE]Ich habe den Bot jetzt mal auf GitHub hochgeladen: http://github.com/zimon/zBot. In der dortigen Version ist er auch an die neue Version von Net::Jabber::Bot angepasst. Leider funktionieren dadurch einige Plugins nicht mehr richtig, aber ich habe im Moment keine Zeit sie zu fixen. Vielleicht hat ja jemand Lust zu forken [/UPDATE]

Man kann den Bot gerne testen, indem man ihn zu seiner Kontaktliste hinzufügt: bruno@jey-key.de

Die Dokumentation ist nun auch online Verfügbar: Dokumenation Version 0.2

Dateien

• zbot_0.2.zip – Das Programm (the program)
• zbot_0.2_doc.zip – Die Dokumentation (the documentation)

Plugins

• Chatbot Plugin – erweitert den zBot um die Möglichkeit “Unterhaltungen” mit dem Bot zu führen.
• Wikipedia Plugin – fügt den Befehl “wiki” hinzu, mit dem die Definition (der erste Abschnitt des Artikels) zu einem Begriff angezeigt werden kann.
• Leo Dictionary Plugin – Deutsch <-> Englisch Übersetzungsplugin
• Wetter Plugin – macht eine Wettervorhersage für eine angegebene Postleitzahl
• Todo Plugin – verwaltet für jeden User eine Todoliste mittels todo.sh
• Whois Plugin – Macht eine Whois-Abfrage zu einer gewünschten Domain und liefert das Ergebnis zurück.

.

English

Here is my Jabber Bot “zBot” written in Perl using the CPAN Module Net::Jabber::Bot.

It is easily extendable with plugins. If you want to write a plugin just look at the modules/Helloworld.pm (I commented this example Plugin better than the other ones). Its important to register your Plugin by calling the function Plugins::registerPlugin in your module. When it’s finished just copy it to the plugins directory. Every command is a plugin.

zBot runs in multi user chats (MUC) and you can add it to your contact list.

I started writing the bot yesterday, so it is not tested well but it works.

To install and start the bot, register a new account for the bot. Then edit the modules/Configs.pm to your needs (password, username,…) and start the zbot.pl (don’t forget to install the CPAN module first). It’s a good idea to start it on a server with

./zbot &

so it stays online when you shut down your own computer. Now you can add the bot to your contact list. After the start the bot needs 20 seconds for initializing before it answers.

By sending “hilfe” to the bot it sends a list of available commands. With “hilfe <command>” you get the description of the plugin (for example: “hilfe helloworld”).

The bot is licenced under GPL. An english documentation is available.

All strings in the Code are in german language but the comments and documentation is english. I wrote an english translation as comment after (or below) each string, so it should be easy to translate.

It would be grate if you send me your plugins and enhancements of the code if you create some.

[UPDATE]I have uploaded the bot on GitHub: http://github.com/zimon/zBot. There it is adapted to the new Net::Jabber::Bot version. By doing this some of the Plugins broke and I don’t have time to fix them. Maybe someone wants to fork it [/UPDATE]

For questions or problems you may contact me.