## 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:

Attribute | Description | Required
type | specifies one of the built-in implementations. | Exactly one of both
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.

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.

Examples:

>     <mapper type="identity"/>

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`

#### 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.

Examples:

>     <mapper type="flatten"/>

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`

#### 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"/>

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`

#### 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.

Examples:

>     <mapper type="glob" 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"/>

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`

#### 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 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.

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 jakarta-ORO; if that cannot be found, try jakarta-regexp.

Examples:

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

Source file name | Target file name
`A.java` | ignored
`foo/bar/B.java` | `foo/bar/bar-B.java`
`C.properties` | ignored
`Classes/dir/dir2/A.properties` | `Classes/dir/dir2/dir2-A.properties`

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

Source file name | Target file name
`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`

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