From e888cc1fc8d1adfafcd9c29866691d095abed7bf Mon Sep 17 00:00:00 2001 From: Stefan Bodewig Date: Fri, 1 Dec 2000 14:06:57 +0000 Subject: [PATCH] Documentation of . git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@268285 13f79535-47bb-0310-9956-ffa450edef68 --- WHATSNEW | 4 + docs/index.html | 314 +++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 317 insertions(+), 1 deletion(-) diff --git a/WHATSNEW b/WHATSNEW index df0e30b0e..31907d61a 100644 --- a/WHATSNEW +++ b/WHATSNEW @@ -33,6 +33,10 @@ Other changes: * now supports passive mode. +* New data type that can be used to get influence on the + target files for some tasks like or enable new types of tasks + like . + Fixed bugs: ----------- diff --git a/docs/index.html b/docs/index.html index 0ab2d3aff..51fb78d79 100644 --- a/docs/index.html +++ b/docs/index.html @@ -27,7 +27,7 @@
  • Dave Walend (dwalend@cs.tufts.edu)
    • -

    Version 1.3 - 2000/11/30

    +

    Version 1.3 - 2000/12/01

    Table of Contents

    @@ -864,6 +864,318 @@ name.

    Groups all files in directory ${client.src} using the same patterns as the example before.

    +

    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, +but 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:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeDescriptionRequired
    typeSpecify one of the built in implementationsExactly one of both
    classnameSpecify the implementation by class name
    classpaththe classpath to use when looking up + classname.No
    classpathrefthe classpath to use, given as reference to a PATH defined elsewhere.No
    fromThe "from" attribute for the given + implementationDepends on implementation.
    toThe "to" attribute for the given + implementationDepends on implementation.
    +

    The classpath can as well be specified via a nested +<classpath>, 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 nameTarget file name
    A.javaA.java
    foo/bar/B.javafoo/bar/B.java
    C.propertiesC.properties
    Classes/dir/dir2/A.propertiesClasses/dir/dir2/A.properties
    +

    flatten

    +

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

    +
    Examples:
    +
    +<mapper type="flatten" />
+
    + + + + + + + + + + + + + + + + + + + + + +
    Source file nameTarget file name
    A.javaA.java
    foo/bar/B.javaB.java
    C.propertiesC.properties
    Classes/dir/dir2/A.propertiesA.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 nameTarget file name
    A.javaarchive.tar
    foo/bar/B.javaarchive.tar
    C.propertiesarchive.tar
    Classes/dir/dir2/A.propertiesarchive.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 by 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 nameTarget file name
    A.javaA.java.bak
    foo/bar/B.javafoo/bar/B.java.bak
    C.propertiesignored
    Classes/dir/dir2/A.propertiesignored
    +
    +<mapper type="glob" from="C*ies" to="Q*y" />
+
    + + + + + + + + + + + + + + + + + + + + + +
    Source file nameTarget file name
    A.javaignored
    foo/bar/B.javaignored
    C.propertiesQ.property
    Classes/dir/dir2/A.propertiesQlasses/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 constructed from the +to pattern using \0 to \9 as back references for the full +match (\0) or the matches of the subexpressions in parens. Source +files not matching the from pattern will be ignored.

    +

    Note that you need to escape a $-sign with another $-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 nameTarget file name
    A.javaA.java.bak
    foo/bar/B.javafoo/bar/B.java.bak
    C.propertiesignored
    Classes/dir/dir2/A.propertiesignored
    +
    +<mapper type="regexp" from="^(.*)/([^/]+)/([^/]*)$$" to="\1/\2/\2-\3" />
+
    + + + + + + + + + + + + + + + + + + + + + +
    Source file nameTarget file name
    A.javaignored
    foo/bar/B.javafoo/bar/bar-B.java
    C.propertiesignored
    Classes/dir/dir2/A.propertiesClasses/dir/dir2/dir2-A.properties
    +
    +<mapper type="regexp" from="^(.*)\.(.*)$$" to="\2.\1" />
+
    + + + + + + + + + + + + + + + + + + + + + +
    Source file nameTarget file name
    A.javajava.A
    foo/bar/B.javajava.foo/bar/B
    C.propertiesproperties.C
    Classes/dir/dir2/A.propertiesproperties.Classes/dir/dir2/A
    +

    Built in tasks