Selectors

セレクター

Selectors are a mechanism whereby the files that make up a fileset can be selected based on criteria other than filename as provided by the <include> and <exclude> tags.

セレクターとは、 <include><exclude> タグによって与えられるファイル名以外の基準をもとにファイルセットを構成するファイルを選択する仕組みです。

How to use a Selector

セレクターの使い方

A selector is an element of FileSet, and appears within it. It can also be defined outside of any target by using the <selector> tag and then using it as a reference.

セレクターはファイルセットの要素であり、ファイルセット中に現れます。 またセレクターは、<selector> タグを使用し、それを参照として使用することでどんなターゲットの外部でも定義可能です。

Different selectors have different attributes. Some selectors can contain other selectors, and these are called Selector Containers. There is also a category of selectors that allow user-defined extensions, called Custom Selectors. The ones built in to Ant are called Core Selectors.

異なったセレクターは異なった属性を持ちます。セレクターの中には、他のセレクターを含むことができ、それらは セレクターコンテナ と呼ばれています。 また、ユーザ定義による拡張を許したセレクター郡もあり、 カスタムセレクターと呼ばれています。 Ant組み込みのものは コアセレクター と呼ばれています。

Core Selectors

コアセレクター

Core selectors are the ones that come standard with Ant. They can be used within a fileset and can be contained within Selector Containers.

コアセレクターはAntに標準で付いてきます。ファイルセット中で使用できますし、セレクターコンテナ中に含むこともできます。

The core selectors are:

コアセレクターは:

Contains Selector

コンテインズセレクター

The <contains> tag in a FileSet limits the files defined by that fileset to only those which contain the string specified by the text attribute. .

ファイルセット中の<contains> タグはそのファイルセットで定義されたファイルを text 属性で指定された文字列を含むものだけに限定します。 .

Attribute Description Required
text Specifies the text that every file must contain Yes
casesensitive Whether to pay attention to case when looking for the string in the text attribute. Default is true. No
属性 説明 必須
text それぞれのファイルに含まれなければならない文字を指定します。 Yes
casesensitive text 属性中の文字列を調べるときに大文字小文字を注意するかどうか。 デフォルトでは真です。 No

Here is an example of how to use the Contains Selector:

ここにコンテインズセレクターの使用例があります:

<fileset dir="${doc.path}" includes="**/*.html">
    <contains text="script" casesensitive="no"/>

</fileset>

Selects all the HTML files that contain the string script.

scriptというも文字列を含む全てのHTMLファイルを選択します。

Date Selector

デイトセレクター

The <date> tag in a FileSet will put a limit on the files specified by the include tag, so that tags whose last modified date does not meet the date limits specified by the selector will not end up being selected.

ファイルセット中の<date> タグはincludeタグで指定されたファイルに制限を設けます。 そのため最終更新日がセレクターによって指定された期限を満たさないタグは結局選択されません。

Attribute Description Required
datetime Specifies the date and time to test for using a string of the format MM/DD/YYYY HH:MM AM_or_PM. At least one of the two.
millis The number of milliseconds since 1970 that should be tested for. It is usually much easier to use the datetime attribute.
granularity The number of milliseconds leeway to give before deciding whether a files modification time matches a date. This is needed because not every file system supports tracking the last modified time to the millisecond level. The file will be selected provided the condition could be true were the granularity added or subtracted from the actual time. Default is 0 milliseconds except on Windows systems, where it is 2000 milliseconds (2 seconds). No
when Indicates how to interpret the date, whether the files to be selected are those whose last modified times should be before, after, or equal to the specified value. Acceptable values for this attribute are:
  • before - select files whose last modified date is before the indicated date
  • after - select files whose last modified date is after the indicated date
  • equal - select files whose last modified date is this exact date
The default is equal.
No
属性 説明 必須
datetime MM/DD/YYYY HH:MM AM_or_PMフォーマットの文字列を使用して 調べる日付と時間を指定します。 2つのうちのどちらか1つ
millis 1970年からのミリ秒値。 たいていはdatetime属性を使用するよりずっと簡単です。
granularity ファイルの更新時刻が日付と一致するかどうかを決定する前のミリ秒の余裕。 全てのファイルシステムがミリ秒単位で最終更新時刻を追跡可能にしているわけではないとの 理由でこれは必要です。 もし実際の時刻にgranularityを足したか引いたときに条件が真になるならファイルは選択されます。 Windowsシステム以外ではデフォルトは0ミリ秒であり、Windowsシステムでは2000ミリ秒(2秒)です。 No
when 選択されるべきファイルを、それらファイルの最終更新時刻が指定された値の前、後まはた同じかどうか で決定するために日付をどのように解釈するかを指示します この属性で受け付ける値は:
  • before - 最終更新日が指示された日付より前のファイルを選択します
  • after - 最終更新日が指示された日付より後のファイルを選択します
  • equal - 最終更新日がこの正確な日付であるファイルを選択します
デフォルトはequalです。
No

Here is an example of how to use the Date Selector:

ここにデイトセレクターの使用例があります:


<fileset dir="${jar.path}" includes="**/*.jar">
    <date datetime="01/01/2001 12:00 AM" when="before"/>
</fileset>

Selects all JAR files which were last modified before midnight January 1, 2001.

2001年1月1日の真夜中より前に最終更新された全てのJARファイルを選択します。

Depend Selector

ディペンドセレクター

The <depend> tag selects files whose last modified date is later than another, equivalent file in another location.

<depend> タグは最終更新日時が他のファイルや他の場所にある同じファイルより新しいファイルを選択します。

The <depend> tag supports the use of a contained <mapper> element to define the location of the file to be compared against. If no <mapper> element is specified, the identity type mapper is used.

<depend> タグは比較対象ファイルの位置を決定するために 包含された<mapper> 要素の使用をサポートします。 もし<mapper> 要素が1つも指定されなかった場合は、identity タイプマッパーが使用されます。

Attribute Description Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. Yes
granularity The number of milliseconds leeway to give before deciding a file is out of date. This is needed because not every file system supports tracking the last modified time to the millisecond level. Default is 0 milliseconds except on Windows systems, where it is 2000 milliseconds (2 seconds). No
属性 説明 必須
targetdir 比較対照ファイルを探すための基準ディレクトリ。 正確な位置はこの属性と、もしあれば、<mapper> 要素の組み合わせに 依存します。 Yes
granularity ファイルの更新時刻が日付と一致するかどうかを決定する前のミリ秒の余裕。 全てのファイルシステムがミリ秒単位で最終更新時刻を追跡可能にしているわけではないとの 理由でこれは必要です。 もし実際の時刻にgranularityを足したか引いたときに条件が真になるならファイルは選択されます。 Windowsシステム以外ではデフォルトは0ミリ秒であり、Windowsシステムでは2000ミリ秒(2秒)です。 No

Here is an example of how to use the Depend Selector:

ここにディペンドセレクターの使用例があります:

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">

    <depend targetdir="${ant.1.4.1}/src/main"/>
</fileset>

Selects all the Java source files which were modified in the 1.5 release.

1.5リリースで更新された全てのJavaソースファイルが選択します。

Depth Selector

デプスセレクター

The <depth> tag selects files based on how many directy levels deep they are in relation to the base directory of the fileset.

<depth> タグはファイルセットの基準ディレクトリに対してどれくらいのディレクトリ階層の深さに ファイルがあるかを元にしてファイルを選択します。

Attribute Description Required
min The minimum number of directory levels below the base directory that a file must be in order to be selected. Default is no limit. At least one of the two.
max The maximum number of directory levels below the base directory that a file can be and still be selected. Default is no limit.
属性 説明 必須
min 選択されないといけないファイルが存在する基準ディレクトリ以下のディレクトリ階層の最小値。 デフォルトは制限なしです。 2つのうちのどちらか1つ
max 選択可能でまだ選択されていないファイルが存在する基準ディレクトリ以下のディレクトリ階層の最大値。 デフォルトは制限なしです。

Here is an example of how to use the Depth Selector:

ここにデプスセレクターの使用例があります:

<fileset dir="${doc.path}" includes="**/*">
    <depth max="1"/>

</fileset>

Selects all files in the base directory and one directory below that.

基準ディレクトリとそれより1つ下のディレクトリにある全てのファイルを選択します。

Filename Selector

ファイルネームセレクター

The <filename> tag acts like the <include> and <exclude> tags within a fileset. By using a selector instead, however, one can combine it with all the other selectors using whatever selector container is desired.

<filename> はファイルセット中の<include><exclude>のように振る舞います。 しかしながら、セレクターを使用することによって、どんなセレクターコンテナ を 使用して全ての他のセレクターとそれを組み合わせることができます。

Attribute Description Required
name The name of files to select. The name parameter can contain the standard Ant wildcard characters. Yes
casesensitive Whether to pay attention to case when looking at file names. Default is "true". No
negate Whether to reverse the effects of this filename selection, therefore emulating an exclude rather than include tag. Default is "false". No
属性 説明 必須
name 選択するファイル名。nameパラメータはAnt標準のワイルドカード文字を含むことができます。 Yes
casesensitive ファイル名を探すときに大文字小文字を区別するかどうか。 デフォルトは"真"です。 No
negate このファイル名選択の効果を逆にするかどうか。 その結果includeタグではなくexcludeタグをまねています。 デフォルトは"偽"です。 No

Here is an example of how to use the Filename Selector:

ここにファイルネームセレクターの使用例があります:

<fileset dir="${doc.path}" includes="**/*">

    <filename name="**/*.css"/>
</fileset>

Selects all the cascading style sheet files.

全てのカスケーディングスタイルシートを選択します。

Present Selector

プレゼントセレクター

The <present> tag selects files that have an equivalent file in another directory tree.

<present> タグは他のディレクトリ階層中の同一ファイルを選択します。

The <present> tag supports the use of a contained <mapper> element to define the location of the file to be tested against. If no <mapper> element is specified, the identity type mapper is used.

<depend> タグは比較対象ファイルの位置を決定するために 包含された<mapper> 要素の使用をサポートします。 もし<mapper> 要素が1つも指定されなかった場合は、identity タイプマッパーが使用されます。

Attribute Description Required
targetdir The base directory to look for the files to compare against. The precise location depends on a combination of this attribute and the <mapper> element, if any. Yes
present Whether we are requiring that a file is present in the src directory tree only, or in both the src and the target directory tree. Valid values are:
  • srconly - select files only if they are in the src directory tree but not in the target directory tree
  • both - select files only if they are present both in the src and target directory trees
Default is both.
No
属性 説明 必須
targetdir 比較対照ファイルを探すための基準ディレクトリ。 正確な位置はこの属性と、もしあれば、<mapper> 要素の組み合わせに 依存します。 Yes
present ファイルがsrcディレクトリだけか、srcとtargetディレクトリツリーの両方に存在することを 必要とするかどうか。有効な値は:
  • srconly - targetディレクトリツリーではなくsrcディレクトリツリーに存在する場合にのみファイルを選択します
  • both - srcとtargetディレクトリツリー両方に存在する場合にのみファイルを選択します
デフォルトはbothです。
No

Here is an example of how to use the Present Selector:

ここにプレゼントセレクターの使用例があります:

<fileset dir="${ant.1.5}/src/main" includes="**/*.java">

    <present targetdir="${ant.1.4.1}/src/main"/>
</fileset>

Selects all the Java source files which are new in the 1.5 release.

1.5リリースで新規である全てのJavaソースファイルを選択します。

Size Selector

サイズセレクター

The <size> tag in a FileSet will put a limit on the files specified by the include tag, so that tags which do not meet the size limits specified by the selector will not end up being selected.

ファイルセット中の<date> タグはincludeタグで指定されたファイルに制限を設けます。 そのためセレクターによって指定されたサイズ制限を満たさないタグは結局選択されません。

Attribute Description Required
value The size of the file which should be tested for. Yes
units The units that the value attribute is expressed in. When using the standard single letter SI designations, such as "k","M", or "G", multiples of 1000 are used. If you want to use power of 2 units, use the IEC standard: "Ki" for 1024, "Mi" for 1048576, and so on. The default is no units, which means the value attribute expresses the exact number of bytes. No
when Indicates how to interpret the size, whether the files to be selected should be larger, smaller, or equal to that value. Acceptable values for this attribute are:
  • less - select files less than the indicated size
  • more - select files greater than the indicated size
  • equal - select files this exact size
The default is equal.
No
属性 説明 必須
value 検査されるべきファイルのサイズ Yes
units value 属性中で表す単位。 "k","M", or "G" のような標準的な1文字SI表示を使用するとき、1000倍されたものが使用されます。 もし2の累乗の単位を使用したいなら、IEC標準を使用してください: "Ki" を1024とし、"Mi" を1048576などのように。 デフォルトでは単位はありません。これが意味するところはvalue は正確なバイト数を表すということです。 No
when 選択されるべきファイルを、それらファイルのサイズが指定された値より小さい、大きいまはた同じかどうか で決定するためにサイズをどのように解釈するかを指示します この属性で受け付ける値は:
  • less - 指示されたサイズより小さいファイルを選択します
  • more - 指示されたサイズより大きいファイルを選択します
  • equal - 正確なサイズのファイルを選択します
デフォルトはequalです。
No

Here is an example of how to use the Size Selector:

ここにサイズセレクターの使用例があります:


<fileset dir="${jar.path}">
  <patternset>
    <include name="**/*.jar"/>
  </patternset>
  <size value="4" units="Ki" when="more"/>

</fileset>

Selects all JAR files that are larger than 4096 bytes.

4096バイトより大きい全てのJARファイルを選択します。

Selector Containers

セレクターコンテナ

To create more complex selections, a variety of selectors that contain other selectors are available for your use. They combine the selections of their child selectors in various ways.

より複雑な選択物を作成するには、他のセレクターを含む様々なセレクターを 使用することができます。それらはいろんな方法で子セレクターによる選択物を 組み合わせます。

The selector containers are:

セレクターコンテナは:

All selector containers can contain any other selector, including other containers, as an element. Using containers, the selector tags can be arbitrarily deep. Here is a complete list of allowable selector elements within a container:

全てのセレクターコンテナは、他のセレクターコンテナを含め、他のどんなセレクターを要素として含むことができます。 コンテナを使用することで、selectorタグは任意に深くすることができます。 ここにコンテナ内に許容されるselector要素の完全な一覧があります:

And Selector

アンドセレクター

The <and> tag selects files that are selected by all of the elements it contains. It returns as soon as it finds a selector that does not select the file, so it is not guaranteed to check every selector.

<and> タグはそれが含む全ての要素によって選択されたファイルを選択します。 これはそのファイルを選択しないセレクターを見つけたらすぐに戻るので、 全てのセレクターを検査することは保証されません。

Here is an example of how to use the And Selector:

ここにアンドセレクターの使用例があります:

<fileset dir="${dist}" includes="**/*.jar">

    <and>
        <size value="4" units="Ki" when="more"/>
        <date datetime="01/01/2001 12:00 AM" when="before"/>

    </and>
</fileset>

Selects all the JAR file larger than 4096 bytes which haven't been update since the last millenium.

2001年1月1日午前12時から更新されていない4096バイトより大きい全てのJARファイルを選択します。

Majority Selector

マジョリティセレクター

The <majority> tag selects files provided that a majority of the contained elements also select it. Ties are dealt with as specified by the allowtie attribute.

<majority> タグは包含される要素の大部分がファイルを選択する場合にそのファイルを選択します。 タイはallowtie 属性によって指定されることで扱われます。

Attribute Description Required
allowtie Whether files should be selected if there are an even number of selectors selecting them as are not selecting them. Default is true. No
属性 説明 必須
allowtie もしあるファイルを選択するセレクターと選択しないセレクターが同数の場合に そのファイルが選択されるべきかどうかどうか。 デフォルトは真です。 No

Here is an example of how to use the Majority Selector:

ここにマジョリティセレクターの使用例があります:

<fileset dir="${docs}" includes="**/*.html">

    <majority>
        <contains text="project" casesensitive="false"/>
        <contains text="taskdef" casesensitive="false"/>
        <contains text="IntrospectionHelper" casesensitive="true"/>

    </majority>
</fileset>

Selects all the HTML files which contain at least two of the three phrases "project", "taskdef", and "IntrospectionHelper" (this last phrase must match case exactly).

少なくとも"project"、 "taskdef" と "IntrospectionHelper"(この最後の語句は正確に大文字小文字を 区別しなければなりません)の3つのうち2つを含む全てのHTMLファイルを選択します。

None Selector

ナンセレクター

The <none> tag selects files that are not selected by any of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

<none> タグはそれが含むどの要素からも選択されていないファイルを選択します。 これはそのファイルを選択するセレクターを見つけたらすぐに戻るので、 全てのセレクターを検査することは保証されません。

Here is an example of how to use the None Selector:

ここにナンセレクターの使用例があります:

<fileset dir="${src}" includes="**/*.java">
    <none>

        <present targetdir="${dest}"/>
        <present targetdir="${dest}">
            <mapper type="glob" from="*.java" to="*.class"/>

        </present>
    </none>
</fileset>

Selects only Java files which do not have equivalent java or class files in the dest directory.

destディレクトリ中の.javaや.classファイルと同等ではないJavaファイルだけを選択します。

Not Selector

ノットセレクター

The <not> tag reverses the meaning of the single selector it contains.

<not> タグはそれを含む単一のセレクターの意味を逆転します。

Here is an example of how to use the Not Selector:

ここにノットセレクターの使用例があります:

<fileset dir="${src}" includes="**/*.java">
    <not>

        <contains text="test"/>
    </not>
</fileset>

Selects all the files in the src directory that do not contain the string "test".

srcディレクトリ中にある"test"という文字列を含まない全てのファイルを選択します。

Or Selector

オアセレクター

The <or> tag selects files that are selected by any one of the elements it contains. It returns as soon as it finds a selector that selects the file, so it is not guaranteed to check every selector.

<and> タグはそれが含むいづれかの要素によって選択されたファイルを選択します。 これはそのファイルを選択しないセレクターを見つけたらすぐに戻るので、 全てのセレクターを検査することは保証されません。

Here is an example of how to use the Or Selector:

ここにオアセレクターの使用例があります:

<fileset dir="${basedir}">

    <or>
        <depth max="0"/>
        <filename name="*.png"/>
        <filename name="*.gif"/>
        <filename name="*.jpg"/>

    </or>
</fileset>

Selects all the files in the top directory along with all the image files below it.

トップディレクトリ中の全てのファイルとすべてのイメージファイルを選択します。

Selector Reference

セレクターリファレンス

The <selector> tag is used to create selectors that can be reused through references. It should be used outside of any target, as an element of the <project> tag. It can contain only one other selector, but of course that selector can be a container.

<selector> タグは参照を通じて再利用できるセレクターを作成するのに向いています。 それは<project> タグの要素としていづれのtarget外で使用しなければなりません。 それは1つだけ他のセレクターを含むことができますが、もちろんそのセレクターはコンテナにすることができます。

Here is an example of how to use the Selector Reference:

ここにセレクターリファレンスの使用例があります:


<project default="all" basedir="./jakarta-ant">

    <selector id="completed">
        <none>
            <depend targetdir="build/classes">

                <mapper type="glob" from="*.java" to="*.class"/>
            </depend>
            <depend targetdir="docs/manual/api">

                <mapper type="glob" from="*.java" to="*.html"/>
            </depend>
        </none>

    </selector>

    <target>
        <zip>
            <fileset dir="src/main" includes="**/*.java">

                <selector refid="completed"/>
            </fileset>
        </zip>
    </target>

</project>

Zips up all the Java files which have an up-to-date equivalent class file and javadoc file associated with them.

それらに関係する最新のものと同等な.classファイルとJavadocファイルを持つ全てのJavaファイルをZip圧縮します。

Custom Selectors

カスタムセレクター

You can write your own selectors and use them within the selector containers by specifying them within the <custom> tag.

自分自身のセレクターを書くことができ、それらを<custom> タグ中に指定することで セレクターコンテナの中でそれらを使用することができます。

First, you have to write your selector class in Java. The only requirement it must meet in order to be a selector is that it implements the org.apache.tools.ant.types.selectors.FileSelector interface, which contains a single method. See Programming Selectors in Ant for more information.

まず、自分自身のセレクタークラスをJavaで書かなければなりません。 セレクターとして満たさなければならないただ1つの必要条件は、1つのメソッドを持つ org.apache.tools.ant.types.selectors.FileSelector インターフェースを実装することです。 詳しくはProgramming Selectors in Ant を見てください。

Once that is written, you include it in your build file by using the <custom> tag.

一度セレクターを書くと、the <custom> タグを使用して あなたのビルドファイルにそのセレクターを含めることができます。

Attribute Description Required
classname The name of your class that implements org.apache.tools.ant.types.selectors.FileSelector. Yes
classpath The classpath to use in order to load the custom selector class. If neither this classpath nor the classpathref are specified, the class will be loaded from the classpath that Ant uses. No
classpathref A reference to a classpath previously defined. If neither this reference nor the classpath above are specified, the class will be loaded from the classpath that Ant uses. No
属性 説明 必須
classname org.apache.tools.ant.types.selectors.FileSelectorを実装するあなたのクラス名。 Yes
classpath カスタムセレクタークラスをロードするために使用するクラスパス。 もしこのclasspathとclasspathrefのどちらも指定されない場合、そのクラスはAntが使用しているクラスパスからロードされます。 No
classpathref 既に定義されているクラスパスへの参照。 もしこの参照と上記classpathのどちらも指定されない場合、そのクラスはAntが使用しているクラスパスからロードされます。 No

Here is how you use <custom> to use your class as a selector:

あなたのクラスをセレクターとして使用するための<custom> タグをどのように 使用するかがここにあります:


<fileset dir="${mydir}" includes="**/*">
    <custom classname="com.mydomain.MySelector">
        <param name="myattribute" value="myvalue"/>

    </custom>
</fileset>

A number of core selectors can also be used as custom selectors by specifying their attributes using <param> elements. These are

<param> 要素を使用して属性を指定することによって、多くのコアセレクターはカスタムセレクターとしても使用できます。 これらは

Here is the example from the Depth Selector section rewritten to use the selector through <custom>.

デプスセレクターの節からの例を<custom>タグを通してセレクターを使用するように書き直したものが ここにあります。

<fileset dir="${doc.path}" includes="**/*">
    <custom classname="org.apache.tools.ant.types.selectors.DepthSelector">
        <param name="max" value="1"/>

    </custom>
</fileset>

Selects all files in the base directory and one directory below that.

基準ディレクトリとその1つ下のディレクトリにある全てのファイルを選択します。

For more details concerning writing your own selectors, consult Programming Selectors in Ant.

自分自身のセレクターを書くことに関するより詳しい情報については、 Programming Selectors in Antを参考にしてください。


Copyright © 2002 Apache Software Foundation. All rights Reserved.

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