eval両用文字列化
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
# OO 用法
$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 して元々参照したものと同一の複製にもどすことが
できます.
渡されたもののいずれかと同じリファレンスは $VARn (nは数値の
サフィックス) となり, $VARn の中の部分構造への重複したリファレンス
矢印記法を用いて適切にラベル付けされます. Dump() メソッドを
用いたり, $VAR プレフィックスをデフォルトから他の何かに変えることで
ダンプされる個々の値の名前を指定することもできます.
後述の $Data::Dumper::Varname 及び $Data::Dumper::Terse を
参照してください.
自己参照している構造のデフォルトの出力は eval することができますが,
$VARn へのネストしたリファレンスは, 再帰した構造をPerl文１つで
構築できないために未定義です. これらのリファレンスを正しく出力するには
Purity フラグに 1 を設定して複数の文での出力を行う必要があります.
拡張用法形式では, ダンプされるリファレンスはユーザが指定した名前と共に
与えることができます. 名前が * で始まっていると出力は供給された
ハッシュ, 配列, コードリファレンスをデリファレンスした型で記述します.
Terse フラグを設定したときは可能な場所であれば名前の出力が抑制されます.
オブジェクトの内部状態を設定するために使われる関数の多くはオブジェクト 自身を返します. これはメソッドを連続して呼び出すのに便利です.
Indent フラグを設定することでいくつかの出力形式が利用できます.
詳細は後述の 設定変数及びメソッド を参照してください.
新しく Data::Dumper オブジェクトを生成して返します.
最初の引数はダンプしたい値の配列へのリファレンスです.
２番目の引数は省略可能で, 値に対応する名前を配列への引数で
渡します. 名前は $ で始まっていなくてもかまいません.
しかし英数文字で構成されていなければなりません. 名前を * で始めることで
ARRAY や HASH リファレンスに対してリファレンスではなくデリファレンスされた
型でダンプさせることができます.
値に対応する名前が未定義だったときには,
$Data::Dumper::Varname で指定されたプレフィックスに数値を追加したものが
使われます.
Data::Dumper は値をダンプした際に見つけたすべてのリファレンスを
取り出します. クロスリファレンス (perl構文において部分構造の名前の
形式での)が発生する地点に挿入されます. これによって元の値の集合での
構造が維持されます. 構造の走査順は深さ優先です. そして(newメソッドに)
最初に供給された値から最後に供給されたものの順で処理されていきます.
オブジェクトに格納された値の文字列形式を返します((Data::Dumperの)newに
渡された順番が維持されます). 後述する設定オプションの影響を受けます.
リストコンテキストでは供給された値に対応する文字列をリストで返します.
２番目の形式では, これはより便利な形式で, 与えられた引数を使って
オブジェクトを直にダンプする前に単純に new を呼び出します.
これまでに遭遇したリファレンスの内部テーブルを問い合わせもしくは
追加します. 必要であるのなら, 明示的にテーブルをクリアするために
Reset を使わなければなりません. その様なリファレンスはダンプされず,
サブクエリでそれらに遭遇した箇所には代わりに名前がダンプされます.
これは特にサブルーティンリファレンスを適切にダンプするのに用います.
名前 => 値ペアの無名ハッシュは例外です. 同じルールが new での名前に
適用されます. もし引数がなのも渡されなければ, リストコンテキストにおいては
名前 => 値ペアの "既出" リストが返されます. そうでなければ
オブジェクト自身が返されます.
ダンプされる値の内部リストを取得もしくは置換します. 引数無しで呼ばれたときには値を返し, そうでなければ オブジェクト自身を返します.
ダンプされる値に対応してユーザが指定した名前の内部リストを取得 もしくは置換します. 引数無しで呼ばれたときには名前を, そうでなければ オブジェクト自身を返します.
"既出" リファレンスの内部テーブルをクリアし, オブジェクト自身を返します.
渡されたリストの値を文字列化して返します. 後述の設定オプションが適用
されます. 値の名前には $VARn が使われます. n は
数値のサフィックスです. リストコンテキストでは文字列のリストを返します.
いくつかの設定変数は関数インターフェースを使って生成される出力の
コントロールに使うことができます. これらの変数は変更してもコードの
他の部分に副作用をもたらさないように大抵は local して使います.
これらの変数は new メソッドを呼び出して作成されたオブジェクトの
初期状態を決定します. しかしそれ以降のオブジェクトの状態を変えることは
できません. (訳注: new の時点で初期状態が取り込まれ, それ以降は
設定変数を変更してもオブジェクトには影響しない.) オブジェクトの
内部状態を取得若しくは設定するには同じ名前のメソッドを使います.
メソッド形式は引数をつけて呼び出したときにはオブジェクト自身を返します. これはメソッドを連続して呼び出すのに便利です.
$Data::Dumper::Indent or $OBJ->Indent([NEWVAL])
インデントスタイルを制御します. 設定できる値は 0, 1, 2, 3 のいずれかです. スタイル 0 では改行, インデント, 項目間の空白を一切出力しません. 有効なperl文として呼び出せるものとしてとてもコンパクトな形式です. スタイル 1 では改行文字(訳注:及び基本的なインデント)を入れることで 可読性があがります. ファンシーなインデントはされません(構造の各行は 単純に固定幅の空白でインデントされるのみです). スタイル 2 (デフォルト) ではハッシュキーの長さも計算され(その為ハッシュの値も整列されます) 読みやすい形式です. スタイル 3 はスタイル 2 と似ていますが, 配列にはそのインデックスをコメントに入れます(しかしコメントはそれ自身で １行を取るため配列出力時には２倍の行になります). デフォルトのスタイルは 2 です.
$Data::Dumper::Purity or $OBJ->Purity([NEWVAL])
出力が eval された時にどの程度オリジナルの構造を再現できるかの
度合いを制御します. 1 を設定するとネストしたリファレンスを適切に
再構築する追加のPerl文が生成されるようになります.
デフォルトは 0 です.
$Data::Dumper::Pad or $OBJ->Pad([NEWVAL])
出力の各行に前置させる文字列を指定します. デフォルトは空文字列です.
$Data::Dumper::Varname or $OBJ->Varname([NEWVAL])
出力で変数名をタグ付けする為に使うプレフィックスを設定します. デフォルトは "VAR" です.
$Data::Dumper::Useqq or $OBJ->Useqq([NEWVAL])
設定すると文字列値の表現にダブルクオートの使用を有効にします.
スペース以外の白空白は [\n\r\t] の様に表現されます.
また, "安全ではない" 文字はバックスラッシュされ, 出力できない(unprintable)
文字は８進数として出力されます. この設定はパフォーマンス上のペナルティ
となるためデフォルトでは 0 になっています. このフラグを設定すると
Dump() が遅くなるのは高速な XSUB 実装がまだサポートされていないためです.
$Data::Dumper::Terse or $OBJ->Terse([NEWVAL])
設定すると単一の, 自己参照していない値を文としてではなくアトム/項として
出力します. つまり $VARn という名前部分が可能であれば省略されます.
但しこの出力は eval で認識できないこともあるかもしれません.
$Data::Dumper::Freezer or $OBJ->Freezer([NEWVAL])
メソッド名を設定できます. または空文字列を設定することでこの機能を 無効にもできます. Data::Dumper はオブジェクトを文字列化する前に オブジェクトの指定したメソッドを呼び出します. このメソッドでは オブジェクトの内容(例えばCでアロケートされたデータ等)を変更できます. 異なるパッケージblessし直すこともできます. クライアント(訳注:多分Freezer を使おうとした人)は指定したメソッドがオブジェクト経由で呼び出し可能 であること, そしてそのオブジェクトがメソッドの呼び出しを終えた時点で perl データ型のみを格納していることを保証するべきです. デフォルトでは空文字列です.
$Data::Dumper::Toaster or $OBJ->Toaster([NEWVAL])
メソッド名を指定します. またはから文字列を設定することでこの機能を
無効にもできます. Data::Dumper bless(DATA, CLASS)->METHOD() 構文を
使ってダンプされることになっているオブジェクトに対してメソッドコールを
発行します. そのメソッドではオブジェクトに対して(新しい状態を作ったり
異なるパッケージにblessし直す等)の変更をかけ, 返さなくてはなりません.
クライアントはそのメソッドがオブジェクト経由で呼び出すことができること,
そして有効なオブジェクトを返すことを保証するべきです.
デフォルトでは空文字列です.
$Data::Dumper::Deepcopy or $OBJ->Deepcopy([NEWVAL])
構造体のディープコピーを有効にするかどうかの真偽値を設定できます. クロスリファレンスは確実に効果があるときに行われるのみです(例えば リファレンス循環の停止等). デフォルトは 0 です.
$Data::Dumper::Quotekeys or $OBJ->Quotekeys([NEWVAL])
ハッシュキーをクオートするかどうかを制御する真偽値を設定できます. ハッシュキーが単純な文字列っぽいときは, 偽の値であればクオートを 回避します. デフォルトは 1 で, 常にハッシュキーをクオートします.
$Data::Dumper::Bless or $OBJ->Bless([NEWVAL])
オブジェクトを作成するために bless 組み込み演算子の替わりに
使われるものを文字列で指定します. 指定した名前を持つ関数が
存在しているべきです. また, ビルトインと同じ引数を受け取るべきです.
デフォルトは bless です.
$Data::Dumper::Pair or $OBJ->Pair([NEWVAL])
ハッシュキーと値との間の区切りとする文字列を設定できます.
ネストしたハッシュ, 配列, スカラー値を JavaScript にダンプする為には
$Data::Dumper::Pair = ' : '; を使います. JavaScript での
bless の実装は読者の課題としておきます.
(訳注:blessの一文が混ざってる？)指定した名前を持つ関数が
存在しているべきです. また, ビルトインと同じ引数を受け取るべきです.
デフォルト値: => .
$Data::Dumper::Maxdepth or $OBJ->Maxdepth([NEWVAL])
そこから先は構造に取り込まない深さを正の整数で設定できます.
Data::Dumper::Purity が設定されているときには効果を持ちません.
(デバッガなどである程度以上深くは見たくないときに便利です.)
デフォルトは 0 で, これは無制限を意味します.
$Data::Dumper::Useperl or $OBJ->Useperl([NEWVAL])
Data::Dumper の pure Perl 実装を使うかどうかの制御をする
真偽値を設定できます. Data::Dumper モジュールは多重実装されいて,
ほぼ全ての機能が pure Perl と共に XS ('C') でも記述されています.
XS バージョンはとても高速で, 可能であれば常に使われます. この
オプションではデフォルトの振る舞いを変えることができます.
大抵はテスト目的で使うのみでしょう. デフォルトは0 で, 可能であれば
XS 実装を使用します.
$Data::Dumper::Sortkeys or $OBJ->Sortkeys([NEWVAL])
ハッシュキーをダンプ時にソートするかどうかを制御する真偽値を
設定できます. 真を設定すると全てのハッシュのキーが Perl の sort 順で
ダンプされるようになります. また, 関数リファレンスを設定することで
ダンプされようとする各ハッシュ毎に呼び出せます. この時 Data::Dumper
は各ハッシュに対して一度, ハッシュのリファレンスを引数にして関数を
呼び出します. この関数の目的はダンプしたい順でダンプするキーを
配列のリファレンスとして返すことです. この機能を使う事で, キーの
順番と実際に出力するキーとを制御することができます. 言い換えると,
ダンプ時に特定のキーを除外するフィルタとして使うことができます.
デフォルトは 0 で, ソートしないことを意味します.
$Data::Dumper::Deparse or $OBJ->Deparse([NEWVAL])
コードリファレンスを perl ソースコードに変換するかどうかを制御する
真偽値を設定できます. 真に設定するとコードリファレンスのソースコード
を得るために B::Deparse が使われます. 高速な XSUB 実装はサポート
していないのでこのオプションはダンプしている Perl 実装に依存します.
警告: このオプションは, コードリファレンスが B::Deparse で正しく
再構成できる時にのみ使うようにしてください.
以下のコード片を実行することでこのモジュールの振る舞いをささっと 感じ取ることができます. これらの例を読み終える頃にはこれまでに説明 してきた設定変数を追加・変更したくなっているでしょう. (さらに 多くの例については 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
# eval 用の隙間埋め
print Data::Dumper->Dump([$a, $b], [qw(*a b)]); # print as @a
# @a で表示
print Data::Dumper->Dump([$b, $a], [qw(*b a)]); # print as %b
# %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
# 3つより深く行かない
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 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']);
########
# symbol substitution (useful for recreating CODE refs)
# シンボル置換 (CODEリファレンスの再構築に便利)
########
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
# 数値降順で %$foo のキーをソート
$hash eq $foo ? (sort {$b <=> $a} keys %$hash) :
# Only dump the odd number keys of %$bar
# %$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 することができますが, 作成された無名関数が
プレースホルダのように記憶されているだけです. いつの日か,
perl がコードのコンパイルされた断片の文字列形式を必要に応じて
キャッシュするように切り替わることを祈ります. データを構成している
すべてのコードリファレンスに対してそれがどういうものかより知っているのなら
内部リファレンステーブルに先に種をまいておくために Seen メソッドを
使うことができ, そしてダンプされる出力で代わりにそれを指すように
できます(訳注:この１文ちょっと不明).
前述の "EXAMPLES" を参照してください.
Useqq 及び Deparse フラグは Dump() の実行を遅くさせます.
これはこれらには XSUB 実装がサポートされていないためです.
SCALAR オブジェクトは奇妙な bless 検出動作をします(訳注:この文も
ちょっと不明).
Dat::Dumper の pure Perl バージョンは, Perl 5.8.0 及びそれ以降でのみ
UTF-8 文字列を適切にエスケープします.
Perl 5.8.1 から, Perl の実行毎に異なるハッシュキー順序を持ちます.
この変更はセキュリティの大きな向上となります.
"Algorithmic Complexity Attacks" in perlsec を参照してください.
これはデータにハッシュを含んでいる場合には Perl の実行毎に
異なる出力となることを意味します. もし Perl の別々の実行
毎でも同じ Data::Dumper 出力を必要とするのなら,
PERL_HASH_SEED を使うこともできます, これに関しては
"PERL_HASH_SEED" in perlrun を参照してください.
これを使うことで以前の(プラットフォーム依存の)順序に戻せます.
しかしもっと優れた解決方法は Data::Dumper の Sortkeys フィルタを
使うことでしょう.
Gurusamy Sarathy gsar@activestate.com
Copyright (c) 1996-98 Gurusamy Sarathy. All rights reserved. このプログラムはフリーソフトウェアです. このプログラムは Perl 自身と 同じ条件下で再配布・改変可能です.
Version 2.121 (Aug 24 2003)
perl(1)
山科 氷魚 (YAMASHINA Hio) <hio@hio.jp>
eval両用文字列化
eval両用文字列化