| <!DOCTYPE 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 |
| |
| https://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 lang="en"> |
| |
| <head> |
| <link rel="stylesheet" type="text/css" href="../stylesheets/style.css"> |
| <title>PathConvert Task</title> |
| </head> |
| |
| <body> |
| |
| <h2 id="pathconvert">Pathconvert</h2> |
| <h3>Description</h3> |
| <p>Converts nested <a href="../Types/resources.html#collection">resource collections</a>, 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.</p> |
| <p>Nested <code><map></code> elements can be specified to map Windows drive letters to Unix |
| paths, and vice-versa.</p> |
| <p>More complex transformations can be achieved using a |
| nested <a href="../Types/mapper.html"><code><mapper></code></a> (<em>since Apache Ant |
| 1.6.2</em>).</p> |
| |
| <h3>Parameters</h3> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>targetos</td> |
| <td>The target architecture. Must be one |
| of <q>unix</q>, <q>windows</q>, <q>netware</q>, <q>tandem</q> or <q>os/2</q>. This is a |
| shorthand mechanism for specifying both <var>pathsep</var> and <var>dirsep</var> according |
| to the specified target architecture.</td> |
| <td>No</td> |
| </tr> |
| <tr> |
| <td>dirsep</td> |
| <td>The character(s) to use as the directory separator in the generated paths.</td> |
| <td>No; defaults to current JVM <code>File.separator</code></td> |
| </tr> |
| <tr> |
| <td>pathsep</td> |
| <td>The character(s) to use as the path-element separator in the generated paths.</td> |
| <td>No; defaults to current JVM <code>File.pathSeparator</code></td> |
| </tr> |
| <tr> |
| <td>property</td> |
| <td>The name of the property in which to place the converted path.</td> |
| <td>No, result will be logged if unset</td> |
| </tr> |
| <tr> |
| <td>refid</td> |
| <td>What to convert, given as a <a href="../using.html#references">reference</a> to |
| a <code><path></code>, <code><fileset></code>, <code><dirset></code>, |
| or <code><filelist></code> defined elsewhere</td> |
| <td>Yes, unless a nested <code><path></code> element is supplied</td> |
| </tr> |
| <tr> |
| <td>setonempty</td> |
| <td>Should the property be set, even if the result is the empty string?</td> |
| <td>No; default is <q>true</q></td> |
| </tr> |
| <tr> |
| <td>preserveduplicates</td> |
| <td>Whether to preserve duplicate resources. <em>Since Ant 1.8</em></td> |
| <td>No; default is <q>false</q></td> |
| </tr> |
| </table> |
| <h3>Parameters specified as nested elements</h3> |
| <h4>map</h4> |
| <p>Specifies the mapping of path prefixes between Unix and Windows.</p> |
| <table class="attr"> |
| <tr> |
| <th scope="col">Attribute</th> |
| <th scope="col">Description</th> |
| <th scope="col">Required</th> |
| </tr> |
| <tr> |
| <td>from</td> |
| <td>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. <em>Since Ant |
| 1.7.0</em>, on Windows this value is also insensitive to the slash style used for directories, |
| one can use <q>/</q> or <q>\</q>.</td> |
| <td>Yes</td> |
| </tr> |
| <tr> |
| <td>to</td> |
| <td>The replacement text to use when <var>from</var> is matched.</td> |
| <td>Yes</td> |
| </tr> |
| </table> |
| |
| <p>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.</p> |
| <p><strong>Note</strong>: 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 <var>from</var> values are prefixes of other <var>from</var> values.</p> |
| <h4>resource collections</h4> |
| <p>If the <var>refid</var> attribute is not specified, then one or more |
| nested <a href="../Types/resources.html#collection">resource collections</a> must be supplied.</p> |
| <h4>mapper</h4> |
| <p>A single nested <a href="../Types/mapper.html"><code><mapper></code></a> element can be |
| specified to perform any of various filename transformations (<em>since Ant 1.6.2</em>).</p> |
| |
| <h3>Examples</h3> |
| <p>In the examples below, assume that the <samp>${wl.home}</samp> property has the |
| value <samp>d:\weblogic</samp>, and <samp>${wl.home.unix}</samp> has the |
| value <samp>/weblogic</samp>.</p> |
| <h4>Example 1</h4> |
| <p>Here, the task</p> |
| <pre> |
| <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></pre> |
| <p>will generate the path shown below and store it in the property |
| named <code>wl.path.unix</code>.</p> |
| <pre class="output">/weblogic/lib/weblogicaux.jar:/weblogic/classes:/weblogic/mssqlserver4/classes:/WINNT/SYSTEM32</pre> |
| |
| <h4>Example 2</h4> |
| <p>Given a FileList defined as:</p> |
| <pre> |
| <filelist id="custom_tasks.jars" |
| dir="${env.HOME}/ant/lib" |
| files="njavac.jar,xproperty.jar"/></pre> |
| <p>then:</p> |
| <pre> |
| <pathconvert targetos="unix" property="custom_tasks.jars" refid="custom_tasks.jars"> |
| <map from="${env.HOME}" to="/usr/local"/> |
| </pathconvert></pre> |
| <p>will convert the list of files to the following Unix path:</p> |
| <pre class="output">/usr/local/ant/lib/njavac.jar:/usr/local/ant/lib/xproperty.jar</pre> |
| |
| <h4>Example 3</h4> |
| <p>Here, the names of files determined by the fileset (all files ending in <samp>.java</samp>) are |
| joined separated by comma, and the resulting list is placed into the |
| property <code>javafiles</code>. 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 <code>javadoc</code>, that requires a comma separated list of files.</p> |
| <pre> |
| <fileset dir="${src.dir}" id="src.files"> |
| <include name="**/*.java"/> |
| </fileset> |
| |
| <pathconvert pathsep="," property="javafiles" refid="src.files"/></pre> |
| |
| <h4>Example 4</h4> |
| <p>This task sets the property <code>prop</code> to <q>def|ghi</q> on Windows and on Unix.</p> |
| <pre> |
| <pathconvert property="prop" dirsep="|"> |
| <map from="${basedir}/abc/" to=""/> |
| <path location="abc/def/ghi"/> |
| </pathconvert></pre> |
| </body> |
| </html> |
