perl/5.22.1/perldbmfilter.pod


=encoding euc-jp

=head1 NAME

=begin original

perldbmfilter - Perl DBM Filters

=end original

perldbmfilter - Perl DBM フィルタ

=head1 SYNOPSIS

    $db = tie %hash, 'DBM', ...

    $old_filter = $db->filter_store_key  ( sub { ... } );
    $old_filter = $db->filter_store_value( sub { ... } );
    $old_filter = $db->filter_fetch_key  ( sub { ... } );
    $old_filter = $db->filter_fetch_value( sub { ... } );

=head1 DESCRIPTION

=begin original

The four C<filter_*> methods shown above are available in all the DBM
modules that ship with Perl, namely DB_File, GDBM_File, NDBM_File,
ODBM_File and SDBM_File.

=end original

上述の四つの C<filter_*> メソッドは、Perl と共に出荷されている全ての
DBM モジュール、つまり DB_File, GDBM_File, NDBM_File, ODBM_File,
SDBM_File で利用可能です。

=begin original

Each of the methods works identically, and is used to install (or
uninstall) a single DBM Filter. The only difference between them is the
place that the filter is installed.

=end original

それぞれのメソッドは全く同じように動作し、一つの DBM フィルタの
インストール(またはアンインストール)のために使われます。
これらの唯一の違いはフィルタをインストールする場所です。

=begin original

To summarise:

=end original

要約すると:

=over 5

=item B<filter_store_key>

=begin original

If a filter has been installed with this method, it will be invoked
every time you write a key to a DBM database.

=end original

フィルタがこのメソッドにインストールされると、DBM データベースにキーを
書き込む毎に起動されます。

=item B<filter_store_value>

=begin original

If a filter has been installed with this method, it will be invoked
every time you write a value to a DBM database.

=end original

フィルタがこのメソッドにインストールされると、DBM データベースに値を
書き込む毎に起動されます。

=item B<filter_fetch_key>

=begin original

If a filter has been installed with this method, it will be invoked
every time you read a key from a DBM database.

=end original

フィルタがこのメソッドにインストールされると、DBM データベースからキーを
読み込む毎に起動されます。

=item B<filter_fetch_value>

=begin original

If a filter has been installed with this method, it will be invoked
every time you read a value from a DBM database.

=end original

フィルタがこのメソッドにインストールされると、DBM データベースから値を
読み込む毎に起動されます。

=back

=begin original

You can use any combination of the methods from none to all four.

=end original

これらのメソッドは 0 個から 4 個全てまで好きな組み合わせで使えます。

=begin original

All filter methods return the existing filter, if present, or C<undef>
if not.

=end original

全てのフィルタメソッドはもしあれば既に登録されているフィルタを、
なければ C<undef> を返します。

=begin original

To delete a filter pass C<undef> to it.

=end original

フィルタを削除するには C<undef> を渡します。

=head2 The Filter

(フィルタ)

=begin original

When each filter is called by Perl, a local copy of C<$_> will contain
the key or value to be filtered. Filtering is achieved by modifying
the contents of C<$_>. The return code from the filter is ignored.

=end original

それぞれのフィルタが Perl によって呼び出されると、C<$_> のローカルコピーには
フィルタされるキーや値が入ります。
フィルタリングは C<$_> の内容を変更することによって行われます。
フィルタからの返り値は無視されます。

=head2 An Example: the NULL termination problem.

(例: NULL 終端問題)

=begin original

DBM Filters are useful for a class of problems where you I<always>
want to make the same transformation to all keys, all values or both.

=end original

全てのキー、全ての値、あるいはその両方に対して同じ変換を I<常に>
行いたいような問題の種類には DBM フィルタが便利です。

=begin original

For example, consider the following scenario. You have a DBM database
that you need to share with a third-party C application. The C application
assumes that I<all> keys and values are NULL terminated. Unfortunately
when Perl writes to DBM databases it doesn't use NULL termination, so
your Perl application will have to manage NULL termination itself. When
you write to the database you will have to use something like this:

=end original

例えば、以下のようなシナリオを考えます。
サードパーティ C アプリケーションと共有する必要がある DBM データベースが
あります。
C アプリケーションは I<全ての> キーと値が NULL 終端されていることを
仮定しています。
残念ながら Perl が DBM データベースに書き込むときには NULL 終端しないので、
Perl アプリケーションは自分自身で NULL 終端を管理する必要があります。
データベースに書き込むときに、以下のようなことをする必要があります:

    $hash{"$key\0"} = "$value\0";

=begin original

Similarly the NULL needs to be taken into account when you are considering
the length of existing keys/values.

=end original

同様に、すでにあるキーや値の長さを考慮するときには NULL を計算に入れる
必要があります。

=begin original

It would be much better if you could ignore the NULL terminations issue
in the main application code and have a mechanism that automatically
added the terminating NULL to all keys and values whenever you write to
the database and have them removed when you read from the database. As I'm
sure you have already guessed, this is a problem that DBM Filters can
fix very easily.

=end original

メインアプリケーションのコードでは NULL 終端問題を無視して、
データベースに書き込むときには自動的に終端の NULL を追加して、
データベースから読み込むときには自動的に削除する機構があれば
とても便利です。
既に想像はしていると思いますが、これは DBM フィルタが簡単に修正できる
問題です。

    use strict;
    use warnings;
    use SDBM_File;
    use Fcntl;

    my %hash;
    my $filename = "filt";
    unlink $filename;

    my $db = tie(%hash, 'SDBM_File', $filename, O_RDWR|O_CREAT, 0640)
      or die "Cannot open $filename: $!\n";

    # Install DBM Filters
    $db->filter_fetch_key  ( sub { s/\0$//    } );
    $db->filter_store_key  ( sub { $_ .= "\0" } );
    $db->filter_fetch_value( 
        sub { no warnings 'uninitialized'; s/\0$// } );
    $db->filter_store_value( sub { $_ .= "\0" } );

    $hash{"abc"} = "def";
    my $a = $hash{"ABC"};
    # ...
    undef $db;
    untie %hash;

=begin original

The code above uses SDBM_File, but it will work with any of the DBM
modules.

=end original

上述のコードでは SDBM_File を使っていますが、いずれの DBM モジュールでも
動作します。

=begin original

Hopefully the contents of each of the filters should be
self-explanatory. Both "fetch" filters remove the terminating NULL,
and both "store" filters add a terminating NULL.

=end original

出来れば、それぞれのフィルタの内容は自己説明的であるべきです。
両方の "fetch" フィルタは終端の NULL を削除し、両方の "store" フィルタは
終端する NULL を追加します。

=head2 Another Example: Key is a C int.

(もう一つの例: キーは C の int)

=begin original

Here is another real-life example. By default, whenever Perl writes to
a DBM database it always writes the key and value as strings. So when
you use this:

=end original

もう一つの実際の生活の例です。
デフォルトでは、Perl が DBM データベースに書き込むときはいつでも、
キーと値を文字列として書き込みます。
従って、以下のように使うと:

    $hash{12345} = "something";

=begin original

the key 12345 will get stored in the DBM database as the 5 byte string
"12345". If you actually want the key to be stored in the DBM database
as a C int, you will have to use C<pack> when writing, and C<unpack>
when reading.

=end original

キー 12345 は、5 バイトの文字列 "12345" として DBM データベースとして
保管されます。
実際に DBM データベースに C の int としてキーを保管したい場合は、
書き込むときに C<pack> を使い、読み込むときに C<unpack> を使う
必要があります。

=begin original

Here is a DBM Filter that does it:

=end original

以下はこのために DBM を使います:

    use strict;
    use warnings;
    use DB_File;
    my %hash;
    my $filename = "filt";
    unlink $filename;

    my $db = tie %hash, 'DB_File', $filename, O_CREAT|O_RDWR, 0666,
        $DB_HASH or die "Cannot open $filename: $!\n";

    $db->filter_fetch_key  ( sub { $_ = unpack("i", $_) } );
    $db->filter_store_key  ( sub { $_ = pack ("i", $_) } );
    $hash{123} = "def";
    # ...
    undef $db;
    untie %hash;

=begin original

The code above uses DB_File, but again it will work with any of the
DBM modules.

=end original

上述のコードでは DB_File を使っていますが、いずれの DBM モジュールでも
動作します。

=begin original

This time only two filters have been used; we only need to manipulate
the contents of the key, so it wasn't necessary to install any value
filters.

=end original

今回は二つのフィルタだけを使っています; キーの内容だけを操作する
必要があるので、値フィルタをインストールする必要はありませんでした。

=head1 SEE ALSO

=begin original

L<DB_File>, L<GDBM_File>, L<NDBM_File>, L<ODBM_File> and L<SDBM_File>.

=end original

L<DB_File>, L<GDBM_File>, L<NDBM_File>, L<ODBM_File>, L<SDBM_File>

=head1 AUTHOR

Paul Marquess

=begin meta

Translate: SHIRAKATA Kentaro <argrath@ub32.org>
Status: completed

=end meta
