<scriptmapper>, with tests and docs. At this point we have near total script coverage of all the core ant extension points. Note the refactoring of scriptcondition to give us a better base for these things.

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@278273 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -98,6 +98,9 @@ Fixed bugs:
 * <xmlvalidate> and <schemavalidate> create a new parser for every file in a
   fileset, and so validate multiple files properly. Bugzilla Report 32791
 
+* New mapper, <scriptmapper>, supports scripted mapping of source files/strings to
+  destination strings.
+
 Other changes:
 --------------
 
@@ -203,6 +206,8 @@ Other changes:
 * project name is now used for *all* targets so one can write consistent import
   build file. bugzilla report 28444.
 
+
+
 Changes from Ant 1.6.3 to current Ant 1.6 CVS version
 =====================================================
 

docs/manual/CoreTypes/mapper.html

@@ -683,6 +683,106 @@ with <code>&lt;uptodate&gt;</code> and <code>&lt;junit&gt;</code> output.</p>
   <p>The filtermapper has no corresponding
     <code>&lt;mapper <b>type</b>&gt;</code> attribute.
   </p>
+
+    <!--                                        -->
+    <!--             Script Mapper              -->
+    <!--                                        -->
+
+<h4><a name="script-mapper">scriptmapper (since ant 1.7)</a></h4>
+<p>
+This mapper executes a script written in <a href="http://jakarta.apache.org/bsf" target="_top">Apache BSF</a>
+supported language, once per file to map.</p>
+The script can be declared inline or in a specified file.
+</p>
+<p>
+See the <a href="../OptionalTasks/script.html">Script</a> task for
+an explanation of scripts and dependencies.
+</p>
+
+  <table border="1" cellpadding="2" cellspacing="0">
+    <tr>
+      <td valign="top"><b>Attribute</b></td>
+      <td valign="top"><b>Description</b></td>
+      <td align="center" valign="top"><b>Required</b></td>
+    </tr>
+    <tr>
+      <td valign="top">language</td>
+      <td valign="top">
+        Scripting language
+      </td>
+      <td align="center" valign="top">Yes</td>
+    </tr>
+    <tr>
+      <td valign="top">src</td>
+      <td valign="top">
+        File containing the script
+      </td>
+      <td align="center" valign="top">No</td>
+    </tr>
+    </table>
+
+<p>
+Example
+</p>
+<blockquote><pre>
+&lt;scriptmapper language="javascript"&gt;
+  self.addMappedName(source.toUpperCase());
+  self.addMappedName(source.toLowerCase());
+&lt;/scriptmapper&gt;
+</pre></blockquote>
+
+<table border="1" cellpadding="2" cellspacing="0">
+  <tr>
+    <td valign="top"><b>Source file name</b></td>
+    <td valign="top"><b>Target file names</b></td>
+  </tr>
+  <tr>
+    <td valign="center"><code>foo\bar\A.java</code></td>
+    <td valign="top"><code>FOO\BAR\A.JAVA foo\bar\a.java</code></td>
+  </tr>
+</table>
+
+<p>
+To use this mapper, the scripts need access to the source file,
+and the ability to return multiple mappings. Here are the relevant beans and
+their methods. The script is called once for every source file, with the
+list of mapped names reset after every invocation.
+
+  <table border="1" cellpadding="2" cellspacing="0">
+    <tr>
+      <td valign="top"><b>Script bean</b></td>
+      <td valign="top"><b>Description</b></td>
+    </tr>
+    <tr>
+      <td valign="top"><code>source: String</code></td>
+      <td valign="top">
+        The file/path to map
+      </td>
+    </tr>
+    <tr>
+      <td valign="top">self</td>
+      <td valign="top">
+        the scriptmapper itself
+      </td>
+    </tr>
+    <tr>
+      <td valign="top"><code>self.addMappedName(String name)</code></td>
+      <td valign="top">
+        Add a new mapping
+      </td>
+    </tr>
+    <tr>
+      <td valign="top"><code>self.clear()</code></td>
+      <td valign="top">
+        Reset the list of files.
+      </td>
+    </tr>
+    </table>
+
+  <p>The scriptmapper has no corresponding
+    <code>&lt;mapper <b>type</b>&gt;</code> attribute.
+  </p>
+
 <hr>
 <p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
 Reserved.</p>

src/etc/testcases/types/mappers/define.mapperresult.xml

@@ -2,4 +2,7 @@
   <typedef name="mapperresult"
            classpath="../../../../../build/testcases"
            classname="org.apache.tools.ant.types.mappers.MapperResult"/>
+
+  <!-- this is what you get with no result -->           
+  <property name="no-results" value="&lt;NULL&gt;" />           
 </project>

src/etc/testcases/types/mappers/scriptmapper.xml

@@ -0,0 +1,41 @@
+<project name="scriptmapper">
+  <import file="define.mapperresult.xml"/>
+
+  
+  <target name="testSetSingle">
+    <mapperresult input="" output="a">
+      <scriptmapper language="javascript">
+        self.addMappedName("a");
+      </scriptmapper>
+    </mapperresult>
+  </target>
+
+  <target name="testClear">
+    <mapperresult input="" output="${no-results}">
+      <scriptmapper language="javascript">
+        self.addMappedName("a");
+        self.clear();
+      </scriptmapper>
+    </mapperresult>
+  </target>
+
+  <target name="testSetMultiple">
+    <mapperresult input="" output="a|b">
+      <scriptmapper language="javascript">
+        self.addMappedName("a");
+        self.addMappedName("b");
+      </scriptmapper>
+    </mapperresult>
+  </target>
+
+  <target name="testPassthrough">
+    <mapperresult input="a" output="A|a">
+      <scriptmapper language="javascript">
+        //relying on "a" to map to "A" on all locales.
+        self.addMappedName(source.toUpperCase());
+        self.addMappedName(source.toLowerCase());
+      </scriptmapper>
+    </mapperresult>
+  </target>
+  
+</project>

src/main/org/apache/tools/ant/types/defaults.properties

@@ -43,3 +43,4 @@ scriptselector=org.apache.tools.ant.types.optional.ScriptSelector
 scriptcondition=org.apache.tools.ant.types.optional.ScriptCondition
 xor=org.apache.tools.ant.taskdefs.condition.Xor
 parsersupports=org.apache.tools.ant.taskdefs.condition.ParserSupports
+scriptmapper=org.apache.tools.ant.types.optional.ScriptMapper

src/main/org/apache/tools/ant/types/optional/AbstractScriptComponent.java

@@ -0,0 +1,87 @@
+/** (C) Copyright 2005 Hewlett-Packard Development Company, LP
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+ For more information: www.smartfrog.org
+
+ */
+
+package org.apache.tools.ant.types.optional;
+
+import org.apache.tools.ant.ProjectComponent;
+import org.apache.tools.ant.util.ScriptRunner;
+
+import java.io.File;
+
+/**
+ * This is a {@link ProjectComponent} that has script support built in
+ * Use it as a foundation for scriptable things.
+ */
+public abstract class AbstractScriptComponent extends ProjectComponent {
+    /**
+     * script runner
+     */
+    private ScriptRunner runner = new ScriptRunner();
+
+    /**
+     * Get our script runner
+     * @return
+     */ 
+    public ScriptRunner getRunner() {
+        return runner;
+    }
+
+    /**
+     * Load the script from an external file ; optional.
+     *
+     * @param file the file containing the script source.
+     */
+    public void setSrc(File file) {
+        runner.setSrc(file);
+    }
+
+    /**
+     * The script text.
+     *
+     * @param text a component of the script text to be added.
+     */
+    public void addText(String text) {
+        runner.addText(text);
+    }
+
+    /**
+     * Defines the language (required).
+     *
+     * @param language the scripting language name for the script.
+     */
+    public void setLanguage(String language) {
+        runner.setLanguage(language);
+    }
+
+    /**
+     * Initialize the script runner. Calls this before running the system
+     */ 
+    protected void initScriptRunner() {
+        getRunner().bindToComponent(this);
+    }
+
+    /**
+     * Run a script
+     * @param execName name of the script
+     */
+    protected void executeScript(String execName) {
+        getRunner().executeScript(execName);
+    }
+}

src/main/org/apache/tools/ant/types/optional/ScriptCondition.java

@@ -25,49 +25,17 @@ import java.io.File;
 
 /**
  * A condition that lets you include script.
- * The condition component sets a bean "self", whose attribute "result"
+ * The condition component sets a bean "self", whose attribute "value"
  * must be set to true for the condition to succeed, false to fail.
  * The default is 'false'
  */
-public class ScriptCondition extends ProjectComponent implements Condition {
-
-    /**
-     * script runner
-     */
-    private ScriptRunner runner = new ScriptRunner();
+public class ScriptCondition extends AbstractScriptComponent implements Condition {
 
     /**
      * result field
      */
     private boolean value = false;
 
-    /**
-     * Load the script from an external file ; optional.
-     *
-     * @param file the file containing the script source.
-     */
-    public void setSrc(File file) {
-        runner.setSrc(file);
-    }
-
-    /**
-     * The script text.
-     *
-     * @param text a component of the script text to be added.
-     */
-    public void addText(String text) {
-        runner.addText(text);
-    }
-
-    /**
-     * Defines the language (required).
-     *
-     * @param language the scripting language name for the script.
-     */
-    public void setLanguage(String language) {
-        runner.setLanguage(language);
-    }
-
 
     /**
      * Is this condition true?
@@ -78,8 +46,8 @@ public class ScriptCondition extends ProjectComponent implements Condition {
      *          if an error occurs
      */
     public boolean eval() throws BuildException {
-        runner.bindToComponent(this);
-        runner.executeScript("ant_condition");
+        initScriptRunner();
+        executeScript("ant_condition");
         return getValue();
     }
 

src/main/org/apache/tools/ant/types/optional/ScriptMapper.java

@@ -0,0 +1,98 @@
+/** (C) Copyright 2005 Hewlett-Packard Development Company, LP
+
+ This library is free software; you can redistribute it and/or
+ modify it under the terms of the GNU Lesser General Public
+ License as published by the Free Software Foundation; either
+ version 2.1 of the License, or (at your option) any later version.
+
+ This library is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ Lesser General Public License for more details.
+
+ You should have received a copy of the GNU Lesser General Public
+ License along with this library; if not, write to the Free Software
+ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+
+ For more information: www.smartfrog.org
+
+ */
+
+package org.apache.tools.ant.types.optional;
+
+import org.apache.tools.ant.util.FileNameMapper;
+import org.apache.tools.ant.util.ScriptRunner;
+import org.apache.tools.ant.ProjectComponent;
+
+import java.util.ArrayList;
+
+/**
+ * Script support at map time. 
+ * @since Ant1.7
+ */
+public class ScriptMapper extends AbstractScriptComponent implements FileNameMapper {
+
+
+    ArrayList files;
+    static final String[] EMPTY_STRING_ARRAY = new String[0];
+
+
+    /**
+     * Sets the from part of the transformation rule.
+     *
+     * @param from a string.
+     */
+    public void setFrom(String from) {
+
+    }
+
+    /**
+     * Sets the to part of the transformation rule.
+     *
+     * @param to a string.
+     */
+    public void setTo(String to) {
+
+    }
+
+    /**
+     * Reset the list of files
+     */
+    public void clear() {
+        files=new ArrayList(1);
+    }
+
+    /**
+     * Add a mapped name
+     * @param mapping
+     */
+    public void addMappedName(String mapping) {
+        files.add(mapping);
+    }
+
+    /**
+     * Returns an array containing the target filename(s) for the given source
+     * file.
+     * <p/>
+     * <p>if the given rule doesn't apply to the source file, implementation
+     * must return null. SourceFileScanner will then omit the source file in
+     * question.</p>
+     *
+     * @param sourceFileName the name of the source file relative to some given
+     *                       basedirectory.
+     * @return an array of strings if the rule applies to the source file, or
+     *         null if it does not.
+     */
+
+    public String[] mapFileName(String sourceFileName) {
+        initScriptRunner();
+        getRunner().addBean("source", sourceFileName);
+        clear();
+        executeScript("ant_mapper");
+        if(files.size()==0) {
+            return null;
+        } else {
+            return (String[])files.toArray(EMPTY_STRING_ARRAY);
+        }
+    }
+}

src/testcases/org/apache/tools/ant/types/mappers/MapperResult.java

@@ -36,6 +36,11 @@ public class MapperResult extends Task {
     private String output;
     private FileNameMapper fileNameMapper;
 
+    /**
+     * The output on an empty string array
+     */
+    private static final String NULL_MAPPER_RESULT = "<NULL>";
+
     public void setFailMessage(String failMessage) {
         this.failMessage = failMessage;
     }
@@ -72,7 +77,7 @@ public class MapperResult extends Task {
         String[] result = fileNameMapper.mapFileName(input);
         String flattened;
         if (result == null) {
-            flattened = "<NULL>";
+            flattened = NULL_MAPPER_RESULT;
         } else {
             StringBuffer b = new StringBuffer();
             for (int i = 0; i < result.length; ++i) {

src/testcases/org/apache/tools/ant/types/optional/ScriptMapperTest.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright  2005 The Apache Software Foundation
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License");
+ *  you may not use this file except in compliance with the License.
+ *  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  Unless required by applicable law or agreed to in writing, software
+ *  distributed under the License is distributed on an "AS IS" BASIS,
+ *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *  See the License for the specific language governing permissions and
+ *  limitations under the License.
+ *
+ */
+
+package org.apache.tools.ant.types.optional;
+
+import org.apache.tools.ant.BuildFileTest;
+
+/**
+ * Test our script mapping
+ */
+public class ScriptMapperTest extends BuildFileTest {
+    public ScriptMapperTest(String name) {
+        super(name);
+    }
+
+    public void setUp() {
+        configureProject("src/etc/testcases/types/mappers/scriptmapper.xml");
+    }
+
+    public void testClear() {
+        executeTarget("testClear");
+    }
+    public void testSetMultiple() {
+        executeTarget("testSetMultiple");
+    }
+    public void testPassthrough() {
+        executeTarget("testPassthrough");
+    }
+}