This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Pogo.jp, Next: PogoLink, Prev: Pogo, Up: Module List Perl GOODS interface ******************** NAME ==== Pogo - Perl GOODS interface SYNOPSIS ======== use Pogo; $pogo = new Pogo 'sample.cfg'; # データベースに接続 $root = $pogo->root_tie; # データベースのrootハッシュへの参照を得る $root->{key1} = "string"; # 文字列をデータベースに格納 $value = $root->{key1}; # $value は "string" $root->{key2} = [1,2,3]; # 配列をデータベースに格納 $arrayref = $root->{key1}; # データベース中の配列への参照を得る $value = $root->{key2}->[0]; # $value は 1 $root->{key3} = {a=>1,b=>2}; # ハッシュをデータベースに格納 $hashref = $root->{key3}; # データベース中のハッシュへの参照を得る $value = $root->{key3}->{b}; # $value は 2 $root->{key4} = new Pogo::Btree;# Bツリーハッシュを作る $hashref = $root->{key5}; # Bツリーはハッシュとしてアクセスできる $root->{key5} = new Pogo::Htree;# Hツリーハッシュを作る $hashref = $root->{key6}; # Hツリーはハッシュとしてアクセスできる $root->{key6} = new Aclass; # オブジェクトをデータベースに格納 $obj = $root->{key4}; # $obj はデータベース中の Aclass オブジェクト DESCRIPTION =========== 概要 ---- Pogo は GOODS (Generic Object Oriented Database System)の Perl インタ ーフェースです。Pogo は Perl のスカラや配列やハッシュやオブジェクトを ダイレクトにデータベースオブジェクトに対応づけます。Pogo には次のデー タタイプがあります。 - スカラー - 配列 - ハッシュ - Hツリー (ハッシュエントリ表がBツリーとなっているハッシュ) - Bツリー スカラーデータや集合タイプデータの要素の値は、文字列か、他のデータへの 参照です。Pogo は Perl の tie の仕組みを利用してデータベース中の永続デ ータへの透過的なアクセス方法を提供します。データベース中の各データは内 部的にクラス名を持てるので、Perl のオブジェクト（つまりクラス名で bless された参照）をデータベース中に格納できます。 GOODS サーバー -------------- Pogo のベースとなっている GOODS は、クライアントサーバー型のデータベー スです。Pogo のアプリケーションは、同じマシン上か TCP/IP でつながった 他のマシン上で動作中の、GOODS サーバープロセスを必要とします。GOODS サ ーバーのプログラムは「goodsrv」という名前で、/usr/local/goods/bin/ に インストールされます。Pogo のアプリケーションとそれに対応する goodsrv はお互いに通信するために同じ TCP ポートを使う必要があります。そのため に両者は、goodsrv のホスト名と TCP ポート番号を記載した同じ設定ファイ ルを参照します。設定ファイルは「.cfg」の拡張子でなければなりません。ロ ーカルマシン上の goodsrv に対する典型的な設定ファイルは次のような内容 になります。 1 0: localhost:6100 １行目の「1」はこのデータベースが一つの goodsrv を使うことを意味します （二つ以上使うことも可能ですが Pogo では一つしか使いません）。二行目の 「0: localhost:6100」は、一つ目の goodsrv が、localhost にあって、ポー ト番号6100を使うことを意味しています。 この設定ファイルが、「test.cfg」として作られているならば、goodsrvは次のように起動できます。 goodsrv test すると、goodsrv は次に示す一組のデータベースファイルを作成します。これ らのファイルを削除したり直接編集したりは絶対にしないでください。 test.his test.idx test.log test.map test.odb 起動した goodsrv はコンソールからのコマンド入力を待ちつつ、指定された TCP ポートを通じてデータベースサービスを提供します。コマンドによって、 データベースの統計情報を見たり、バックアップを取ったりできます。GOODS の readme.htm を参照してください。 実用上は、goodsrv はバックグラウンドプロセスとして起動されることになる でしょう。Pogo は、goodsrv をバックグラウンドで起動するためと、その goodsrv にコマンドを送るための、二つのユーティリティースクリプトを用意 しています。goodsrv を、test.cfg に従って起動するには次のようにします。 startgoodsrv test & この場合、goodsrvの画面出力はtest.goodsrv.logに保存されます。 goodsrvを終了するには、次のようにします。 cmdgoodsrv test exit tieインターフェース ------------------- 接続 まず最初に、実行中のGOODSサーバーに接続します。 $pogo = new Pogo $cfgfilename; $cfgfilename は GOODS サーバーを指定する設定ファイル名です。これで得ら れた Pogo オブジェクトは以下で使用します。 ルートを得る 次に、データベース中のルートBツリーへの参照を得ます。 $root = $pogo->root_tie; ノート：GOODS データベース中の永続データは、必ず他の永続データから参照 されていなくてはなりません。もしあるデータがどの永続データからも参照さ れなくなると、そのデータは GOODS のガベージコレクションシステムによっ て回収されます。このことから、データベースには少なくとも一つは、絶対的 な永続データがなければならないということになります。それがルートと呼ば れるデータです。Pogo データベースのルートは B ツリーデータです。 root_tie メソッドは、このルート B ツリーデータへの参照を返します。 文字列と数値 データベースにデータを格納するには、単に Perl のデータを $root を通じ て代入するだけです。$root はハッシュ参照であることに注意してください。 $root->{key} = "value"; $root->{pi} = 3.14; ノート：Pogo データベースでは、データ値文字列にはヌル文字（"\x00"）を 含むことができますが、ハッシュキー文字列には含むことができません。 ノート：数値3.14は文字列"3.14"として格納されます。このデータ変換はオー バーヘッドですので、将来の Pogo では直接数値として格納するようになるで しょう。 データベースにデータを格納したら、それを取り出すことができます。 $value = $root->{key}; # $value は "value" $pi = $root->{pi}; # $pi は "3.14" 配列とハッシュ 配列やハッシュを格納するには、参照を代入します。 $root->{key1} = \@array; $root->{key2} = [1,2,3]; $root->{key3} = \%hash; $root->{key4} = {a=>1,b=>2,c=>3}; $root->{key5} = {a=>[1,2],b=>{c=>3,d=>4}}; この代入は、参照だけを格納するのではなく、その配列やハッシュの中味もデ ータベースに格納されるということに注意してください。データベース中の永 続データは、非永続（つまりメモリ上の）データを参照することはできません ので。つまり、配列やハッシュのコピーがデータベース中に作られてその参照 が代入されることになるわけです。上の例で言えば、代入後に@array や % hash を変更しても、$root->{key1}の配列や $root->{key3}のハッシュが変更 されるわけではありません。 格納した値を得るには、普通に -> や [] や {} の記号を使えばよい。 $value = $root->{key5}->{a}->[1]; # $value は 2 $value = $root->{key5}{a}[1]; # {} や [] の間の -> は省略可能 もし指定した値がデータベース中の別のデータへの参照であった場合は、然る べき型の参照が得られます。その参照は、データベースにデータを格納したり 得たりするのに使えます。 $hashref = $root->{key4}; # ハッシュ参照を得る $hashref->{d} = 4; # データを格納する $value = $hashref->{c}; # $value は 3 ノート：CODEとIOの参照はデータベースに格納することはできません。 配列のサイズ Pogo の配列は必要なときに自動的に大きくなります。しかし、これはデータ ベース内のデータの再配置をともないます。配列参照が代入されたときには、 その配列のサイズに設定されますが、もし最大サイズが見積もれるなら、あら かじめサイズを設定しておくことをお勧めします。サイズを指定して配列を作 るには、Pogo::Array::new メソッドを使います。 $root->{sqrt} = new Pogo::Array 1000; for(0..999) { $root->{sqrt}->[$_] = sqrt $_; } ハッシュのサイズ Pogo のハッシュは、固定サイズのハッシュエントリ表を持ち、そのサイズを 変更することはできません。ハッシュエントリ表のサイズは、格納できるキー の数を制限するわけではありませんが、ハッシュエントリ表のサイズに対して 多すぎるキーを格納すると遅くなります。ですから、ハッシュの用途に応じて 適切なハッシュエントリ表のサイズを選ぶことが必要です。（将来の Pogo で は自動的なハッシュエントリ表のサイズ拡張がサポートされるようになるでし ょう。）ハッシュ参照が代入されるときには、そのハッシュと同じハッシュエ ントリ表のサイズが設定されます。ハッシュエントリ表のサイズを指定してハ ッシュを作るには、Pogo::Hash::new メソッドを使います。 $root->{smallhash} = new Pogo::Hash 8; $root->{largehash} = new Pogo::Hash 1024; サイズを省略すると、256になります。 Hツリー Pogo のハッシュのハッシュエントリ表は固定サイズの配列なので、あまり大 きなサイズのハッシュは実用的ではありません。もし非常に大きなハッシュが 必要なら、H ツリーを使ってください。H ツリーのハッシュエントリ表は B ツリーになっているので、巨大なサイズが可能です。ハッシュエントリ表のサ イズを指定して H ツリーを作るには、Pogo::Htree::new メソッドを使います。 $root->{hugehash} = new Pogo::Htree 131072; サイズを省略すると、65536になります。 Bツリー もうひとつの巨大ハッシュを作る方法は、B ツリーです。B ツリーでは、ハッ シュのキー自体が B ツリーのキーとなります。そのためにキーは自動的に整 列されることになります。また、ハッシュエントリ表のサイズのサイズの問題 はありません。その一方で、Pogo の B ツリーのキー索引はキー文字列の先頭 8バイトから作られるため、もし多くのキーが先頭8バイトが同じであると、そ のキーを検索は遅くなります。B ツリーを作るには、Pogo::Btree::new メソ ッドを使います。 $root->{btree} = new Pogo::Btree; サイズの指定は必要ありません。 tie インターフェースでは、ある文字列に部分一致するハッシュキーを探すと いうことはできません。それには、Pogo::tied_object と Pogo::Btree::find _key を使います。 $foundkey = Pogo::tied_object($root->{btree})->find_key($string); Pogo::tied_object は、データの参照先に tie された隠れたオブジェクトを 返します。$root->{btree}が B ツリーであれば、Pogo::tied_object($root-> {btree}) は Pogo::Btree オブジェクトになります。そして、Pogo::Btree:: find_key メソッドは、指定された文字列に前方部分一致するキーを返します。 Nツリー B ツリーでキーを整数値として扱いたい場合があります。つまり、「10」が 「2」より後になるようにしたい（B ツリーでは文字列として扱うので逆にな る）。そういう場合には N ツリーを使えば、キーは long 整数値として扱わ れます。その点を除けば B ツリーと同じです。 $root->{ntree} = new Pogo::Ntree; オブジェクト SCALAR/ARRAY/HASH 参照だけを使っている Perl オブジェクトであれば、Pogo データベースに格納できます。 sub Foo::new { bless {name => $_[1]}, $_[0]; } sub Foo::name { $_[0]->{name}; } $root->{obj} = new Foo "bar"; $obj = $root->{obj}; # $obj は Foo オブジェクト $name = $obj->name; # $name は "bar" もし、オブジェクトで使うハッシュエントリ表のサイズを指定したかったり、 H ツリーや B ツリーを使いたいという場合は、Pogo::Hash::new_tie、Pogo:: Htree::new_tie、Pogo::Btree::new_tie のメソッドを使ってください。 sub Bar::new { my($class, $name) = @_; my $self = new_tie Pogo::Htree 10000; $self->{name} = $name; bless $self, $class; } Pogo::*::new_tie を使ったクラスは Pogo データベース用になることに注意 してください。 トランザクション Pogo にはトランザクション機構があります。もしデータベースについての一 連の操作を「不可分」としたい場合、トランザクションを使います。「不可 分」とは、一連の操作がすべて成功裏に実行されるか、あるいは何も行われな いか、のどちらかであることを意味します。また、他のデータベースクライア ントが、その一連の操作に割り込んで来ないことも意味しています。 データベース全体についてのトランザクションを操作するには、Pogo:: begin_transaction、Pogo::abort_transaction、Pogo::end_transaction のメ ソッドを使います。 $root->{key} = 1; $pogo->begin_transaction; $root->{key} = 2; $pogo->abort_transaction; # 中止: 上の代入はキャンセルされる $value = $root->{key}; # $value は 1 のまま $pogo->begin_transaction; $root->{key} = 3; $pogo->end_transaction; # 終了: 上の代入は有効 $value = $root->{key}; # $value は 3 これらのメソッドは、クラスメソッドとしてではなく、オブジェクトメソッド として呼ばなければなりません。 このトランザクションはデータベース全体をロックするので、長時間のトラン ザクションは並行処理の効率を低下させます。 データ毎のトランザクションが必要な場合は、Pogo::atomic_call メソッドを 使います。 $root->{key} = \@array; Pogo::atomic_call(\&sortarray, $root->{key}); sub sortarray { my $aref = shift; @$aref = sort @$aref; } sortarray が呼ばれている間、$root->{key}はロックされます。従って他のデ ータベースクライアントがソートを邪魔することがありませんし、ソートが中 途半端に終わるということもありません。 データ毎のトランザクションには、ユーザーによる中止の機能はありません。 受動的動作 データベース中のデータを監視し、他のデータベースクライアントによってそ のデータが変更されたら何かの処理をする、というスクリプトが必要な場合は、 Pogo::wait_modification 関数を使います。 $result = Pogo::wait_modification($root->{key}, 5); この文が実行されると、$root->{key}が他のデータベースクライアントによっ て変更されるか、5秒経つまで、実行は止まります。$result は、データが変 更された場合は1、時間切れの場合は0になります。 時間切れまでの秒数を省略すると、永遠に待ち続けます。 データベースブラウザ -------------------- Pogo には Pogo データベースの内容を覗くスクリプト browse が付属してい ます。test.cfg のデータベースを覗くには、次のように実行します。 browse test すると、browseは次のように表示して、コマンド入力を待ちます。 test.cfg opened root=(HASH(Btree)(10000))> 「ls」と入力するとルート B ツリーハッシュの内容が例えば次のように見ら れます。他のデータへの参照についてはクラス名、データ種別、オブジェクト ID が表示されます。 {aobj} = Aclass(HASH(Hash)(1012d)) {index} = (HASH(Btree)(10282)) {list} = (ARRAY(10036)) {name} = "test" ここで「cd index」と入力すると、現在位置が $root->{index}になり、プロ ンプトは次のように変わります。 root{index}=(HASH(Btree))> 「cd」と入力するとルートに戻ります。「cd ..」と入力すると親に戻ります。 「exit」で終了です。 メソッド -------- 「クラスメソッド」と記されたもの以外は、オブジェクトメソッドです。[]記 号は省略可能な引数を意味します。 $pogo = Pogo->new [config_filename] クラスメソッド。Pogo オブジェクトを作って返します。config_filename が 指定されていると、その設定ファイルに従って動作している GOODS サーバー に接続します。対応する GOODS サーバーは動作中でなければなりません。 $pogo->open config_filename もし Pogo オブジェクトがまだ GOODS サーバーに接続していなければ、この メソッドで接続します。 $pogo->close GOODS サーバーとの接続を切ります。このメソッドを使う必要はありません。 Pogo オブジェクトが破棄されるときに自動的に実行されます。 $pogo->root ルートBツリーに対応したPogo::Btreeオブジェクトを作って返します。 $pogo->root_tie ルート B ツリーに対応した Pogo::Btree オブジェクトを作り、それに tie されたハッシュへの参照を返します。 $pogo->begin_transaction トランザクションを開始します。 $pogo->abort_transaction トランザクションを中止します。 $pogo->end_transaction トランザクションを終了します。 $obj = Pogo::Scalar->new [pogoobj] クラスメソッド。Pogo::Scalar オブジェクトを作って返します。Pogo オブジ ェクト pogoobj を指定した場合は、そのデータベースに格納されます。 $scalarref = Pogo::Scalar->new_tie [pogoobj [,class]] クラスメソッド。Pogo::Scalar オブジェクトを作り、スカラをそれに tie し、 そのスカラの参照を返します。Pogo オブジェクト pogoobj を指定した場合は、 そのデータベースに格納されます。クラス名 class を指定した場合は、その クラス名で bless されます。 $obj = Pogo::Array->new [size [,pogoobj]] クラスメソッド。size で指定されたサイズの Pogo::Array オブジェクトを作 って返します。size が省略されると、1になります。Pogo オブジェクト pogoobj を指定した場合は、そのデータベースに格納されます。 $arrayref = Pogo::Array->new_tie [size [,pogoobj [,class]]] クラスメソッド。size で指定されたサイズの Pogo::Array オブジェクトを作 り、配列をそれに tie し、その配列の参照を返します。 size が省略される と、1になります。Pogo オブジェクト pogoobj を指定した場合は、そのデー タベースに格納されます。クラス名 class を指定した場合は、そのクラス名 で bless されます。 $obj = Pogo::Hash->new [size [,pogoobj]] クラスメソッド。size で指定されたサイズのハッシュエントリ表の Pogo:: Hash オブジェクトを作って返します。size が省略されると、256 になります。 Pogo オブジェクト pogoobj を指定した場合は、そのデータベースに格納され ます。 $hashref = Pogo::Hash->new_tie [size [,pogoobj [,class]]] クラスメソッド。size で指定されたサイズのハッシュエントリ表の Pogo:: Hash オブジェクトを作り、ハッシュをそれに tie し、そのハッシュの参照を 返します。size が省略されると、256 になります。Pogo オブジェクト pogoobj を指定した場合は、そのデータベースに格納されます。クラス名 class を指定した場合は、そのクラス名で bless されます。 $obj = Pogo::Htree->new [size [,pogoobj]] クラスメソッド。size で指定されたサイズのハッシュエントリ表の Pogo:: Htree オブジェクトを作って返します。size が省略されると、 65536 になり ます。Pogo オブジェクト pogoobj を指定した場合は、そのデータベースに格 納されます。 $hashref = Pogo::Htree->new_tie [size [,pogoobj [,class]]] クラスメソッド。size で指定されたサイズのハッシュエントリ表の Pogo:: Htree オブジェクトを作り、ハッシュをそれに tie し、そのハッシュの参照 を返します。size が省略されると、 65536 になります。Pogo オブジェクト pogoobj を指定した場合は、そのデータベースに格納されます。クラス名 class を指定した場合は、そのクラス名で bless されます。 $obj = Pogo::Btree->new [pogoobj] クラスメソッド。Pogo::Btree オブジェクトを作って返します。Pogo オブジ ェクト pogoobj を指定した場合は、そのデータベースに格納されます。 $hashref = Pogo::Btree->new_tie [pogoobj [,class]] クラスメソッド。Pogo::Btree オブジェクトを作り、ハッシュをそれに tie し、そのハッシュの参照を返します。Pogo オブジェクト pogoobj を指定した 場合は、そのデータベースに格納されます。クラス名 class を指定した場合 は、そのクラス名で bless されます。 $obj = Pogo::Ntree->new [pogoobj] クラスメソッド。Pogo::Ntree オブジェクトを作って返します。Pogo オブジ ェクト pogoobj を指定した場合は、そのデータベースに格納されます。 $hashref = Pogo::Ntree->new_tie [pogoobj [,class]] クラスメソッド。Pogo::Ntree オブジェクトを作り、ハッシュをそれに tie し、そのハッシュの参照を返します。Pogo オブジェクト pogoobj を指定した 場合は、そのデータベースに格納されます。クラス名 class を指定した場合 は、そのクラス名で bless されます。 ノート：これらの Pogo::*::new や Pogo::*::new_tie メソッドで作られたオ ブジェクトは、引数で Pogo オブジェクトが指定されない限り、メモリ上にあ り、まだ永続的ではありません。既存の永続データに代入された時に始めて、 永続データになります。また、引数に Pogo オブジェクトを指定すると、その データベースに格納されますが、やはり既存の永続データに参照されて始めて 真に永続データになります。 ユーティリティー関数 -------------------- Pogo::type_of 指定されたPogoデータの参照タイプ、クラス名、tieクラス名を返します。 ($reftype, $class, $tiedclass) = Pogo::type_of($root->{key}); 例えば次のような値が得られます。 () : 参照でない ('ARRAY', '', 'Pogo::Array') : 配列 ('HASH', '', 'Pogo::Btree') : Bツリーハッシュ ('HASH', 'Aclass', 'Pogo::Hash') : Aclassオブジェクト Pogo::tied_object 指定されたPogoデータの参照先がtieされたPogo::*オブジェクトを返します。 Pogo::equal 二つの Pogo データを引数にとって、それが同じデータベースオブジェクトを 指すなら1、違うなら0を返します。 Pogo::object_id 指定されたPogoデータのデータベースオブジェクトIDを返します。 Pogo::atomic_call 指定された関数を「不可分」に実行し、その結果を返します。 $result = Pogo::atomic_call(\&func, $data, @args); \&func はサブルーチン参照、$data は Pogo データです。$data は実行中ロ ックされます。ロックがおこなわれる点を除けば、次と同じです。 $result = func($data, @args); funcはスカラコンテキストで呼ばれ、返り値は整数に変換されます。 Pogo::wait_modification 指定されたデータが他のデータベースクライアントによって変更されるか、あ るいは指定された秒数経つまで待ちます。データが変更された場合は1、時間 切れの場合は0を返します。 $result = Pogo::wait_modification($data, $sec); 時間切れまでの秒数が省略されると、永遠に待ちます。 低レベルメソッド ---------------- 以下のメソッドはtieインターフェース内部で使われているものです。 Pogo::Var Pogo::Var は、以下の Pogo::*クラス群すべての抽象基本クラスです。Pogo:: Var オブジェクトは使えません。 Pogo::Var::get_class Pogo::Var::set_class Pogo::Var::begin_transaction Pogo::Var::abort_transaction Pogo::Var::end_transaction Pogo::Var::call Pogo::Var::equal Pogo::Var::wait_modification Pogo::Var::object_id Pogo::Scalar Pogo::Scalar::get Pogo::Scalar::set Pogo::Array Pogo::Array::get Pogo::Array::set Pogo::Array::get_size Pogo::Array::set_size Pogo::Array::clear Pogo::Array::push Pogo::Array::pop Pogo::Array::insert Pogo::Array::remove Pogo::Hash Pogo::Hash::get Pogo::Hash::set Pogo::Hash::exists Pogo::Hash::remove Pogo::Hash::clear Pogo::Hash::first_key Pogo::Hash::next_key Pogo::Htree Pogo::Htree::get Pogo::Htree::set Pogo::Htree::exists Pogo::Htree::remove Pogo::Htree::clear Pogo::Htree::first_key Pogo::Htree::next_key Pogo::Btree Pogo::Btree::get Pogo::Btree::set Pogo::Btree::exists Pogo::Btree::remove Pogo::Btree::clear Pogo::Btree::first_key Pogo::Btree::last_key Pogo::Btree::next_key Pogo::Btree::prev_key Pogo::Btree::find_key AUTHOR ====== 中島 靖 SEE ALSO ======== GOODSのreadme.htm  File: pm.info, Node: PogoLink, Next: PogoLink.jp, Prev: Pogo.jp, Up: Module List Bidirectional relationship class for objects in a Pogo database *************************************************************** NAME ==== PogoLink - Bidirectional relationship class for objects in a Pogo database SYNOPSIS ======== use PogoLink; # Define relationships package Person; sub new { my($class, $pogo, $name) = @_; # Make a hash ref persistent by $pogo and blessed by $class my $self = new_tie Pogo::Hash 8, $pogo, $class; %$self = ( NAME => $name, FATHER => new PogoLink::Scalar($self, 'Man', 'CHILDREN'), MOTHER => new PogoLink::Scalar($self, 'Woman', 'CHILDREN'), FRIENDS => new PogoLink::Btree ($self, 'Person', 'FRIENDS', 'NAME'), ); $self; } package Man; @ISA = qw(Person); sub new { my($class, $pogo, $name) = @_; my $self = $class->SUPER::new($pogo, $name); $self->{CHILDREN} = new PogoLink::Array ($self, 'Person', 'FATHER'); $self->{WIFE} = new PogoLink::Scalar($self, 'Woman', 'HUS'); $self; } package Woman; @ISA = qw(Person); sub new { my($class, $pogo, $name) = @_; my $self = $class->SUPER::new($pogo, $name); $self->{CHILDREN} = new PogoLink::Array ($self, 'Person', 'MOTHER'); $self->{HUS} = new PogoLink::Scalar($self, 'Man', 'WIFE'); $self; } # Use relationships $Pogo = new Pogo 'sample.cfg'; $Dad = new Man $Pogo, 'Dad'; $Mom = new Woman $Pogo, 'Mom'; $Jr = new Man $Pogo, 'Jr'; $Gal = new Woman $Pogo, 'Gal'; # Marriage $Dad->{WIFE}->add($Mom); # $Mom->{HUS} links to $Dad automatically # Birth $Dad->{CHILDREN}->add($Jr); # $Jr->{FATHER} links to $Dad automatically $Mom->{CHILDREN}->add($Jr); # $Jr->{MOTHER} links to $Mom automatically # Jr gets friend $Jr->{FRIENDS}->add($Gal); # $Gal->{FRIENDS} links to $Jr automatically # Oops! Gal gets Dad $Gal->{HUS}->add($Dad); # $Dad->{WIFE} links to $Gal automatically # $Mom->{HUS} unlinks to $Dad automatically DESCRIPTION =========== PogoLink makes single-single or single-multi or multi-multi bidirectional relationships between objects in a Pogo database. The relationships are automatically maintained to link each other correctly. You can choose one of Pogo::Array, Pogo::Hash, Pogo::Htree, Pogo::Btree and Pogo::Ntree to make a multi end of link. Classes ------- PogoLink::Scalar This class makes a single end of link. PogoLink::Array This class makes a multi end of link as an array. It uses Pogo::Array to have links. PogoLink::Hash, PogoLink::Htree, PogoLink::Btree, PogoLink::Ntree These classes make a multi end of link as a hash. Each uses corresponding Pogo::* to have links. Methods ------- new PogoLink::* $selfobject, $linkclass, $invattr, $keyattr Constructor. Class method. $selfobject is a object in the database which possesses this link. It must be a object as a hash reference. $linkclass is a class name of linked object. If $linkclass defaults, any class object is allowed. $invattr is an attribute (i.e. hash key) name of the linked object which links inversely. $keyattr is only necessary for PogoLink::Hash, PogoLink::Htree, PogoLink::Btree, PogoLink::Ntree. It specifies an attribute name of the linked object thats value is used as the key of this link hash. NOTE: You cannot use PogoLink::* constructors as follows in a class constructor. sub new { my($class) = @_; my $self = {}; bless $self, $class; $self->{FOO} = new PogoLink::Scalar $self, 'Foo', 'BAR'; $self; } Because the self-object which is passed to PogoLink::* constructors must be a object in the database. In the above sample, $self is on the memory yet. The right way is as follows. sub new { my($class, $pogo) = @_; my $self = new_tie Pogo::Hash 8, $pogo, $class; $self->{FOO} = new PogoLink::Scalar $self, 'Foo', 'BAR'; $self; } You can make a database-stored and blessed reference by using new_tie which takes a Pogo object and a class name as arguments. get $idx_or_key Get the linked object. For PogoLink::Scalar, $idx_or_key is not necessary. For PogoLink::Array, $idx_or_key is an array index number. For other, $idx_or_key is a hash key string. getlist Get the linked object list. getkeylist Get the hash key list of linked objects. Only available for PogoLink::Hash, PogoLink::Htree, PogoLink::Btree, PogoLink::Ntree. find $object Test the link if it links to $object. clear Unlink to all objects in the link. del $object Unlink to $object. add $object Link to $object. AUTHOR ====== Sey Nakajima SEE ALSO ======== Pogo(3). sample/person.pl.  File: pm.info, Node: PogoLink.jp, Next: PostScript/Columns, Prev: PogoLink, Up: Module List 名称 ==== PogoLink - Pogoデータベース中のオブジェクトの双方向関係を実現するクラス 概要 ==== use PogoLink; # 関係の定義 package Person; sub new { my($class, $pogo, $name) = @_; # Make a hash ref persistent by $pogo and blessed by $class my $self = new_tie Pogo::Hash 8, $pogo, $class; %$self = ( NAME => $name, FATHER => new PogoLink::Scalar($self, 'Man', 'CHILDREN'), MOTHER => new PogoLink::Scalar($self, 'Woman', 'CHILDREN'), FRIENDS => new PogoLink::Btree ($self, 'Person', 'FRIENDS', 'NAME'), ); $self; } package Man; @ISA = qw(Person); sub new { my($class, $pogo, $name) = @_; my $self = $class->SUPER::new($pogo, $name); $self->{CHILDREN} = new PogoLink::Array ($self, 'Person', 'FATHER'); $self->{WIFE} = new PogoLink::Scalar($self, 'Woman', 'HUS'); $self; } package Woman; @ISA = qw(Person); sub new { my($class, $pogo, $name) = @_; my $self = $class->SUPER::new($pogo, $name); $self->{CHILDREN} = new PogoLink::Array ($self, 'Person', 'MOTHER'); $self->{HUS} = new PogoLink::Scalar($self, 'Man', 'WIFE'); $self; } # 関係の使用 $Pogo = new Pogo 'sample.cfg'; $Dad = new Man $Pogo, 'Dad'; $Mom = new Woman $Pogo, 'Mom'; $Jr = new Man $Pogo, 'Jr'; $Gal = new Woman $Pogo, 'Gal'; # 結婚 $Dad->{WIFE}->add($Mom); # $Mom->{HUS} は自動的に $Dad を指す # 誕生 $Dad->{CHILDREN}->add($Jr); # $Jr->{FATHER} は自動的に $Dad を指す $Mom->{CHILDREN}->add($Jr); # $Jr->{MOTHER} は自動的に $Mom を指す # Jrに友達ができる $Jr->{FRIENDS}->add($Gal); # $Gal->{FRIENDS} は自動的に $Jr を指す # おっと、GalがDadをゲットしちゃった $Gal->{HUS}->add($Dad); # $Dad->{WIFE} は自動的に $Gal を指す # $Mom->{HUS} は自動的に $Dad を指さなくなる 解説 ==== PogoLink は、一対一、一対多、多対多の双方向関係を、Pogo データベース中 のオブジェクト間に作ります。その関係は、お互いを正しく指すように、自動 的に保たれます。関係の多端を作るのに、Pogo::Array, Pogo::Hash, Pogo:: Htree, Pogo::Btree, Pogo::Ntree のどれかを選べます。 クラス ------ PogoLink::Scalar 一対一や一対多関係の一端を作ります。 PogoLink::Array 一対多や多対多関係の多端を、配列として作ります。Pogo::Array が使われま す。 PogoLink::Hash, PogoLink::Htree, PogoLink::Btree, PogoLink::Ntree これらのクラスは、多端をハッシュとして作ります。それぞれ対応した Pogo: :*が使われます。 メソッド -------- new PogoLink::* $selfobject, $linkclass, $invattr, $keyattr コンストラクタ。クラスメソッド。$selfobject はこの関係を持つデータベー ス中のオブジェクトです。ハッシュ参照としてのオブジェクトでなければなり ません。$linkclass はこの関係が指す相手オブジェクトのクラス名です。省 略すると、どんなクラスのオブジェクトでも許されます。$invattr はこの関 係の相手オブジェクトの属性名（ハッシュキー）で、その属性が逆に相手から こちらを指すことになります。$keyattr は、PogoLink::Hash, PogoLink:: Htree, PogoLink::Btree, PogoLink::Ntree についてだけ必要で、この関係の 相手オブジェクトの属性名（ハッシュキー）で、その属性値がハッシュキーと して使われます。 注意：PogoLink::*コンストラクタを、クラスのコンストラクタの中で次のよ うに使うことはできません。 sub new { my($class) = @_; my $self = {}; bless $self, $class; $self->{FOO} = new PogoLink::Scalar $self, 'Foo', 'BAR'; $self; } なぜなら、PogoLink::*コンストラクタの引数となるそのオブジェクト自身は、 データベース中のオブジェクトでなければならないからです。この例では、 $self はまだメモリ上にあるだけです。正しくは次のようにします。 sub new { my($class, $pogo) = @_; my $self = new_tie Pogo::Hash 8, $pogo, $class; $self->{FOO} = new PogoLink::Scalar $self, 'Foo', 'BAR'; $self; } Pogo オブジェクトとクラス名を引数とした new_tie を使えば、データベース に格納され、bless された参照が得られるのです。 get $idx_or_key 関係の相手オブジェクトを返します。PogoLink::Scalar では $idx_or_key は 不要です。PogoLink::Array では、$idx_or_key は配列の添字番号です。その 他の場合は、$idx_or_key はハッシュキーです。 getlist 関係の相手オブジェクトのリストを返します。 getkeylist 関係の相手のリストを、ハッシュのキーのリストとして返します。PogoLink:: Hash, PogoLink::Htree, PogoLink::Btree, PogoLink::Ntree についてだけ有 効なメソッドです。 find $object 関係の相手に$objectがあるか調べます。あれば真を返します。 clear 関係の全ての相手オブジェクトへの関係を断ちます。 del $object $objectへの関係を断ちます。 add $object $objectへの関係を追加します。 作者 ==== 中島　靖 参照 ==== Pogo(3). sample/person.pl.  File: pm.info, Node: PostScript/Columns, Next: PostScript/Elements, Prev: PogoLink.jp, Up: Module List Squeeze a text file into multiple columns. ****************************************** NAME ==== PostScript::Columns - Squeeze a text file into multiple columns. SYNOPSIS ======== use PostScript::ColDoc; $psdoc= pscolumns( -margins => [30,15], # NS,EW or N,E,W,S -headfont => 'NimbusMonL-Bold', -headsize => 12, -head => $head, -font => 'NimbusMonL-Regu', -size => 10, -text => $text, # default font/size for foot: -foot => "Page \$p of \$pp", # will interpolate later :) ); # use all defaults, no footer $doc= pscolumns( -size => 5, -head => "Left\nLeft Also\tTest Document\tRight", -text => $text, -foot => scalar(localtime)."\tFoot\tPage \$p of \$pp", ); DESCRIPTION =========== Creates a PostScript document with a user-defined header and footer, then attempts to squeeze the data into as many columns as possible. AVAILABLE FONTS =============== Only the monospace PostScript fonts are available: `NimbusMonL-Regu' `NimbusMonL-Bold' `NimbusMonL-ReguObli' `NimbusMonL-BoldObli' OPTIONS ======= -margins Array ref that specifies page margins, in points (1/72 of an inch). North, East, West South are expressed as four elements: [ N, E, S, W ] or two elements [ N_S, E_W ]. (This is the same order that CSS uses.) Note: Different printers may require drastically different margins. You'll have to experiment each time you use this module with a new printer. -headfont Name of the font to use for the header (see `"AVAILABLE FONTS"' in this node). -headsize Size of the font to use for the header (in points). -head String to use as header. Upper-right, centered, and upper-left fields are tab-separated. In the string, $p will be replaced by the current page number, and `$pp' with the total number of pages. -font Name of the font to use for the text (see `"AVAILABLE FONTS"' in this node). -size Size of the font to use for the text (in points). -text Columnar text. -footfont Name of the font to use for the footer (see `"AVAILABLE FONTS"' in this node). -footsize Size of the font to use for the footer (in points). -foot String to use as footer. Lower-right, centered, and lower-left fields are tab-separated. In the string, $p will be replaced by the current page number, and `$pp' with the total number of pages. AUTHOR ====== v, SEE ALSO ======== perl(1).  File: pm.info, Node: PostScript/Elements, Next: PostScript/Font, Prev: PostScript/Columns, Up: Module List Generate PostScript code for circles, boxes, lines ************************************************** NAME ==== PostScript::Elements - Generate PostScript code for circles, boxes, lines DESCRIPTION =========== An object for representing lines, circles, boxes, and images such that they can be easily output as PostScript code. SYNOPSIS ======== AUTHOR ======  File: pm.info, Node: PostScript/Font, Next: PostScript/FontInfo, Prev: PostScript/Elements, Up: Module List module to fetch data from PostScript fonts ****************************************** NAME ==== PostScript::Font - module to fetch data from PostScript fonts SYNOPSIS ======== my $info = new PostScript::Font (filename, options); print STDOUT ("Name = ", $info->FontName, "\n"); DESCRIPTION =========== This package reads PostScript font files and stores the information in memory. Most font file formats that are in use are recognised, especially the Type 1 and Type 42 font formats. Other formats that usually parse okay are Type 5 and Type 3, although Type 3 can sometimes fail depending on how weird the font information is stored. The input font file can be encoded in ASCII (so-called `.pfa' format), or binary (so-called `.pfb' format). True Type fonts are understood as well, they are converted internally to Type 42 format. Currently this requires an external program, *ttftot42*. This program will be used automatically if it can be located in the execution PATH. Alternatively, you can set the variable `$PostScript::Font::ttftot42' (or `$PostScript::FontMetrics::ttftot42') to the name of the actual program. See also `EXTERNAL PROGRAMS' in this node. CONSTRUCTOR =========== new ( FILENAME [ , OPTIONS ] ) The constructor will read the file and parse its contents. OPTIONS ======= error => [ 'die' | 'warn' | 'ignore' ] How errors must be handled. Default is to call die(). In any case, new() returns a undefined result. format => [ 'ascii' | 'pfa' | 'binary' | 'pfb' ] The format in which the font data is stored. Default is `'ascii'', suitable to be downloaded to a PostScript printer. verbose => value Prints verbose info if value is true. trace => value Prints tracing info if value is true. debug => value Prints debugging info if value is true. Implies 'trace' and 'verbose'. INSTANCE METHODS ================ Each of these methods can return undef if the corresponding information could not be found in the file. FileName The name of the file, e.g. 'tir_____.pfb'. FontName The name of the font, e.g. 'Times-Roman'. FamilyName The family name of the font, e.g. 'Times'. Version The version of the font, e.g. '001.007'. ItalicAngle The italicity of the font, e.g. 0 (normal upright fonts) or -16 (italic font). isFixedPitch Indicates if this font has fixed pitch. Weight This font weight. FontType The font type, e.g. '1' for a Type 1 PostScript font, or 't' for a True Type font. True Type fonts will be converted to Type 42 internally, but still have 't' as FontType. FontMatrix The font matrix as a reference to an anonymous array with the 6 values. To find the font scale, use int(1/$font->FontMatrix->[0]) FontBBox The font bounding box as a reference to an anonymous array with the 4 values. DataFormat The format in which the data is kept internally. See the format option. FontData The complete contents of the file, normalised to Unix-style line endings. It is in the format as returned by the DataFormat method. Encoding This is either one of the strings `'StandardEncoding'' or `'ISOLatin1Encoding'', or a reference to an array that holds the encoding. In this case, the array will contain a glyph name (a string) for each element that is encoded. NOTE: Getting the encoding information can fail if the way it was stored in the font is not recognized by the parser. This is most likely to happen with manually constructed fonts. EncodingVector Like encoding, but always returns a reference to the encoding array. In other words, the standard encodings are returned as arrays as well. FontGlyphs This returns a reference to an array holding all the names of the glyphs this font defines, in the order the definitions occur in the font data. NOTE: Getting the glyphs information can fail if the way it was stored in the font is not recognized by the parser. This is most likely to happen with manually constructed fonts. Extracting the glyphs can be slow. It can be speeded up by using the external program *t1disasm*. This program will be used automatically, if it can be found in the execution PATH. Alternatively, you can set the variable `$PostScript::Font::t1disasm' to point to the *t1disasm* program. This does not apply to type 42 fonts, since these fonts do not require disassembly to get at the glyph list. CLASS METHODS ============= StandardEncoding Returns a reference to an array that contains all the glyphs names for Adobe's Standard Encoding. ISOLatin1Encoding Returns a reference to an array that contains all the glyphs names for ISO-8859-1 (ISO Latin-1) encoding. EXTERNAL PROGRAMS ================= Two external programs can be used by this package. *ttftot42* is required when True Type fonts must be handled. It is called as follows: ttftot42 -fc filename This invocation will write the Type 42 version of the True Type font to standard output. *ttftot42* can be found on http://ftp.giga.or.at/pub/nih/ttftot42 An alternative, but not encouraged, way to handle True Type fonts is by converting them to Type 1 fonts. An excellent converter, *ttf2pt1*, can be used for this. To use this program, create a fake *ttftot42* script and set variable $PostScript::Font::ttftot42 to the name of this script. The script should contain something like this: $!/bin/sh shift # get rid of '-fc' argument exec ttf2pt1 -ef "$@" - 2>/dev/null The redirection of error output to /dev/null is necessary. since the program is quite verbose. Unfortunately, error messages will disappear as well. *ttf2pt1* can be found on http://www.netspace.net.au/~mark/ttf2pt1 Note: the resultant Type1 font is not a real conversion, but a (very similar) imitation of the original True Type font. Small differences may be noticable depending on the font quality. *t1disasm* can be used to speed up the fetching of the list of font glyphs from Type 1 fonts. It is called as follows: t1disasm filename This invocation will write the disassembled version of the Type 1 font to standard output. *t1disasm* is part of the *t1utils* package that can be found at http://www.lcdf.org/~eddietwo/type/ and several other places. KNOWN BUGS ========== Invoking external programs (*t1disasm*, *ttftot42*) is guaranteed to work on Unix only. SEE ALSO ======== http://www.adobe.com/supportservice/devrelations/PDFS/TN/T1_SPEC.PDF The specification of the Type 1 font format. http://www.adobe.com/supportservice/devrelations/PDFS/TN/5012.Type42_Spec.pdf The specification of the Type 42 font format. http://fonts.apple.com/TTRefMan/index.html The True Type reference manual. http://www.adobe.com/supportservice/devrelations/PDFS/TN/5004.AFM_Spec.pdf The specification of the Adobe font metrics file format. AUTHOR ====== Johan Vromans, Squirrel Consultancy COPYRIGHT and DISCLAIMER ======================== This program is Copyright 2000,1998 by Squirrel Consultancy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.  File: pm.info, Node: PostScript/FontInfo, Next: PostScript/FontMetrics, Prev: PostScript/Font, Up: Module List module to fetch data from PostScript font `.inf' files ****************************************************** NAME ==== PostScript::FontInfo - module to fetch data from PostScript font `.inf' files SYNOPSIS ======== my $info = new PostScript::FontInfo (filename, options); print STDOUT ("Name = ", $info->name, "\n"); DESCRIPTION =========== This package allows font info files, so called `.inf' files, to be read and (partly) parsed. CONSTRUCTOR =========== new ( FILENAME [ , OPTIONS ] ) The constructor will read the file and parse its contents. OPTIONS ======= error => [ 'die' | 'warn' | 'ignore' ] How errors must be handled. Default is to call die(). In any case, new() returns a undefined result. verbose => value Prints verbose info if value is true. trace => value Prints tracing info if value is true. debug => value Prints debugging info if value is true. Implies 'trace' and 'verbose'. INSTANCE METHODS ================ Each of these methods can return undef if the corresponding information could not be found in the file. FileName The name of the file, e.g. 'tir_____.afm'. FontName The name of the font, e.g. 'Times-Roman'. FamilyName The family name of the font, e.g. 'Times'. Version The version of the font, e.g. '001.007'. PCFileNamePrefix The prefix used to form MS-DOS compliant file names, e.g. 'tir__'. InfoData The complete contents of the file, normalised to Unix-style line endings. AUTHOR ====== Johan Vromans, Squirrel Consultancy COPYRIGHT and DISCLAIMER ======================== This program is Copyright 2000,1998 by Squirrel Consultancy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.  File: pm.info, Node: PostScript/FontMetrics, Next: PostScript/MailLabels, Prev: PostScript/FontInfo, Up: Module List module to fetch data from Adobe Font Metrics file ************************************************* NAME ==== PostScript::FontMetrics - module to fetch data from Adobe Font Metrics file SYNOPSIS ======== my $info = new PostScript::FontMetrics (filename, options); print STDOUT ("Name = ", $info->FontName, "\n"); print STDOUT ("Width of LAV = ", $info->kstringwidth("LAV", 10), "\n"); DESCRIPTION =========== This package allows Adobe standard font metric files, so called `.afm' files, to be read and (partly) parsed. True Type fonts are understood as well, their metrics are extracted. Currently this requires an external program, *ttftot42*. This program will be used automatically if it can be located in the execution PATH. Alternatively, you can set the variable `$PostScript::FontMetrics::ttftot42' (or `$PostScript::Font::ttftot42') to the name of the actual program. See also `EXTERNAL PROGRAMS' in this node. CONSTRUCTOR =========== new ( FILENAME [ , OPTIONS ]) The constructor will read the file and parse its contents. OPTIONS ======= error => [ 'die' | 'warn' | 'ignore' ] How errors must be handled. Default is to call die(). In any case, new() returns a undefined result. verbose => value Prints verbose info if value is true. trace => value Prints tracing info if value is true. debug => value Prints debugging info if value is true. Implies 'trace' and 'verbose'. INSTANCE METHODS ================ Note: Most of the info from the AFM file can be obtained by calling a method of the same name, e.g. FontName and `IsFixedPitch'. Each of these methods can return undef if the corresponding information could not be found in the file. FileName The name of the file, e.g. 'tir_____.afm'. This is not derived from the metrics data, but the name of the file as passed to the new method. MetricsData The complete contents of the file, normalised to Unix-style line endings. CharWidthData Returns a reference to a hash with the character widths for each glyph. EncodingVector Returns a reference to an array with the glyph names for each encoded character. CharBBoxData Returns a reference to a hash with the bounding boxes (a 4-element array) for each glyph. KernData Returns a reference to a hash with the kerning data for glyph pairs. It is indexed by two glyph names (two strings separated by a comma, e.g. $kd->{"A","B"}). stringwidth ( string [ , pointsize ] ) Returns the width of the string, in character space units. Deprecated: When a pointsize argument is supplied, the resultant width is scaled to user space units. This assumes that the font maps 1000 character space units to one user space unit (which is generally the case). kstringwidth ( string [ , pointsize ] ) Returns the width of the string in character space units, taking kerning information into account. Deprecated: When a pointsize argument is supplied, the resultant width is scaled to user space units. This assumes that the font maps 1000 character space units to one user space unit (which is generally the case). kstring ( string [ , extent ] ) Returns an array reference (in scalar context) or an array (in array context) with substrings of the given string, interspersed with kerning info. The kerning info is the amount of movement needed for the correct kerning, in character space (which is usually 1000 times a PostScript point). The substrings are ready for printing: non-ASCII characters have been encoded and parentheses are put around them. If the extend argument is supplied, this amount of displacement is added to each space in the string. For example, for a given font, the following call: $typesetinfo = $metrics->kstring ("ILVATAB"); could return in $typesetinfo: [ "(IL)", -97, "(V)", -121, "(A)", -92, "(T)", -80, "(AB)" ] There are several straightforward ways to process this. By translating to a series of 'show' and 'rmoveto' operations: foreach ( @$typesetinfo ) { if ( /^\(/ ) { print STDOUT ($_, " show\n"); } else { printf STDOUT ("%.3f 0 rmoveto\n", ($_*$fontsize)/$fontscale); } } Or, assuming the following definition in the PostScript preamble (48 is the font size): /Fpt 48 1000 div def /TJ {{ dup type /stringtype eq { show } { Fpt mul 0 rmoveto } ifelse } forall } bind def the following Perl code would suffice: print PS ("[ @$typesetinfo ] TJ\n"); EXTERNAL PROGRAMS ================= *ttftot42* is required when True Type fonts must be handled. It is called as follows: ttftot42 -ac filename This invocation will write the metrics for the True Type font to standard output. *ttftot42* can be found on http://ftp.giga.or.at/pub/nih/ttftot42 SEE ALSO ======== http://www.adobe.com/supportservice/devrelations/PDFS/TN/5004.AFM_Spec.pdf The specification of the Adobe font metrics file format. AUTHOR ====== Johan Vromans, Squirrel Consultancy COPYRIGHT and DISCLAIMER ======================== This program is Copyright 2000,1998 by Squirrel Consultancy. All rights reserved. This program is free software; you can redistribute it and/or modify it under the terms of either: a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" which comes with Perl. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See either the GNU General Public License or the Artistic License for more details.