マッピングファイル名

いくつかのタスクはソースファイルを使ってターゲットファイルを作成します。 タスクにも依りますが、ターゲットファイルがどの名前になるのかは一目瞭然かもしれません (javacでは、ご存知のとおり .java ファイルに対して .class ファイルが生成されます) - しかし、他の場合にAntの手助けをしたりとかちょっとした特別の機能を使いたいとかという理由でターゲットファイルを指定したいかも知れません。

ソースファイルは通常ファイルセットとして指定しますが、 ターゲットファイルを直接指定することはありません - その代わりに1つのソースファイルに対して(複数の)ターゲットファイルを見つける方法を Ant に伝えることができます。これは、org.apache.tools.ant.util.FileNameMapper の実装が担当します。それは fromto 属性でパラメータ化されたルールをもとにしてターゲットファイルを作り上げます - つまり、このことの正確な意味は実装依存ということです。

これらの実装は、次の属性を持つ <mapper> 要素で定義します。

属性 説明 必須
type 組み込み実装の1つを指定する。 2つのうちどれか1つ
classname 実装をクラス名で指定する。
classpath classname を探すときに使用するクラスパス。 No
classpathref 使用されるクラスパスであり、どこかで定義されたパスへの 参照 として与えられます。 No
from 選択した実装の from属性。 実装依存。
to 選択した実装の to属性。 実装依存。

Antは tofrom 属性中の \ や / 文字を、 現在のプラットフォームの正しいディレクトリセパレータに自動的に変換しないことに注意してください。 このセパレータを指定する必要があるなら、代わりに ${file.separator} を使用してください。

ネストした要素として指定されるパラメータ

クラスパスはネストした <classpath> 要素、つまり パス 類似構造として指定できます。

組み込まれているマッパ型:

すべての組み込まれているマッパは、大文字小文字を区別します。

identity

ターゲットファイル名はソースファイル名と同一です。tofrom は共に無視します。

例:
<mapper type="identity"/>
ソースファイル名 ターゲットファイル名
A.java A.java
foo/bar/B.java foo/bar/B.java
C.properties C.properties
Classes/dir/dir2/A.properties Classes/dir/dir2/A.properties

flatten

ターゲットファイル名は先行するディレクトリ情報を取り除いた形でソースファイル名と同一です。 tofrom は共に無視します。

例:
<mapper type="flatten"/>
ソースファイル名 ターゲットファイル名
A.java A.java
foo/bar/B.java B.java
C.properties C.properties
Classes/dir/dir2/A.properties A.properties

merge

ターゲットファイル名は to で定義された名前で常に同じになります。 from は無視されます。

例:
<mapper type="merge" to="archive.tar"/>
ソースファイル名 ターゲットファイル名
A.java archive.tar
foo/bar/B.java archive.tar
C.properties archive.tar
Classes/dir/dir2/A.properties archive.tar

glob

tofrom 共に、多くても1つの * を含むパターンを定義します。 from のパターンに一致するそれぞれのソースファイルに対して、 ターゲットファイル名は to のパターン中の *from のパターン中の * に一致した文字列と置き換えることによって to のパターンから構築します。from のパターンに一致しないソースファイル名は無視します。

例:
<mapper type="glob" from="*.java" to="*.java.bak"/>
ソースファイル名 ターゲットファイル名
A.java A.java.bak
foo/bar/B.java foo/bar/B.java.bak
C.properties ignored
Classes/dir/dir2/A.properties ignored
<mapper type="glob" from="C*ies" to="Q*y"/>
ソースファイル名 ターゲットファイル名
A.java ignored
foo/bar/B.java ignored
C.properties Q.property
Classes/dir/dir2/A.properties Qlasses/dir/dir2/A.property

regexp

tofrom ともに正規表現を定義します。 ソースファイル名が fromのパターンにマッチした場合、 ターゲットファイル名は to のパターンから構築します。 その際 \0 から \9 を全一致(\0)や () で囲まれた部分正規表現にマッチした内容を表す後方参照として使用します。 from のパターンに一致しないソースファイル名は無視します。

Antの中ではドル記号($)はもう1つドル記号を使ってエスケープする必要があることに注意してください。

regexp マッパにはサポートライブラリ、またはそのライブラリの指定を隠す org.apache.tools.ant.util.regexp.RegexpMatcher の実装が必要です。 Antには、JDK 1.4のjava.util.regex パッケージjakarta-regexp および jakarta-ORO の実装が付いてきます。 ソースからコンパイルしてそれらのうちのどれかを使うつもりなら、そのライブラリが CLASSPATHの中に含まれているか確認してください。 gnu.regexpgnu.rex をAntと一緒に 使用するための情報として この記事を参照してください。

これが意味するところは、使用しているAntリリースの optional.jar サポートされている正規表現ライブラリの1つを必要とするということです。 両方が同じクラスパスからロードされることを確認してください。つまり CLASSPATHANT_HOME/lib ディレクトリまたはそのマッパのネストした <classpath> 要素のいずれかにそれらを配置してください。 optional.jarANT_HOME/lib に配置し正規表現ライブラリをネストした <classpath> 要素にすることはできません。

Antは次のアルゴリズムをもとに正規表現ライブラリを選びます:

例:
<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>
ソースファイル名 ターゲットファイル名
A.java A.java.bak
foo/bar/B.java foo/bar/B.java.bak
C.properties 無視する
Classes/dir/dir2/A.properties 無視する
<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>
ソースファイル名 ターゲットファイル名
A.java 無視する
foo/bar/B.java foo/bar/bar-B.java
C.properties 無視する
Classes/dir/dir2/A.properties Classes/dir/dir2/dir2-A.properties
<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>
ソースファイル名 ターゲットファイル名
A.java java.A
foo/bar/B.java java.foo/bar/B
C.properties properties.C
Classes/dir/dir2/A.properties properties.Classes/dir/dir2/A

package

glob マッパ と同じシンタックスを共有し、 package マッパはソースパターンにマッチした中で見つかったディレクトリセパレータを、 ターゲットパターンで置き換わる部分でドットに置き換えます。 このマッパーは <uptodate><junit> の出力と一緒に組み合わせると特に有用です。

例:
<mapper type="package"
        from="*Test.java" to="TEST-*Test.xml"/>
ソースファイル名 ターゲットファイル名
org/apache/tools/ant/util/PackageMapperTest.java TEST-org.apache.tools.ant.util.PackageMapperTest.xml
org/apache/tools/ant/util/Helper.java ignored

unpackage (Ant 1.6 から)

このマッパは、package マッパと逆になります。 このマッパは、パッケージ名の中のドットをディレクトリセパレータに置き換えます。 これは、JUnit がテストしたテストケースと対応する XML フォーマッタの結果をマッチさせるのに有用です。 このマッパは、glob マッパ を元にしたシンタックスを共有します。

例:
<mapper type="unpackage"
        from="TEST-*Test.xml" to="${test.src.dir}/*Test.java">
ソースファイル名 ターゲットファイル名
TEST-org.acme.AcmeTest.xml ${test.src.dir}/org/acme/AcmeTest.java

Copyright © 2000-2004 The Apache Software Foundation. All rights Reserved.

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