FilterChains and FilterReaders

フィルターチェーンとフィルターリーダー

Look at Unix pipes - they offer you so much flexibility - say you wanted to copy just those lines that contained the string blee from the first 10 lines of a file 'foo' to a file 'bar' - you would do something like

Unix のパイプを見て、とても高い柔軟性を提供しているので、 ファイル 'foo' の最初の 10 行より文字列 blee の入っている行のみをファイル 'bar' にコピーしたいとしましょう。 - すると、次のようにするでしょう。

cat foo|head -n10|grep blee > bar

Ant was not flexible enough. There was no way for the <copy> task to do something similar. If you wanted the <copy> task to get the first 10 lines, you would have had to create special attributes:

Ant はそれほど柔軟性が高くはありません。 <copy>タスクで同様の事を行う方法がありません。 <copy>タスクで最初の十行のを得たい場合には、 特別な属性を作成しなければならなかったのです。

<copy file="foo" tofile="bar" head="10" contains="blee"/>

The obvious problem thus surfaced: Ant tasks would not be able to accomodate such data transformation attributes as they would be endless. The task would also not know in which order these attributes were to be interpreted. That is, must the task execute the contains attribute first and then the head attribute or vice-versa? What Ant tasks needed was a mechanism to allow pluggable filter (data tranformer) chains. Ant would provide a few filters for which there have been repeated requests. Users with special filtering needs would be able to easily write their own and plug them in.

次のような明白な問題が現れます: Ant のタスクには そのような無限に続くようなデータ変換属性があるとは 言えません。 このタスクはこれらの属性が解釈される順番もわからないのです。 即ち、そのタスクは中に含まれる属性を先に実行し、 次に、先頭の属性を実行しなければならないなどということになるのでしょうか。 Ant のタスクに必要なのは、 プラグイン可能なフィルター(データ変換機能)の連鎖を使えるようにすることです。 Ant は繰り返された要求ある幾つかのフィルターを提供します。 特別なフィルタリングを必要とするユーザは、 簡単に自分のフィルターを書き、プラグインすることができるでしょう。

The solution was to refactor data transformation oriented tasks to support FilterChains. A FilterChain is a group of ordered FilterReaders. Users can define their own FilterReaders by just extending the java.io.FilterReader class. Such custom FilterReaders can be easily plugged in as nested elements of <filterchain> by using <filterreader> elements.

その解決策はデータ変換指向のタスクがフィルターチェーンをサポートするようにリファクタリングすることです。 フィルターチェーンは順序付けられたフィルターリーダーの集合です。 ユーザは自分のフィルターリーダーを単に java.io.FilterReader クラスを拡張することにより定義できます。 そのようなカスタムフィルターリーダーは <filterreader>要素を用いて、 ネストされた<filterchain>の要素に簡単にプラグインできます。

Example:

例:

<copy file="${src.file}" tofile="${dest.file}">
  <filterchain>
    <filterreader classname="your.extension.of.java.io.FilterReader">

      <param name="foo" value="bar"/>
    </filterreader>
    <filterreader classname="another.extension.of.java.io.FilterReader">
      <classpath>

        <pathelement path="${classpath}"/>
      </classpath>
      <param name="blah" value="blee"/>
      <param type="abra" value="cadabra"/>

    </filterreader>
  </filterchain>
</copy>

Ant provides some built-in filter readers. These filter readers can also be declared using a syntax similar to the above syntax. However, they can be declared using some simpler syntax also.

Ant には幾つかの組み込みのフィルターリーダーがあります。 これらのフィルターリーダーも 上述の文法と同じ文法を用いて宣言されています。 しかしながら、これは、より簡単な文法を使っても宣言することができます。

Example:

例:

<loadfile srcfile="${src.file}" property="${src.file.head}">
  <filterchain>
    <headfilter lines="15"/>

  </filterchain>
</loadfile>

is equivalent to:

は、次と等価です:

<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>

  </filterchain>
</loadfile>

The following built-in tasks support nested <filterchain> elements.

次の組み込みタスクはネストされた<filterchain>要素をサポートしています。

Copy,
LoadFile,
LoadProperties,
Move

A FilterChain is formed by defining zero or more of the following nested elements.

フィルターチェーンは、 ゼロ個以上の次のネストされた要素を定義することにより作られます。

FilterReader
ClassConstants
ExpandProperties
HeadFilter
LineContains
LineContainsRegExp
PrefixLines
ReplaceTokens
StripJavaComments
StripLineBreaks
StripLineComments
TabsToSpaces
TailFilter

フィルターリーダー/FilterReader

The filterreader element is the generic way to define a filter. User defined filter elements are defined in the build file using this. Please note that built in filter readers can also be defined using this syntax. A FilterReader element must be supplied with a class name as an attribute value. The class resolved by this name must extend java.io.FilterReader. If the custom filter reader needs to be parameterized, it must implement org.apache.tools.type.Parameterizable.

filterreader 要素はフィルターを定義する一般的な方法です。 ユーザ定義されたフィルター要素は この要素を用いてビルドファイル中で定義されます。 組み込みのフィルターリーダーもまた、 この文法を用いて定義できることに注意してください。 filterreader 要素は、属性値としてクラス名を与えなければなりません。 この名前により名前解決されたクラスは、 java.io.FilterReader を拡張したものでなければなりません。 カスタムフィルターリーダーがパラメーター化されている必要がある場合、 org.apache.tools.type.Parameterizableを実装しなければなりません。

Attribute Description Required
classname The class name of the filter reader. Yes
属性 説明 必須
classname フィルターリーダーのクラス名 Yes

Nested Elements:

ネストされた要素:

<filterreader> supports <classpath> and <param> as nested elements. Each <param> element may take in the following attributes - name, type and value.

<filterreader> は、 <classpath> および <param> をネストされた要素としてサポートします。 個々の<param> 要素は次の属性、name、type および value を取ります。

The following FilterReaders are supplied with the default distribution.

次に示すフィルターリーダーはデフォルトの配布で提供されています。

ClassConstants

This filters basic constants defined in a Java Class, and outputs them in lines composed of the format name=value

これは、Java クラスで定義された基本的な定数をフィルタリングし、 名前=値の形式に変換して行に出力します。

Example:

例:

This loads the basic constants defined in a Java class as Ant properties.

これは、Java クラスで定義された基本的な定数を Ant のプロパティとしてロードします。

<loadproperties srcfile="foo.class">
  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.ClassConstants"/>
  </filterchain>
</loadproperties>

Convenience method:

便利な方法は次の通りです:

<loadproperties srcfile="foo.class">
  <filterchain>
    <classconstants/>
  </filterchain>
</loadproperties>

ExpandProperties

If the data contains data that represents Ant properties (of the form ${...}), that is substituted with the property's actual value.

データが Ant の(${...}の形式をした)プロパティを表すデータを含んでいた場合、 それは、そのプロパティの実際の値に置き換えられます。

Example:

例:

This results in the property modifiedmessage holding the value "All these moments will be lost in time, like teardrops in the rain"

これは、 プロパティ modifiedmessageの値が "All these moments will be lost in time, like teardrops in the rain" という結果になります。

<echo
  message="All these moments will be lost in time, like teardrops in the ${weather}"
  file="loadfile1.tmp"
  />

<property name="weather" value="rain" />
<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
  <filterchain>

    <filterreader classname="org.apache.tools.ant.filters.ExpandProperties"/>
  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<echo
  message="All these moments will be lost in time, like teardrops in the ${weather}"
  file="loadfile1.tmp"
  />
<property name="weather" value="rain" />

<loadfile property="modifiedmessage" srcFile="loadfile1.tmp">
  <filterchain>
    <expandproperties/>
  </filterchain>
</loadfile>

HeadFilter

This filter reads the first few lines from the data supplied to it.

このフィルターは与えられたデータから最初の何行かを読み込みます。

Parameter Name Parameter Value Required
lines Number of lines to be read. Defaults to "10" No
パラメータ名 パラメータ値 必須
lines 読み込まれる行数。 デフォルトは "10" No

Example:

例:

This stores the first 15 lines of the supplied data in the property ${src.file.head}

これは、プロパティ${src.file.head}で与えられたデータの最初の 15行を保存します。

<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>

  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${src.file}" property="${src.file.head}">

  <filterchain>
    <headfilter lines="15"/>
  </filterchain>
</loadfile>

LineContains

This filter includes only those lines that contain all the user-specified strings.

このフィルターはユーザが指定した全ての文字列を含む行のみを取り込みます。

Parameter Type Parameter Value Required
contains Substring to be searched for. Yes
パラメータ種類 パラメーター値 必須
contains 検索する部分文字列 Yes

Example:

例:

This will include only those lines that contain foo and bar.

これは、foo および bar を含む行のみを取り込みます。

<filterreader classname="org.apache.tools.ant.filters.LineContains">
  <param type="contains" value="foo"/>

  <param type="contains" value="bar"/>
</filterreader>

Convenience method:

便利な方法は次の通りです:

<linecontains>
  <contains value="foo">
  <contains value="bar">
</linecontains>

LineContainsRegExp

Filter which includes only those lines that contain the user-specified regular expression matching strings.

ユーザが指定した正規表現にマッチする文字列を含む行のみを取り込むフィルターです。

Parameter Type Parameter Value Required
regexp Pattern of the substring to be searched for. Yes
パラ−メータ種類 パラメータ値 必須
regexp 検索する部分文字列のパターン Yes

Example:

例:

This will fetch all those lines that contain the pattern foo

パターンfooを含む全ての行を取ってきます。

<filterreader classname="org.apache.tools.ant.filters.LineContainsRegExp">
  <param type="regexp" value="foo*"/>

</filterreader>

Convenience method:

便利な方法は次の通りです:

<linecontainsregexp>
  <regexp pattern="foo*">

</linecontainsregexp>

PrefixLines

Attaches a prefix to every line.

全ての行に接頭辞をつけます。

Parameter Name Parameter Value Required
prefix Prefix to be attached to lines. Yes
パラメータ名 パラメータ値 必須
prefix 行に加えられる接頭辞 Yes

Example:

例:

This will attach the prefix Foo to all lines.

接頭辞Fooを全ての行につけます。

<filterreader classname="org.apache.tools.ant.filters.PrefixLines">

  <param name="prefix" value="Foo"/>
</filterreader>

Convenience method:

便利な方法は次の通りです:

<prefixlines prefix="Foo"/>

ReplaceTokens

This filter reader replaces all strings that are sandwiched between begintoken and endtoken with user defined values.

このフィルターリーダーはユーザにより定義された begintoken と endtoken で挟まれた全ての文字列を置換します。

Parameter Type Parameter Name Parameter Value Required
tokenchar begintoken Character marking the beginning of a token. Defaults to @ No
tokenchar endtoken Character marking the end of a token. Defaults to @ No
token User defined String. User defined search String Yes
パラメータ種類 パラメータ名 パラメータ値 必須
tokenchar begintoken トークンの始まりを示す文字。 デフォルトは @ No
tokenchar endtoken トークンの終わりを示す文字。 デフォルトは @ No
token ユーザ定義の文字列 ユーザ定義された検索文字列 Yes

Example:

例:

This replaces occurences of the string @DATE@ in the data with today's date and stores it in the property ${src.file.replaced}

これは、データ中で文字列 @DATE@ が出現したら、 本日の日付で置換し、それをプロパティ ${src.file.replaced} に保存します。

<tstamp/>

<loadfile srcfile="${src.file}" property="${src.file.replaced}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.ReplaceTokens">
      <param type="token" name="DATE" value="${TODAY}"/>

    </filterreader>
  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<tstamp/>

<loadfile srcfile="${src.file}" property="${src.file.replaced}">
  <filterchain>
    <replacetokens>
      <token key="DATE" value="${TODAY}"/>

    </replacetokens>
  </filterchain>
</loadfile>

StripJavaComments

This filter reader strips away comments from the data, using Java syntax guidelines. This filter does not take in any parameters.

このフィルターリーダーは Java 文法ガイドラインを用いてデータよりコメントを取り除きます。 このフィルターは何もパラメータを取り込みません。

Example:

例:

<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripJavaComments"/>

  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${java.src.file}" property="${java.src.file.nocomments}">

  <filterchain>
    <stripjavacomments/>
  </filterchain>
</loadfile>

StripLineBreaks

This filter reader strips away specific characters from the data supplied to it.

このフィルターリーダーは与えられたデータから特定の文字を取り除きます。

Parameter Name Parameter Value Required
linebreaks Characters that are to be stripped out. Defaults to "\r\n" No
パラメータ名 パラメータ値 必須
linebreaks 取り除かれる(複数の)文字。 デフォルトは"\r\n" No

Examples:

例:

This strips the '\r' and '\n' characters.

これは、'\r' および '\n' の文字を取り除きます

<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks"/>

  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${src.file}" property="${src.file.contents}">

  <filterchain>
    <striplinebreaks/>
  </filterchain>
</loadfile>

This treats the '(' and ')' characters as line break characters and strips them.

これは、'(' および ')' を改行文字として扱い、取り除きます。

<loadfile srcfile="${src.file}" property="${src.file.contents}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.StripLineBreaks">
      <param name="linebreaks" value="()"/>

    </filterreader>
  </filterchain>
</loadfile>

StripLineComments

This filter removes all those lines that begin with strings that represent comments as specified by the user.

このフィルターは、 ユーザにより指定されたコメントを表す文字列ではじまる行を全て削除します。

Parameter Type Parameter Value Required
comment Strings that identify a line as a comment when they appear at the start of the line. Yes
パラメータ種類 パラメータ値 必須
comment 行の先頭に現れた場合、その行をコメントと判断する文字列 Yes

Examples:

例:

This removes all lines that begin with #, --, REM, rem and //

#、 --、 REM、 rem および // ではじまる全ての行を削除します。

<filterreader classname="org.apache.tools.ant.filters.StripLineComments">
  <param type="comment" value="#"/>
  <param type="comment" value="--"/>

  <param type="comment" value="REM "/>
  <param type="comment" value="rem "/>
  <param type="comment" value="//"/>

</filterreader>

Convenience method:

便利な方法は次の通りです:

<striplinecomments>
  <comment value="#"/>

  <comment value="--"/>
  <comment value="REM "/>
  <comment value="rem "/>
  <comment value="//"/>

</striplinecomments>

TabsToSpaces

This filter replaces tabs with spaces

このフィルターはタブを空白文字で置換します。

Parameter Name Parameter Value Required
lines tablength Defaults to "8" No

Examples:

例:

This replaces tabs in ${src.file} with spaces.

これは、${src.file} 中のタブを空白文字で置換します。

<loadfile srcfile="${src.file}" property="${src.file.notab}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.TabsToSpaces"/>
  </filterchain>

</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${src.file}" property="${src.file.notab}">
  <filterchain>

    <tabstospaces/>
  </filterchain>
</loadfile>

TailFilter

This filter reads the last few lines from the data supplied to it.

このフィルターは与えられたデータより最後の数行を読み込みます。

Parameter Name Parameter Value Required
lines Number of lines to be read. Defaults to "10" No

Examples:

例:

This stores the last 15 lines of the supplied data in the property ${src.file.tail}

これはプロパティ ${src.file.tail} 中の与えられたデータの終わりの 15 行を保存します。

<loadfile srcfile="${src.file}" property="${src.file.tail}">
  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.TailFilter">

      <param name="lines" value="15"/>
    </filterreader>
  </filterchain>
</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${src.file}" property="${src.file.tail}">
  <filterchain>
    <tailfilter lines="15"/>

  </filterchain>
</loadfile>

This stores the last 5 lines of the first 15 lines of the supplied data in the property ${src.file.mid}

これはプロパティ ${src.file.mid} 中の与えられたデータの最初の 15 行のうちの、終わりの 5 行を保存します。

<loadfile srcfile="${src.file}" property="${src.file.mid}">

  <filterchain>
    <filterreader classname="org.apache.tools.ant.filters.HeadFilter">
      <param name="lines" value="15"/>
    </filterreader>

    <filterreader classname="org.apache.tools.ant.filters.TailFilter">
      <param name="lines" value="5"/>
    </filterreader>
  </filterchain>

</loadfile>

Convenience method:

便利な方法は次の通りです:

<loadfile srcfile="${src.file}" property="${src.file.mid}">
  <filterchain>

    <headfilter lines="15"/>
    <tailfilter lines="5"/>
  </filterchain>
</loadfile>

Copyright © 2002 Apache Software Foundation. All rights Reserved.

[訳注:これは漆島賢二が翻訳しました。日本語訳に対するコメントがあれば report@jajakarta.orgに送ってください]