| # Einführung in das Arbeiten mit Modulen
| Allgemeines zu Modulen in Perl Module einbinden mit require und use Speicherorte für Module und die Liste @INC Adressierungs-Syntax beim Einbinden von Modulen Packages und Module Erweiterte Verwendung von use (@EXPORT, @EXPORT_OK und qw) Moduldokumentationen lesen mit perldoc

## Allgemeines zu Modulen in Perl

Beim Programmieren werden Sie schnell feststellen, dass Sie bestimmte Routine-Aufgaben immer wieder benötigen. Immer wieder müssen Dateien eingelesen werden, in einer CGI-Umgebung müssen immer wieder Formulare verarbeitet werden, zur Kommunikation mit fernen Rechnern im Internet muss immer wieder eine Internet-Socket-Verbindung aufgebaut werden usw. Nun bietet der Perl-Interpreter ja bereits eine Menge Funktionen an, die solche Routine-Aufgaben bewältigen. Doch je mehr solcher Funktionen im Perl-Interpreter fest eingebaut sind, desto größer, langsamer und ressourcen-unfreundlicher wird der Interpreter. Daher gibt es einen zweiten Typ Funktionen, nämlich solche, die nicht direkt in den Perl-Interpreter eingebaut sind, sondern in Form von Perl-Scripts zur Verfügung stehen. Diese speziellen Perl-Scripts werden Module genannt. Module stellen Funktionen (aber auch Variablen) für bestimmte Routine-Aufgaben zur Verfügung. Um in Ihren eigenen Perl-Scripts solche Funktionen verwenden zu können, binden Sie einfach die Module ein, in denen die gewünschten Funktionen stehen. Anschließend können Sie auf die Funktionen und Variablen der Module zugreifen.

Mittlerweile gibt es tausende von Perl-Modulen, die frei verfügbar sind. Es gibt praktisch kaum mehr ein Programmiergebiet, für das es nicht schon Module mit fertigen leistungsstarken Funktionen gibt. Die Module werden der Allgemeinheit von eifrigen und fähigen Perl-Programmierern im Internet zur Verfügung gestellt. Einige dieser Module konkurrieren miteinander, und im Laufe der Zeit stellt sich heraus, dass eines der Module in der Praxis am tauglichsten ist. Natürlich gibt es auch Module, die häufiger zum Einsatz kommen als andere. Letzteres hat dazu geführt, dass mittlerweile zwischen zwei wichtigen Klassen von öffentlich verfügbaren Modulen unterschieden wird: es gibt Standardmodule und CPAN-Module. Standardmodule sind solche, die zusammen mit dem Perl-Interpreter ausgeliefert werden, und CPAN-Module stehen im Internet zum Download zur Verfügung. Standardmodule erhalten dadurch natürlich einen wesentlich höheren Verbreitungsgrad. Da sie bei jeder typischen Installation des Perl-Interpreters mit installiert werden, können sie auch fast so bedenkenlos verwendet werden wie die fest eingebauten Funktionen von Perl. Denn auch wenn ein Perl-Script auf einen anderen Rechner portiert wird und dort seine Arbeit verrichten soll, stehen die gleichen Module zur Verfügung - vorausgesetzt, eine entsprechend aktuelle Version des Perl-Interpreters ist installiert. Wenn Sie dagegen CPAN-Module downloaden und in Ihre eigenen Scripts einbinden, ist die Portierung eines Scripts auf einen anderen Rechner nicht ganz so unproblematisch. Denn das Script funktioniert dort erst, nachdem die gleichen CPAN-Module installiert sind.
Innerhalb dieses Kapitels finden Sie einen Abschnitt über die Standardmodule von Perl und einen Abschnitt über CPAN-Module. Dort erhalten Sie eine Übersicht, welche Module zur Verfügung stehen.

Daneben ist es selbstverständlich auch möglich, eigene Module zu schreiben. Für größere Perl-Scripts ist es auch besser, den Code so zu verteilen, dass es nur noch ein schlankes Hauptscript mit eingebundenen Modulen für spezielle Aufgaben gibt. Angenommen, Sie programmieren ein Perl-Script, das eine Datei mit einer bestimmten Datenstruktur verarbeitet. Bei dieser Aufgabe könnten Sie ein Modul schreiben, das alle Funktionen zum Einlesen der Datei in geeignete Variablen und zum Zurückschreiben verarbeiteter Daten in die Datei enthält. Im Hauptscript können Sie dann einfach dieses Modul einbinden und auf dessen Funktionen und Variablen zugreifen. Sollte sich dann beispielsweise das Dateiformat der Datendatei ändern, muss nur das Modul umgeschrieben werden, während das Hauptscript und mögliche andere Module davon unberührt bleiben. Typische Beispiele zum Erstellen projekteigener Module finden Sie im Abschnitt über objektorientierte Programmierung. Das ist kein Zufall. Denn modul-orientiertes Arbeiten im modernen Stil und objektorientiertes Programmieren gehören bei Perl eng zusammen.

Perl-Module sind also (meistens) selber Perl-Scripts. Es handelt sich jedoch um Scripts, bei denen ein paar Regeln und Besonderheiten zu beachten sind, auf die im folgenden noch näher eingegangen wird.

## Module einbinden mit require oder use

Zum Einbinden von Modulen stehen in Perl die Funktionen use und require zur Verfügung. Im allgemeinen wird heute empfohlen, die Funktion `use` zu verwenden, weil sie konsequenter den Modul-Gedanken verfolgt. Bei Verwendung von `use` wird das Modul ganz zu Beginn des Hauptscripts eingebunden. Es steht also zur Verfügung, bevor überhaupt die erste Code-Zeile Ihres Scripts ausgeführt wird. Bei Verwendung von `require` wird die andere Datei dagegen erst an der Stelle eingebunden, an der die `require`-Anweisung steht. Vor dem entsprechenden Aufruf stehen also Funktionen oder Variablen des Moduls noch nicht zur Verfügung, und falls der `require`-Aufruf beispielsweise in einem Zweig einer bedingten Anweisung steht, wird er nur dann ausgeführt, wenn das Script in den entsprechenden Zweig gelangt. Ein Beispiel soll dies verdeutlichen.

### Beispiel - Teil 1: Moduldatei Testmodul.pm

    #!/usr/bin/perl -w

    print "Hier meldet sich das Modul \"Testmodul.pm\"\n";

    1;

### Beispiel - Teil 2a: Hauptscript test_require.pl

    #!/usr/bin/perl -w

    print "Hier meldet sich das Hauptscript\n";
    require Testmodul;

### Beispiel - Teil 2b: Hauptscript test_use.pl

    #!/usr/bin/perl -w

    print "Hier meldet sich das Hauptscript\n";
    use Testmodul;

### Erläuterung:

Der erste Teil des Beispiels zeigt den Code der Datei Testmodul.pm. Die Beispielteile 2a und 2b zeigen jeweils ein Perl-Script, in dem diese Moduldatei eingebunden wird. Im Script test_require.pl (2a) wird das Modul mit `require` eingebunden, im Script test_use.pl (2b) dagegen mit `use`. Beide Scripts (2a und 2b) sind identisch bis auf den unterschiedlichen Funktionsaufruf. Das Ergebnis der Ausgabe ist jedoch verschieden. In 2a (also beim Einbinden des Moduls mit `require` lautet es:
`Hier meldet sich das Hauptscript
Hier meldet sich das Modul "Testmodul.pm"`
In 2b dagegen (Einbinden des Moduls mit `use`) lautet die Ausgabe dagegen:
`Hier meldet sich das Modul "Testmodul.pm"
Hier meldet sich das Hauptscript`
Der Grund ist, dass ein mit `use` eingebundenes Modul ausgeführt wird, bevor der Code des einbindenden Scripts ausgeführt wird. Bei `require` wird das eingebundene Script dagegen an der Stelle ausgeführt, an der es eingebunden wird.

Auf den ersten Blick spricht dieser Unterschied eher für die Verwendung von `require` und weniger für den von `use`. In der Praxis ist es jedoch so, dass Moduldateien meist keinen direkt auszuführenden Code enthalten, sondern aus Funktionen (Subroutinen) bestehen, die dann im einbindenden Script aufgerufen werden können.

### Beispiel - Teil 1: Moduldatei Testmodul.pm

    #!/usr/bin/perl -w

    sub Modulprint {
      print "Hier meldet sich das Modul \"Modul.pm\"\n";
    }

    1;

### Beispiel - Teil 2a: Hauptscript test_require.pl

    #!/usr/bin/perl -w

    print "Hier meldet sich das Hauptscript\n";
    require Testmodul;
    Modulprint();

### Beispiel - Teil 2b: Hauptscript test_use.pl

    #!/usr/bin/perl -w

    print "Hier meldet sich das Hauptscript\n";
    use Testmodul;
    Modulprint();

### Erläuterung:

In diesem Beispiel-Ensemble erzeugen die Scripts aus 2a und 2b die gleiche Ausgabe, nämlich:
`Hier meldet sich das Hauptscript
Hier meldet sich das Modul "Testmodul.pm"`
Der Grund ist, dass der Code des Moduls nun in einer Subroutine namens `Modulprint` steht. In den einbindenden Scripts test_require.pl und test_use.pl wird mit der Anweisung `Modulprint();` die entsprechende Funktion im eingebundenen Modul aufgerufen.

### Beachten Sie:

Ein weiterer wichtiger Unterschied zwischen `use` und `require` ist, dass Sie bei `use` genau angeben können, welche Funktions- und Variablennamen Sie aus einem Modul importieren wollen, während `require` diese Möglichkeit nicht anbietet. Mehr dazu weiter unten im Abschnitt Erweiterte Verwendung von use.

## Speicherorte für Module und die Liste @INC

Moduldateien können in einem der Verzeichnisse abgelegt werden, die in der vordefinierten Variablen `@INC` definiert sind, oder in einem Unterverzeichnis davon. Bei einer typischen Perl-Installation enthält die Liste `@INC` eine Reihe von Unterverzeichnissen des Perl-Installationsverzeichnisses sowie das jeweils aktuelle Verzeichnis, also meistens das Verzeichnis, in dem das die Moduldatei einbindende Hauptscript liegt.

Das Ablegen von Moduldateien im Verzeichnis bzw. einem Unterverzeichnis des Hauptscripts ist dann sinnvoll, wenn die Moduldateien von keinem anderen Script verwendet werden. Wenn die Moduldateien dagegen so allgemein geschriebenen Code enthalten, dass Sie sie für verschiedene Scripts verwenden können, dann ist es besser, Sie legen die Moduldateien in einem der anderen Verzeichnisse ab, die in `@INC` genannt werden.

Um zu entscheiden, wo Sie Moduldateien ablegen können, müssen Sie also erst einmal die Liste der erlaubten Verzeichnisse kennen. Das folgende einfache Perl-Script hilft dabei.

### Beispiel-Script zur Ausgabe von @INC (als CGI-Script):

Anzeigebeispiel: So sieht's aus (Zum Aufruf des Scripts ist eine Internet-Verbindung erforderlich)

    #!/usr/bin/perl -w

    print "Content-type: text/html\n\n";
    print '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">', "\n";
    print "<html><head><title>Erlaubte Modulverzeichnisse</title>\n";
    print "</head><body>\n";
    print "<h1>Verzeichnisse zum Ablegen von Moduldateien:</h1>\n";
    foreach (@INC) {
     print "<tt>$_</tt><br>\n";
    }
    print "</body></html>\n";

### Erläuterung:

Das Script gibt einfach den Inhalt der Liste `@INC` zeilenweise als HTML-Code aus. Wenn Sie den Code als pl-Datei im CGI-Verzeichnis abspeichern und die pl-Datei von einem Browser anfordern lassen, werden die verfügbaren Verzeichnispfade angezeigt. In der üblichen Konfiguration ist der letzte Eintrag der Liste ein einzelner Punkt (`.`). Dies steht für "aktuelles Verzeichnis" und bewirkt, dass der Perl-Interpreter, nachdem er eine eingebundene Datei in den allgemeinen Verzeichnispfaden nicht gefunden hat, im aktuellen Verzeichnis sucht.

Falls Sie Ihre Moduldatei in keinem der Verzeichnisse ablegen wollen, die von `@INC` angeboten werden, können Sie sie auch woanders ablegen. Dann müssen Sie allerdings vor dem Einbinden einer solchen Moduldatei die Liste `@INC` um den Verzeichnispfad erweitern, in dem die Moduldatei liegt.

### Beispiel:

    #!/usr/bin/perl -w

    use lib "/httpd/docs/cgi-shared/speziell";
    use lib "/httpd/docs/cgi-shared/module";

    print "Content-type: text/html\n\n";
    print '<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">', "\n";
    print "<html><head><title>Erlaubte Modulverzeichnisse</title>\n";
    print "</head><body>\n";
    print "<h1>Verzeichnisse zum Ablegen von Moduldateien:</h1>\n";
    foreach (@INC) {
     print "<tt>$_</tt><br>\n";
    }
    print "</body></html>\n";

### Erläuterung:

Durch eine Anweisung vom Typ `use lib` mit anschließender Angabe eines Verzeichnispfades wird dieser Pfad an den Anfang der Liste `@INC` übernommen. Das Beispiel-Script ist das gleiche CGI-Script zur Ausgabe der Pfade von `@INC` wie zuvor. In diesem Fall zeigt es, dass die so definierten eigenen Pfade mit in die Liste aufgenommen wurden.

## Adressierungs-Syntax beim Einbinden von Modulen

Module können in einem der Verzeichnisse von `@INC` oder einem Unterverzeichnis davon abgelegt werden. Daraus ergeben sich dann die möglichen Formen der Adressierung eines Moduls beim Einbinden mit `use` oder `require`.

### Beispiele für Module in einem @INC-Verzeichnis:

    require "Statistik.pm";
    require Statistik;
    use "Statistik.pm";
    use Statistik;

### Erläuterung:

Alle vier Beispiele zeigen das Einbinden eines Moduls, das in einer Datei namens `Statistik.pm` abgelegt ist. Die Datei befindet sich direkt in einem der Verzeichnisse, die in der Liste `@INC` als mögliche Speicherorte für Module zur Verfügung stehen. Für `require` und `use` gelten die gleichen Regeln. Entweder notieren Sie den vollständigen Dateinamen der Moduldatei in Anführungszeichen (Moduldateien sollten die Endung `.pm` haben), oder Sie notieren den Dateinamen ohne die Endung `.pm` ohne Anführungszeichen.

Wenn sich die Datei in einem Unterverzeichnis eines der Verzeichnisse von `@INC` befindet, ist die relative Pfadangabe erforderlich.

### Beispiele für Module in Unterverzeichnissen eines @INC-Verzeichnisses:

    require "Berechnungsmodule/Statistik.pm";
    require Berechnungsmodule::Statistik;
    use "Berechnungsmodule/Statistik.pm";
    use Berechnungsmodule::Statistik;

### Erläuterung:

Wieder zeigen alle vier Beispiele das Einbinden eines Moduls `Statistik.pm`. Die Datei befindet sich unterhalb eines der `@INC`-Verzeichnisse in einem Unterverzeichnis namens `Berechnungsmodule`. In diesem Fall ist allerdings die Syntax ohne Anführungszeichen vorzuziehen. Denn wenn Sie mit Anführungszeichen arbeiten, müssen Sie die einzubindende Datei mit "vollem" Namen ansprechen. Die Syntax ohne Anführungszeichen kommt dagegen ohne die Dateiendung .pm aus. Es wird erwartet, dass die eingebundene Moduldatei diese Endung hat. Die Zeichenfolge, die die Verzeichnistrenner symbolisiert, also Hierarchien darstellt, besteht aus einem doppelten Doppelpunkt (`::`).

## Packages und Module

So einfach das Konzept der Module in Perl erst einmal klingt - es bringt doch ein paar Probleme mit sich. Angenommen, in Ihrem eigenen Perl-Script definieren Sie eine Subroutine namens `get_data()`. In dem gleichen Script binden Sie ein Modul ein, in dessen Code ebenfalls eine Subroutine namens `get_data()` definiert ist. Damit der Perl-Interpreter beim Aufruf von `get_data()` weiß, welche der beiden Funktionen gemeint ist, muss es eine Möglichkeit geben, ihm mitzuteilen, welche der Funktionen gemeint ist.

Zu diesem Zweck gibt es in Perl das Konzept der Namensräume. Jeder Namensraum stellt ein so genanntes Package (engl. für Paket) dar. Jedes Perl-Script, in dem Sie keine besondere Angabe machen, welchen Namensraum (welches Package) Sie meinen, benutzt ein Default-Package. Es hat den Namen `main`.

### Beispiel:

    #!/usr/bin/perl -w

    $Ausgabetext = "Hallo alte Welt. ";
    print $Ausgabetext;

    package NeueWelt;
    $Ausgabetext = "Hallo neue Welt. ";
    print $Ausgabetext;

    package main;
    print $Ausgabetext;

### Erläuterung:

Das Beispiel verdeutlicht den Default-Namensraum mit dem Namen `main`. Zunächst wird ein Skalar namens `$Ausgabetext` definiert und mit einem Wert belegt. Dieser Wert wird gleich anschließend ausgegeben. Da bis zum Ausführungszeitpunkt noch keine weitere Angabe zum Namensraum gemacht wurde, befindet sich das Script im Defaultnamensraum `main`. Im zweiten Schritt wird mit Hilfe der Funktion package ein neuer eigener Namensraum mit Namen `NeueWelt` definiert. Unterhalb davon wird wiederum ein Skalar namens `$Ausgabetext` definiert, diesmal mit anderem Wert. Dieser neue Wert wird wieder ausgegeben.

Zu diesem Ausführungszeitpunkt existieren nun zwei Skalare namens `$Ausgabetext` - nämlich der aus dem Package `NeueWelt` und der aus dem Default-Package `main`. Zur Kontrolle wird im Beispiel wieder auf das Package `main` "umgeschaltet". Dazu wird wieder die Funktion `package` aufgerufen, diesmal aber mit dem Defaultnamen `main`. Von den beiden existierenden Skalaren dieses Namens wird nun der im Script zuerst definierte ausgegeben, also derjenige, der zum Default-Namensraum `main` gehört. Der unterste `print`-Aufruf gibt also wieder `Hallo alte Welt.` aus.

Wie das Beispiel zeigt, lässt sich der Namensraum innerhalb einer Scriptdatei also beliebig wechseln. Dadurch lässt sich ein hohes Maß an Flexibilität erreichen. Von dieser Flexibilität profitieren die Module in Perl. Ein Modul kann nämlich durch Anwendung der Package-Technik beispielsweise mehrere (Objekt-)Klassen in einer Moduldatei unterbringen oder andere Module (die ja auch aus Packages bestehen) erweitern, auch wenn die Technik zugegebenermaßen etwas unsauber ist. Ein einfaches Beispiel soll diesen Zusammenhang verdeutlichen.

### Beispiel - Teil 1: Moduldatei Testmodul.pm

    $Modultext = "Dies ist der Inhalt des Skalars \$Modultext\n";

    package Testmodul;
    $Text = "Dies ist der Inhalt des Skalars \$Text\n";

    1;

### Beispiel - Teil 2: Hauptscript, z.B. test.pl

    #!/usr/bin/perl -w

    use Testmodul;

    print $Modultext;
    print $Testmodul::Text;

### Erläuterung:

Der erste Teil des Beispiels ist das Modulscript, der zweite Teil das Hauptscript. Das Modulscript erhält im Beispiel den Namen Testmodul.pm und wird im Hauptscript mit der Anweisung `use Testmodul;` eingebunden.

Die Moduldatei beginnt mit der Definition eines Skalars namens `$Modultext`. Da zuvor kein anderes package aufgerufen wird, ist das Package aktiv, in das das Modul eingebunden wird. Alles, was innerhalb dieses Namensraums definiert wird, befindet sich somit im Namensraum `main` des einbindenden Scripts. Im Beispiel gibt das einbindende Script, also das Hauptscript, mit `print $Modultext;` in seinem Default-Namensraum `main` einfach die Variable aus, die im Namensraum `main` der Moduldatei definiert wurde. `$Modultext` wurde also direkt im Default-Namensraum des einbindenden Scripts definiert. Damit wurde das Package `main` durch das Modul erweitert.

Im Modulscript, also in der Modul.pm, wird im weiteren Verlauf jedoch mit `package` ein neuer Namensraum definiert. Er hat den gleichen Namen wie der Vorname der Moduldatei, nämlich `Testmodul`. Im einbindenden Hauptscript kann auf Variablen und Funktionen, die im Modul unterhalb des Packages `Testmodul` definiert werden, nur durch Angabe des entsprechenden Namensraums zugegriffen werden. Die Anweisung `print $Testmodul::Text;` zeigt, wie auf das andere Package zugegriffen wird. Dem Namen einer Variablen oder einer Funktion wird der Name des Packages und ein doppelter Doppelpunkt (`::`) vorangestellt. Skalare, Listen und Hashes beginnen weiterhin mit ihren typischen Kennzeichen `$`, `@` und `%`. Zwischen dem Kennzeichen und dem Variablennamen steht jedoch der Package-Name und der doppelte Doppelpunkt.

### Beachten Sie:

Das Ansprechen von Variablen oder Funktionen in anderen Packages oder Modulen mit `Package-Name::Variablen/Funktionsname` ist nicht möglich, wenn die Variablen oder Funktionen mit my deklariert sind. Die Anwendung von `my` wird deshalb auch in der Praxis empfohlen, um eine saubere Kapselung von Variablen und Funktionen, die nur innerhalb eines Packages oder Moduls von Bedeutung sind, zu erreichen.

## Erweiterte Verwendung von use (@EXPORT, @EXPORT_OK und qw)

Da Module selbst wieder andere Module einbinden können und einzelne Module aber eigentlich Dateninseln darstellen sollen, stößt die Technik des Erweiterns von Packages irgendwann an ihre Grenzen. Um "öffentliche" Schnittstellen von Modulen festlegen zu können, haben Sie die Möglichkeit, einzelne Symbole (also Variablennamen oder Funktionsnamen beispielsweise) in beiden Packages (also dem einbindenden und dem eingebundenen) sichtbar zu machen. Sie können die Symbole aus dem Modul exportieren bzw. in das einbindende Script oder Modul importieren.

Ein Modul kann deshalb erzwingen, dass Sie beim Einbinden genau angeben müssen, welche Variablen oder Funktionen Sie in den Namensraum des einbindenden Scripts importieren möchten. Dazu gibt es das so genannte Exporter-Modul, ein Standardmodul von Perl. Dieses Modul erwartet im eingebundenen Package zwei Listen namens `@EXPORT` und `@EXPORT_OK`. Ein Modul kann das Exporter-Modul einbinden und diese beiden Listen mit denjenigen Variablen- und Funktionsnamen füllen, die in ein einbindendes Modul überhaupt exportiert werden können. Im einbindenden Script wiederum können Sie angeben, welche der exportierbaren Namen des Moduls Sie in den Namensraum Ihres Scripts importieren möchten.

### Beispiel - Teil 1: Moduldatei Testmodul.pm

    package Testmodul;
    require Exporter;
    @ISA = qw(Exporter);
    @EXPORT = qw(%FORMULARFELDER);
    @EXPORT_OK = qw($Zeitstempel @Logdaten Besteller_ermitteln);

    # hier folgt der Code des Moduls ...
    # in dem Code kommen unter anderem vor:
    # ein Hash namens %FORMULARFELDER
    # ein Skalar namens $Zeitstempel
    # eine Liste namens @Logdaten
    # eine Funktion namens Besteller_ermitteln

    1;

### Beispiel - Teil 2: Hauptscript, z.B. test.pl

    #!/usr/bin/perl -w

    use Testmodul qw($Zeitstempel);

    # hier folgt der Code des Scripts ...

### Erläuterung:

Die Moduldatei bindet im Beispiel mit require selbst ein Modul ein, nämlich das Standardmodul `Exporter`. Die Anweisung `@ISA = qw(Exporter)` definiert die Klasse `Exporter` als Basisklasse der aktuellen Klasse, die durch das aktuelle Package (im Beispiel also `Testmodul`) repräsentiert wird. Damit wird die Methode `import`, die im Modul bzw. der Klasse `Exporter` definiert ist, an die Klasse `Testmodul` vererbt. Diese etwas kompliziert klingenden Erläuterungen sind durch den Sprachgebrauch der objektorientierten Programmierung bedingt.

Die Liste `@EXPORT` kann Namen der Module aufnehmen, die in den Namensraum eines einbindenden Scripts standardmäßig exportiert werden, wenn bei der Einbindung keine spezielle Importliste angegeben ist. Die Liste `@EXPORT_OK` nimmt dagegen die Namen auf, die ein einbindendes Script maximal in den eigenen Namensraum übernehmen kann, aber nicht übernehmen muss.

Im obigen Beispiel ist in der Moduldatei bei der `@EXPORT`-Liste nur ein Name notiert, nämlich ein Hash namens `%FORMULARFELDER`. Diese Variable wird in den Namensraum eines einbindenden Scripts exportiert, wenn bei der `use`-Anweisung keine Importliste angegeben wird. Bei der Liste `@EXPORT_OK` sind im Beispiel drei Namen notiert: ein Skalar namens `$Zeitstempel`, eine Liste namens `@Logdaten` und eine Subroutine namens `Besteller_ermitteln`.
Zur Notation der Listen bietet sich besonders der Operator `qw` an, da er es ermöglicht, die Variablennamen ohne ständige Anführungszeichen notieren zu können. `qw($Zeitstempel @Logdaten Besteller_ermitteln)` entspricht eigentlich der Notation `('$Zeitstempel', '@Logdaten', 'Besteller_ermitteln')`, ist aber übersichtlicher.
Innerhalb der Klammern von `qw` werden die gewünschten Namen notiert und durch Leerraumzeichen getrennt. Variablennamen erhalten dabei die üblichen Kennzeichen für Skalare, Listen und Hashes.

Das einbindende Script bindet das Modul im Beispiel mit `use Testmodul` ein und muss in der nachfolgenden Liste angeben, welche der bei `@EXPORT` oder `EXPORT_OK` genannten Namen es in den eigenen Namensraum importieren möchte. Im Beispiel wird nur der Skalar `$Zeitstempel` angegeben und als einziger Name importiert. Wenn Sie die Listenangabe weglassen (im Beispiel also nur `use Testmodul;` notieren würden), werden die in `@EXPORT` aufgeführten Namen importiert.

## Moduldokumentationen lesen mit perldoc

Module, die Sie nicht selbst geschrieben haben, aber in Ihre Scripts einbinden möchten, müssen Sie natürlich so weit verstehen, dass Sie in der Lage sind, die darin enthaltenen Funktionen richtig aufzurufen, darin definierte Variablen zu kennen und zu benutzen usw. Deshalb sind zumindest alle wichtigen Standardmodule und Module aus dem CPAN-Verzeichnis dokumentiert. Da separate readme-Dateien aber leicht verloren gehen, stellt Perl die Möglichkeit bereit, die Dokumentation innerhalb der Datei mit dem Quellcode zu notieren. Zum Lieferumfang von Perl gehört das Programm perldoc, mit dem Sie den Dokumentationsteil am Bildschirm ausgeben können.

Das folgende Beispiel zeigt den vollständigen Code eines kleinen Standardmoduls von Perl. Die Aufgabe des Moduls soll hier nicht weiter interessieren. Gezeigt werden soll, wie die Dokumentation in den Quellcode integriert ist.

### Beispiel - die Moduldatei "Nox.pm"

    package CPAN::Nox;
    use strict;
    use vars qw($VERSION @EXPORT);

    BEGIN{
      $CPAN::Suppress_readline=1 unless defined $CPAN::term;
    }

    use base 'Exporter';
    use CPAN;

    $VERSION = "1.03";
    $CPAN::META->has_inst('Digest::MD5','no');
    $CPAN::META->has_inst('LWP','no');
    $CPAN::META->has_inst('Compress::Zlib','no');
    @EXPORT = @CPAN::EXPORT;

    *AUTOLOAD = \&CPAN::AUTOLOAD;

    1;

    __END__

    =head1 NAME

    CPAN::Nox - Wrapper around CPAN.pm without using any XS module

    =head1 SYNOPSIS

    Interactive mode:

      perl -MCPAN::Nox -e shell;

    =head1 DESCRIPTION

    This package has the same functionality as CPAN.pm, but tries to
    prevent the usage of compiled extensions during its own
    execution. Its primary purpose is a rescue in case you upgraded perl
    and broke binary compatibility somehow.

    =head1  SEE ALSO

    CPAN(3)

    =cut

### Erläuterung:

Das Beispiel zeigt den Code des CPAN-Moduls Nox.pm. Der obere Teil der Moduldatei enthält den eigentlich ausführbaren Code des Moduls, und der untere Teil enthält die Dokumentation zum Modul. Die Dokumentation beginnt mit Anweisungen, die in einer neuen Zeile beginnen und als erstes Zeichen ein Gleichheitszeichen (`=`) haben. Mit `=head1 NAME` wird beispielsweise eine Überschrift mit dem Titel `NAME` erzeugt. Alles, was danach kommt, wird bis zur beendenden Anweisung `=cut` als Dokumentation interpretiert.

Um die Dokumentation separat lesen zu können, müssen Sie auf der Kommandozeile Ihres Betriebssystems eingeben:
`perldoc [Pfad]Modulname`
Unter Windows können Sie die DOS-Eingabeaufforderung benutzen oder ein Programm, das in der Lage ist, Standard-Out-Ergebnisse eines Programms aufzufangen (manche besseren Texteditoren können das beispielsweise). Auf Unix-Systemen benutzen Sie einfach eine geeignete Shell. Wenn Sie den Pfad zu einer Moduldatei mit angeben, können Sie die Verzeichnisse mit einem Schrägstrich (`/`) trennen. Oder Sie wechseln in das Verzeichnis der Moduldatei. Dann können Sie die Pfadangabe weglassen.
Im obigen Beispiel der Moduldatei Nox.pm sind Aufrufe möglich wie:
`perldoc CPAN::Nox`
`perldoc Nox.pm`
`perldoc Nox`
`perldoc -m Nox` (listet den Quellcode mit auf)

| Standardmodule von Perl
| Funktionen für Module und Packages

© 2007 Impressum