Native2Ascii Task

## Native2Ascii

### Description

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.

Files in the directory src 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 includes and excludes attributes. For more information on file matching patterns, see the section on directory based tasks. If no encoding is specified, the default encoding for the JVM is used. If ext 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 `<mapper>` element. By default an identity mapper will be used. If dest and src point to the same directory, the ext attribute or a nested `<mapper>` is required.

This task forms an implicit FileSet, and supports most attributes of `<fileset>` (dir becomes src) as well as nested `<include>`, `<exclude>`, and `<patternset>` elements.

It is possible to use different converters. This can be selected with the implementation attribute or a nested element. Here are the choices of the attribute:

- default—the default converter for the platform: kaffe when run on Kaffe, builtin otherwise.
- sun—used to be the standard converter of the JDK 8 or earlier
- kaffe—the standard converter of Kaffe
- builtin—Ant's internal implementation. Since Ant 1.9.8

Attribute | Description | Required
--- | --- | ---
reverse | Reverse the sense of the conversion, i.e. convert from ASCII to native Only supported by the sun and builtin converters | No
encoding | The native encoding the files are in | No; defaults to default JVM character encoding
src | The directory to find files in; default is basedir | No
dest | The directory to output file to | Yes
ext | File extension to use in renaming output files | No
includes | Comma- or space-separated list of patterns of files that must be included. | No; defaults to all (**)
includesfile | Name of a file. Each line of this file is taken to be an include pattern | No
excludes | Comma- or space-separated list of patterns of files that must be excluded. | No; defaults to default excludes or none if defaultexcludes is no
excludesfile | Name of a file. Each line of this file is taken to be an exclude pattern | No
defaultexcludes | Indicates whether default excludes should be used or not (yes|no). | No; defaults to yes
implementation | The converter implementation to use. (See the above list of valid converters.) | No; defaults to default converter for the current JVM

### Parameters specified as nested elements

#### arg

You can specify additional command line arguments for the converter with nested `<arg>` elements. These elements are specified like Command-line Arguments but have an additional attribute that can be used to enable arguments only if a given converter implementation will be used.

Attribute | Description | Required
--- | --- | ---
value | See Command-line Arguments. | Exactly one of these
line
file
path
implementation | 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 list of valid compilers.) | No

#### implementationclasspath

Since Apache Ant 1.8.0

A path-like structure 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.

#### Any nested element of a type that implements Native2AsciiAdapter

Since Ant 1.8.0

If a defined type implements the `Native2AsciiAdapter` interface a nested element of that type can be used as an alternative to the implementation attribute.

### Examples

Convert all files in the directory `srcdir` ending in `.eucjis` from the EUCJIS encoding to ASCII and rename them to end in `.java`.

    <native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
                  includes="**/*.eucjis" ext=".java"/>

Convert all the files ending in `.java` in the directory `native/japanese` to ASCII, placing the results in the directory `src`. The names of the files remain the same.

    <native2ascii encoding="EUCJIS" src="native/japanese" dest="src"
                  includes="**/*.java"/>

If you want to use a custom `Native2AsciiAdapter` `org.example.MyAdapter` you can either use the implementation attribute:

    <native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
                  includes="**/*.eucjis" ext=".java"
                  implementation="org.example.MyAdapter"/>

or a define a type and nest this into the task like in:

    <componentdef classname="org.example.MyAdapter"
                  name="myadapter"/>
    <native2ascii encoding="EUCJIS" src="srcdir" dest="srcdir"
                  includes="**/*.eucjis" ext=".java">
        <myadapter/>
    </native2ascii>

in which case your `native2ascii` adapter can support attributes and nested elements of its own.