File Name Mappers

Mapping File Names

The IzPack File Name Mapper concept has been adapted from the Apache Ant File Name Mapper core type. Its functionality has been shrunken to the needs of IzPack.

During copying and manipulating with files during an IzPack installation you might want to specify, how should the target files be named depending on the source files, for instance replacing a filename suffix by a different one.

While source files are usually specified as filesets, you don't specify target files directly - instead, you tell IzPack how to find the target file(s) for one source file.

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

Note that IzPack 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. For the regexpmapper, ${file.separator} will not work, as on windows it is the '\' character, and this is an escape character for regular expressions, one should use the handledirsep attribute instead.

Nested Elements

Nested File Mappers can be supplied via either <mapper> elements. If nested File Mappers are specified by either means, the mapper will be implicitly configured as a composite mapper.

Mapper Type Reference

All built-in mappers are case-sensitive.

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.

identity

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

Examples:

<mapper type="identity"/>
<identitymapper/>

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

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"/>
<mergemapper 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.

Examples:

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

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

The globmapper mapper can take the following extra attributes.

Example:

<globmapper from="*.java" to="*.java.bak" casesensitive="no"/>

renames all target files endings .java to .java.bak.

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.

Examples:

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

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

The regexpmapper mapper can take the following extra attributes:

composite

This mapper implementation can contain multiple nested mappers. File mapping is performed by passing the source filename to each nested mapper in turn, returning all results. The to and from attributes are ignored.

Example:

<compositemapper>
    <identitymapper/>
    <packagemapper from="*.java" to="*"/>
</compositemapper>

The composite mapper has no corresponding mapper type attribute.