Ant: The Definitive Guide

Argument DataType

The apply, exec, and java tasks accept nested <arg> elements, specifying command-line arguments for their respective process calls. The org.apache.tools.ant.types.Commandline.Argument class implements this DataType.^[27] If several <arg> elements are specified, each is treated as a separate argument to the process call. Following is a list of all <arg> attributes:

file (all, File,*)

A filename as a single argument. In the buildfile, this filename is relative to the current working directory. The “current working directory” varies depending on the context this type is used in. The name is converted to an absolute path when passed as an argument.

line (all, String,*)

A space-delimited list of multiple arguments.

path (all, Path, *)

A path, as explained later in the section “Path DataType.”

value (all, String, *)

A single command-line argument. Use this if your argument has spaces, but you still want to treat it as a single value.

Exactly one of these attributes is required.

Example

Let’s look at a complete buildfile to put things into perspective. In Example 4-1, we use the java task to invoke Apache’s Xalan XSLT processor, transforming an XML file into HTML using XSLT.^[28] As you might expect, the java task invokes any Java class with a main( ) method. Use <arg> elements to pass arguments to the java task.

Example 4-1. <arg> usage

<?xml version="1.0"?>
<project name="arg demo" default="xslt" basedir=".">

  <property name="xalan.home" value="C:/java/xalan-j_2_1_0"/>
  <property name="xalan.jar" value="${xalan.home}/bin/xalan.jar"/>
  <property name="xerces.jar" value="${xalan.home}/bin/xerces.jar"/>

  <property name="xmldata" value="familyTree.xml"/>
  <property name="stylesheet" value="familyTree.xslt"/>
  <property name="result" value="Family Tree.html"/>

  <path id="project.class.path">
    <pathelement location="${xalan.jar}"/>
    <pathelement location="${xerces.jar}"/>
  </path>

  <target name="clean">
    <delete file="${result}"/>
  </target>

  <target name="xslt">
    <echo message="Transforming '${xmldata}' using '${stylesheet}'"/>

    <java fork="true" classname="org.apache.xalan.xslt.Process"
          failonerror="true">
      <arg line="-IN"/>
      <arg value="${xmldata}"/>
      <arg line="-XSL"/>
      <arg value="${stylesheet}"/>
      <arg line="-OUT"/>
      <arg value="${result}"/>
      <classpath refid="project.class.path"/>
    </java>

    <echo message="Success! See '${result}' for the output."/>
  </target>
</project>

We’ll look at other interesting facets of this buildfile later in this chapter. For now, let’s focus on the command-line arguments. Here is what the command line looks like if you invoke Xalan directly from a shell:

java org.apache.xalan.xslt.Process -IN familyTree.xml
        -XSL familyTree.xslt -OUT "Family Tree.html"

You are free to use as many <arg> tags as you want, and the arguments are passed to the command in the order in which they are listed in the buildfile. You can also mix and match usages of the various attributes for each <arg> tag. You might be wondering why we didn’t specify all of the arguments at once, like this:

<arg line="-IN ${xmldata} -XSL ${stylesheet} -OUT ${result}"/>

The answer lies in the final argument, "Family Tree.html". In this example, the filename contains a space. Remember that the line attribute expects several space-delimited arguments, and will treat "Family Tree.html" as two arguments: "Family" and "Tree.html". Since we want to pass the entire filename as a single argument, space included, we must use the value attribute:

<arg value="${result}"/>

Since we defined each of our filenames as Ant properties, someone might change the XML and XSLT filenames to something else in the future. Since these names may also contain spaces, we chose to use the value attribute for all three filename arguments. We are able to use the line attribute for the "-IN", "-XSL", and "-OUT" arguments because they never contain spaces, although the value attribute would yield the same results in this case.

You may also be wondering why we use the value attribute instead of path for this example. With value, the attribute text is passed unmodified to the process being executed. With the path attribute, text like "familyTree.xml" is converted into a platform-specific path such as C:\path\to\file\familyTree.xml before it is passed to the process. Applications that need absolute pathnames require you to use the path attribute. Our Xalan example works regardless of whether you use value or path because it works with both absolute and relative pathnames.^[29]

Additional Examples

This section shows a few additional examples of the argument DataType. argument allows several variations, all of which can be used together to pass several arguments to a process. As we already mentioned, multiple arguments are always passed in the order listed in the buildfile. Here is how you can pass two separate command-line arguments to a process:

<arg line="-mode verbose"/>

Here is how you pass a single command-line argument containing a space character:

<arg value="Eric Burke"/>

Finally, here is how you pass a path-like structure as a command-line argument:

<arg path="/temp;/tmp"/>

This is converted to C:\temp;C:\tmp^[30] on Windows systems, and /temp:/tmp on Unix systems.

---

^[27] Argument is treated as a DataType, although it does not extend from the DataType base class.

^[28] The style task is normally used for XSLT transformations; see Chapter 7.

^[29] Technically, Xalan expects URLs rather than filenames as arguments. For this reason, the platform-specific filename produced by the path attribute is less desirable than the relative URL possible with the value attribute.

^[30] Or some other drive letter, depending on where your base directory resides.