re-0.09 > re
re-0.09
Other versions:
re-0.08

名前

re - Perl pragma to alter regular expression behaviour

re - 正規表現の振る舞いを変えるための Perl プラグマ

概要

    use re 'taint';
    ($x) = ($^X =~ /^(.*)$/s);     # $x is tainted here
    use re 'taint';
    ($x) = ($^X =~ /^(.*)$/s);     # $x はここで汚染されている
    $pat = '(?{ $foo = 1 })';
    use re 'eval';
    /foo${pat}bar/;                # won't fail (when not under -T switch)
    $pat = '(?{ $foo = 1 })';
    use re 'eval';
    /foo${pat}bar/;                # 失敗しない (-T スイッチがないとき)
    {
        no re 'taint';             # the default
        ($x) = ($^X =~ /^(.*)$/s); # $x is not tainted here
    {
        no re 'taint';             # デフォルト
        ($x) = ($^X =~ /^(.*)$/s); # $x はここで汚染されていない
        no re 'eval';              # the default
        /foo${pat}bar/;            # disallowed (with or without -T switch)
    }
        no re 'eval';              # デフォルト
        /foo${pat}bar/;            # 許されない (-T スイッチの有無に関係なく)
    }
    use re 'debug';                # output debugging info during
    /^(.*)$/s;                     #     compile and run time
    use re 'debug';                # コンパイル時と実行時に
    /^(.*)$/s;                     #     デバッグ情報を出力する
    use re 'debugcolor';           # same as 'debug', but with colored output
    ...
    use re 'debugcolor';           # 'debug' と同じだが、出力に色がつく
    ...
    use re qw(Debug All);          # Finer tuned debugging options.
    use re qw(Debug More);
    no re qw(Debug ALL);           # Turn of all re debugging in this scope
    use re qw(Debug All);          # より細かいデバッグオプション
    use re qw(Debug More);
    no re qw(Debug ALL);           # このスコープ内で全ての re デバッグを有効化

    use re qw(is_regexp regexp_pattern); # import utility functions
    my ($pat,$mods)=regexp_pattern(qr/foo/i);
    if (is_regexp($obj)) { 
        print "Got regexp: ",
            scalar regexp_pattern($obj); # just as perl would stringify it
    }                                    # but no hassle with blessed re's.

(We use $^X in these examples because it's tainted by default.)

(これらの例では、デフォルトで汚染されているので $^X を使っています。)

説明

'taint' モード

When use re 'taint' is in effect, and a tainted string is the target of a regex, the regex memories (or values returned by the m// operator in list context) are tainted. This feature is useful when regex operations on tainted data aren't meant to extract safe substrings, but to perform other transformations.

use re 'taint' が有効で、汚染された文字列が正規表現の ターゲットであるとき、正規表現のメモリ(もしくはリストコンテキストで m// 演算子が返す値)は汚染されます。 この機能は汚染されたデータに対する正規表現演算が安全な部分文字列を 取り出すものでないときに便利ですが、その他の変換は働きます。

'eval' モード

When use re 'eval' is in effect, a regex is allowed to contain (?{ ... }) zero-width assertions even if regular expression contains variable interpolation. That is normally disallowed, since it is a potential security risk. Note that this pragma is ignored when the regular expression is obtained from tainted data, i.e. evaluation is always disallowed with tainted regular expressions. See "(?{ code })" in perlre.

use re 'eval' が有効なとき、変数展開を含む正規表現でも ゼロ幅表明 (?{ ... }) を持つことができます。 これは通常はセキュリティ上のリスクとなる可能性があるので許されていません。 このプラグマは正規表現が汚染されたデータからきたものである場合には 無視されることに注意してください。 つまり、汚染された正規表現を評価することは常に許されません。 "(?{ code })" in perlre を参照してください。

For the purpose of this pragma, interpolation of precompiled regular expressions (i.e., the result of qr//) is not considered variable interpolation. Thus:

このプラグマの目的のため、プリコンパイルされた正規表現 (つまり、qr// の結果)の展開(interpolation)は変数展開とは みなされません。 したがって:

    /foo${pat}bar/

is allowed if $pat is a precompiled regular expression, even if $pat contains (?{ ... }) assertions.

は、$pat がプリコンパイルされた正規表現であれば、たとえ $pat が (?{ ... }) 表明を含んでいたとしても 許されます

'debug' モード

When use re 'debug' is in effect, perl emits debugging messages when compiling and using regular expressions. The output is the same as that obtained by running a -DDEBUGGING-enabled perl interpreter with the -Dr switch. It may be quite voluminous depending on the complexity of the match. Using debugcolor instead of debug enables a form of output that can be used to get a colorful display on terminals that understand termcap color sequences. Set $ENV{PERL_RE_TC} to a comma-separated list of termcap properties to use for highlighting strings on/off, pre-point part on/off. See "Debugging regular expressions" in perldebug for additional info.

use re 'debug' が有効なとき、perl は正規表現をコンパイルするときと 使うときにデバッグ用メッセージを出力します。 その出力は -DDEBUGGING が有効になっている perl インタプリタに -Dr スイッチを与えたときと同じです。 これはマッチの複雑さに応じて非常に多弁になる可能性があります。 debug の代わりに debugcolor を使うと、termcap カラーシーケンスを 使ったカラフルな出力を端末に行います。 termcap プロパティのカンマ区切りのリストを $ENV{PERL_RE_TC} に セットすることで、文字列のオン/オフや pre-point 部分のオン/オフを ハイライトできます。 更なる情報については "Debugging regular expressions" in perldebug を参照してください。

As of 5.9.5 the directive use re 'debug' and its equivalents are lexically scoped, as the other directives are. However they have both compile-time and run-time effects.

5.9.5 現在、 use re 'debug' 指示子およびそれと等価な設定は、他の指示子と同様 レキシカルスコープです。 しかしこれらはコンパイル時と実行時の両方に影響を及ぼします。

"Pragmatic Modules" in perlmodlib を参照してください。

'Debug' モード

Similarly use re 'Debug' produces debugging output, the difference being that it allows the fine tuning of what debugging output will be emitted. Options are divided into three groups, those related to compilation, those related to execution and those related to special purposes. The options are as follows:

use re 'Debug' と同様にデバッグ出力を生成しますが、 どのデバッグ情報が出力されるかを細かく制御できることが違います。 操作は、コンパイル関係、実行関係、特殊用途関係の 3 つのグループに 分割されます。 オプションは以下の通りです:

Compile related options

(コンパイル関係オプション)

COMPILE

Turns on all compile related debug options.

コンパイル関係のオプションを全て有効にします。

PARSE

Turns on debug output related to the process of parsing the pattern.

パターンのパース処理に関係するデバッグ出力を有効にします。

OPTIMISE

Enables output related to the optimisation phase of compilation.

コンパイルの最適化フェーズに関係するデバッグ出力を有効にします。

TRIEC

Detailed info about trie compilation.

トライ木のコンパイルに関する詳細情報。

DUMP

Dump the final program out after it is compiled and optimised.

コンパイルと最適化の後の最終的なプログラムの出力をダンプします。

Execute related options

(実行関係オプション)

EXECUTE

Turns on all execute related debug options.

実行関係のデバッグオプションを全て有効にします。

MATCH

Turns on debugging of the main matching loop.

メインマッチングループのデバッグを有効にします。

TRIEE

Extra debugging of how tries execute.

トライ木をどのように実行するかに関する追加のデバッグ。

INTUIT

Enable debugging of start point optimisations.

開始点最適化のデバッグを有効にします。

Extra debugging options

(追加デバッグオプション)

EXTRA

Turns on all "extra" debugging options.

「追加の」デバッグオプションを全て有効にします。

BUFFERS

Enable debugging the capture buffer storage during match. Warning, this can potentially produce extremely large output.

マッチング中の捕捉バッファのデバッグを有効にします。 これは極めて大きい出力を生成する可能性があることを警告しておきます。

TRIEM

Enable enhanced TRIE debugging. Enhances both TRIEE and TRIEC.

拡張された TRIE デバッグを有効にします。 TRIEE と TRIEC の両方を拡張します。

STATE

Enable debugging of states in the engine.

エンジンの状態のデバッグを有効にします。

STACK

Enable debugging of the recursion stack in the engine. Enabling or disabling this option automatically does the same for debugging states as well. This output from this can be quite large.

エンジンの再帰スタックのデバッグを有効にします。 このオプションを有効または無効にすると、デバッグ状態も同様に 同じ状態になります。 この出力はかなり大きくなることがあります。

OPTIMISEM

Enable enhanced optimisation debugging and start point optimisations. Probably not useful except when debugging the regex engine itself.

拡張最適化デバッグと開始位置最適化を有効にします。 正規表現自身をデバッグするのでなければ、おそらく有用ではありません。

OFFSETS

Dump offset information. This can be used to see how regops correlate to the pattern. Output format is

オフセット情報をダンプします。 これは、どのように regops がパターンと関連するかを見るために使えます。 出力フォーマットは

   NODENUM:POSITION[LENGTH]

Where 1 is the position of the first char in the string. Note that position can be 0, or larger than the actual length of the pattern, likewise length can be zero.

文字列の最初の文字の位置は 1 です。 位置が 0 であったり、パターンの実際の長さより大きかったり、 長さが 0 であったりするかもしれないことに注意してください。

OFFSETSDBG

Enable debugging of offsets information. This emits copious amounts of trace information and doesn't mesh well with other debug options.

オフセット情報のデバッグを有効にします。 これは大量のトレース情報を出力し、他のデバッグオプションとはうまく かみ合いません。

Almost definitely only useful to people hacking on the offsets part of the debug engine.

ほぼ確実に、デバッグエンジンのオフセット部分をハックする人々によってのみ 有用です。

Other useful flags

(その他の便利なフラグ)

These are useful shortcuts to save on the typing.

タイプ数を節約するための便利な短縮記法があります。

ALL

Enable all options at once except OFFSETS, OFFSETSDBG and BUFFERS

OFFSETS, OFFSETSDBG, BUFFERS 以外の全てのオプションを有効にします。

All

Enable DUMP and all execute options. Equivalent to:

DUMP と、全ての実行関係のオプションを有効にします。 以下と等価です:

  use re 'debug';
MORE
More

Enable TRIEM and all execute compile and execute options.

TRIEM と、全てのコンパイル関係および実行関係のオプションを有効にします。

As of 5.9.5 the directive use re 'debug' and its equivalents are lexically scoped, as the other directives are. However they have both compile-time and run-time effects.

5.9.5 以降、use re 'debug' 指示子およびその等価物は、その他の指示子と同様 レキシカルスコープを持ちます。 しかし、これらはコンパイル時と実行時の両方で効果があります。

エクスポート可能な関数

As of perl 5.9.5 're' debug contains a number of utility functions that may be optionally exported into the caller's namespace. They are listed below.

perl 5.9.5 以降、're' debug には、呼び出し元の名前空間にエクスポートできる、 いくつかの便利関数を含んでいます。 以下に一覧を示します。

is_regexp($ref)

Returns true if the argument is a compiled regular expression as returned by qr//, false if it is not.

引数が、qr// から返された、コンパイル済み正規表現の場合は真を、 さもなければ偽を返します。

This function will not be confused by overloading or blessing. In internals terms, this extracts the regexp pointer out of the PERL_MAGIC_qr structure so it it cannot be fooled.

この関数はオーバーロードや bless によって混乱しません。 内部用語で言うと、PERL_MAGIC_qr 構造体から正規表現ポインタを 取り出しているので、だまされることはありません。

regexp_pattern($ref)

If the argument is a compiled regular expression as returned by qr//, then this function returns the pattern.

引数が、qr// から返された、コンパイル済み正規表現の場合、 この関数はパターンを返します。

In list context it returns a two element list, the first element containing the pattern and the second containing the modifiers used when the pattern was compiled.

リストコンテキストでは 2 要素のリストを返し、1 番目の要素はパターン、 2 番目はパターンがコンパイルされたときに使われた修飾子です。

  my ($pat, $mods) = regexp_pattern($ref);

In scalar context it returns the same as perl would when strigifying a raw qr// with the same pattern inside. If the argument is not a compiled reference then this routine returns false but defined in scalar context, and the empty list in list context. Thus the following

スカラコンテキストでは、生の qr// の中に書くことで perl が 文字列化したときに同じ内容になるものを返します。 引数がコンパイルされたリファレンスではない場合、スカラコンテキストでは 「偽だが定義済み」を返し、リストコンテキストでは空リストを返します。 従って、以下の文

    if (regexp_pattern($ref) eq '(?i-xsm:foo)')

will be warning free regardless of what $ref actually is.

は、実際の $ref が何であっても警告は出ません。

Like is_regexp this function will not be confused by overloading or blessing of the object.

is_regexp と同様、この関数はオブジェクトのオーバーロードや bless によって 混乱しません。

regmust($ref)

If the argument is a compiled regular expression as returned by qr//, then this function returns what the optimiser consiers to be the longest anchored fixed string and longest floating fixed string in the pattern.

引数が qr// で返されたコンパイル済み正規表現の場合、この関数は、 パターンの中でオプティマイザが最長の不動不変文字列および最長の 浮遊不変文字列と考えたものを返します。

A fixed string is defined as being a substring that must appear for the pattern to match. An anchored fixed string is a fixed string that must appear at a particular offset from the beginning of the match. A floating fixed string is defined as a fixed string that can appear at any point in a range of positions relative to the start of the match. For example,

不変文字列 (fixed string) とは、マッチングするパターンとして 現れなければならない部分文字列として定義されます。 不動不変文字列 (anchored fixed string) とは、マッチングの開始からの 特定の位置に現れなければならない不変文字列です。 浮遊不変文字列 (floating fixed string) とは、マッチングの開始からの 相対位置の範囲でどの位置に現れてもよい不変文字列として定義されます。 例えば、

    my $qr = qr/here .* there/x;
    my ($anchored, $floating) = regmust($qr);
    print "anchored:'$anchored'\nfloating:'$floating'\n";

results in

これの結果は

    anchored:'here'
    floating:'there'

Because the here is before the .* in the pattern, its position can be determined exactly. That's not true, however, for the there; it could appear at any point after where the anchored string appeared. Perl uses both for its optimisations, prefering the longer, or, if they are equal, the floating.

パターンの中で here.* の前にあるので、この位置は正確に 決定されます。 しかし、このことは there には当てはまりません; これは不動不変文字列の後ならどの地点にでも現れる可能性があります。 Perl は最適化のためにこれらの両方を、長い方(同じ場合は浮遊)を優先して 使います。

NOTE: This may not necessarily be the definitive longest anchored and floating string. This will be what the optimiser of the Perl that you are using thinks is the longest. If you believe that the result is wrong please report it via the perlbug utility.

注意: これは最終的な最長の不動及び浮遊文字列とは限りません。 これは Perl のオプティマイザが最長と考えたものです。 もし結果が間違っていると信じるなら、perlbug ユーティリティ経由で 報告を送ってください。

regname($name,$all)

Returns the contents of a named buffer of the last successful match. If $all is true, then returns an array ref containing one entry per buffer, otherwise returns the first defined buffer.

最後に成功したマッチングの名前付きバッファの内容を返します。 $all が真なら、バッファごとに一つの要素となる配列リファレンスを返します; さもなければ最初に定義されたバッファを返します。

regnames($all)

Returns a list of all of the named buffers defined in the last successful match. If $all is true, then it returns all names defined, if not it returns only names which were involved in the match.

最後に成功したマッチングで定義された全ての名前付きバッファのリストを 返します。 $all が真なら、定義された全ての名前を返します; さもなければマッチングに関わった名前のみを返します。

regnames_count()

Returns the number of distinct names defined in the pattern used for the last successful match.

最後に成功したマッチングで使われたパターンで定義された、異なる名前の数を 返します。

Note: this result is always the actual number of distinct named buffers defined, it may not actually match that which is returned by regnames() and related routines when those routines have not been called with the $all parameter set.

注意: この結果は常に、定義された異なる名前付きバッファの実際の数となり、 regnames() や関連するルーチンが $all 引数をセットせずに呼び出された 場合に返したものと一致しないことがあります。

SEE ALSO

"Pragmatic Modules" in perlmodlib.