Using Antlib props in Ant 1.8

Ant 1.8 introduced the concept of Property Helpers to provide user defined property handlers and extensions. The best place for Ant info on this subject is http://ant.apache.org/manual/properties.html#propertyHelper in the Ant manual http://ant.apache.org/manual/index.html.

An existing Ant project named props (http://ant.apache.org/antlibs/props/index.html) provides some pre-defined property handlers that are very useful. Especially the "nested" that supports nested properties and "stringops" which performs *nix like string handling.

However, the Ant manual doesn't really define how to use them. So this post is intended to provide a quick overview. First, Antlib props is not distributed in binary form, so you need to build the jar before use. My path to using Antlib props consisted of the following top-level steps, which are further described below:
1. Create Ant script to pull and build Antlib props source
2. Build Antlib props jar and install for use by Ant
3. Add props to Ant propertyhelper and test

Create Ant Script to pull and build Antlib props source
I chose to use Ant to download and build the source, because I don't have a Subversion client (the horror). To do this I needed to enable Subversion support from Ant. For this task I used SvnAnt from http://subclipse.tigris.org/svnant.html, I picked version 1.3. I extracted this to a convenient local directory I'll call PATH_TO_SVNANT.
SvnAnt requires the svnjavahl (since I don't have a local Subversion client). I downloaded svcClientAdapter from http://subclipse.tigris.org/servlets/ProjectDocumentList?folderID=1926&expandFolder=1926&folderID=2240 for the svnjavahl.dll.
I extracted this to a second convenient local directory I'll call PATH_TO_SVCLIENTADAPTER.
Next, to get things going, I added these libraries temporarily to my PATH with:

set PATH=%PATH%;PATH_TO_SVNCLIENTADAPTER\lib

Next I created the following build.xml file to complete step 1:


<project name="antlib" default="full" basedir=".">

<property name="props.path" value="props"/>

<typedef resource="org/tigris/subversion/svnant/svnantlib.xml" classpath="svnant.jar" />

<target name="get" description="Get the source using Subversion">
<svn>
<checkout url="https://svn.apache.org/repos/asf/ant/antlibs/props/trunk/"
destPath="${props.path}"/>
</svn>
</target>

<target name="build"
description="Create the antlib jar from source">
<ant dir="${props.path}" target="antlib" inheritAll="false"/>
</target>

<target name="full" description="Download antlibs and build"
depends="get,build"/>

<target name="fullclean" description="Cleanup build and download">
<delete dir="${props.path}"/>
</target>
</project>


Build Antlib props jar and install for use by Ant
With the Ant script in place, now we can build the library and make it available for use in our development environment. As you see, SvnAnt is dependent on svnant.jar. To make this available, simply include it on the Ant run line with the -l option, such as:

ant -lib PATH_TO_SVNANT\lib full

If you've followed the instructions to this point find the Antlib props jar at: props\build\lib\ant-props-1.0Alpha.jar

The easiest thing to do now is copy jar this into your %ANT_HOME%\lib directory. There are other options that I'm not going into here. Viola - Antlib props is ready to use.

Add props to Ant propertyhelper and test
Now that you have Antlib props setup, how do you use it. The instructions are located in the props\docs\index.html retrieved during the build above. But here is a quick sample for using the nested property delegate.
This relies on the use of namespaces in Ant for clarity. Use at your discretion:

<project xmlns:props="antlib:org.apache.ant.props">
<typedef uri="antlib:org.apache.ant.props"
resource="org/apache/ant/props/antlib.xml"
classpath="ant-props-1.0Alpha.jar"/>

<propertyhelper>
<props:nested />
</propertyhelper>

<property name="william" value="darby" />
<property name="will" value="william" />

<target name="will">
<echo>What is Will's last name: ${${will}}</echo>


That's it. Now you can use nested properties and other Antlib props cool helpers.
>ant will

will:
[echo] What is Will's last name: darby

BUILD SUCCESSFUL
Total time: 2 seconds