## Introduction

This is a library of supplementary handlers for Ant properties resolution.

## Requirements

The current version of this antlib is built against the Ant 1.8.0.

## Where is it?

The source code for the library lives in the antlibs subspace of Ant's git - https://gitbox.apache.org/repos/asf?p=ant-antlibs-props.git.

## Installation

If you are building this from sources, run the antlib target and you'll get a file `ant-props.jar`.

There are several ways to use the tasks:

- The traditional way:

                <typedef resource="org/apache/ant/props/antlib.xml"
                         classpath="YOUR-PATH-TO/ant-props.jar"/>

  Using this approach the provided extensions will live in the default namespace.

- Similar, but assigning a namespace URI

                <typedef uri="antlib:org.apache.ant.props"
                         resource="org/apache/ant/props/antlib.xml"
                         classpath="YOUR-PATH-TO/ant-props.jar"/>

  Placing the properties extensions into their own namespace, usable e.g.:

                <project xmlns:props="antlib:org.apache.ant.props">
                  ...
                  <propertyhelper>
                    <props:nested />
                  </propertyhelper>

  or a variation thereof.

- Using Ant's autodiscovery. Place `ant-props.jar` into a directory and use `ant -lib DIR-CONTAINING-THE-JAR` or copy it into `ANT_HOME/lib` - and then in your build file, simply declare the namespace on the `project` tag:

                <project xmlns:props="antlib:org.apache.ant.props">

  And all tasks of this library will automatically be available in the `props` namespace without any `typedef`.

## Tasks and Types

The types provided are instances of `org.apache.tools.ant.PropertyHelper.Delegate` and can be invoked using the `<propertyhelper>` task provided by Ant:

Delegate | Delegate Type | Description
--- | --- | ---
nested | PropertyExpander | Implements nested property expansion; e.g. `${${double-expand-me}}`.
stringops | PropertyEvaluator | Implements *nix shell-inspired string operations.
types | PropertyEvaluator | Given `type(arg)`, attempts to invoke `type` constructor `(Project, arg)`, then `(arg)`.
conditions | PropertyEvaluator | Given `condition([arg1=value1,arg2=value2,...])`, 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 ${os(family=unix)} / ${!os(family=unix)}. 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 nested evaluator should be included with your active PropertyHelper delegates. This is probably most useful together with the `if`/`unless` attributes of tasks or targets.
encodeURL | PropertyEvaluator | Given `encodeURL:arg`, attempts to encode arg as a URL per the suggested approach in the javadoc API of `java.net.URL`.