Make native2ascii a full-blown facade task, add docs

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

WHATSNEW

@@ -198,6 +198,8 @@ Other changes:
 
 * Added length task to get strings' and files' lengths.
 
+* <natice2ascii> now also supports Kaffe's version.
+
 Fixed bugs:
 -----------
 

docs/manual/OptionalTasks/native2ascii.html

@@ -40,6 +40,15 @@
       and <code>&lt;patternset&gt;</code> elements.
     </p>
 
+    <p>It is possible to use different converters. This can be selected
+      with the <code>implementation</code> attribute.
+      <a name="implementationvalues">Here are the choices</a>:</p>
+    <ul>
+      <li>default - the default converter (kaffe or sun) for the platform.</li>
+      <li>sun (the standard converter of the JDK)</li>
+      <li>kaffe (the standard converter of <a href="http://www.kaffe.org" target="_top">Kaffe</a>)</li>
+    </ul>
+
     <table border="1" cellpadding="2" cellspacing="0">
       <tr>
         <td><b>Attribute</b></td>
@@ -49,7 +58,8 @@
       <tr>
         <td>reverse</td>
         <td>Reverse the sense of the conversion,
-          i.e. convert from ASCII to native</td>
+          i.e. convert from ASCII to native <b>only supported by the
+            sun converter</b></td>
         <td align="center">No</td>
       </tr>
       <tr>
@@ -105,8 +115,57 @@
           taken to be an exclude pattern</td>
         <td align="center">No</td>
       </tr>
+      <tr>
+        <td valign="top">implementation</td>
+        <td valign="top">The converter implementation to use.
+          If this attribute is not set, the default converter for the
+          current VM will be used.  (See the above <a
+          href="#implementationvalues">list</a> of valid converters.)</td>
+        <td align="center" valign="top">No</td>
+      </tr>
     </table>
 
+<h3>Parameters specified as nested elements</h3>
+
+<h4>arg</h4>
+
+<p>You can specify additional command line arguments for the converter
+with nested <code>&lt;arg&gt;</code> elements.  These elements are
+specified like <a href="../using.html#arg">Command-line Arguments</a>
+but have an additional attribute that can be used to enable arguments
+only if a given converter implementation will be used.</p>
+
+<table border="1" cellpadding="2" cellspacing="0">
+<tr>
+  <td width="12%" valign="top"><b>Attribute</b></td>
+  <td width="78%" valign="top"><b>Description</b></td>
+  <td width="10%" valign="top"><b>Required</b></td>
+</tr>
+  <tr>
+    <td valign="top">value</td>
+    <td align="center" rowspan="4">See
+    <a href="../using.html#arg">Command-line Arguments</a>.</td>
+    <td align="center" rowspan="4">Exactly one of these.</td>
+  </tr>
+  <tr>
+    <td valign="top">line</td>
+  </tr>
+  <tr>
+    <td valign="top">file</td>
+  </tr>
+  <tr>
+    <td valign="top">path</td>
+  </tr>
+  <tr>
+    <td valign="top">implementation</td>
+    <td>Only pass the specified argument if the chosen converter
+    implementation matches the value of this attribute.  Legal values
+    are the same as those in the above <a
+    href="#implementationvalues">list</a> of valid compilers.)</td>
+    <td align="center">No</td>
+  </tr>
+</table>
+
     <h3>Examples</h3>
 
     <pre>
@@ -133,6 +192,6 @@
     </p>
   </body>
 <hr>
-<p align="center">Copyright &copy; 2000-2002,2004 The Apache Software Foundation. All rights
+<p align="center">Copyright &copy; 2000-2002,2004-2005 The Apache Software Foundation. All rights
 Reserved.</p>
 </html>

src/main/org/apache/tools/ant/taskdefs/optional/Native2Ascii.java

@@ -29,6 +29,8 @@ import org.apache.tools.ant.types.Mapper;
 import org.apache.tools.ant.util.FileNameMapper;
 import org.apache.tools.ant.util.IdentityMapper;
 import org.apache.tools.ant.util.SourceFileScanner;
+import org.apache.tools.ant.util.facade.FacadeTaskHelper;
+import org.apache.tools.ant.util.facade.ImplementationSpecificArgument;
 
 /**
  * Converts files from native encodings to ASCII.
@@ -44,6 +46,11 @@ public class Native2Ascii extends MatchingTask {
     private String extension = null;  // Extension of output files if different
 
     private Mapper mapper;
+    private FacadeTaskHelper facade = null;
+
+    public Native2Ascii() {
+        facade = new FacadeTaskHelper(Native2AsciiAdapterFactory.getDefault());
+    }
 
     /**
      * Flag the conversion to run in the reverse sense,
@@ -114,6 +121,19 @@ public class Native2Ascii extends MatchingTask {
         this.extension = ext;
     }
 
+    /**
+     * Choose the implementation for this particular task.
+     * @param compiler the name of the compiler
+     * @since Ant 1.6.3
+     */
+    public void setImplementation(String impl) {
+        if ("default".equals(impl)) {
+            facade.setImplementation(Native2AsciiAdapterFactory.getDefault());
+        } else {
+            facade.setImplementation(impl);
+        }        
+    }
+
     /**
      * Defines the FileNameMapper to use (nested mapper element).
      *
@@ -139,6 +159,18 @@ public class Native2Ascii extends MatchingTask {
         createMapper().add(fileNameMapper);
     }
 
+    /**
+     * Adds an implementation specific command-line argument.
+     * @return a ImplementationSpecificArgument to be configured
+     *
+     * @since Ant 1.6.3
+     */
+    public ImplementationSpecificArgument createArg() {
+        ImplementationSpecificArgument arg =
+            new ImplementationSpecificArgument();
+        facade.addImplementationArgument(arg);
+        return arg;
+    }
 
     /**
      * Execute the task
@@ -230,12 +262,23 @@ public class Native2Ascii extends MatchingTask {
 
         log("converting " + srcName, Project.MSG_VERBOSE);
         Native2AsciiAdapter ad = 
-            Native2AsciiAdapterFactory.getAdapter(null, this);
+            Native2AsciiAdapterFactory.getAdapter(facade.getImplementation(),
+                                                  this);
         if (!ad.convert(this, srcFile, destFile)) {
             throw new BuildException("conversion failed");
         }
     }
 
+    /**
+     * Returns the (implementation specific) settings given as nested
+     * arg elements.
+     *
+     * @since Ant 1.6.3
+     */
+    public String[] getCurrentArgs() {
+        return facade.getArgs();
+    }
+
     private class ExtMapper implements FileNameMapper {
 
         public void setFrom(String s) {

src/main/org/apache/tools/ant/taskdefs/optional/native2ascii/DefaultNative2Ascii.java

@@ -50,7 +50,8 @@ public abstract class DefaultNative2Ascii implements Native2AsciiAdapter {
     /**
      * Sets up the initial command line.
      *
-     * <p>only the -encoding argument gets handled here.</p>
+     * <p>only the -encoding argument and nested arg elements get
+     * handled here.</p>
      *
      * @param cmd Command line to add to
      * @param args provides the user-setting and access to Ant's
@@ -62,6 +63,7 @@ public abstract class DefaultNative2Ascii implements Native2AsciiAdapter {
             cmd.createArgument().setValue("-encoding");
             cmd.createArgument().setValue(args.getEncoding());
         }
+        cmd.addArguments(args.getCurrentArgs());
     }
 
     /**