PathConvert Task

## Pathconvert

### Description

Converts nested ResourceCollections, or a reference to just one, into a path form for a particular platform, optionally storing the result into a given property. It can also be used when you need to convert a Resource Collection into a list, separated by a given character, such as a comma or space, or, conversely, e.g. to convert a list of files in a FileList into a path.

Nested `<map>` elements can be specified to map Windows drive letters to Unix paths, and vice-versa.

More complex transformations can be achieved using a nested `<mapper>` (since Apache Ant 1.6.2).

### Parameters

Attribute | Description | Required
targetos | The target architecture. Must be one of 'unix', 'windows', 'netware', 'tandem' or 'os/2'. This is a shorthand mechanism for specifying both `pathsep` and `dirsep` according to the specified target architecture. | No
dirsep | The character(s) to use as the directory separator in the generated paths. | No, defaults to current JVM `File.separator`
pathsep | The character(s) to use as the path-element separator in the generated paths. | No, defaults to current JVM `File.pathSeparator`
property | The name of the property in which to place the converted path. | No, result will be logged if unset
refid | What to convert, given as a reference to a `<path>`, `<fileset>`, `<dirset>`, or `<filelist>` defined elsewhere | No; if omitted, a nested `<path>` element must be supplied.
setonempty | Should the property be set, even if the result is the empty string? | No; default is "true".
preserveduplicates | Whether to preserve duplicate resources. Since Ant 1.8 | No; default "false".

### Parameters specified as nested elements

#### map

Specifies the mapping of path prefixes between Unix and Windows.

Attribute | Description | Required
from | The prefix to match. Note that this value is case-insensitive when the build is running on a Windows platform and case-sensitive when running on a Unix platform. Since Ant 1.7.0, on Windows this value is also insensitive to the slash style used for directories, one can use '/' or '\'. | Yes
to | The replacement text to use when `from` is matched. | Yes

Each map element specifies a single replacement map to be applied to the elements of the path being processed. If no map entries are specified, then no path prefix mapping is performed.

Note: The map elements are applied in the order specified, and only the first matching map element is applied. So, the ordering of your map elements can be important, if any `from` values are prefixes of other `from` values.

#### Resource Collections

If the `refid` attribute is not specified, then one or more nested Resource Collections must be supplied.

#### mapper

A single nested `<mapper>` element can be specified to perform any of various filename transformations (since Ant 1.6.2).

### Examples

In the examples below, assume that the `${wl.home}` property has the value `d:\weblogic`, and `${wl.home.unix}` has the value `/weblogic`.

#### Example 1

        <path id="wl.path">
          <pathelement location="${wl.home}/lib/weblogicaux.jar"/>
          <pathelement location="${wl.home}/classes"/>
          <pathelement location="${wl.home}/mssqlserver4/classes"/>
          <pathelement location="c:\winnt\System32"/>
        </path>

        <pathconvert targetos="unix" property="wl.path.unix" refid="wl.path">
          <map from="${wl.home}" to="${wl.home.unix}"/>
          <map from="c:" to=""/>
        </pathconvert>

will generate the path shown below and store it in the property named `wl.path.unix`.

    /weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32

#### Example 2

Given a FileList defined as:

      <filelist id="custom_tasks.jars"
            dir="${env.HOME}/ant/lib"
            files="njavac.jar,xproperty.jar"/>

then:

        <pathconvert targetos="unix" property="custom_tasks.jars" refid="custom_tasks.jars">
          <map from="${env.HOME}" to="/usr/local"/>
        </pathconvert>

will convert the list of files to the following Unix path:

    /usr/local/ant/lib/njavac.jar:/usr/local/ant/lib/xproperty.jar

#### Example 3

        <fileset dir="${src.dir}" id="src.files">
          <include name="**/*.java"/>
        </fileset>

        <pathconvert pathsep="," property="javafiles" refid="src.files"/>

This example takes the set of files determined by the fileset (all files ending in `.java`), joins them together separated by commas, and places the resulting list into the property `javafiles`. The directory separator is not specified, so it defaults to the appropriate character for the current platform. Such a list could then be used in another task, like `javadoc`, that requires a comma separated list of files.

#### Example 4

        <pathconvert property="prop" dirsep="|">
          <map from="${basedir}/abc/" to=''/>
          <path location="abc/def/ghi"/>
        </pathconvert>

This example sets the property "prop" to "def|ghi" on Windows and on Unix.