Data::Dumper - Umwandlung von Perl-Datenstrukturen in Strings, die sowohl zum Drucken als auch für eval geeignet sind.
use Data::Dumper;
# Einfache prozedurale Schnittstelle
print Dumper($foo, $bar);
# Erweiterte Nutzung mit Namen
print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
# Konfigurationsvariablen
{
local $Data::Dump::Purity = 1;
eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
}
# OO-Ansatz
$d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
...
print $d->Dump;
...
$d->Purity(1)->Terse(1)->Deepcopy(1);
eval $d->Dump;
Data::Dumper verlangt eine Liste von Skalaren oder Referenzvariablen und schreibt deren Inhalt in Perl-Syntax aus. Bei den Referenzen kann es sich auch um Objekte handeln. Der Inhalt jeder Variable wird in einer einzelnen Perl-Anweisung ausgegeben. Selbstreferenzierende Strukturen werden korrekt behandelt.
Der Rückgabewert kann evaluiert werden, um eine identische Kopie der ursprünglichen Referenzstruktur zu erzeugen.
Alle Referenzen, die mit einer der übergebenen Referenzen identisch sind, werden mit $VARn benannt (wobei n ein numerisches Suffix ist). Sich wiederholende Referenzen auf Substrukturen innerhalb $VARn werden über die Pfeil-Notation (arrow notation) entsprechend benannt. Sie können Namen individuell zu "dumpender" Werte angeben, wenn Sie die Dump()-Methode verwenden. Sie können aber auch das Standard-$VAR-Präfix ändern. Beachten Sie hierzu $Data::Dumper::Varname und $Data::Dumper::Terse.
Die Standardausgabe selbstreferenzierender Strukturen kann evaluiert werden, allerdings bleiben die verschachtelten Referenzen auf $VARn undefiniert, weil eine rekursive Struktur nicht in einer einzelnen Perl-Anweisung konstruiert werden kann. Sie müssen das Purity-Flag auf 1 setzen, damit zusätzliche Anweisungen generiert werden, die diese Referenzen korrekt ausfüllen.
In der erweiterten Form können den "gedumpten" Referenzen benutzerspezifische Namen gegeben werden. Beginnt ein Name mit einem *, beschreibt die Ausgabe bei Hashes, Arrays und Coderefs den dereferenzierten Typ der übergebenen Referenz. Die Ausgabe von Namen wird, soweit es geht, unterdrückt, wenn das Terse-Flag gesetzt ist.
In vielen Fällen liefern Methoden, die den internen Zustand eines Objekts ändern, das Objekt selbst zurück. Methodenaufrufe können also bequem verkettet werden.
Verschiedene Arten der Ausgabe sind möglich und werden über das Indent-Flag kontrolliert. Details finden Sie unter Konfigurationsvariablen und -methoden.
Gibt ein neu angelegtes Data::Dumper-Objekt zurück. Das erste Argument ist ein anonymes Array mit den zu "dumpenden" Werten. Das zweite Argument ist optional und besteht aus einem anonymen Array mit den Namen für die Werte. Den Namen muß kein $-Zeichen voranstehen, und sie müssen aus alphanumerischen Zeichen bestehen. Sie können dem Namen ein *-Zeichen voranstellen, um bei ARRAY- und HASH-Referenzen festzulegen, daß der dereferenzierte Typ anstelle der Referenz selbst "gedumpt" werden soll.
Das durch $Data::Dumper::Varname festgelegte Präfix wird zusammen mit einem numerischen Suffix verwendet, wenn der Name für einen Wert undefiniert ist.
Data::Dumper katalogisiert alle während eines Dumps entdeckten Werte. Cross-Referenzen (in Form von Namen von Substrukturen in Perl-Syntax) werden an allen möglichen Punkten eingefügt, womit alle strukturellen Abhängigkeiten der Ursprungswerte erhalten bleiben. Das Traversieren (Queren) der Struktur erfolgt aus der Tiefe, und die Verarbeitung erfolgt vom ersten angegebenen Wert bis zum letzten.
Gibt die im Objekt gespeicherten Werte in Form eines Strings zurück (wobei die bei new angewandte Reihenfolge erhalten bleibt). Ist den weiter unten stehenden Konfigurationsoptionen unterworfen. In einem Arraykontext wird eine Liste von Strings zurückgegeben, die den übergebenen Werten entsprechen.
Die zweite Form ruft der Bequemlichkeit halber einfach new für die Argumente auf und generiert daraufhin unmittelbar einen Dump des Objekts.
Diese Methode ist verfügbar, wenn Sie in der Lage waren, die XSUB-Erweiterung für Data::Dumper zu kompilieren und einzubinden. Sie entspricht genau der oben beschriebenen Dump-Methode, ist aber 4- bis 5mal schneller, weil sie vollständig in C entwickelt wurde.
Fragt die interne Tabelle der bereits entdeckten Referenzen ab bzw. fügt neue hinzu. Sie müssen diese Tabelle bei Bedarf explizit mit Reset löschen. Solche Referenzen werden nicht "gedumpt", ihre Namen werden vielmehr bei jedem Vorkommen aufgenommen. Das ist insbesondere nützlich, um Referenzen auf Subroutinen korrekt zu "dumpen".
Erwartet wird ein anonymer Hash mit Name => Wert-Paaren. Für die Namen gelten die gleichen Regeln wie unter new. Wird kein Argument übergeben, gibt die Methode eine Liste der bereits entdeckten Name => Wert-Paare im Arraykontext zurück. Anderenfalls wird das Objekt selbst zurückgegeben.
Fragt das interne Array mit den zu "dumpenden" Werten ab oder ersetzt diese. Erfolgt der Aufruf ohne Argumente, werden die Werte zurückgegeben. Anderenfalls wird das Objekt selbst zurückgeliefert.
Fragt das interne Array mit den vom Benutzer bereitgestellten Namen für die zu "dumpenden" Werte ab oder ersetzt diese. Erfolgt der Aufruf ohne Argumente, werden die Namen zurückgegeben. Anderenfalls wird das Objekt selbst zurückgeliefert.
Löscht die interne Tabelle der "gesehenen" Referenzen und gibt das Objekt selbst zurück.
Gibt die Werte in der Liste entsprechend den nachfolgenden Konfigurationsoptionen in Form eines Strings zurück. Die Werte werden bei der Ausgabe mit $VARn benannt, wobei n ein numerisches Suffix ist. Zurückgegeben wird eine Liste von Strings im Arraykontext.
Entspricht der obigen Dumper()-Funktion, ruft aber die XSUB-Implementierung auf. Ist nur verfügbar, wenn Sie in der Lage waren, die XSUB-Erweiterung für Data::Dumper zu kompilieren und zu installieren.
Verschiedene Konfigurationsvariablen können verwendet werden, um bei Verwendung der prozeduralen Schnittstelle die Art der Ausgabe zu kontrollieren. Diese Variablen liegen üblicherweise local in einem Block, so daß andere Teile des Codes von Änderungen nicht betroffen sind.
Diese Variablen bestimmen den Standardzustand des Objekts, das durch einen Aufruf von new erzeugt wurde. Sie können allerdings nicht verwendet werden, um später den Zustand des Objekts zu ändern. Die gleichlautenden Methodennamen müssen verwendet werden, um den internen Zustand eines Objekts abzufragen bzw. zu ändern.
Die Methodenformen rufen das Objekt selbst auf, wenn der Aufruf ohne Argumente erfolgt, d.h., sie können auf einfache Weise verkettet werden.
Legt die Art der Einrückung für die Ausgabe fest. Kann auf 0, 1, 2 oder 3 gesetzt werden. Bei 0 erfolgt die Ausgabe ohne irgendwelche Zeilenvorschübe, Einrückungen oder Leerzeichen zwischen den Listenelementen. Hierbei handelt es sich um das kompakteste Format, das immer noch als gültiges Perl bezeichnet werden kann. Bei 1 erfolgt die Ausgabe in einer lesbaren Form mit Zeilenvorschüben, aber ohne nette Einrückungen (jede Ebene der Struktur wird einfach nur um eine feste Zahl von Whitespaces eingerückt). Bei Typ 2 (Standard) erfolgt die Ausgabe in einer sehr leicht zu lesenden Form, bei der die Länge der Hashschlüssel berücksichtigt wird (so daß die Hashwerte alle in einer Reihe liegen). Typ 3 entspricht Typ 2, versieht die Elemente von Arrays aber auch mit ihrem Index (wobei der Kommentar in einer eigenen Zeile vorliegt, was bedeutet, daß die Ausgabe doppelt so viele Zeilen benötigt). Voreingestellt ist Typ 2.
Legt den Grad fest, zu dem die Ausgabe evaluiert werden kann, um die übergebenen Referenzstrukturen neu zu erzeugen. Setzen Sie den Wert auf 1, werden zusätzliche Perl-Anweisungen ausgegeben, die verschachtelte Referenzen korrekt regenerieren. Voreingestellt ist 0.
Legt den String fest, der jeder Ausgabezeile vorangestellt wird. Standardmäßig der Leer-String.
Enthält das Präfix, das Variablennamen in der Ausgabe vorangestellt wird. Voreingestellt ist "VAR".
Falls gesetzt, wird die Verwendung von Anführungszeichen für String-Werte aktiviert. Whitespace-Zeichen (außer Leerzeichen) werden als [\n\t\r] dargestellt, "unsichere" Zeichen werden über Backslashes geschützt, und nicht-druckbare Zeichen werden als entsprechend gesicherte Oktalwerte ausgegeben. Weil das Setzen dieser Variable zu einem Performanzverlust führt, ist sie standardmäßig mit 0 voreingestellt. Die Dumpxs()-Methode unterstützt dieses Flag noch nicht.
Falls gesetzt, gibt Data::Dumper einzelne, nicht selbstreferenzierte Werte als Atome/Terme aus und nicht als Anweisungen. Das bedeutet, daß die Namen $VARn, wann immer möglich, vermieden werden. Es sei aber auch darauf hingewiesen, daß diese Ausgabe nicht immer von eval verarbeitet werden kann.
Kann auf einen Methodennamen gesetzt werden bzw. auf einen Leer-String, wenn dieses Feature deaktiviert werden soll. Data::Dumper ruft diese Methode über das Objekt auf, bevor versucht wird, die Struktur in Form eines Strings zurückzugeben. Diese Methode kann den Inhalt des Objekts ändern (wenn beispielsweise über C bereitgestellte Daten enthalten sind) oder das Objekt sogar über bless in einem anderen Objekt freigeben. Der Client ist dafür verantwortlich, daß die spezifizierte Methode über das Objekt aufgerufen werden kann und daß das Objekt nur Perl-Datentypen enthält, nachdem die Methode aufgerufen wurde. Voreingestellt mit einem Leer-String.
Kann auf einen Methodennamen gesetzt werden bzw. auf einen Leer-String, wenn dieses Feature deaktiviert werden soll. Data::Dumper setzt einen Methodenaufruf für jedes zu "dumpende" Objekt ab, wobei die Syntax bless(DATA, CLASS)-METHOD()> verwendet wird. Beachten Sie, daß die spezifizierte Methode alle für das Objekt notwendigen Modifikationen vornehmen (etwa die Einstellung eines neuen Zustands oder die Freigabe in einem anderen Paket mittels bless) und es dann zurückgeben muß. Der Client ist dafür verantwortlich, daß die Methode über das Objekt aufgerufen werden kann und daß ein gültiges Objekt zurückgeliefert wird. Voreingstellt ist ein Leer-String.
Kann auf einen Booleschen Wert gesetzt werden, um auch tiefe Strukturen zu kopieren. Cross-Referenzen werden nur dann angelegt, wenn es absolut notwendig ist (d.h. um Referenzkreise aufzubrechen). Voreingestellt ist 0.
Kann auf einen Booleschen Wert gesetzt werden, um festzulegen, ob Hashschlüssel mit Quoting-Zeichen versehen werden. Ein falsch-Wert vermeidet das Quoting von Hashschlüsseln, wenn diese nach einfachen Strings aussehen. Voreingestellt ist 1, was Hashschlüssel immer in Quoting-Zeichen setzt.
Kann auf einen String gesetzt werden, der eine Alternative zum integrierten Operator bless (mit dem Objekte erzeugt werden) bereitstellt. Eine Funktion mit dem entsprechenden Namen muß existieren und muß die gleichen Argumente akzeptieren wie der fest integrierte Operator. Voreingestellt ist bless.
Führen Sie die folgenden Codeschnipsel aus, um ein Gefühl für das Verhalten dieses Moduls zu entwickeln. Wenn Sie mit diesen Beispielen durch sind, können Sie die weiter oben beschriebenen Konfigurationsvariablen ändern/hinzufügen, um deren Verhalten zu untersuchen. (Weitere Beispiele finden Sie in der Testsektion der Data::Dumper-Distribution.)
use Data::Dumper;
package Foo;
sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};
package Fuz; # ein seltsames REF-REF-SKALAR-Objekt
sub new {bless \($_ = \ 'fu\'z'), $_[0]};
package main;
$foo = Foo->new;
$fuz = Fuz->new;
$boo = [ 1, [], "abcd", \*foo,
{1 => 'a', 023 => 'b', 0x45 => 'c'},
\\"p\q\'r", $foo, $fuz];
########
# einfache Nutzung
########
$bar = eval(Dumper($boo));
print($@) if $@;
print Dumper($boo), Dumper($bar); # Pretty-Print (ohne Arrayindizes)
$Data::Dumper::Terse = 1; # Nach Möglichkeit keine Namen ausgeben.
$Data::Dumper::Indent = 0; # Pretty-Print komplett deaktivieren.
print Dumper($boo), "\n";
$Data::Dumper::Indent = 1; # einfacher Pretty-Print
print Dumper($boo);
$Data::Dumper::Indent = 3; # Pretty-Print mit Arrayindizes
print Dumper($boo);
$Data::Dumper::Useqq = 1; # Quoting von Strings
print Dumper($boo);
########
# rekursive Strukturen
########
@c = ('c');
$c = \@c;
$b = {};
$a = [1, $b, $c];
$b->{a} = $a;
$b->{b} = $a->[1];
$b->{c} = $a->[2];
print Data::Dumper->Dump([$a,$b,$c], [qw(a b c)]);
$Data::Dumper::Purity = 1; # Löcher für eval stopfen.
print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # Ausgabe als @a
print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # Ausgabe als %b
$Data::Dumper::Deepcopy = 1; # keine Cross-Referenzen
print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
$Data::Dumper::Purity = 0; # keine Cross-Referenzen
print Data::Dumper->Dump([$b, $a], [qw(*b a)]);
########
# objektorientierter Ansatz
########
$d = Data::Dumper->new([$a,$b], [qw(a b)]);
$d->Seen({'*c' => $c}); # Referenz verschwinden lassen, ohne sie auszugeben.
$d->Indent(3);
print $d->Dump;
$d->Reset->Purity(0); # Cache leeren.
print join "----\n", $d->Dump;
########
# Persistenz
########
package Foo;
sub new { bless { state => 'awake' }, shift }
sub Freeze {
my $s = shift;
print STDERR "Gehe schlafen\n";
$s->{state} = 'asleep';
return bless $s, 'Foo::ZZZ';
}
package Foo::ZZZ;
sub Thaw {
my $s = shift;
print STDERR "Wache auf\n";
$s->{state} = 'awake';
return bless $s, 'Foo';
}
package Foo;
use Data::Dumper;
$a = Foo->new;
$b = Data::Dumper->new([$a], ['c']);
$b->Freezer('Freeze');
$b->Toaster('Thaw');
$c = $b->Dump;
print $c;
$d = eval $c;
print Data::Dumper->Dump([$d], ['d']);
########
# Substitution von Symbolen (nützlich zur Regenerierung von Codereferenzen)
########
sub foo { print "foo speaking\n" }
*other = \&foo;
$bar = [ \&other ];
$d = Data::Dumper->new([\&other,$bar],['*other','bar']);
$d->Seen({ '*foo' => \&foo });
print $d->Dump;
Aufgrund der Perl-Einschränkungen in der Semantik für Subroutinen können Sie kein Array und keinen Hash übergeben. Stellen Sie statt dessen ein \ voran, um eine entsprechende Referenz zu übergeben. Das wird sich mit der Zeit ändern, sobald eine spätere Perl-Version Prototypen einführt. Im Augenblick müssen Sie die erweiterte Form verwenden und dem Namen ein * voranstellen, um einen Hash oder ein Array auszugeben.
Data::Dumper schummelt bei CODE-Referenzen. Wird eine Codereferenz in der bearbeiteten Struktur entdeckt, wird eine anonyme Subroutine eingefügt, die den String "DUMMY" zurückliefert. Außerdem wird eine Warnung ausgegeben, wenn Purity gesetzt ist. Sie können das Ergebnis zwar evaluieren, dürfen aber nicht vergessen, daß die erzeugte anonyme Subroutine nur ein Platzhalter ist. Irgendwann wird Perl, so hoffe ich, einen Switch besitzen, mit dem bei Bedarf eine String-Version eines kompilierten Codes vorgehalten werden kann. Wenn Sie vorher wissen, welche Codereferenzen Ihre Datenstrukturen enthalten werden, können Sie die Seen-Methode verwenden, um die interne Referenztabelle durchzusehen und die "gedumpte" Ausgabe darauf verweisen zu lassen. Siehe auch "BEISPIELE".
Das Useqq-Flag wird von Dumpxs() nicht beachtet (Strings werden immer in Hochkommata eingeschlossen).
SKALAR-Objekte haben das am komischsten aussehende bless-Drumherum.
Version 2.10 (31. Oktober 1998)
Gurusamy Sarathy gsar@umich.edu
Copyright (c) 1996-98 Gurusamy Sarathy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
perl(1)