=encoding euc-jp

=head1 NAME

=begin original

perlreapi - perl regular expression plugin interface

=end original

perlreapi - perl 正規表現プラグインインターフェース

(訳注: (TBR)がついている段落は「みんなの自動翻訳＠TexTra」による
機械翻訳です。)

=head1 DESCRIPTION

=begin original

As of Perl 5.9.5 there is a new interface for plugging and using other
regular expression engines than the default one.

=end original

Perl 5.9.5 から、デフォルトと異なるその他の正規表現エンジンを使うための
新しいインターフェスがあります。

=begin original

Each engine is supposed to provide access to a constant structure of the
following format:

=end original

それぞれのエンジンは以下の形式の定数構造体へのアクセスを提供することに
なっています:

    typedef struct regexp_engine {
        REGEXP* (*comp) (pTHX_ const SV * const pattern, const U32 flags);
        I32     (*exec) (pTHX_ REGEXP * const rx, char* stringarg, char* strend,
                         char* strbeg, I32 minend, SV* screamer,
                         void* data, U32 flags);
        char*   (*intuit) (pTHX_ REGEXP * const rx, SV *sv, char *strpos,
                           char *strend, U32 flags,
                           struct re_scream_pos_data_s *data);
        SV*     (*checkstr) (pTHX_ REGEXP * const rx);
        void    (*free) (pTHX_ REGEXP * const rx);
        void    (*numbered_buff_FETCH) (pTHX_ REGEXP * const rx, const I32 paren,
                                 SV * const sv);
        void    (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
                                       SV const * const value);
        I32     (*numbered_buff_LENGTH) (pTHX_ REGEXP * const rx, const SV * const sv,
                                        const I32 paren);
        SV*     (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
                               SV * const value, U32 flags);
        SV*     (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
                                    const U32 flags);
        SV*     (*qr_package)(pTHX_ REGEXP * const rx);
    #ifdef USE_ITHREADS
        void*   (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
    #endif

=begin original

When a regexp is compiled, its C<engine> field is then set to point at
the appropriate structure, so that when it needs to be used Perl can find
the right routines to do so.

=end original

正規表現がコンパイルされるとき、C<engine> フィールドが適切な構造体を
指すように設定されるので、使われる必要があるとき、Perl はそうするための
正しいルーチンを見つけられます。

=begin original

In order to install a new regexp handler, C<$^H{regcomp}> is set
to an integer which (when casted appropriately) resolves to one of these
structures. When compiling, the C<comp> method is executed, and the
resulting regexp structure's engine field is expected to point back at
the same structure.

=end original

新しいregexpハンドラをインストールするために、C<$^H{regcomp}>はこれらの構造体の1つを(適切にギプス固定時)解決する整数に設定されます。
コンパイル時にはC<comp>メソッドが実行され、生成されたregexp構造体のエンジンフィールドは同じ構造体を指すことが期待されます。
(TBR)

=begin original

The pTHX_ symbol in the definition is a macro used by perl under threading
to provide an extra argument to the routine holding a pointer back to
the interpreter that is executing the regexp. So under threading all
routines get an extra argument.

=end original

定義内のpTHX_シンボルは、perlがスレッド化の下で使用するマクロで、regexpを実行しているインタプリタへのポインタを保持するルーチンに追加引数を提供します。
したがって、スレッド化の下では、すべてのルーチンが追加引数を取得します。
(TBR)

=head1 Callbacks

=head2 comp

    REGEXP* comp(pTHX_ const SV * const pattern, const U32 flags);

=begin original

Compile the pattern stored in C<pattern> using the given C<flags> and
return a pointer to a prepared C<REGEXP> structure that can perform
the match. See L</The REGEXP structure> below for an explanation of
the individual fields in the REGEXP struct.

=end original

与えられたC<flags>を使用してC<pattern>に格納されたパターンをコンパイルし、マッチを実行できる準備されたC<REGEXP>構造体へのポインタを返します。
REGEXP構造体の個々のフィールドの説明については、下記のL</The REGEXP structure>を参照してください。
(TBR)

=begin original

The C<pattern> parameter is the scalar that was used as the
pattern. previous versions of perl would pass two C<char*> indicating
the start and end of the stringified pattern, the following snippet can
be used to get the old parameters:

=end original

C<pattern>パラメータは、パターンとして使用されたスカラです。
以前のバージョンのperlでは、文字列化されたパターンの開始と終了を示す2つのC<char*>が渡されていました。
古いパラメータを取得するには、次のスニペットを使用できます。
(TBR)

    STRLEN plen;
    char*  exp = SvPV(pattern, plen);
    char* xend = exp + plen;

=begin original

Since any scalar can be passed as a pattern it's possible to implement
an engine that does something with an array (C<< "ook" =~ [ qw/ eek
hlagh / ] >>) or with the non-stringified form of a compiled regular
expression (C<< "ook" =~ qr/eek/ >>). perl's own engine will always
stringify everything using the snippet above but that doesn't mean
other engines have to.

=end original

どんなスカラもパターンとして渡すことができるので、配列(C<< "ook" =~ [ qw/ eek hlagh / ] >>)や、非ストリング形式のコンパイルされた正規表現(C<< "ook" =~ qr/eek/ >>)を使って何かを行うエンジンを実装することができます。
perl自身のエンジンは常に上記のスニペットを使ってすべてをストリング化しますが、他のエンジンがそうしなければならないというわけではありません。
(TBR)

=begin original

The C<flags> parameter is a bitfield which indicates which of the
C<msixp> flags the regex was compiled with. It also contains
additional info such as whether C<use locale> is in effect.

=end original

C<flags>パラメータは、regexがどのC<msixp>フラグでコンパイルされたかを示すビットフィールドである。
また、C<use locale>が有効かどうかといった追加情報も含まれる。
(TBR)

=begin original

The C<eogc> flags are stripped out before being passed to the comp
routine. The regex engine does not need to know whether any of these
are set as those flags should only affect what perl does with the
pattern and its match variables, not how it gets compiled and
executed.

=end original

C<eogc>フラグはcompルーチンに渡される前に取り除かれます。
regexエンジンは、これらのフラグが設定されているかどうかを知る必要はありません。
なぜなら、これらのフラグはperlがパターンとマッチ変数で行うことに影響を与えるだけで、コンパイル方法や実行方法には影響を与えないからです。
(TBR)

=begin original

By the time the comp callback is called, some of these flags have
already had effect (noted below where applicable). However most of
their effect occurs after the comp callback has run in routines that
read the C<< rx->extflags >> field which it populates.

=end original

compコールバックが呼び出されるまでに、これらのフラグのいくつかはすでに有効になっています(適用可能な場合は後述します)。
ただし、これらの効果のほとんどは、compコールバックがC<< rx->extflags>>フィールドを読み込むルーチンで実行された後に発生します。
(TBR)

=begin original

In general the flags should be preserved in C<< rx->extflags >> after
compilation, although the regex engine might want to add or delete
some of them to invoke or disable some special behavior in perl. The
flags along with any special behavior they cause are documented below:

=end original

一般に、これらのフラグはコンパイル後にC<< rx->extflags>>に保存する必要があります。
ただし、regexエンジンは、perlでの特殊な動作を起動または無効にするために、フラグの一部を追加または削除する必要がある場合があります。
これらのフラグとフラグが引き起こす特殊な動作については、以下で説明します。
(TBR)

=begin original

The pattern modifiers:

=end original

パターン修飾子:
(TBR)

=over 4

=item C</m> - RXf_PMf_MULTILINE

=begin original

If this is in C<< rx->extflags >> it will be passed to
C<Perl_fbm_instr> by C<pp_split> which will treat the subject string
as a multi-line string.

=end original

これがC<< rx->extflags>>にある場合、C<pp_split>によってC<Perl_fbm_instr>に渡されます。
C<pp_split>は、対象ストリングを複数行ストリングとして処理します。
(TBR)

=item C</s> - RXf_PMf_SINGLELINE

=item C</i> - RXf_PMf_FOLD

=item C</x> - RXf_PMf_EXTENDED

=begin original

If present on a regex C<#> comments will be handled differently by the
tokenizer in some cases.

=end original

regexに存在する場合、C<#>コメントは、場合によってはトークナイザによって異なる方法で処理されます。
(TBR)

=begin original

TODO: Document those cases.

=end original

TODO:これらのケースを記録します。
(TBR)

=item C</p> - RXf_PMf_KEEPCOPY

=back

=begin original

Additional flags:

=end original

追加フラグ:
(TBR)

=over 4

=item RXf_PMf_LOCALE

=begin original

Set if C<use locale> is in effect. If present in C<< rx->extflags >>
C<split> will use the locale dependent definition of whitespace under
when RXf_SKIPWHITE or RXf_WHITE are in effect. Under ASCII whitespace
is defined as per L<isSPACE|perlapi/ISSPACE>, and by the internal
macros C<is_utf8_space> under UTF-8 and C<isSPACE_LC> under C<use
locale>.

=end original

C<use locale>が有効な場合に設定されます。
C<< rx->extflags>>に存在する場合、C<split>は、RXf_SKIPWHITEまたはRXf_WHITEが有効な場合に、以下の空白のロケール依存の定義を使用します。
ASCIIでは、空白はL<isSPACE|perlapi/ISSPACE>によって定義され、内部マクロC<is_utf8_space>(UTF-8)とC<isSPACE_LC>(C<use locale>)によって定義されます。
(TBR)

=item RXf_UTF8

=begin original

Set if the pattern is L<SvUTF8()|perlapi/SvUTF8>, set by Perl_pmruntime.

=end original

パターンがPerl_pmruntimeで設定されたL<SvUTF8()|perlapi/SvUTF8>の場合に設定されます。
(TBR)

=begin original

A regex engine may want to set or disable this flag during
compilation. The perl engine for instance may upgrade non-UTF-8
strings to UTF-8 if the pattern includes constructs such as C<\x{...}>
that can only match Unicode values.

=end original

regexエンジンは、コンパイル中にこのフラグを設定または無効にしたい場合があります。
例えば、Perlエンジンは、パターンにUnicode値にしか一致しないC<\x{.}>のような構造体が含まれている場合、非UTF-8文字列をUTF-8にアップグレードします。
(TBR)

=item RXf_SPLIT

=begin original

If C<split> is invoked as C<split ' '> or with no arguments (which
really means C<split(' ', $_)>, see L<split|perlfunc/split>), perl will
set this flag. The regex engine can then check for it and set the
SKIPWHITE and WHITE extflags. To do this the perl engine does:

=end original

C<split>がC<split ' '>として、または引数なしで呼び出された場合(これは実際にはC<split(' ', $_)>を意味します。
L<split|perlfunc/split>を参照してください)、perlはこのフラグを設定します。
regexエンジンはこのフラグをチェックして、SKIPWHITEとホワイトextflagsを設定します。
これを行うために、perlエンジンは以下を行います。
(TBR)

    if (flags & RXf_SPLIT && r->prelen == 1 && r->precomp[0] == ' ')
        r->extflags |= (RXf_SKIPWHITE|RXf_WHITE);

=back

=begin original

These flags can be set during compilation to enable optimizations in
the C<split> operator.

=end original

コンパイル時にこれらのフラグを設定して、C<split>演算子での最適化を有効にすることができます。
(TBR)

=over 4

=item RXf_SKIPWHITE

=begin original

If the flag is present in C<< rx->extflags >> C<split> will delete
whitespace from the start of the subject string before it's operated
on. What is considered whitespace depends on whether the subject is a
UTF-8 string and whether the C<RXf_PMf_LOCALE> flag is set.

=end original

フラグがC<< rx->extflags>>に存在する場合、C<split>は操作の前に対象文字列の先頭から空白文字を削除します。
空白文字とみなされるものは、対象文字列がUTF-8文字列であるかどうか、およびC<RXf_PMf_LOCALE>フラグが設定されているかどうかによって異なります。
(TBR)

=begin original

If RXf_WHITE is set in addition to this flag C<split> will behave like
C<split " "> under the perl engine.

=end original

このフラグに加えてRXf_WHITEが設定されている場合、PerlエンジンではC<split>はC<split " ">のように動作します。
(TBR)

=item RXf_START_ONLY

=begin original

Tells the split operator to split the target string on newlines
(C<\n>) without invoking the regex engine.

=end original

regexエンジンを呼び出さずに、ターゲット文字列を改行(C<\n>)で分割するように、分割演算子に指示します。
(TBR)

=begin original

Perl's engine sets this if the pattern is C</^/> (C<plen == 1 && *exp
== '^'>), even under C</^/s>, see L<split|perlfunc>. Of course a
different regex engine might want to use the same optimizations
with a different syntax.

=end original

Perlのエンジンは、パターンがC</^/>(C<plen == 1 && *exp == '^'>)の場合にこれを設定します。
C</^/s>の下でも、L<split|perlfunc>を参照してください。
もちろん、regexエンジンが異なれば、同じ最適化を異なる構文で使用することもできます。
(TBR)

=item RXf_WHITE

=begin original

Tells the split operator to split the target string on whitespace
without invoking the regex engine. The definition of whitespace varies
depending on whether the target string is a UTF-8 string and on
whether RXf_PMf_LOCALE is set.

=end original

regexエンジンを呼び出さずにターゲット文字列を空白で分割するよう、分割演算子に指示します。
空白の定義は、ターゲット文字列がUTF-8文字列であるかどうか、およびRXf_PMf_LOCALEが設定されているかどうかによって異なります。
(TBR)

=begin original

Perl's engine sets this flag if the pattern is C<\s+>.

=end original

Perlのエンジンは、パターンがC<\s+>の場合、このフラグを設定します。
(TBR)

=item RXf_NULL

=begin original

Tells the split operator to split the target string on
characters. The definition of character varies depending on whether
the target string is a UTF-8 string.

=end original

ターゲット文字列を文字で分割するように分割演算子に指示します。
文字の定義は、ターゲット文字列がUTF-8文字列かどうかによって異なります。
(TBR)

=begin original

Perl's engine sets this flag on empty patterns, this optimization
makes C<split //> much faster than it would otherwise be. It's even
faster than C<unpack>.

=end original

Perlのエンジンは空のパターンにこのフラグをセットします。
この最適化により、C<split //>は、そうでない場合よりもはるかに高速になります。
C<unpack>よりもさらに高速です。
(TBR)

=back

=head2 exec

    I32 exec(pTHX_ REGEXP * const rx,
             char *stringarg, char* strend, char* strbeg,
             I32 minend, SV* screamer,
             void* data, U32 flags);

=begin original

Execute a regexp.

=end original

regexpを実行します。
(TBR)

=head2 intuit

    char* intuit(pTHX_ REGEXP * const rx,
                  SV *sv, char *strpos, char *strend,
                  const U32 flags, struct re_scream_pos_data_s *data);

=begin original

Find the start position where a regex match should be attempted,
or possibly whether the regex engine should not be run because the
pattern can't match. This is called as appropriate by the core
depending on the values of the extflags member of the regexp
structure.

=end original

正規表現の一致を試行する開始位置、またはパターンが一致しないために正規表現エンジンを実行すべきでないかどうかを検索します。
これは、regexp構造体のextflagsメンバーの値に応じて、コアによって適切に呼び出されます。
(TBR)

=head2 checkstr

    SV*	checkstr(pTHX_ REGEXP * const rx);

=begin original

Return a SV containing a string that must appear in the pattern. Used
by C<split> for optimising matches.

=end original

パターンに表示される文字列を含むSVを返します。
マッチを最適化するためにC<split>によって使用されます。
(TBR)

=head2 free

    void free(pTHX_ REGEXP * const rx);

=begin original

Called by perl when it is freeing a regexp pattern so that the engine
can release any resources pointed to by the C<pprivate> member of the
regexp structure. This is only responsible for freeing private data;
perl will handle releasing anything else contained in the regexp structure.

=end original

perlがregexpパターンを解放して、regexp構造体のC<pprivate>メンバーによってポイントされたリソースをエンジンが解放できるようにするときに呼び出されます。
これはプライベートデータの解放のみを行います。
perlはregexp構造体に含まれる他のすべての解放を処理します。
(TBR)

=head2 Numbered capture callbacks

(番号付き捕捉コールバック)

=begin original

Called to get/set the value of C<$`>, C<$'>, C<$&> and their named
equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
numbered capture buffers (C<$1>, C<$2>, ...).

=end original

C<$`>、C<$'>、C<$&>、およびそれらに対応する名前付きの${^PREMATCH}、${^POSTMATCH}、$^{MATCH}、および番号付きキャプチャバッファ(C<$1>、C<$2>、.)の値を取得/設定するために呼び出されます。
(TBR)

=begin original

The C<paren> parameter will be C<-2> for C<$`>, C<-1> for C<$'>, C<0>
for C<$&>, C<1> for C<$1> and so forth.

=end original

C<paren>パラメータは、C<$`>に対してC<-2>、C<$'>に対してC<-1>、C<$&>に対してC<0>、C<$1>に対してC<1>などとなります。
(TBR)

=begin original

The names have been chosen by analogy with L<Tie::Scalar> methods
names with an additional B<LENGTH> callback for efficiency. However
named capture variables are currently not tied internally but
implemented via magic.

=end original

名前は、効率性のためにL<Tie::Scalar>メソッド名と追加のB<LENGTH>コールバックから類推して選択されている。
ただし、名前付きキャプチャ変数は現在、内部では結合されておらず、マジックによって実装されている。
(TBR)

=head3 numbered_buff_FETCH

    void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
                             SV * const sv);

=begin original

Fetch a specified numbered capture. C<sv> should be set to the scalar
to return, the scalar is passed as an argument rather than being
returned from the function because when it's called perl already has a
scalar to store the value, creating another one would be
redundant. The scalar can be set with C<sv_setsv>, C<sv_setpvn> and
friends, see L<perlapi>.

=end original

指定された番号付きキャプチャをフェッチします。
C<sv>を返すスカラに設定する必要があります。
このスカラは関数から返されるのではなく引数として渡されます。
というのは、perlという関数が既に値を格納するスカラを持っている場合には、別のスカラを作成するのは冗長になるからです。
スカラはC<sv_setsv>、C<sv_setpvn>、friendsで設定できます。
L<perlapi>を参照してください。
(TBR)

=begin original

This callback is where perl untaints its own capture variables under
taint mode (see L<perlsec>). See the C<Perl_reg_numbered_buff_fetch>
function in F<regcomp.c> for how to untaint capture variables if
that's something you'd like your engine to do as well.

=end original

このコールバックは、perlがuntaintsモード(L<perlsec>を参照)で独自のキャプチャ変数をテイントする場所です。
エンジンにも同様に行わせたい場合は、F<regcomp.c>のC<Perl_reg_numbered_buff_fetch>関数を参照してください。
(TBR)

=head3 numbered_buff_STORE

    void    (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
                                    SV const * const value);

=begin original

Set the value of a numbered capture variable. C<value> is the scalar
that is to be used as the new value. It's up to the engine to make
sure this is used as the new value (or reject it).

=end original

番号付きキャプチャ変数の値を設定します。
C<value>は、新しい値として使用されるスカラです。
これが新しい値として使用される(または拒否される)かどうかはエンジン次第です。
(TBR)

=begin original

Example:

=end original

例:
(TBR)

    if ("ook" =~ /(o*)/) {
        # `paren' will be `1' and `value' will be `ee'
        $1 =~ tr/o/e/;
    }

=begin original

Perl's own engine will croak on any attempt to modify the capture
variables, to do this in another engine use the following callback
(copied from C<Perl_reg_numbered_buff_store>):

=end original

Perl自身のエンジンは、キャプチャ変数を変更しようとするときにクロッキングします。
別のエンジンでこれを行うには、次のコールバック(C<Perl_reg_numbered_buff_store>からコピー)を使用します。
(TBR)

    void
    Example_reg_numbered_buff_store(pTHX_ REGEXP * const rx, const I32 paren,
    							    SV const * const value)
    {
        PERL_UNUSED_ARG(rx);
        PERL_UNUSED_ARG(paren);
        PERL_UNUSED_ARG(value);

        if (!PL_localizing)
            Perl_croak(aTHX_ PL_no_modify);
    }

=begin original

Actually perl will not I<always> croak in a statement that looks
like it would modify a numbered capture variable. This is because the
STORE callback will not be called if perl can determine that it
doesn't have to modify the value. This is exactly how tied variables
behave in the same situation:

=end original

実際には、番号付きのキャプチャ変数を変更するような文では、perlは<常に>確認できません。
これは、perlが値を変更する必要がないと判断した場合には、STOREコールバックが呼び出されないためです。
同じ状況では、ひも付き変数は次のように動作します。
(TBR)

    package CaptureVar;
    use base 'Tie::Scalar';

    sub TIESCALAR { bless [] }
    sub FETCH { undef }
    sub STORE { die "This doesn't get called" }

    package main;

    tie my $sv => "CatptureVar";
    $sv =~ y/a/b/;

=begin original

Because C<$sv> is C<undef> when the C<y///> operator is applied to it
the transliteration won't actually execute and the program won't
C<die>. This is different to how 5.8 and earlier versions behaved
since the capture variables were READONLY variables then, now they'll
just die when assigned to in the default engine.

=end original

C<$sv>はC<undef>なので、C<y///>演算子がそれに適用されたときに音訳は実際には実行されず、プログラムはC<die>を実行しません。
これは5.8以前のバージョンとは異なります。
なぜなら、キャプチャ変数はREADONLY変数であったため、デフォルトエンジンでに割り当てられたときに単に消滅するからです。
(TBR)

=head3 numbered_buff_LENGTH

    I32 numbered_buff_LENGTH (pTHX_ REGEXP * const rx, const SV * const sv,
                              const I32 paren);

=begin original

Get the C<length> of a capture variable. There's a special callback
for this so that perl doesn't have to do a FETCH and run C<length> on
the result, since the length is (in perl's case) known from an offset
stored in C<< rx->offs >> this is much more efficient:

=end original

キャプチャ変数のC<length>を取得します。
このための特別なコールバックがあり、perlがFETCHを実行して結果に対してC<length>を実行する必要がありません。
長さは(perlの場合)C<< rx->offs>>に格納されたオフセットからわかるので、これは非常に効率的です:
(TBR)

    I32 s1  = rx->offs[paren].start;
    I32 s2  = rx->offs[paren].end;
    I32 len = t1 - s1;

=begin original

This is a little bit more complex in the case of UTF-8, see what
C<Perl_reg_numbered_buff_length> does with
L<is_utf8_string_loclen|perlapi/is_utf8_string_loclen>.

=end original

これはUTF-8の場合にはもう少し複雑です。
C<Perl_reg_reg_numbered_buff_length>がL<is_utf8_string_loclen|perlapi/is_utf8_string_loclen>で行っていることを見てください。
(TBR)

=head2 Named capture callbacks

(名前付き捕捉コールバック)

=begin original

Called to get/set the value of C<%+> and C<%-> as well as by some
utility functions in L<re>.

=end original

C<%+>とC<%->の値を取得/設定するために、またL<re>のユーティリティ関数によって呼び出されます。
(TBR)

=begin original

There are two callbacks, C<named_buff> is called in all the cases the
FETCH, STORE, DELETE, CLEAR, EXISTS and SCALAR L<Tie::Hash> callbacks
would be on changes to C<%+> and C<%-> and C<named_buff_iter> in the
same cases as FIRSTKEY and NEXTKEY.

=end original

2つのコールバックがあります。
C<named_buff>はすべての場合に呼び出されます。
FETCH、STORE、DELETE、CLEAR、EXISTSおよびSCALAR L<Tie::Hash>コールバックは、C<%+>、C<%->およびC<named_buff_iter>への変更時に、FIRSTKEYおよびNEXTKEYと同じ場合に呼び出されます。
(TBR)

=begin original

The C<flags> parameter can be used to determine which of these
operations the callbacks should respond to, the following flags are
currently defined:

=end original

C<flags>パラメータを使用して、これらのどの操作にコールバックが応答するかを決定できます。
現在、次のフラグが定義されています。
(TBR)

=begin original

Which L<Tie::Hash> operation is being performed from the Perl level on
C<%+> or C<%+>, if any:

=end original

C<%+>またはC<%+><%+>に対して実行されているL<Tie::Hash>操作(ある場合):
(TBR)

    RXapif_FETCH
    RXapif_STORE
    RXapif_DELETE
    RXapif_CLEAR
    RXapif_EXISTS
    RXapif_SCALAR
    RXapif_FIRSTKEY
    RXapif_NEXTKEY

=begin original

Whether C<%+> or C<%-> is being operated on, if any.

=end original

C<%+>またはC<%->が操作されているかどうか(もしあれば)。
(TBR)

    RXapif_ONE /* %+ */
    RXapif_ALL /* %- */

=begin original

Whether this is being called as C<re::regname>, C<re::regnames> or
C<re::regnames_count>, if any. The first two will be combined with
C<RXapif_ONE> or C<RXapif_ALL>.

=end original

C<re::regname>、C<re::regnames>、またはC<re::regnames_count>のいずれか(存在する場合)。
最初の2つはC<RXapif_ONE>またはC<RXapif_ALL>と結合されます。
(TBR)

    RXapif_REGNAME
    RXapif_REGNAMES
    RXapif_REGNAMES_COUNT

=begin original

Internally C<%+> and C<%-> are implemented with a real tied interface
via L<Tie::Hash::NamedCapture>. The methods in that package will call
back into these functions. However the usage of
L<Tie::Hash::NamedCapture> for this purpose might change in future
releases. For instance this might be implemented by magic instead
(would need an extension to mgvtbl).

=end original

内部的には、C<%+>とC<%->は、L<Tie::Hash::NamedCapture>を介して実際に結合されたインターフェイスで実装されます。
そのパッケージのメソッドは、これらの関数にコールバックします。
ただし、この目的のためのL<Tie::Hash::NamedCapture>の使用方法は、将来のリリースで変更される可能性があります。
例えば、これは代わりにmagicによって実装される可能性があります(mgvtblへの拡張が必要です)。
(TBR)

=head3 named_buff

    SV*     (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
                           SV * const value, U32 flags);

=head3 named_buff_iter

    SV*     (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
                                const U32 flags);

=head2 qr_package

    SV* qr_package(pTHX_ REGEXP * const rx);

=begin original

The package the qr// magic object is blessed into (as seen by C<ref
qr//>). It is recommended that engines change this to their package
name for identification regardless of whether they implement methods
on the object.

=end original

(C<ref qr//>で見られるように)qr//magicオブジェクトが祝福されるパッケージ。
エンジンは、オブジェクトにメソッドを実装しているかどうかに関係なく、識別のためにこれをパッケージ名に変更することを推奨する。
(TBR)

=begin original

The package this method returns should also have the internal
C<Regexp> package in its C<@ISA>. C<qr//->isa("Regexp")> should always
be true regardless of what engine is being used.

=end original

このメソッドが返すパッケージには、C<@ISA>内に内部C<Regexp>パッケージも含まれている必要があります。
C<qr//->isa("Regexp")>は、使用されているエンジンに関係なく常にtrueである必要があります。
(TBR)

=begin original

Example implementation might be:

=end original

実装例は次のようになります。
(TBR)

    SV*
    Example_qr_package(pTHX_ REGEXP * const rx)
    {
    	PERL_UNUSED_ARG(rx);
    	return newSVpvs("re::engine::Example");
    }

=begin original

Any method calls on an object created with C<qr//> will be dispatched to the
package as a normal object.

=end original

C<qr//>で作成されたオブジェクトに対するメソッド呼び出しは、通常のオブジェクトとしてパッケージにディスパッチされます。
(TBR)

    use re::engine::Example;
    my $re = qr//;
    $re->meth; # dispatched to re::engine::Example::meth()

=begin original

To retrieve the C<REGEXP> object from the scalar in an XS function use
the C<SvRX> macro, see L<"REGEXP Functions" in perlapi|perlapi/REGEXP
Functions>.

=end original

XS関数のスカラからC<REGEXP>オブジェクトを取得するには、C<SvRX>マクロを使用します。
L<"REGEXP Functions"in perlapi|perlapi/REGEXP Functions>を参照してください。
(TBR)

    void meth(SV * rv)
    PPCODE:
        REGEXP * re = SvRX(sv);

=head2 dupe

    void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);

=begin original

On threaded builds a regexp may need to be duplicated so that the pattern
can be used by multiple threads. This routine is expected to handle the
duplication of any private data pointed to by the C<pprivate> member of
the regexp structure.  It will be called with the preconstructed new
regexp structure as an argument, the C<pprivate> member will point at
the B<old> private structure, and it is this routine's responsibility to
construct a copy and return a pointer to it (which perl will then use to
overwrite the field as passed to this routine.)

=end original

スレッド化ビルドでは、パターンを複数のスレッドで使用できるように、regexpを複製する必要がある場合があります。
このルーチンは、regexp構造体のC<pprivate>メンバによってポイントされるプライベートデータの複製を処理することが期待されています。
このルーチンは、事前に構築された新しいregexp構造体を引数として呼び出され、C<pprivate>メンバはB<old>プライベート構造体をポイントします。
そして、コピーを作成してそのポインタを返すのは、このルーチンの責任です(このルーチンに渡されたフィールドを上書きするためにperlが使用します)。
(TBR)

=begin original

This allows the engine to dupe its private data but also if necessary
modify the final structure if it really must.

=end original

これにより、エンジンはプライベートデータを複製することができますが、必要に応じて最終構造を変更することもできます。
(TBR)

=begin original

On unthreaded builds this field doesn't exist.

=end original

スレッド化されていないビルドでは、このフィールドは存在しません。
(TBR)

=head1 The REGEXP structure

(REGEXP 構造体)

=begin original

The REGEXP struct is defined in F<regexp.h>. All regex engines must be able to
correctly build such a structure in their L</comp> routine.

=end original

REGEXP構造体はF<regexp.h>で定義されています。
すべてのregexエンジンは、L</comp>ルーチンでこのような構造体を正しく構築できなければなりません。
(TBR)

=begin original

The REGEXP structure contains all the data that perl needs to be aware of
to properly work with the regular expression. It includes data about
optimisations that perl can use to determine if the regex engine should
really be used, and various other control info that is needed to properly
execute patterns in various contexts such as is the pattern anchored in
some way, or what flags were used during the compile, or whether the
program contains special constructs that perl needs to be aware of.

=end original

REGEXP構造体には、正規表現で適切に動作するためにperlが認識する必要があるすべてのデータが含まれています。
この構造体には、regexエンジンを実際に使用すべきかどうかを判断するためにperlが使用できる最適化に関するデータや、さまざまなコンテキストでパターンを適切に実行するために必要なその他のさまざまな制御情報(パターンが何らかの方法で固定されているかどうか、コンパイル時にどのフラグが使用されたか、プログラムにperlが認識する必要がある特殊な構造体が含まれているかどうかなど)が含まれています。
(TBR)

=begin original

In addition it contains two fields that are intended for the private
use of the regex engine that compiled the pattern. These are the
C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
an arbitrary structure whose use and management is the responsibility
of the compiling engine. perl will never modify either of these
values.

=end original

さらに、パターンをコンパイルしたregexエンジンのプライベートな使用を目的とした2つのフィールドが含まれています。
これらはC<intflags>メンバとC<pprivate>メンバです。
C<pprivate>は任意の構造体へのvoidポインタで、その使用と管理はコンパイルエンジンが担当します。
perlはこれらの値を変更することはありません。
(TBR)

    typedef struct regexp {
        /* what engine created this regexp? */
        const struct regexp_engine* engine;

        /* what re is this a lightweight copy of? */
        struct regexp* mother_re;

        /* Information about the match that the perl core uses to manage things */
        U32 extflags;   /* Flags used both externally and internally */
        I32 minlen;     /* mininum possible length of string to match */
        I32 minlenret;  /* mininum possible length of $& */
        U32 gofs;       /* chars left of pos that we search from */

        /* substring data about strings that must appear
           in the final match, used for optimisations */
        struct reg_substr_data *substrs;

        U32 nparens;  /* number of capture buffers */

        /* private engine specific data */
        U32 intflags;   /* Engine Specific Internal flags */
        void *pprivate; /* Data private to the regex engine which 
                           created this object. */

        /* Data about the last/current match. These are modified during matching*/
        U32 lastparen;            /* last open paren matched */
        U32 lastcloseparen;       /* last close paren matched */
        regexp_paren_pair *swap;  /* Swap copy of *offs */
        regexp_paren_pair *offs;  /* Array of offsets for (@-) and (@+) */

        char *subbeg;  /* saved or original string so \digit works forever. */
        SV_SAVED_COPY  /* If non-NULL, SV which is COW from original */
        I32 sublen;    /* Length of string pointed by subbeg */

        /* Information about the match that isn't often used */
        I32 prelen;           /* length of precomp */
        const char *precomp;  /* pre-compilation regular expression */

        char *wrapped;  /* wrapped version of the pattern */
        I32 wraplen;    /* length of wrapped */

        I32 seen_evals;   /* number of eval groups in the pattern - for security checks */
        HV *paren_names;  /* Optional hash of paren names */

        /* Refcount of this regexp */
        I32 refcnt;             /* Refcount of this regexp */
    } regexp;

=begin original

The fields are discussed in more detail below:

=end original

フィールドについては、以下で詳しく説明します。
(TBR)

=head2 C<engine>

=begin original

This field points at a regexp_engine structure which contains pointers
to the subroutines that are to be used for performing a match. It
is the compiling routine's responsibility to populate this field before
returning the regexp object.

=end original

このフィールドは、マッチングの実行に使用されるサブルーチンへのポインタを含むregexp_engine構造体を指します。
regexpオブジェクトを返す前にこのフィールドに値を入力するのは、コンパイルルーチンの責任です。
(TBR)

=begin original

Internally this is set to C<NULL> unless a custom engine is specified in
C<$^H{regcomp}>, perl's own set of callbacks can be accessed in the struct
pointed to by C<RE_ENGINE_PTR>.

=end original

C<$^H{regcomp}>でカスタムエンジンが指定されていない限り、内部的にはこれはC<NULL>に設定されます。
perl独自のコールバックセットは、C<RE_ENGINE_PTR>が指す構造体でアクセスできます。
(TBR)

=head2 C<mother_re>

=begin original

TODO, see L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>

=end original

TODOについては、L<http://www.mail-archive.com/perl5-changes@perl.org/msg17328.html>を参照してください。
(TBR)

=head2 C<extflags>

=begin original

This will be used by perl to see what flags the regexp was compiled
with, this will normally be set to the value of the flags parameter by
the L<comp|/comp> callback. See the L<comp|/comp> documentation for
valid flags.

=end original

これは、perlがregexpがコンパイルされたフラグを確認するために使用します。
これは通常、L<comp|/comp>コールバックによってflagsパラメータの値に設定されます。
有効なフラグについては、L<comp|/comp>のドキュメントを参照してください。
(TBR)

=head2 C<minlen> C<minlenret>

=begin original

The minimum string length required for the pattern to match.  This is used to
prune the search space by not bothering to match any closer to the end of a
string than would allow a match. For instance there is no point in even
starting the regex engine if the minlen is 10 but the string is only 5
characters long. There is no way that the pattern can match.

=end original

パターンが一致するために必要な文字列の最小長。
これは、一致が可能な文字列よりも文字列の最後に近い文字列を一致させないようにすることで、サーチスペースを削減するために使用されます。
例えば、minlenが10で文字列が5文字しかない場合、regexエンジンを起動しても意味がありません。
パターンが一致する方法はありません。
(TBR)

=begin original

C<minlenret> is the minimum length of the string that would be found
in $& after a match.

=end original

C<minlenret>は、$&の中でマッチ後に見つかる文字列の最小長です。
(TBR)

=begin original

The difference between C<minlen> and C<minlenret> can be seen in the
following pattern:

=end original

C<minlen>とC<minlenret>の違いは、次のパターンで確認できます。
(TBR)

    /ns(?=\d)/

=begin original

where the C<minlen> would be 3 but C<minlenret> would only be 2 as the \d is
required to match but is not actually included in the matched content. This
distinction is particularly important as the substitution logic uses the
C<minlenret> to tell whether it can do in-place substitution which can result in
considerable speedup.

=end original

この場合、C<minlen>は3になりますが、C<minlenret>は2になります。
これは、\dは一致する必要がありますが、一致したコンテンツに実際には含まれていないためです。
この区別は特に重要です。
置換ロジックでは、C<minlenret>を使用して、大幅な高速化が可能なin-place置換が可能かどうかを判断します。
(TBR)

=head2 C<gofs>

=begin original

Left offset from pos() to start match at.

=end original

pos()からマッチを開始するまでの左オフセット。
(TBR)

=head2 C<substrs>

=begin original

Substring data about strings that must appear in the final match. This
is currently only used internally by perl's engine for but might be
used in the future for all engines for optimisations.

=end original

最終マッチで出現しなければならない文字列に関する部分文字列データ。
これは現在、perlのエンジン内部でのみ使用されていますが、将来的には最適化のためにすべてのエンジンで使用される可能性があります。
(TBR)

=head2 C<nparens>, C<lasparen>, and C<lastcloseparen>

=begin original

These fields are used to keep track of how many paren groups could be matched
in the pattern, which was the last open paren to be entered, and which was
the last close paren to be entered.

=end original

これらのフィールドは、パターン内でマッチさせることができる括弧グループの数、入力されるべき最後のオープン括弧と入力されるべき最後のクローズ括弧を追跡するために使用されます。
(TBR)

=head2 C<intflags>

=begin original

The engine's private copy of the flags the pattern was compiled with. Usually
this is the same as C<extflags> unless the engine chose to modify one of them.

=end original

パターンがコンパイルされたフラグのエンジンのプライベートコピーです。
通常、エンジンがフラグのいずれかを変更しない限り、これはC<extflags>と同じです。
(TBR)

=head2 C<pprivate>

=begin original

A void* pointing to an engine-defined data structure. The perl engine uses the
C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
engine should use something else.

=end original

エンジン定義のデータ構造体を指すvoid*です。
perlエンジンはC<regexp_internal>構造体(L<perlreguts/Base Structures>を参照)を使用しますが、カスタムエンジンは他の構造体を使用する必要があります。
(TBR)

=head2 C<swap>

=begin original

TODO: document

=end original

TODO:ドキュメント
(TBR)

=head2 C<offs>

=begin original

A C<regexp_paren_pair> structure which defines offsets into the string being
matched which correspond to the C<$&> and C<$1>, C<$2> etc. captures, the
C<regexp_paren_pair> struct is defined as follows:

=end original

C<regexp_paren_pair>構造体は、C<$&>とC<$1>、C<$2>などのキャプチャに対応する、マッチングされる文字列へのオフセットを定義します。
C<regexp_paren_pair>構造体は以下のように定義されます。
(TBR)

    typedef struct regexp_paren_pair {
        I32 start;
        I32 end;
    } regexp_paren_pair;

=begin original

If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
capture buffer did not match. C<< ->offs[0].start/end >> represents C<$&> (or
C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
C<$paren >= 1>.

=end original

C<< ->offs[num].start>>またはC<< ->offs[num].end>>がC<-1>の場合、そのキャプチャバッファは一致しませんでした。
C<< ->offs[0].start/end>>はC<$&>(またはC<//p>の下のC<${^MATCH>)を表し、C<< ->offs[paren].end>>はC<$$paren>(ここでC<$paren >=1>)と一致します。
(TBR)

=head2 C<precomp> C<prelen>

=begin original

Used for optimisations. C<precomp> holds a copy of the pattern that
was compiled and C<prelen> its length. When a new pattern is to be
compiled (such as inside a loop) the internal C<regcomp> operator
checks whether the last compiled C<REGEXP>'s C<precomp> and C<prelen>
are equivalent to the new one, and if so uses the old pattern instead
of compiling a new one.

=end original

最適化に使用されます。
C<precomp>はコンパイルされたパターンのコピーを保持し、C<prelen>はその長さを保持します。
新しいパターンがコンパイルされる場合(ループ内など)、内部C<regcomp>演算子は最後にコンパイルされたC<REGEXP>のC<precomp>とC<prelen>が新しいパターンと等価であるかどうかをチェックし、等価である場合は新しいパターンをコンパイルする代わりに古いパターンを使用します。
(TBR)

=begin original

The relevant snippet from C<Perl_pp_regcomp>:

=end original

C<Perl_pp_regcomp>の関連スニペットは次のとおりです。
(TBR)

	if (!re || !re->precomp || re->prelen != (I32)len ||
	    memNE(re->precomp, t, len))
        /* Compile a new pattern */

=head2 C<paren_names>

=begin original

This is a hash used internally to track named capture buffers and their
offsets. The keys are the names of the buffers the values are dualvars,
with the IV slot holding the number of buffers with the given name and the
pv being an embedded array of I32.  The values may also be contained
independently in the data array in cases where named backreferences are
used.

=end original

これは、名前付き取得バッファとそのオフセットを追跡するために内部的に使用されるハッシュです。
キーはバッファの名前で、値はdualvarsです。
IVスロットは指定された名前を持つバッファの数を保持し、pvはI32の埋め込み配列です。
名前付き後方参照が使用されている場合は、値がデータ配列に独立して含まれることもあります。
(TBR)

=head2 C<substrs>

=begin original

Holds information on the longest string that must occur at a fixed
offset from the start of the pattern, and the longest string that must
occur at a floating offset from the start of the pattern. Used to do
Fast-Boyer-Moore searches on the string to find out if its worth using
the regex engine at all, and if so where in the string to search.

=end original

パターンの先頭から固定オフセットで発生する必要がある最長文字列、およびパターンの先頭から浮動オフセットで発生する必要がある最長文字列に関する情報を保持します。
Fast-Boyer-Moore検索を実行して、regexエンジンを使用する価値があるかどうか、ある場合は文字列のどこを検索するかを調べるために使用します。
(TBR)

=head2 C<subbeg> C<sublen> C<saved_copy>

=begin original

Used during execution phase for managing search and replace patterns.

=end original

実施段階中に検索および置換パターンを管理するために使用されます。
(TBR)

=head2 C<wrapped> C<wraplen>

=begin original

Stores the string C<qr//> stringifies to. The perl engine for example
stores C<(?-xism:eek)> in the case of C<qr/eek/>.

=end original

文字列C<qr//>stringifiesを格納します。
たとえばPerlエンジンは、C<qr/eek/>の場合にC<(?-xism:eek)>を格納します。
(TBR)

=begin original

When using a custom engine that doesn't support the C<(?:)> construct
for inline modifiers, it's probably best to have C<qr//> stringify to
the supplied pattern, note that this will create undesired patterns in
cases such as:

=end original

インライン修飾子のC<(?:)>構造体をサポートしていないカスタムエンジンを使用する場合は、おそらくC<qr//>を提供されたパターンに紐付けするのが最善です。
これは、次のような場合に望ましくないパターンを作成することに注意してください。
(TBR)

    my $x = qr/a|b/;  # "a|b"
    my $y = qr/c/i;   # "c"
    my $z = qr/$x$y/; # "a|bc"

=begin original

There's no solution for this problem other than making the custom
engine understand a construct like C<(?:)>.

=end original

カスタム・エンジンにC<(?:)>のような構造体を理解させる以外に、この問題に対する解決策はありません。
(TBR)

=head2 C<seen_evals>

=begin original

This stores the number of eval groups in the pattern. This is used for security
purposes when embedding compiled regexes into larger patterns with C<qr//>.

=end original

パターン内の評価グループの数を格納します。
これは、コンパイルされた正規表現をC<qr//>を使用してより大きなパターンに埋め込む際のセキュリティ目的で使用されます。
(TBR)

=head2 C<refcnt>

=begin original

The number of times the structure is referenced. When this falls to 0 the
regexp is automatically freed by a call to pregfree. This should be set to 1 in
each engine's L</comp> routine.

=end original

構造体が参照される回数です。
これが0になると、regexpはpregfreeへの呼び出しによって自動的に解放されます。
これは各エンジンのL</comp>ルーチンで1に設定する必要があります。
(TBR)

=head1 HISTORY

=begin original

Originally part of L<perlreguts>.

=end original

元は L<perlreguts> の一部です。

=head1 AUTHORS

=begin original

Originally written by Yves Orton, expanded by E<AElig>var ArnfjE<ouml>rE<eth>
Bjarmason.

=end original

元は Yves Orton によって書かれ E<AElig>var ArnfjE<ouml>rE<eth>
Bjarmason によって拡張されました。

=head1 LICENSE

Copyright 2006 Yves Orton and 2007 E<AElig>var ArnfjE<ouml>rE<eth> Bjarmason.

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

=cut

=begin meta

Translate: SHIRAKATA Kentaro <argrath@ub32.org> (5.10.1)
Status: in progress

=end meta