blob: c025b72a335a35ad14e43ef72260c273ad841d33 [file] [log] [blame]
<!--
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>
<meta http-equiv="Content-Language" content="en-us"></meta>
<link rel="stylesheet" type="text/css" href="style.css">
<title>Props Ant Library</title>
</head>
<body>
<h2>Introduction</h2>
<p>This is a library of supplementary handlers for Ant properties resolution.</p>
<h2>Requirements</h2>
<p>The current version of this antlib is built against the Ant 1.8.0.</p>
<h2>Where is it?</h2>
<p>The source code for the library lives in the antlibs subspace of Ant's SVN -
<a href="http://svn.apache.org/viewvc/ant/antlibs/props/trunk/">http://svn.apache.org/viewvc/ant/antlibs/props/trunk/</a>.</p>
<h2>Installation</h2>
<p>If you are building this from sources, run the antlib target
and you'll get a file <code>ant-props.jar</code>.</p>
<p>There are several ways to use the tasks:</p>
<ul>
<li><p>The traditional way:
<pre>
&lt;typedef resource="org/apache/ant/props/antlib.xml"
classpath="YOUR-PATH-TO/ant-props.jar"/&gt;
</pre>
Using this approach the provided extensions will live in the default namespace.</p>
</li>
<li><p>Similar, but assigning a namespace URI
<pre>
&lt;typedef uri="antlib:org.apache.ant.props"
resource="org/apache/ant/props/antlib.xml"
classpath="YOUR-PATH-TO/ant-props.jar"/&gt;
</pre>
Placing the properties extensions into their own namespace, usable e.g.:
<pre>
&lt;project xmlns:props="antlib:org.apache.ant.props"&gt;
...
&lt;propertyhelper&gt;
&lt;props:nested /&gt;
&lt;/propertyhelper&gt;
</pre>
or a variation thereof.</p>
</li>
<li><p>Using Ant's autodiscovery. Place <code>ant-props.jar</code>
into a directory and use <code>ant -lib
DIR-CONTAINING-THE-JAR</code> or copy it into
<code>ANT_HOME/lib</code> - and then in your build file, simply
declare the namespace on the <code>project</code> tag:
<pre>
&lt;project xmlns:props="antlib:org.apache.ant.props"&gt;
</pre>
And all tasks of this library will automatically be available
in the <code>props</code> namespace without any <code>typedef</code>.</p>
</li>
</ul>
<h2>Tasks and Types</h2>
<p>The types provided are instances of
<code>org.apache.tools.ant.PropertyHelper.Delegate</code> and can be invoked using the
<code>&lt;<a href="http://ant.apache.org/manual/CoreTasks/propertyhelper.html">propertyhelper</a>&gt;</code>
task provided by Ant:</p>
<table border="1" cellspacing="0" cellpadding="2" width="100%">
<tr>
<th width="15%">Delegate</th>
<th width="15%">Delegate Type</th>
<th width="70%">Description</th>
</tr>
<tr>
<a name="nested" />
<td align="center">nested</td>
<td align="center">PropertyExpander</td>
<td>Implements nested property expansion; e.g. <code>${${double-expand-me}}</code>.</td>
</tr>
<tr>
<a name="stringops" />
<td align="center"><a href="stringops.html">stringops</a></td>
<td align="center">PropertyEvaluator</td>
<td>Implements *nix shell-inspired string operations.</td>
</tr>
<tr>
<a name="types" />
<td align="center">types</td>
<td align="center">PropertyEvaluator</td>
<td>Given <code><em>type</em>(<em>arg</em>)</code>, attempts to invoke
<code><em>type</em></code> constructor <code>(Project, <em>arg</em>)</code>,
then <code>(<em>arg</em>)</code>.</td>
</tr>
<tr>
<a name="conditions" />
<td align="center">conditions</td>
<td align="center">PropertyEvaluator</td>
<td>Given <code><em>condition</em>([<em>arg1=value1</em>,<em>arg2=value2</em>,...])</code>,
attempts to invoke an Ant condition of the given name
setting the given attibute values and evaluates to either
Boolean.TRUE or Boolean.FALSE. Usage looks
like <em>${os(family=unix)}</em> / <em>${!os(family=unix)}</em>.
Additionally, logical operations are supported.
In order of precedence, these are !, &, ^, and |, with +
being a secondary alias for & since & is a special character
to the XML format. When you want to combine logical operations
with typed Ant conditions, the typed conditions should be
specified as nested properties and the <a href="#nested">nested
evaluator</a> should be included with your active
PropertyHelper delegates.
This is probably most useful together with the
<code>if</code>/<code>unless</code> attributes of tasks or targets.
</td>
</tr>
<tr>
<a name="encodeURL" />
<td align="center">encodeURL</td>
<td align="center">PropertyEvaluator</td>
<td>Given <code>encodeURL:<em>arg</em></code>, attempts to encode <em>arg</em>
as a URL per the suggested approach in the javadoc API of <code>java.net.URL</code>.
</td>
</tr>
</table>
<hr/>
</body>
</html>