NAME

App::Greple::tee - マッチしたテキストを外部コマンドの結果で置き換えるモジュール

SYNOPSIS

greple -Mtee command -- ...
greple -Mtee -E PAT1 command1 -- -Mtee -E PAT2 command2 -- ...

VERSION

Version 2.00_00

DESCRIPTION

Greple の -Mtee モジュールは、マッチしたテキスト部分を指定したフィルタコマンドに送り、そのコマンドの結果で置き換えます。アイデアは teip と呼ばれるコマンドに由来します。データの一部を外部フィルタコマンドにバイパスするようなイメージです。

フィルタコマンドはモジュール宣言(-Mtee)に続けて記述し、二つのダッシュ(--)で終端します。例えば、次のコマンドはデータ中のマッチした単語に対して、コマンド tr を a-z A-Z の引数で呼び出します。

greple -Mtee tr a-z A-Z -- '\w+' ...

上記のコマンドは、マッチした単語をすべて小文字から大文字に変換します。実はこの例自体はあまり有用ではありません。というのも、greple 自身が --cm オプションで同様のことをより効率的に行えるからです。

デフォルトでは、コマンドは単一プロセスとして実行され、すべてのマッチしたデータは混在したままそのプロセスに送られます。マッチしたテキストが改行で終わっていなければ、送信前に改行が追加され、受信後に取り除かれます。入力と出力のデータは行単位で対応付けられるため、入力と出力の行数は一致していなければなりません。

--discrete オプションを使うと、マッチした各テキスト領域ごとに個別のコマンドが呼び出されます。違いは次のコマンド群で確認できます。

greple -Mtee cat -n -- copyright LICENSE
greple -Mtee cat -n -- copyright LICENSE --discrete

--discrete オプションを用いる場合、入力と出力の行数は一致している必要はありません。

OPTIONS

--discrete

マッチした各部分ごとに新しいコマンドを個別に起動します。

--bulkmode

<--discrete> オプションでは各コマンドはオンデマンドで実行されます。<--bulkmode> オプションではすべての変換を一括で実行します。

このオプションは、"MULTIPLE FILTERS" の新形式では効果がありません。新形式ではフィルターは常にすべてのマッチに対して一度に実行されます。

--crmode

このオプションは、各ブロックの途中にあるすべての改行文字をキャリッジリターンに置き換えます。コマンド実行結果に含まれるキャリッジリターンは改めて改行に戻されます。これにより、--discrete オプションを使わずとも、複数行から成るブロックをバッチ処理できます。

これは ansifold コマンドの --crmode オプションと相性がよく、CR 区切りのテキストを結合し、CR で区切られた折り畳み行を出力します。

--fillup

フィルタコマンドに渡す前に、連続する非空行を1行にまとめます。全角文字(日本語、中国語)の間の改行は削除し、その他の改行は空白に置き換えます。韓国語(ハングル)は ASCII テキスト同様に空白で連結します。

--squeeze

連続する2つ以上の改行を1つにまとめます。

-ML --offload command

teip(1) の --offload オプションは、別モジュール App::Greple::L(-ML)で実装されています。

greple -Mtee cat -n -- -ML --offload 'seq 10 20'

-ML モジュールを使って、次のように偶数行のみを処理することもできます。

greple -Mtee cat -n -- -ML 2::2

MULTIPLE FILTERS

内部にパターンを含む -Mtee を繰り返すと、パターンの各組に異なるフィルタが適用されます。

-Mtee [ OPTIONS ] [ COMMAND [ ARGS ... ] ] --

最初の非オプション引数より前はすべてモジュールのオプションであり、残りの -- までがコマンドです。たとえば次のコマンドは、PAT1 または PAT2 に一致する行を ansifold で折り返し、PAT3 に一致する行を ansicolumn で列に整形します。

greple -Mtee --crmode -E PAT1 -E PAT2 '&ansifold' --crmode -w80 -- \
       -Mtee --discrete -E PAT3 '&ansicolumn' -t -- \
       file

形式は2つあります。

Legacy form

-Mtee 内にパターンがない場合、従来どおり -- に続くすべてのパターンにコマンドが適用されます。2回指定した場合は、最後のものが有効です。

New form

-Mtee 内にパターンがある場合、コマンドはその -Mtee 内のパターンにのみ適用されます。

2つの形式を混在させるとエラーになります。-Mtee::config(...) -Mtee ... の前半のように、-- まで引数のない -Mtee は設定のみを行い、どちらの形式にも数えられません。

エラーは、出力が行われる前の最初のファイルの検索時に検出されます。

Options inside -Mtee

--discrete, --bulkmode, --crmode, --fillup, --squeeze, --nofork

フィルタのモードです。--no-crmode のように、--no- 形式で否定できます。

-E, --re

正規表現パターン。

-e

パターン。空白を含んでいても1つのパターンです。

--fe

固定文字列パターン。

--le

単一のキーワード、または &function。空白で区切った複数のキーワードを指定するとエラーになります。

--cm

そのまま greple に渡されます。色はパターンに結び付けられるのではなく、指定された順にパターン番号へ循環的に割り当てられます("LIMITATIONS" を参照)。

--config

Getopt::EX::Config の機能です。すべてのフィルタに共通する設定を変更します。

--exclude などのほかのオプションはエラーです。-- の後に記述してください。これらはすべてのフィルタに適用されます。

Priority of modes

モードの値は、実行時に次の順序で決定されます。

  1. -Mtee 内で指定したもの(--crmode、--no-crmode)。

  2. -- の後、または -Mtee::config(...) で指定したもの。

Special cases

  • 新形式では、いずれか1つのパターンを含むブロックが処理されるように(OR)、--need=1 が自動的に追加されます。これを上書きするには -- の後で --need を指定します。--need=2 を指定すると AND に戻ります。旧形式は従来どおり(AND)動作します。-Mtee および -Mtee を含むエイリアスオプションのそれぞれが再び --need=1 を追加するため、--need はすべてのそれらの後に置いてください。

  • コマンドを省略した場合(-Mtee -E PAT --)、パターンはテキストを選択しますが、テキストは変更されません。

  • 新形式では、-Mtee の外にあるパターンはエラーです。-Mtee の外にある --callback も同様です。

  • 新形式では、オプションなしで -- の後に指定したパターンは、オプションでパターンが指定されているためパターンとして扱われません。greple はそれをファイル名として扱います。

  • 異なるフィルタの一致箇所が重なった場合、greple はそれらを1つの領域に結合し、先に開始する一致のフィルタを適用します。

LIMITATIONS

  • コマンドラインで -Mtee 内に直接記述した {DEFINE} は展開されません。option 定義内では展開されます。

  • -M は引数の先頭になければならないため、-Mtee モジュールの間にほかのオプションを記述することはできません。これらはエイリアスオプションを介して組み合わせられます。

  • 従来どおり、-- をコマンド引数に含めることはできません。

  • --cm はフィルタごとに独立していません。一部のパターンにだけ指定すると、他の -Mtee 内のものを含む他のパターンの色が、greple の循環割り当てによって変化します。色を指定する際は、すべてのパターンに --cm を指定してください。

  • 別のモジュールが -Mtee に続く場合(-Mtee -E PAT cmd -- -Mcolors)、パターンはモジュールの default オプションを介して greple に渡され、$ENV{NAME} や __PACKAGE__ などのオプション定義の展開がそれらに適用されます。これらをエスケープする処理は行われません。

  • default オプションに新形式の -Mtee を含むモジュールが、-Mfoo -Mtee -E PAT cmd -- -Mcolors のように、別のモジュールが続く -Mtee より前に読み込まれると、パターンが失われ、エラー(「passed twice or lost」)として検出されます。モジュールは -Mtee の後に読み込んでください。

CONFIGURATION

モジュールのパラメータは、次の文法で Getopt::EX::Config モジュールにより設定できます。

greple -Mtee::config(discrete) ...
greple -Mtee::config(fillup,crmode) ...

これはシェルのエイリアスやモジュールファイルと組み合わせると便利です。

利用可能なパラメータは次のとおりです: discrete、bulkmode、crmode、fillup、squeeze、nofork。

FUNCTION CALL

外部コマンドの代わりに、コマンド名の前に&を付けることでPerl関数を呼び出せます。

greple -Mtee '&App::ansifold::ansifold' -w40 -- ...

関数はフォークされた子プロセスで実行されるため、次の要件に従う必要があります:

  • 一致したテキストをSTDINから読み込む

  • 変換結果をSTDOUTへ出力する

  • 引数は@ARGVおよび@_の両方で渡される

任意の完全修飾関数名を使用できます:

greple -Mtee '&Your::Module::function' -- ...

モジュールは未ロードの場合、自動的にロードされます。

便宜のため、以下の短いエイリアスが利用可能です:

&ansicolumn

App::ansicolumn::ansicolumnを呼び出します。

&ansifold

App::ansifold::ansifoldを呼び出します。

&cat-v

App::cat::v->new->run(@_)を呼び出します。

関数呼び出しを使用すると、呼び出しごとに外部プロセスをフォークするオーバーヘッドを回避でき、--discreteオプションと併用した場合にパフォーマンスを大幅に向上させることができます。

LEGACIES

--blocks オプションは削除されました。greple に --stretch(-S)オプションが実装されたため、もはや不要です。代わりに次を使用してください。

greple -Mtee cat -n -- --all -SE foo

WHY DO NOT USE TEIP

まず何より、teip コマンドで実現できる場合はそれを使ってください。優れたツールであり、greple よりもはるかに高速です。

greple は文書ファイルの処理を目的に設計されているため、マッチ領域の制御など、それに適した多くの機能を備えています。それらの機能を活用するために greple を使う価値はあります。

また、teip は複数行のデータをひとつの単位として扱えませんが、greple は複数行からなるデータチャンクに対して個別のコマンドを実行できます。

EXAMPLE

次のコマンドは、Perl モジュールファイルに含まれる perlpod(1) 形式ドキュメント内のテキストブロックを見つけます。

greple --inside '^=(?s:.*?)(^=cut|\z)' --re '^([\w\pP].+\n)+' tee.pm

上記コマンドに -Mtee モジュールを組み合わせて deepl コマンドを呼び出すことで、DeepL サービスで翻訳できます。使い方は次のとおりです:

greple -Mtee deepl text --to JA - -- --fillup ...

ただし、この目的には専用モジュール App::Greple::xlate::deepl のほうが効果的です。実際、tee モジュールの実装のヒントは xlate モジュールから得られました。

EXAMPLE 2

次のコマンドは、LICENSE ドキュメント内のいくつかのインデントされた部分を見つけます。

greple --re '^[ ]{2}[a-z][)] .+\n([ ]{5}.+\n)*' -C LICENSE

  a) distribute a Standard Version of the executables and library files,
     together with instructions (in the manual page or equivalent) on where to
     get the Standard Version.

  b) accompany the distribution with the machine-readable source of the Package
     with your modifications.

この部分は、tee モジュールと ansifold コマンドを使って再整形できます。両方の --crmode オプションを併用すると、複数行ブロックを効率よく処理できます:

greple -Mtee ansifold -sw40 --prefix '     ' --crmode -- --crmode --re ...

  a) distribute a Standard Version of
     the executables and library files,
     together with instructions (in the
     manual page or equivalent) on where
     to get the Standard Version.

  b) accompany the distribution with the
     machine-readable source of the
     Package with your modifications.

--discrete オプションも使用できますが、複数のプロセスを起動するため、実行に時間がかかります。

EXAMPLE 3

ヘッダー行以外から文字列を grep したい状況を考えてみます。例えば、docker image ls コマンドから Docker イメージ名を検索したいが、ヘッダー行は残したい場合です。以下のコマンドで実現できます。

greple -Mtee grep perl -- -ML 2: --discrete --all

オプション -ML 2: は、後ろから2行目以降を取り出して grep perl コマンドに送ります。入力と出力の行数が変わるため --discrete オプションが必要ですが、コマンドは一度しか実行されないので性能上のデメリットはありません。

同じことを teip コマンドでやろうとすると、teip -l 2- -- grep は出力行数が入力行数より少ないためエラーになります。ただし、得られる結果自体に問題はありません。

INSTALL

CPANMINUS

$ cpanm App::Greple::tee

SEE ALSO

App::Greple::tee, https://github.com/kaz-utashiro/App-Greple-tee

https://github.com/greymd/teip

App::Greple, https://github.com/kaz-utashiro/greple

https://github.com/tecolicom/Greple

App::Greple::xlate

App::ansifold, https://github.com/tecolicom/App-ansifold

AUTHOR

Kazumasa Utashiro

LICENSE

Copyright © 2023-2026 Kazumasa Utashiro.

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