We need you!

Icon

The IzPack documentation needs work, and you are invited to edit it!

Skip to end of metadata
Go to start of metadata

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:

Attribute

Description

Required

type

specifies one of the built-in implementations.

Exactly one of these

from

the from attribute for the given implementation.

Depends on implementation.

to

the to attribute for the given implementation.

Depends on implementation.

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:

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:

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:

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:

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

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.

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.

No

Example:

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:

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

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

The regexpmapper mapper can take the following extra attributes:

Attribute

Description

Required

casesensitive

If this is false, the mapper will ignore case when matching the pattern. This attribute can be true or false, the default is true.

No

handledirsep

If this is specified, the mapper will treat a \ character in a filename as a / for the purposes of matching. This attribute can be true or false, the default is false. This attribute is useful for cross-platform build files.

No

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:

Source file name

Target file names

foo/bar/A.java

foo/bar/A.java
foo.bar.A

The composite mapper has no corresponding mapper type attribute.

  • No labels