Selbstdokumentierende Perl-Scripte

Da ich häufig Scripte schreibe, bin ich es leid, diese im nachhinein noch ausgiebig zu dokumentieren. Zumal ich es unpraktisch finde, wenn die Dokumentation an andere Stelle separat gepflegt werden muss, denn das bedeutet doppelte Arbeit. Mit pod2usage kann man Scripte inline direkt beim Schreiben dokumentieren (egal, ob es um eine Benutzeranleitung oder technische Doku geht) und mit getOptions lassen sich die Dokumentationen gezielt per Scriptaufruf anzeigen. Wie das geht, zeige ich hier. 

Benötigt werden die Module Pod::Usage und Getopt::Long, damit sieht der Header des Scripts in etwa so aus:

In der letzten Zeile habe ich bereits ein paar Variablen deklariert, anhand derer ich später abfragen kann, welche Optionen gesetzt wurden. Das geht dann mit GetOptions wie folgt:

Wenn nun das Script mit --help, -?, --documentation usw. aufgerufen wird, werden die enstprechenden Variablen auf einen true-Wert gesetzt. Werden unzulässige Optionen aufgerufen, dann wird pod2usage(2); ausgeführt (dazu gleich mehr).

Das schöne an dem Getopt::Long-Modul ist, dass man die Optionsnamen auch abkürzen kann, ohne dass man extra etwas programmieren muss. Das heißt, mit obigem Quelltext, kann man das Script auch z.B. mit diesen Optionen aufrufen:

  • --list oder -l anstelle von --listchecks
  • -v statt --verbose
  • --doc oder -d statt --documentation

Abkürzungen sind beliebig möglich, solange der Optionsname daraus eindeutig abgeleitet werden kann.

Die im Script enthaltene Dokumentation schließt sich nun direkt an und kann beispielsweise so aussehen:

Zeilen, die mit einem ‚=‘, gefolgt von speziellen Schlüsselwörtern beginnen, sind ein Kennzeichen, dass hier POD-Auszeichnungssprache folgt („Plain Old Documentation“). Solche Bereiche werden vom Perl-Interpreter genau wie Kommentare ignoriert. Mit =cut beendet man einen solchen Bereich und es kann sich wieder Quelltext anschließen. =head1, =head2 usw. sind Überschriften verschiedener Gliederungsebenen. Absätze werden durch Leerzeilen getrennt. Einfache Zeilenumbrüche sind mit POD meines Wissens leider nicht möglich.

Ich habe mir angewöhnt, meine Scripte stets ausführlich zu kommentieren, damit ich auch nach ein paar Monaten (oder nach einer Woche) noch weiß, was ich da getan habe. Mit Hilfe von POD kann man nun anstelle normaler Kommentare einfach direkt die Dokumentation direkt beim Scripten nebenher schreiben. Man kann sie dann einfach durch spezielle Optionen anzeigen lassen.

Im zuvor gezeigten Quelltext steht ein Aufruf von pod2usage(2), der verwendet wird, wenn dem Scriptaufruf unzulässige Optionen mitgegeben wurden. Er sorgt dafür, dass das Script mit Returncode 2 beendet wird und der Abschnitt „SYNOPSIS“ ausgegeben wird. Wenn Returncodes von 2 oder größer angegeben werden, erfolgt die Ausgabe durch pod2usage übrigens immer nach STDERR. Bei kleineren Returncodes erfolgt die Ausgabe nach STDOUT.

pod2usage() verwendet einige Standardwerte beim Aufruf:

  • einen Exit-Code, Standardwert ist 2.
  • Einen Verbosity-Level, Standard ist 0.
  • eine zusätzlich ausgegebene Nachricht („message“), diese ist standardmäßig leer.
  • Eine Liste von POD-Abschnitten, die ausgegeben werden sollen. Der Standard ist hier abhängig vom Verbosity-Level:
    • bei einem Verbosity-Level von 0 wird nur die SYNOPSIS ausgegeben.
    • bei einem Verbosity-Level von 1 werden, soweit vorhanden, die Abschnitte namens SYNOPSIS, OPTIONS bzw. ARGUMENTS ausgegeben.
    • bei einem Verbosity-Level von 2 werden alle Abschnitte ausgegeben.
    • bei einem Verbosity-Level von 99 kann man der Funktion die Liste der auszugebenden Abschnitte selbst mitteilen.

Nun wollen wir noch einige andere Teile der Dokumentation ausgeben lassen, jenachdem, welche Optionen beim Scriptaufruf gesetzt wurden:

Die erste Zeile bewirkt, dass bei Aufruf mit --help der Exitcode 1 ist (und damit die Ausgabe nach STDOUT erfolgt) und der Verbosity-Level ist ebenfalls 1. Die ausgegebenen Dokumentationsabschnitte sind daher „SYNOPSIS“ und, soweit vorhanden, „OPTIONS“ bzw. „ARGUMENTS“. Man sollte also in der Synopsis eine sehr kurze Zusammenfassung der Aufruf-Syntax schreiben und im Kapitel „Options“ dann die Optionen näher erläutern.

Die zweite Zeile setzt die verbose-Stufe auf 2. Dadurch wird die komplette POD-Dokumentation ausgegeben (also alle Abschnitte).

In der dritten und vierten Zeile wird ein konkreter POD-Abschnitt angegeben, welchen pod2usage() ausgeben soll, wenn das Script mit --list aufgerufen wurde; und zwar das Kapitel „CHECKS“, welches ein Unterkapitel von „TECHNICAL DOCUMENTATION“ ist.

Zum Nachlesen:

Veröffentlicht von

Steffi

Hi! Ich bin beruflich v.a. im Linux-Umfeld tätig. In meiner Freizeit nähe und koche ich gern - außerdem studiere ich nebenher Mathematik und mache viel Sport. Über all diese Dinge, und was mich sonst noch beschäftigt, schreibe ich hier in meinem Blog.