mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
252 lines
9.1 KiB
HTML
252 lines
9.1 KiB
HTML
<!--
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
this work for additional information regarding copyright ownership.
|
|
The ASF licenses this file to You 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.
|
|
-->
|
|
<html>
|
|
<head><link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
|
<title>Native2Ascii Task</title></head>
|
|
<body>
|
|
<h2>Native2Ascii</h2>
|
|
|
|
<h3>Description:</h3>
|
|
|
|
<p>
|
|
Converts files from native encodings to ASCII with escaped Unicode.
|
|
A common usage is to convert source files maintained in a native
|
|
operating system encoding, to ASCII prior to compilation.
|
|
</p>
|
|
|
|
<p>
|
|
Files in the directory <em>src</em>
|
|
are converted from a native encoding to ASCII.
|
|
By default, all files in the directory are converted.
|
|
However, conversion may be limited to selected files using
|
|
<em>includes</em> and <em>excludes</em> attributes.
|
|
For more information on file matching patterns,
|
|
see the section on
|
|
<a href="../dirtasks.html#directorybasedtasks">directory based tasks</a>.
|
|
If no <em>encoding</em> is specified,
|
|
the default encoding for the JVM is used.
|
|
If <em>ext</em> is specified, then output files are renamed
|
|
to use it as a new extension.
|
|
More sophisticated file name translations can be achieved using a nested
|
|
<em><code><mapper></code></em> element. By default an
|
|
<a href="../Types/mapper.html#identity-mapper">identity mapper</a> will be used.
|
|
If <em>dest</em> and <em>src</em> point to the same directory,
|
|
the <em>ext</em> attribute or a nested <em><code><mapper></code></em>
|
|
is required.
|
|
</p>
|
|
|
|
<p>
|
|
This task forms an implicit <a href="../Types/fileset.html">File Set</a>,
|
|
and supports most attributes of <code><fileset></code>
|
|
(<code>dir</code> becomes <code>src</code>) as well as
|
|
nested <code><include></code>, <code><exclude></code>,
|
|
and <code><patternset></code> elements.
|
|
</p>
|
|
|
|
<p>It is possible to use different converters. This can be selected
|
|
with the <code>implementation</code> attribute or a nested element.
|
|
<a name="implementationvalues">Here are the choices of the attribute</a>:</p>
|
|
<ul>
|
|
<li>default - the default converter for the platform - kaffee
|
|
when run on Kaffee, builtin if JDK9 or newer is detected, sun
|
|
otherwise.</li>
|
|
<li>sun (the standard converter of the JDK < 9)</li>
|
|
<li>kaffe (the standard converter
|
|
of <a href="http://www.kaffe.org" target="_top">Kaffe</a>)</li>
|
|
<li>builtin - Ant's internal implementation used for
|
|
JDK9+. <em>since ant 1.9.8</em></li>
|
|
</ul>
|
|
|
|
<table border="1" cellpadding="2" cellspacing="0">
|
|
<tr>
|
|
<td><b>Attribute</b></td>
|
|
<td><b>Description</b></td>
|
|
<td><b>Required</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td>reverse</td>
|
|
<td>Reverse the sense of the conversion,
|
|
i.e. convert from ASCII to native <b>only supported by the
|
|
sun and builtin converters</b></td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>encoding</td>
|
|
<td>The native encoding the files are in
|
|
(default is the default encoding for the JVM)</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>src</td>
|
|
<td>The directory to find files in (default is <em>basedir</em>)</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>dest</td>
|
|
<td>The directory to output file to</td>
|
|
<td align="center">Yes</td>
|
|
</tr>
|
|
<tr>
|
|
<td>ext</td>
|
|
<td>File extension to use in renaming output files</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>defaultexcludes</td>
|
|
<td>indicates whether default excludes should be used or not
|
|
("yes"/"no").
|
|
Default excludes are used when omitted.
|
|
</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>includes</td>
|
|
<td>comma- or space-separated list of patterns of files that must be
|
|
included. All files are included when omitted.</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>includesfile</td>
|
|
<td>the name of a file. Each line of this file is
|
|
taken to be an include pattern</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludes</td>
|
|
<td>comma- or space-separated list of patterns of files that must be excluded.
|
|
No files (except default excludes) are excluded when omitted.</td>
|
|
<td align="center">No</td>
|
|
</tr>
|
|
<tr>
|
|
<td>excludesfile</td>
|
|
<td>the name of a file. Each line of this file is
|
|
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><arg></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>
|
|
|
|
<h4>implementationclasspath <em>since Apache Ant 1.8.0</em></h4>
|
|
|
|
<p>A <a href="../using.html#path">PATH like structure</a> holding the
|
|
classpath to use when loading the converter implementation if a
|
|
custom class has been specified. Doesn't have any effect when
|
|
using one of the built-in converters.</p>
|
|
|
|
<h4>Any nested element of a type that implements Native2AsciiAdapter
|
|
<em>since Ant 1.8.0</em></h4>
|
|
|
|
<p>If a defined type implements the <code>Native2AsciiAdapter</code>
|
|
interface a nested element of that type can be used as an
|
|
alternative to the <code>implementation</code> attribute.</p>
|
|
|
|
<h3>Examples</h3>
|
|
|
|
<pre>
|
|
<native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
|
|
includes="**/*.eucjis" ext=".java"/>
|
|
</pre>
|
|
|
|
<p>
|
|
Converts all files in the directory <em>srcdir</em>
|
|
ending in <code>.eucjis</code> from the EUCJIS encoding to ASCII
|
|
and renames them to end in <code>.java</code>.
|
|
</p>
|
|
|
|
<pre>
|
|
<native2ascii encoding="EUCJIS" src="native/japanese" dest="src"
|
|
includes="**/*.java"/>
|
|
</pre>
|
|
|
|
<p>
|
|
Converts all the files ending in <code>.java</code>
|
|
in the directory <em>native/japanese</em> to ASCII,
|
|
placing the results in the directory <em>src</em>.
|
|
The names of the files remain the same.
|
|
</p>
|
|
|
|
<p>If you want to use a custom
|
|
Native2AsciiAdapter <code>org.example.MyAdapter</code> you can either
|
|
use the implementation attribute:</p>
|
|
<pre>
|
|
<native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
|
|
includes="**/*.eucjis" ext=".java"
|
|
implementation="org.example.MyAdapter"/>
|
|
</pre>
|
|
<p>or a define a type and nest this into the task like in:</p>
|
|
<pre>
|
|
<componentdef classname="org.example.MyAdapter"
|
|
name="myadapter"/>
|
|
<native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
|
|
includes="**/*.eucjis" ext=".java">
|
|
<myadapter/>
|
|
</native2ascii>
|
|
</pre>
|
|
<p>in which case your native2ascii adapter can support attributes and
|
|
nested elements of its own.</p>
|
|
</body>
|
|
|
|
</html>
|