h2xs -b VERSION -XAn MODULE_NAME

前回 (d101) で確認した通り、後方互換を指定するオプション「 -b 」を追加しつつディストリビューションのスケルトンを生成するために h2xs を実行します。

$ h2xs -b 5.10.1 -XAn My::Module

Writing My-Module/lib/My/Module.pm

Writing My-Module/Makefile.PL

Writing My-Module/README

Writing My-Module/t/My-Module.t

Writing My-Module/Changes

Writing My-Module/MANIFEST

出力の「 Writing ... 」で、指定したディストリビューション名 ( s/::/-/ ) のディレクトリと、その配下にいくつかのファイルが生成されたことがわかります。

肝心のモジュールはディレクトリ「 lib/ 」配下に「 My/Module.pm 」( .pm ファイル ) として生成されています。

.pm ファイルのコンテンツ

生成された .pm ファイル「 lib/My/Module.pm 」のコンテンツを確認します。これは次のようになっています。なお、コメントの翻訳は参考のために追加しました。

package My::Module;



use 5.010001;

use strict;

use warnings;



require Exporter;



our @ISA = qw(Exporter);



# Items to export into callers namespace by default. Note: do not export

# names by default without a very good reason. Use EXPORT_OK instead.

# Do not simply export all your public functions/methods/constants.

# アイテムです エクスポートする 呼び出し元の名前空間に デフォルトで. 

# 注意: エクスポートしないでください 名前を デフォルトで とても良い理由なしに

# 使います EXPORT_OK を 代わりに.

# シンプルにエクスポートしないでください あなたのパブリックな ファンクション/メソッド/定数を.



# This allows declaration use My::Module ':all';

# If you do not need this, moving things directly into @EXPORT or @EXPORT_OK

# will save memory.

# これは可能にします 宣言を use My::Module ':all'; の

# もしあなたが必要でないなら これを, 物事を移動すれば 直接 @EXPORT or @EXPORT_OK に

# 節約されます メモリが

our %EXPORT_TAGS = ( 'all' => [ qw(

        

) ] );



our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );



our @EXPORT = qw(

        

);



our $VERSION = '0.01';





# Preloaded methods go here.

# プレロードされたメソッドはここに



1;

__END__

# Below is stub documentation for your module. You'd better edit it!

# 以下はスタブドキュメントです あなたのモジュールのための. あなた編集するとよいです それを !





=head1 NAME



My::Module - Perl extension for blah blah blah



=head1 SYNOPSIS



  use My::Module;

  blah blah blah



=head1 DESCRIPTION



Stub documentation for My::Module, created by h2xs. It looks like the

author of the extension was negligent enough to leave the stub

unedited.

スタブドキュメントです My::Module のための, 作成されました h2xs によって. 

作者は この拡張の 怠慢だったようです 残したままにするほど スタブを 未編集で.



Blah blah blah.

なんとかかんとか



=head2 EXPORT



None by default.

デフォルトではなし.





=head1 SEE ALSO



Mention other useful documentation such as the documentation of

related modules or operating system documentation (such as man pages

in UNIX), or any relevant external documentation such as RFCs or

standards.

言及します 他の有用なドキュメントに ドキュメントのような 

関連するモジュールの または オペレーティングシステムのドキュメント (  man ページ

のような UNIX の ), または すべての関係のある外部のドキュメント RFC or

標準のような.



If you have a mailing list set up for your module, mention it here.

もしあなたが持っているなら メーリングリストを セットアップした あなたのモジュールのために,

言及します それを ここで.



If you have a web site set up for your module, mention it here.

もしあなたがもっているなら Web サイトを セットアップした あなたのモジュールのために,

言及します それを ここで.



=head1 AUTHOR



author name (your name), E<lt>your@mail_adder<gt>



=head1 COPYRIGHT AND LICENSE



Copyright (C) 2017 by author name (your name)



This library is free software; you can redistribute it and/or modify

it under the same terms as Perl itself, either Perl version 5.25.6 or,

at your option, any later version of Perl 5 you may have available.



このライブラリはフリーソフトウェアです; あなたはできます これの再配布 and/or これの修正を

同じ規約の元で Perl それ自身と, どちらか Perl バージョン 5.25.6 or,

あなたのオプションで, すべてのそれ以降のバージョン Perl 5 の あなたは利用可能かもしれません.



=cut

以下の項では、このファイルの各パートを確認します。

package と use 行

「 lib/My/Moduel.pm 」の冒頭部分です。

package My::Module;



use 5.010001;

use strict;

use warnings;

最初のディレクティブ「 package 」は、 package on perlmod パッケージ (d058) や オブジェクト指向プログラミング (OOP) 基礎知識 (d067) などで確認したもので、プログラム中の名前空間 ( name space ) を分割し、かつ、OOP ( オプジェクト指向プログラミング ) でのクラス名に相当するものです。

端的にいえば、ここで宣言された文字列「 My::Module 」は、あなたが指定したこのディストリビューション ( とメインモジュール ) の名前です。

それから use 行が続きます。

「 use 5.010001 」は、オプション「 -b 」で指定した互換性のあるバージョン番号を定義しています。

「 strict 」(0x35) と「 warnings 」(0x15) は、現代的な Perl プログラミングでほとんど必須のプラグマです。詳細はリンク先を参照します。

Exporter 関連

use 行に続いて、「 require 」(d001) 以下モジュール「 Exporter 」関連の以下のコードが用意されています。なお、ここでは可読性を考慮してコメント部分を省略しています。

require Exporter;



our @ISA = qw(Exporter);



our %EXPORT_TAGS = ( 'all' => [ qw(

        

) ] );



our @EXPORT_OK = ( @{ $EXPORT_TAGS{'all'} } );



our @EXPORT = qw(

        

);

「 Exporter 」の機能は、基本的には、モジュール内で定義したファンクション ( 関数 ) を、外部、つまりモジュールを利用する側のプログラムの名前空間にエクスポートするものです。

ですから、もしあなたがオブジェクト指向プログラミング ( OOP ) (d067) に準じた方法で「 メソッド 」( method ) を提供するモジュールを作成するつもりなら、これら Exporter 関連のコードはすべて不要です ( と現時点で僕は認識しています )。

なお、OOP をサポートしている現代的なモジュールでも、後方互換のために Exporter によるファンクションのエクスポートをあえて残している場合があります。

モジュール「 Exporter 」については以下のエントリで確認しました。

Perl モジュール Exporter 03 %EXPORT_TAGS タグ (d092)
Perl モジュール Exporter 02 基本 @EXPORT @EXPORT_OK (d091)
Perl モジュール Exporter 01 ドキュメント [翻訳] (d090)
Perl モジュール Exporter 00 use, import (d089)

バージョンの定義

Exporter 関連のコードに続いてあるのが、ディストリビューションのバージョンを定義する行です。

our $VERSION = '0.01';

バージョンをセットする変数「 $VERSION 」は、Perl がモジュールのバージョン番号をセットされていることを期待するスカラ変数で、外部 ( モジュールを利用する側 ) から参照できるようにパッケージ変数を定義する our で宣言します。

これにより、外部から次のようにしてモジュールのバージョンを取得することができます。

use My::Module;



# モジュール My::Module のバージョンをゲット

my $module_version = $My::Module::VERSION;

バージョン番号の形式は、大きくわけて「 Decimal Versions 」( クラシックな浮動小数点数 ) と「 Dotted Decimal Versions 」( 先頭は 'v' で 3 つ以上の整数を小数点で区切る )、それから、Decimal Version をゼロパディングしたものがあるようです。

                          equivalent

decimal    zero-padded    dotted-decimal

-------    -----------    --------------

1.2        1.200          v1.200.0

1.02       1.020          v1.20.0

1.002      1.002          v1.2.0

1.0023     1.002300       v1.2.300

1.00203    1.002030       v1.2.30

1.002003   1.002003       v1.2.3

上記の比較によれば、h2xs によってデフォルトで指定されたバージョン「 0.01 」は、zero-padded の「 0.010000 」と、detted-decimal では「 v0.10.0 」と等価になります。

モジュール「 version.pm 」を use してそのメソッドを使えば、Decimal のバージョンを Dotted decimal に正規化したり、その逆を行えます。

use version;



# parse, normal

print version->parse('0.01')->normal, "\n";



# parse, numify

print version->parse('v0.10.0')->numify, "\n";



__END__

# output

v0.10.0 

0.010000

バージョン指定や解析のイロハについては version および version::Internal あたりを参照します ( 例示のコードが説明通りに動かない.. ? などありますが )。

また、「 _ 」( under score ) を使ったアルファバージョンを使う用意があるなら、あわせて taro-nishinoの日記： バージョンナンバーは退屈な方がいい や $VERSION = eval $VERSION;　の理由 のコメント欄などを参照するとよいかもしれません。

プログラムの終端

.pm ファイルのプログラムは次のパートで終了します。

1;

__END__

「 1; 」は、外部ファイルを読み込んで実行する際に「 初期化コードの実行がうまくいっていることを示す 」ための 真 の値です。

最後に評価される構文が絶対に 真 を返すことが保証されるなら不要ですが、通常は万一に備えてプログラムの末尾に「 1; 」を置くことが習慣です。詳細は require および use を参照します。

キーワード「 __END__ 」は、論理的なプログラムの終端を示すトークンです。つまり、これ以降の文字列は Perl プログラムとしては扱われません。

詳細は perldata を参照します。

埋め込みドキュメント

「 __END__ 」トークン以下は、「 POD 」( (Plain Old|Perl Online) Documentation ) と呼ばれる埋め込みドキュメントのパートです。

POD については、perlpod などを参照します。

ここには、Perl のドキュメンテーションでお馴染みの項目「 NAME 」,「 SYNOPSIS 」,「 DESCRIPTION 」,「 SEE ALSO 」,「 AUTHOR 」,「 COPYRIGHT AND LICENSE 」が用意されています。

# Below is stub documentation for your module. You'd better edit it!



=head1 NAME



My::Module - Perl extension for blah blah blah



=head1 SYNOPSIS



  use My::Module;

  blah blah blah



=head1 DESCRIPTION



Stub documentation for My::Module, created by h2xs. It looks like the

author of the extension was negligent enough to leave the stub

unedited.



Blah blah blah.



=head2 EXPORT



None by default.







=head1 SEE ALSO



Mention other useful documentation such as the documentation of

related modules or operating system documentation (such as man pages

in UNIX), or any relevant external documentation such as RFCs or

standards.



If you have a mailing list set up for your module, mention it here.



If you have a web site set up for your module, mention it here.



=head1 AUTHOR



author name (your name), E<lt>your@mail_adder<gt>



=head1 COPYRIGHT AND LICENSE



Copyright (C) 2017 by author name (your name)



This library is free software; you can redistribute it and/or modify

it under the same terms as Perl itself, either Perl version 5.25.6 or,

at your option, any later version of Perl 5 you may have available.





=cut

このパートは、コマンド「 perldoc 」で整形されたドキュメントとして参照できます。例えば「 perldoc My-Module/lib/My/Module.pm 」を実行すれば、次の結果が得られます。

NAME

    My::Module - Perl extension for blah blah blah



SYNOPSIS

      use My::Module;

      blah blah blah



DESCRIPTION

    Stub documentation for My::Module, created by h2xs. It looks like the

    author of the extension was negligent enough to leave the stub unedited.



    Blah blah blah.



  EXPORT

    None by default.



SEE ALSO

    Mention other useful documentation such as the documentation of related

    modules or operating system documentation (such as man pages in UNIX),

    or any relevant external documentation such as RFCs or standards.



    If you have a mailing list set up for your module, mention it here.



    If you have a web site set up for your module, mention it here.



AUTHOR

    author name (your name), <your@mail_adder>



COPYRIGHT AND LICENSE

    Copyright (C) 2017 by author name (your name)



    This library is free software; you can redistribute it and/or modify it

    under the same terms as Perl itself, either Perl version 5.25.6 or, at

    your option, any later version of Perl 5 you may have available.

また、POD のコンテンツはインストール時などで自動的に抽出され、UNIX 系 OS の man ページや、HTML 形式などのネイティブドキュメント形式に変換されます ( 便利 )。

ですから、実際にディストリビューションとして配布する場合は、この雛形を自作モジュールのドキュメントとして成り立つように適切に編集します。

NEXT

次回は、同じく h2xs の実行によって生成されるファイル「 Makefile.PL 」のコンテンツを確認します。


参考情報は書籍「 続・初めての Perl 改訂版 」, 「 Effective Perl 第 2 版 」を中心に perldoc, Wikipedia および各 Web サイト。それと詳しい先輩。

目次 - Perl Index