內容

名稱

Data::Dumper - 將 Perl 資料結構轉換為字串，適用於列印和 eval

用法

use Data::Dumper;

# simple procedural interface
print Dumper($foo, $bar);

# extended usage with names
print Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);

# configuration variables
{
  local $Data::Dumper::Purity = 1;
  eval Data::Dumper->Dump([$foo, $bar], [qw(foo *ary)]);
}

# OO usage
my $d = Data::Dumper->new([$foo, $bar], [qw(foo *ary)]);
   ...
print $d->Dump;
   ...
$d->Purity(1)->Terse(1)->Deepcopy(1);
eval $d->Dump;

說明

給定一個標量或引用變數的清單，將其內容以 Perl 語法輸出。這些引用也可以是物件。每個變數的內容將在單個 Perl 陳述中輸出。正確處理自我參照結構。

返回值可以進行 eval，以獲得原始參考結構的相同副本。 （請考慮從不受信任的來源 eval 代碼的安全性影響！）

任何與傳遞的參數之一相同的引用將被命名為 $VARn（其中 n 是數字後綴），其他對 $VARn 內子結構的重複引用將使用箭頭符號適當地標記。如果使用 Dump() 方法，則可以為要轉儲的個別值指定名稱，或者您可以將默認的 $VAR 前綴更改為其他內容。請參閱下面的 "設定變數或方法" 中的 $Data::Dumper::Varname 和 $Data::Dumper::Terse。

自我參照結構的默認輸出可以進行 eval，但對於 $VARn 的嵌套引用將是未定義的，因為不能使用一個 Perl 陳述構造遞歸結

在擴展的使用形式中，要轉儲的引用可以給定使用者指定的名稱。如果一個名稱以*開頭，則輸出將描述提供的引用的解引用類型，用於哈希和數組以及代碼引用。如果設置了Terse標誌，將盡可能避免輸出名稱。

在許多情況下，用於設置對象內部狀態的方法將返回對象本身，因此方法調用可以方便地連鎖在一起。

可以使用幾種不同的輸出風格，所有這些都由設置Indent標誌來控制。詳細信息請參閱下面的“配置變量或方法”。

方法

PACKAGE->new(ARRAYREF [, ARRAYREF])

返回一個新創建的Data::Dumper對象。第一個參數是要轉儲的匿名數組的值。可選的第二個參數是值的匿名數組的名稱。名稱不需要以$符號開頭，必須由字母數字字符組成。您可以以*開頭來指定必須轉儲解引用類型而不是引用本身，用於數組和哈希引用。

如果值的名稱未定義，則將使用$Data::Dumper::Varname指定的前綴以數字後綴。

在轉儲值時，Data::Dumper將對所有遇到的引用進行目錄化。交叉引用（以perl語法中的子結構名稱的形式）將插入到所有可能的點上，保留原始值集中的任何結構相互依賴。結構遍歷是深度優先的，並按照從第一個提供的值到最後的順序進行。

$OBJ->Dump 或 PACKAGE->Dump(ARRAYREF [, ARRAYREF])

返回对象中存储值的字符串形式（保留它们被提供给 new 的顺序），受下面配置选项的影响。在列表上下文中，它返回与提供的值对应的字符串列表。

为方便起见，第二种形式在立即转储对象之前简单地在其参数上调用 new 方法。

$OBJ->Seen([HASHREF])

查询或添加到已经遇到的引用的内部表中。如果需要，您必须使用 Reset 明确清除表格。这样的引用不会被转储；相反，它们的名称将被插入到随后遇到它们的地方。这对于正确地转储子例程引用特别有用。

期望一个匿名散列的名称 => 值对。与 new 中的名称相同的规则适用。如果未提供参数，则将以列表上下文返回名称 => 值对的“已看到”列表。否则，返回对象本身。

$OBJ->Values([ARRAYREF])

查询或替换将要转储的值的内部数组。当不带参数调用时，将值作为列表返回。当用替换值数组的引用调用时，返回对象本身。当用其他类型的参数调用时，将会报错。

$OBJ->Names([ARRAYREF])

查询或替换将要转储的值的用户提供名称的内部数组。当不带参数调用时，返回名称。当用替换名称数组调用时，返回对象本身。如果替换名称的数量超过要命名的值的数量，则不会使用多余的名称。如果替换名称的数量少于要命名的值的数量，则替换名称列表将耗尽，剩余的值将不会重命名。当用其他类型的参数调用时，将会报错。

$OBJ->Reset

清除“已看到”引用的内部表并返回对象本身。

函数

Dumper(LIST)

返回列表中值的字符串形式，受下面配置选项的影响。输出中的值将以 $VARn 的形式命名，其中 n 是数字后缀。在列表上下文中返回字符串列表。

配置变量或方法

在使用过程化接口时可以使用几个配置变量来控制生成的输出类型。通常，这些变量在一个块中被 local 化，以便代码的其他部分不受更改的影响。

这些变量确定通过调用 new 方法创建的对象的默认状态，但不能用于改变之后对象的状态。应使用等效的方法名称来查询或设置对象的内部状态。

当使用参数调用方法形式时，将返回对象本身，以便它们可以很好地链接在一起。

導出

Dumper

示例

運行這些代碼片段以快速了解此模塊的行為。在完成這些示例後，您可能希望添加或更改上面描述的各種配置變量，以查看它們的行為。（請參見Data::Dumper發行版中的測試套件以獲取更多示例。）

use Data::Dumper;

package Foo;
sub new {bless {'a' => 1, 'b' => sub { return "foo" }}, $_[0]};

package Fuz;                       # a weird REF-REF-SCALAR object
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];

########
# simple usage
########

$bar = eval(Dumper($boo));
print($@) if $@;
print Dumper($boo), Dumper($bar);  # pretty print (no array indices)

$Data::Dumper::Terse = 1;        # don't output names where feasible
$Data::Dumper::Indent = 0;       # turn off all pretty print
print Dumper($boo), "\n";

$Data::Dumper::Indent = 1;       # mild pretty print
print Dumper($boo);

$Data::Dumper::Indent = 3;       # pretty print with array indices
print Dumper($boo);

$Data::Dumper::Useqq = 1;        # print strings in double quotes
print Dumper($boo);

$Data::Dumper::Pair = " : ";     # specify hash key/value separator
print Dumper($boo);


########
# recursive structures
########

@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;         # fill in the holes for eval
print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b


$Data::Dumper::Deepcopy = 1;       # avoid cross-refs
print Data::Dumper->Dump([$b, $a], [qw(*b a)]);


$Data::Dumper::Purity = 0;         # avoid cross-refs
print Data::Dumper->Dump([$b, $a], [qw(*b a)]);

########
# deep structures
########

$a = "pearl";
$b = [ $a ];
$c = { 'b' => $b };
$d = [ $c ];
$e = { 'd' => $d };
$f = { 'e' => $e };
print Data::Dumper->Dump([$f], [qw(f)]);

$Data::Dumper::Maxdepth = 3;       # no deeper than 3 refs down
print Data::Dumper->Dump([$f], [qw(f)]);


########
# object-oriented usage
########

$d = Data::Dumper->new([$a,$b], [qw(a b)]);
$d->Seen({'*c' => $c});            # stash a ref without printing it
$d->Indent(3);
print $d->Dump;
$d->Reset->Purity(0);              # empty the seen cache
print join "----\n", $d->Dump;


########
# persistence
########

package Foo;
sub new { bless { state => 'awake' }, shift }
sub Freeze {
    my $s = shift;
    print STDERR "preparing to sleep\n";
    $s->{state} = 'asleep';
    return bless $s, 'Foo::ZZZ';
}

package Foo::ZZZ;
sub Thaw {
    my $s = shift;
    print STDERR "waking up\n";
    $s->{state} = 'awake';
    return bless $s, 'Foo';
}

package main;
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']);


########
# symbol substitution (useful for recreating CODE refs)
########

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;


########
# sorting and filtering hash keys
########

$Data::Dumper::Sortkeys = \&my_filter;
my $foo = { map { (ord, "$_$_$_") } 'I'..'Q' };
my $bar = { %$foo };
my $baz = { reverse %$foo };
print Dumper [ $foo, $bar, $baz ];

sub my_filter {
    my ($hash) = @_;
    # return an array ref containing the hash keys to dump
    # in the order that you want them to be dumped
    return [
      # Sort the keys of %$foo in reverse numeric order
        $hash eq $foo ? (sort {$b <=> $a} keys %$hash) :
      # Only dump the odd number keys of %$bar
        $hash eq $bar ? (grep {$_ % 2} keys %$hash) :
      # Sort keys in default order for all other hashes
        (sort keys %$hash)
    ];
}

已知問題

由於Perl子例程調用語義的限制，您不能傳遞陣列或哈希。請在其前面加上\以傳遞其引用。這將在某個時候得到補救，現在Perl具有子例程原型。目前，您需要使用擴展使用形式，並在名稱前加上*以將其輸出為哈希或陣列。

Data::Dumper 透過 CODE 參考來欺騙。如果在處理的結構中遇到代碼參考（且您尚未設置 Deparse 標誌），則將插入一個包含字符串 '"DUMMY"' 的匿名子例程作為其位置，如果設置了 Purity，則會打印警告。您可以 eval 結果，但請注意，所創建的匿名子例程只是一個佔位符。即使使用 Deparse 標誌，在某些情況下，將結果傳遞給 eval 後會產生行為不同的結果；請參閱 B::Deparse 的文檔。

SCALAR 物件具有最奇怪的 bless 解決方法。

註

不同的 Perl 執行將具有不同的哈希鍵排序。此更改是出於更大的安全性考慮，參見 perlsec 中的「Algorithmic Complexity Attacks」。這意味著如果數據包含哈希，不同的 Perl 執行將具有不同的 Data::Dumper 輸出。如果需要從不同的 Perl 執行獲得相同的 Data::Dumper 輸出，請使用環境變數 PERL_HASH_SEED，參見 perlrun 中的「PERL_HASH_SEED」。使用這個方法可以恢復舊的（特定於平台的）排序：更好的解決方法可能是使用 Data::Dumper 的 Sortkeys 過濾器。

作者

Gurusamy Sarathy gsar@activestate.com

版權所有（c）1996-2019 Gurusamy Sarathy。保留所有權利。本程序是自由軟件；您可以按照 Perl 本身的相同條款重新發布或修改它。

版本

版本 2.188

參見

perl(1)