Concepts and Types - TypesFile MappersMapping File NamesSome tasks take source files and create target files. Depending onthe 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) - inother cases you may want to specify the target files, either to helpApache 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. Aninstance of org.apache.tools.ant.util.FileNameMapper isresponsible for this. It constructs target file names based on rulesthat can be parameterized with from and to attributes - the exact meaning of which is implementation-dependent. These instances are defined in <mapper> elementswith the following attributes: Attribute | Description | Required | type | specifies one of the built-in implementations. | Exactly one of these | classname | specifies the implementation by class name. | classpath | the classpath to use when looking up classname . | No | classpathref | the classpath to use, given as reference to a path defined elsewhere. | No | from | the from attribute for the given implementation. | Depends on implementation. | to | the to attribute for the given implementation. | Depends on implementation. | Note that Ant will not automatically convert / or characters inthe to and from attributes to the correctdirectory separator of your current platform. If you need to specifythis separator, use ${file.separator} instead. For the regexpmapper, ${file.separator} will not work,as on windows it is the '' character, and this is an escape characterfor regular expressions, one should use the handledirsep attributeinstead. Parameters specified as nested elementsThe classpath can be specified via a nested<classpath> , as well - that is,a path-like structure. Since Ant 1.7.0, nested File Mappers canbe supplied via either <mapper> elements or<typedef> 'dimplementations of org.apache.tools.ant.util.FileNameMapper .If nested File Mappers are specified by either means, the mapper will beimplicitly configured as a composite mapper.
The built-in mapper types are:All built-in mappers are case-sensitive. As of Ant 1.7.0, each of the built-in mapper implementation types is directly accessible using a specific tagname. This makes it possible for filename mappers to support attributes in addition to the generally available to and from. The <mapper type|classname="..."> usage form remains valid for reasons of backward compatibility. identityThe target file name is identical to the source file name. Bothto and from will be ignored. Examples:<mapper type="identity"/><identitymapper/>
Source file name | Target file name | 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 | flattenThe target file name is identical to the source file name, with allleading directory information stripped off. Both to andfrom will be ignored. Examples:<mapper type="flatten"/><flattenmapper/>
Source file name | Target file name | A.java | A.java | foo/bar/B.java | B.java | C.properties | C.properties | Classes/dir/dir2/A.properties | A.properties | mergeThe target file name will always be the same, as defined byto - from will be ignored. Examples:<mapper type="merge" to="archive.tar"/><mergemapper to="archive.tar"/>
Source file name | Target file name | A.java | archive.tar | foo/bar/B.java | archive.tar | C.properties | archive.tar | Classes/dir/dir2/A.properties | archive.tar | globBoth to and from are required and define patterns that maycontain at most one * . For each source file that matchesthe from pattern, a target file name will be constructedfrom the to pattern by substituting the * inthe to pattern with the text that matches the* in the from pattern. Source file namesthat don't match the from pattern will be ignored. Examples:<mapper type="glob" from="*.java" to="*.java.bak"/><globmapper from="*.java" to="*.java.bak"/>
Source file name | Target file name | 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"/><globmapper from="C*ies" to="Q*y"/>
Source file name | Target file name | A.java | ignored | foo/bar/B.java | ignored | C.properties | Q.property | Classes/dir/dir2/A.properties | Qlasses/dir/dir2/A.property | The globmapper mapper can take the following extra attributes. Attribute | Description | Required | casesensitive | If this is false, the mapper will ignore case when matching the glob pattern. This attribute can be true or false, the default is true. Since Ant 1.6.3. | No | handledirsep | If this is specified, the mapper will ignore the difference between the normal directory separator characters - and /. This attribute can be true or false, the default is false. This attribute is useful for cross-platform build files. Since Ant 1.6.3. | No | An example: <pathconvert property="x" targetos="unix"> <path path="Aj.Java"/> <mapper> <chainedmapper> <flattenmapper/> <globmapper from="a*.java" to="*.java.bak" casesensitive="no"/> </chainedmapper> </mapper> </pathconvert> <echo>x is ${x}</echo> will output "x is j.java.bak". and <pathconvert property="x" targetos="unix"> <path path="d/e/f/j.java"/> <mapper> <globmapper from="${basedir}d/e*" to="*" handledirsep="yes"/> </mapper> </pathconvert> <echo>x is ${x}</echo> will output "x is f/j.java". regexpBoth to and from are required and defineregular expressions. If the source file name (as a whole or in part)matches the from pattern, the target file name will beconstructed from theto pattern, using
|