NAME

Module::Pragma::JA - プラグマモジュールの実装のサポート

SYNOPSIS

        # Foo.pm
        package Foo;
        use base qw(Module::Pragma);

        __PACKAGE__->register_tags(qw(-SHA1 -MD5));
        __PACKAGE__->exclusive_tag( __PACKAGE__->tags );

        sub something
        {
                # ...
                if(__PACKAGE__->enabled(-SHA1)){
                        $mod = 'Digest::SHA1';
                }
                elsif(__PACKAGE__->enabled(-MD5)){
                        $mod = 'Digest::MD5';
                }
                else{
                        $mod = $Digest_Default;
                }
                # ...
        }
        # ...
        1;
        __END__

        # foo.pl
        use Foo;

        Foo->something(); # Foo->enabled(-SHA1)は真
        {
                use Foo -MD5;
                Foo->something(); # Foo->enabled(-MD5)が真
        }
        Foo->something(); # Foo->enabled(-SHA1)が真

        # ...

DESCRIPTION

perl5.10よりユーザープラグマを作れるようになりました。これにより、モジュール実装者はモジュールの実行時のオプションをプラグマに頼ることができるようになります。そして、Module::Pragmaはプラグマモジュールの実装を助けます。

Module::Pragmaがサポートするプラグマはビットマスクベースとなります。これにより、タグの数は最大でも32ないし64個（Perlの整数のサイズによります）に制限されています。

How to set it up

Module::Pragmaはオブジェクト指向モジュールであり、全てのメソッドは継承されたクラスメソッドとして使います。

まず最初に、Module::Pragmaをロードし、スーパークラスとして設定します。

        package mypragma;
        use base qw(Module::Pragma);

次に、サブプラグマ(このモジュールではタグと呼びます)を register_tags() メソッドで登録します。

        __PACKAGE__->register_tags(qw(foo bar baz));

いくつかのタグを register_bundle() メソッドでまとめることもできます。

        __PACKAGE__->register_bundle('foobar' => ['foo', 'bar']);

タグ同士をそれぞれ排他的に選択させるには、 register_exclusive() メソッドを使います。

        __PACKAGE__->register_bundle('foo', 'baz');

これで基本的なセットアップは終了し、プラグマとして使うことができます。

        use mypragma 'foo';
        use mypragma 'baz';     # fooとbazは排他的
                                # ->fooは解除され、bazが設定される
        use mypragma ':foobar'; # fooとbazは排他的
                                # ->bazは解除され、fooとbarが設定される

規定の状態では、プラグマの呼び出しには引数が必要であり、また未知の引数は認められません。

        use mypragma;        # die! 必ず引数が必要
        use mypragma 'fooo'; # die! 未知のタグは禁止

この動作はdefault_import()メソッドとunknown_tag()メソッドのオーバーライドにより変更可能です。

METHODS

Registering tags

PRAGMA->register_tags(tagname [ => flag] [, more ...])

register_tags()はタグを登録します。 それぞれのタグはビットフラグとして扱われ、値が自動的に割り当てられますが、任意で値を設定することもできます。

例えば以下の通りです。

        PRAGMA->register_tags(
                'A' =>   0b00100,
                'B',   # 0b01000
                'C',   # 0b10000
                'D' =>   0b00001,
                'E',   # 0b00010
        );

register_tags()は最後に設定したタグの値（上記の例では 'E' の値）を返します。

PRAGMA->register_bundle(bundlename => tagname [, more ...])

register_bundle()はいくつかのタグをまとめて一つのタグセットを作ります。 タグセットを参照するときは接頭辞としてコロンをつけます。

PRAGMA->register_exclusive(tagname1, tagname2 [, more ...])

register_exclusive()は複数のタグが相互に排他的であることを宣言します。

排他的なタグはimport()時に同時に指定できず、一方を指定すると一方は自動的に解除されます。

Checking Effects

PRAGMA->enabled(tags...)

実行時にタグの効果を調べるメソッドです。 引数を渡さなければ、そのプラグマについて全体の状態を返します。

スカラコンテキストではビット値をそのまま返します。 リストコンテキストではビット値をタグ名のリストに変換して返します。

use/no Directives

Module::Pragma自体のimport()とunimport()はどちらも何もしません。サブクラスから使うときにのみ有効です。

この二つのメソッドは引数をcheck_exclusive()でチェックします。

PRAGMA->import(tags...)

import()はtagsと排他関係にあるタグを無効にし、tagsを有効にします。

tagsを省略するとdefault_import()が呼び出され、(_die()しなければ）その返り値を引数として使います。

PRAGMA->uimport(tags...)

unimport()はtagsを無効にし、tagsと排他関係にあるタグを有効にします。

tagsを省略すると、プラグマの効果を完全に無効化します。

Handling Exception

いくつかの例外処理はオーバーライドすることで規定の動作を変更できます。

PRAGMA->default_import()

import()を引数を指定せずに呼び出すと、規定の動作では_die()します。

この動作はdefault_import()メソッドをオーバーライドすることで変更できます。

default_import()はimport()に引数が渡されなかったときにメソッドとして呼ばれ、返り値がimport()の引数として使用されます。

PRAGMA->unknown_tag(tagname)

未知のタグを発見したときに内部で呼ばれるメソッドです。規定の動作は_die()です。 register_tags()を利用してその場でタグを生成するなどの動作を想定しています。

返り値は(_die()しなければ）タグに相当するビットマスクとして使われます。

Utilities

PRAGMA->hint(level)

コンパイル時にセットされたプラグマの状態を表す値を返します。

PRAGMA->_die(message)

Carp.pmモジュールをロードし、Carp::croak()にPRAGMAとmessageを渡して呼び出します。

PRAGMA->tag(tagname)

tagnameに相当するビット値を返します。tagnameが未登録の場合はunknown_tag()を呼び出します。

PRAGMA->tags()

登録済みのタグのリストを返します。

PRAGMA->pack_tags(tags...)

個々のtagsのビット値の論理和を返します。

PRAGMA->unpack_tags(bits)

bitsの値に相当するタグのリストを返します。

PRAGMA->exclusive_tags(tags...)

tagsと排他関係にあるタグのリストを返します。

PRAGMA->check_exclusive(tags...)

tagsが相互に排他的かどうかをチェックし、排他的であれば_die()します。

SEE ALSO

perlpragmaでプラグマの実装について解説しています。

Module::Pragmaにはプラグマの実装例があります。

AUTHOR

Goro Fuji (藤 吾郎) <gfuji(at)cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2008 Goro Fuji.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Module::Pragma

perl -MCPAN -e shell
install Module::Pragma