Mapping File Names

Some tasks take source files and create target files. Depending on the task, it may be quite obvious which name a target file will have (using javac, you know there will be .class files for your .java files) - in other cases you may want to specify the target files, either to help Ant or to get an extra bit of functionality.

While source files are usually specified as filesets, you don't specify target files directly - instead, you tell Ant how to find the target file(s) for one source file. An instance of org.apache.tools.ant.util.FileNameMapper is responsible for this. It constructs target file names based on rules that can be parameterized with from and to attributes - the exact meaning of which is implementation-dependent.

These instances are defined in <mapper> elements with the following attributes:

Note that Ant will not automatically convert / or \ characters in the to and from attributes to the correct directory separator of your current platform. If you need to specify this separator, use ${file.separator} instead.

Parameters specified as nested elements

The classpath can be specified via a nested <classpath>, as well - that is, a path-like structure.

The built-in mapper types are:

identity

The target file name is identical to the source file name. Both to and from will be ignored.

<mapper type="identity"/>

flatten

The target file name is identical to the source file name, with all leading directory information stripped off. Both to and from will be ignored.

<mapper type="flatten"/>

merge

The target file name will always be the same, as defined by to - from will be ignored.

Examples:

<mapper type="merge" to="archive.tar"/>

glob

Both to and from define patterns that may contain at most one *. For each source file that matches the from pattern, a target file name will be constructed from the to pattern by substituting the * in the to pattern with the text that matches the * in the from pattern. Source file names that don't match the from pattern will be ignored.

<mapper type="glob" from="*.java" to="*.java.bak"/>

<mapper type="glob" from="C*ies" to="Q*y"/>

regexp

Both to and from define regular expressions. If the source file name matches the from pattern, the target file name will be constructed from the to pattern, using \0 to \9 as back-references for the full match (\0) or the matches of the subexpressions in parentheses. Source files not matching the from pattern will be ignored.

Note that you need to escape a dollar-sign ($) with another dollar-sign in Ant.

The regexp mapper needs a supporting library and an implementation of org.apache.tools.ant.util.regexp.RegexpMatcher that hides the specifics of the library. Ant comes with implementations for the java.util.regex package of JDK 1.4, jakarta-regexp and jakarta-ORO. If you compile from sources and plan to use one of them, make sure the libraries are in your CLASSPATH. For information about using gnu.regexp or gnu.rex with Ant, see this article.

This means, you need optional.jar from the Ant release you are using and one of the supported regular expression libraries. Make sure, both will be loaded from the same classpath, that is either put them into your CLASSPATH, ANT_HOME/lib directory or a nested <classpath> element of the mapper - you cannot have optional.jar in ANT_HOME/lib and the library in a nested <classpath>.

Ant will choose the regular-expression library based on the following algorithm:

• If the system property ant.regexp.matcherimpl has been set, it is taken as the name of the class implementing org.apache.tools.ant.util.regexp.RegexpMatcher that should be used.
• If it has not been set, first try the JDK 1.4 classes, then jakarta-ORO and finally try jakarta-regexp.

<mapper type="regexp" from="^(.*)\.java$$" to="\1.java.bak"/>

<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3"/>

<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1"/>

package

Sharing the same syntax as the glob mapper, the package mapper replaces directory separators found in the matched source pattern with dots in the target pattern placeholder. This mapper is particularly useful in combination with <uptodate> and <junit> output.

<mapper type="package"

Copyright © 2000-2001 Apache Software Foundation. All rights Reserved.