## Pathconvert

### Description

Converts a nested `<path>` or reference to a Path, FileSet, DirSet, or FileList into a path form for a particular platform, and stores the result in a given property. It can also be used when you need to convert a Path, FileSet, or DirSet into a list, separated by a given character, such as a comma or space, or, conversely, 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 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. | Yes, unless `pathsep` and/or `dirsep` are specified.
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. | Yes
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".

### 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. | 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.

#### path

If the `refid` attribute is not specified, then a nested `<path>` element must be supplied. See Path-like Structures for details.

#### 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.

Copyright © 2001-2004 The Apache Software Foundation. All rights Reserved.