How-To Guides
Getting Started
Policy Strategies
Format Strings
Extending Antlion
First Tutorial: Simple
Ant Tasks
inner processors
inner repositories
Optional Tasks
About optional tasks
Prev   Next  
Format Strings

Antlion uses a concept called format strings throughout much of the configuration of policies. These can be thought of as similar to Ant property replacements, but their values are based on each library and its entries, rather than a global pool of properties.

In Antlion, a format string is a specific line of text that contains placeholders for <library> and <lib-entry> attributes (depending on the context).

To better understand what happens, let's look at a <library-repository> as an example:

<library-repository id="3rdparty.repository"
  <format text="[[[group]/[version]/[artifact]-[version].[x]" />

Here, the basedir attribute uses the Ant property replacement, which will look up the 3rdparty.dir property from the current project when the <library-repository> task is executed, and replace the string "${3rdparty.dir}" with the value of the property.

Now let's see how Antlion works with format strings. The <format> element defines the format string "[[[group]/[version]/[artifact]-[version].[x] ]". Antlion uses the "[" and "]" pair of characters to denote an attribute replacement. If you have a need to actually insert a "[" character into the text, then you can escape it using two "[" characters ("[["), which will be transformed into a single "[", just like you can escape a "$" in Ant using two "$" characters ("$$").

In order to see how this format string gets parsed, let's look at some context:

	<lib-entry group="G" version="1.0"
	    artifact="widget" type="dtd" />

When the repository attempts to look up this particular library entry, it uses this entry's defined attributes in the formatting of the above format string:

  1. The beginning [[ characters are escaped into a single "[" character.
  2. [group] is replaced with the corresponding group attribute value "G".
  3. the two places where [version] appears are replaced with the corresponding version attribute value "1.0".
  4. [artifact] is replaced with the corresponding artifact attribute value "widget".
  5. Since there is no attribute definition for [x], the string is left in-place.
  6. Even though the type attribute is defined in the lib-entry, it isn't used in the formatted string.
  7. A closing "]" without an accompanied openeing "[" will not be considered a special character.
Therefore, the final generated string would look like:
[G/1.0/widget-1.0.[x] ]
In this situation, however, the [x] was not found in the library entry's attribute context. If one or more attribute replacement cannot be looked up, then the replacement will fail. Therefore, this library entry for this repository will not be considered a match, and won't be discovered. This differs from the standard Ant property behavior.

Changing the token delimiters

As you've seen, the default token delimiters for the format string are '[' and ']'. However, these can be swapped out, as shown in the following example:

<format text="(group)-(version).(type)"
    startToken="(" endToken=")" />
These can even be the same character:
<format text="@group@-0.9.0.@type@"
    startToken="@" endToken="@" />

The escaping rules still apply. Thus, the format:

<format text="@group@-@@-0.9.0@@@type@"
    startToken="@" endToken="@" />
for "group" = "g", "version" = "v", and "type" = "t", would turn into g-@-v@t.

Custom Formatting

If the base formatter isn't sufficient for your needs, then you can exchange it for a custom type. Antlion searches the Ant type definitions (not task definitions!) for the registered type named .antlion.token-formatter-factory. If found, Antlion will create a new instance, which must be of type net.sf.antlion.format.v1.TokenFormatterFactory. This factory will be used for creating new formatters.

So, this means that only one formatter factory can be used at a time by Antlion. It also implies that the type definition must share the same class loader as Antlion. See the documentation here to learn about your options in loading Antlion extensions into Ant.

Prev   Next  
Document version $Revision: 1.6 $ $Date: 2006/02/03 00:34:34 $

SourceForge Logo
Copyright © 2004-2006, The Antlion Project