perl-5.34.0
require VERSION
require EXPR
require

Demands a version of Perl specified by VERSION, or demands some semantics specified by EXPR or by $_ if EXPR is not supplied.

VERSION で指定される Perl のバージョンを要求するか、 EXPR (省略時には $_) によって指定されるいくつかの動作を 要求します。

VERSION may be either a literal such as v5.24.1, which will be compared to $^V (or $PERL_VERSION in English), or a numeric argument of the form 5.024001, which will be compared to $]. An exception is raised if VERSION is greater than the version of the current Perl interpreter. Compare with use, which can do a similar check at compile time.

VERSION は、v5.24.1 のようなリテラル ($^V (または English モジュールでは $PERL_VERSION) と比較されます) か、 5.024001 の数値形式($] と比較されます)で指定します。 VERSION が Perl の現在のバージョンより大きいと、例外が発生します。 use と似ていますが、これはコンパイル時に チェックされます。

Specifying VERSION as a numeric argument of the form 5.024001 should generally be avoided as older less readable syntax compared to v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose numeric form was the only supported syntax, which is why you might see it in older code.

VERSION に 5.024001 の形の数値引数を指定することは一般的には避けるべきです; v5.24.1 に比べてより古く読みにくい文法だからです。 (2002 年にリリースされた) perl 5.8.0 より前では、より冗長な 数値形式が唯一対応している文法でした; これが古いコードでこれを 見るかも知れない理由です。

    require v5.24.1;    # run time version check
    require 5.24.1;     # ditto
    require 5.024_001;  # ditto; older syntax compatible
                          with perl 5.6
    require v5.24.1;    # 実行時バージョンチェック
    require 5.24.1;     # 同様
    require 5.024_001;  # 同様; perl 5.6 と互換性のある古い文法

Otherwise, require demands that a library file be included if it hasn't already been included. The file is included via the do-FILE mechanism, which is essentially just a variety of eval with the caveat that lexical variables in the invoking script will be invisible to the included code. If it were implemented in pure Perl, it would have semantics similar to the following:

それ以外の場合には、require は、既に 読み込まれていないときに読み込むライブラリファイルを要求するものとなります。 そのファイルは、基本的には eval の一種である、 do-FILE によって読み込まれますが、起動したスクリプトのレキシカル変数は 読み込まれたコードから見えないという欠点があります。 ピュア Perl で実装した場合、意味的には、次のようなサブルーチンと 同じようなものです:

    use Carp 'croak';
    use version;

    sub require {
        my ($filename) = @_;
        if ( my $version = eval { version->parse($filename) } ) {
            if ( $version > $^V ) {
               my $vn = $version->normal;
               croak "Perl $vn required--this is only $^V, stopped";
            }
            return 1;
        }

        if (exists $INC{$filename}) {
            return 1 if $INC{$filename};
            croak "Compilation failed in require";
        }

        foreach $prefix (@INC) {
            if (ref($prefix)) {
                #... do other stuff - see text below ....
            }
            # (see text below about possible appending of .pmc
            # suffix to $filename)
            my $realfilename = "$prefix/$filename";
            next if ! -e $realfilename || -d _ || -b _;
            $INC{$filename} = $realfilename;
            my $result = do($realfilename);
                         # but run in caller's namespace

            if (!defined $result) {
                $INC{$filename} = undef;
                croak $@ ? "$@Compilation failed in require"
                         : "Can't locate $filename: $!\n";
            }
            if (!$result) {
                delete $INC{$filename};
                croak "$filename did not return true value";
            }
            $! = 0;
            return $result;
        }
        croak "Can't locate $filename in \@INC ...";
    }

Note that the file will not be included twice under the same specified name.

ファイルは、同じ名前で 2 回読み込まれることはないことに注意してください。

The file must return true as the last statement to indicate successful execution of any initialization code, so it's customary to end such a file with 1; unless you're sure it'll return true otherwise. But it's better just to put the 1;, in case you add more statements.

初期化コードの実行がうまくいったことを示すために、ファイルは真を 返さなければならないので、真を返すようになっている自信がある場合を除いては、 ファイルの最後に 1; と書くのが習慣です。 しかし、実行文を追加するような場合に備えて、1; と書いておいた方が良いです。

If EXPR is a bareword, require assumes a .pm extension and replaces :: with / in the filename for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace, however it will autovivify the stash for the required module.

EXPR が裸の単語であるときには、標準モジュールのロードを簡単にするように、 require は拡張子が .pm であり、::/ に 変えたものがファイル名であると仮定します。 この形式のモジュールロードは、名前空間を変更してしまう危険はありませんが、 要求されたモジュールのためのスタッシュが自動有効化されます。

In other words, if you try this:

言い換えると、以下のようにすると:

        require Foo::Bar;     # a splendid bareword

The require function will actually look for the Foo/Bar.pm file in the directories specified in the @INC array, and it will autovivify the Foo::Bar:: stash at compile time.

require 関数は @INC 配列で指定されたディレクトリにある Foo/Bar.pm ファイルを探し、コンパイル時に Foo::Bar:: のスタッシュを自動有効化します。

But if you try this:

しかし、以下のようにすると:

        my $class = 'Foo::Bar';
        require $class;       # $class is not a bareword
    #or
        require "Foo::Bar";   # not a bareword because of the ""

The require function will look for the Foo::Bar file in the @INC array and will complain about not finding Foo::Bar there. In this case you can do:

require 関数は @INC 配列の Foo::Bar ファイルを探し、 おそらくそこに Foo::Bar がないと文句をいうことになるでしょう。 このような場合には、以下のように:

        eval "require $class";

or you could do

あるいは次のようにも出来ます

        require "Foo/Bar.pm";

Neither of these forms will autovivify any stashes at compile time and only have run time effects.

これらのどちらもコンパイル時にスタッシュを自動有効化せず、 実行時の効果のみを持ちます。

Now that you understand how require looks for files with a bareword argument, there is a little extra functionality going on behind the scenes. Before require looks for a .pm extension, it will first look for a similar filename with a .pmc extension. If this file is found, it will be loaded in place of any file ending in a .pm extension. This applies to both the explicit require "Foo/Bar.pm"; form and the require Foo::Bar; form.

引数が裸の単語の場合、require がどのようにファイルを 探すかを理解してください; 水面下でちょっとした追加の機能があります。 require が拡張子 .pm のファイルを探す前に、まず 拡張子 .pmc を持つファイルを探します。 このファイルが見つかると、このファイルが拡張子 .pm の代わりに 読み込まれます。 これは明示的な require "Foo/Bar.pm"; 形式と require Foo::Bar; 形式の 両方に適用されます。

You can also insert hooks into the import facility by putting Perl code directly into the @INC array. There are three forms of hooks: subroutine references, array references, and blessed objects.

@INC 配列に直接 Perl コードを入れることで、インポート機能に フックを挿入できます。 3 種類のフックがあります: サブルーチンリファレンス、配列リファレンス、 bless されたオブジェクトです。

Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets called with two parameters, the first a reference to itself, and the second the name of the file to be included (e.g., Foo/Bar.pm). The subroutine should return either nothing or else a list of up to four values in the following order:

サブルーチンへのリファレンスは一番単純な場合です。 インクルード機能が @INC を走査してサブルーチンに 出会った場合、このサブルーチンは二つの引数と共に呼び出されます; 一つ目は自身へのリファレンス、二つ目はインクルードされるファイル名 (Foo/Bar.pm など)です。 サブルーチンは何も返さないか、以下の順で最大四つの値のリストを返します。

  1. A reference to a scalar, containing any initial source code to prepend to the file or generator output.

    ファイルやジェネレータの出力の前に追加される初期化ソースコードを含む スカラへのリファレンス。

  2. A filehandle, from which the file will be read.

    ファイルが読み込まれるファイルハンドル。

  3. A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per call, writing the line into $_ and returning 1, then finally at end of file returning 0. If there is a filehandle, then the subroutine will be called to act as a simple source filter, with the line as read in $_. Again, return 1 for each valid line, and 0 after all lines have been returned. For historical reasons the subroutine will receive a meaningless argument (in fact always the numeric value zero) as $_[0].

    サブルーチンへのリファレンス。 (一つ前のアイテムである)ファイルハンドルがない場合、サブルーチンは呼び出し毎に 一行のソースコードを生成し、その行を $_ に書き込んで 1 を 返し、それから最終的にファイル終端で 0 を返すものと想定されます。 ファイルハンドルがある場合、サブルーチンは単純なソースフィルタとして 振舞うように呼び出され、行は $_ から読み込まれます。 再び、有効な行ごとに 1 を返し、全ての行を返した後では 0 を返します。 歴史的な理由により、サブルーチンは $_[0] として意味のない引数 (実際には常に数値 0) を受け取ります。

  4. Optional state for the subroutine. The state is passed in as $_[1].

    サブルーチンのための状態(オプション)。 状態は $_[1] として渡されます。

If an empty list, undef, or nothing that matches the first 3 values above is returned, then require looks at the remaining elements of @INC. Note that this filehandle must be a real filehandle (strictly a typeglob or reference to a typeglob, whether blessed or unblessed); tied filehandles will be ignored and processing will stop there.

空リスト、undef、または上記の最初の三つの値のどれとも 一致しないものが返されると、require@INC の残りの要素を見ます。 このファイルハンドルは実際のファイルハンドル(厳密には型グロブ、型グロブへの リファレンス、bless されているかに関わらず)でなければなりません; tie されたファイルハンドルは無視され、返り値の処理はそこで停止します。

If the hook is an array reference, its first element must be a subroutine reference. This subroutine is called as above, but the first parameter is the array reference. This lets you indirectly pass arguments to the subroutine.

フックが配列のリファレンスの場合、その最初の要素はサブルーチンへの リファレンスでなければなりません。 このサブルーチンは上述のように呼び出されますが、その最初の引数は 配列のリファレンスです。 これによって、間接的にサブルーチンに引数を渡すことが出来ます。

In other words, you can write:

言い換えると、以下のように書いたり:

    push @INC, \&my_sub;
    sub my_sub {
        my ($coderef, $filename) = @_;  # $coderef is \&my_sub
        ...
    }

or:

または以下のように書けます:

    push @INC, [ \&my_sub, $x, $y, ... ];
    sub my_sub {
        my ($arrayref, $filename) = @_;
        # Retrieve $x, $y, ...
        my (undef, @parameters) = @$arrayref;
        ...
    }

If the hook is an object, it must provide an INC method that will be called as above, the first parameter being the object itself. (Note that you must fully qualify the sub's name, as unqualified INC is always forced into package main.) Here is a typical code layout:

フックがオブジェクトの場合、INC メソッドを提供している必要があります; それが、最初の引数をオブジェクト自身として上述のように呼び出されます。 (修飾されていない INC は常にパッケージ main に強制されるため、 サブルーチン名は完全修飾する必要があることに注意してください。) 以下は典型的なコードレイアウトです:

    # In Foo.pm
    package Foo;
    sub new { ... }
    sub Foo::INC {
        my ($self, $filename) = @_;
        ...
    }

    # In the main program
    push @INC, Foo->new(...);

These hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See "%INC" in perlvar.

これらのフックは、読み込まれるファイルに対応する %INC エントリをセットすることも許可します。 "%INC" in perlvar を参照してください。

For a yet-more-powerful import facility, see use and perlmod.

より強力な import 機能については、このドキュメントの use の項と、perlmod を参照してください。