manual page for antlib

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@275164 13f79535-47bb-0310-9956-ffa450edef68
22 years ago · 62e36bbd11
--- a/docs/manual/CoreTasks/typedef.html
+++ b/docs/manual/CoreTasks/typedef.html
@@ -42,7 +42,8 @@
  </pre>
  <p>
    The xml format is described below in the <a href="#antlib">Antlib</a>
    The xml format is described in the
    <a href="../CoreTypes/antlib.html">Antlib</a>
    section.
  </p>
@@ -81,7 +82,7 @@
      are "properties" or "xml". If the value is "properties" the file/resource
      is a property file contains name to classname pairs. If the value
      is "xml", the file/resource is an xml file/resource structured according
      to   <a href="#antlib">Antlib</a>.
      to   <a href="../CoreTypes/antlib.html">Antlib</a>.
      The default is "properties" unless the file/resorce name ends with
      ".xml", in which case the format attribute will have the value "xml".
      (introduced in ant1.6)
@@ -167,29 +168,6 @@
             classname="com.acme.ant.RunClock"
             adapter="org.acme.ant.RunnableAdapter"/&gt;
  </pre>
  <h3><a name="antlib">Antlib xml format</a></h3>
  An antlib file is an xml file with a root element of "antlib".
  Antlib is actually a <a href="sequential.html">Sequential</a> task with
  special treatment for tasks that are ant definition tasks - like typedef
  and <a href="taskdef.html">Taskdef</a>.
    A group of tasks and types may be defined together in an antlib
    file. For example the file <i>sample.xml</i> contains the following:
  <pre>
    &lt;?xml version="1.0"?&gt;
    &lt;antlib&gt;
      &lt;typedef name="if" classname="org.acme.ant.If"/&gt;
      &lt;typedef name="scriptpathmapper"
               classname="org.acme.ant.ScriptPathMapper"
               onerror="ignore"/&gt;
    &lt;/antlib&gt;
  </pre>
    It defines two types or tasks, <i>if</i> and <i>scriptpathmapper</i>.
    This antlib file may be used in a build script as follows:
    <pre>
      &lt;typedef file="sample.xml"/&gt;
    </pre>
 <hr>
 <p align="center">Copyright &copy; 2001-2003 Apache Software
 Foundation. All rights Reserved.</p>
--- a/docs/manual/CoreTypes/antlib.html
+++ b/docs/manual/CoreTypes/antlib.html
@@ -0,0 +1,204 @@
 <html>
  <head>
    <meta http-equiv="Content-Language" content="en-us"></meta>
    <title>AntLib</title>
  </head>
  <body>
    <h2><a name="antlib">Antlib</a></h2>
    <p>
      <i>EXPERIMENTAL:</i> The antlib concept and implementation is experimental
      and may be under continual change until Ant1.6 ships.
      The contents of this page uses the experimental tasks
      &lt;macrodef&gt; and &lt;presetdef&gt; which may not be in
      Ant1.6.
    </p>
    <h3>Description</h3>
    <p>
      An antlib file is an xml file with a root element of "antlib".
      Antlib is actually a <a href="sequential.html">Sequential</a> task with
      special treatment for tasks that are ant definition tasks - like
      <a href="../CoreTasks/typedef.html">Typedef</a>
      and <a href="../CoreTasks/taskdef.html">Taskdef</a>.
    </p>
    <p>
      A group of tasks and types may be defined together in an antlib
      file. For example the file <i>sample.xml</i> contains the following:
    </p>
    <blockquote>
      <pre>
 &lt;?xml version="1.0"?&gt;
 &lt;antlib&gt;
   &lt;typedef name="if" classname="org.acme.ant.If"/&gt;
   &lt;typedef name="scriptpathmapper"
            classname="org.acme.ant.ScriptPathMapper"
            onerror="ignore"/&gt;
 &lt;/antlib&gt;
      </pre>
    </blockquote>
    <p>
      It defines two types or tasks, <i>if</i> and <i>scriptpathmapper</i>.
      This antlib file may be used in a build script as follows:
    </p>
    <blockquote>
      <pre>
 &lt;typedef file="sample.xml"/&gt;
      </pre>
    </blockquote>
    <p>
      The other attributes of &lt;typedef&gt; may be used as well.
      For example, assuming that the <i>sample.xml</i> is in a jar
      file <i>sample.jar</i> also containing the classes, the
      following build fragment will define the <i>if</i> and <i>scriptpathmapper</i>
      tasks/types and place them in the namespace uri <i>samples:/acme.org</i>.
    </p>
    <blockquote>
      <pre>
 &lt;typedef resource="org/acme/ant/sample.xml"
         uri="samples:/acme.org"/&gt;
      </pre>
    </blockquote>
    <p>
      The definitions may then be used as follows:
    </p>
    <blockquote>
      <pre>
 &lt;sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org"&gt;
   &lt;sample:scriptpathmapper language="beanshell"&gt;
      some bean shell
   &lt;/sample:scriptpathmapper&gt;
 &lt;/sample:if&gt;
      </pre>
    </blockquote>
    <h3><a name="antlibnamespace">Antlib namespace</a></h3>
    <p>
      The name space URIs with the pattern <b>antlib:<i>java package</i></b>
      are given special treatment.
    </p>
    <p>
      When ant encounters a element with a namespace URI with this pattern, it
      will check to see if there is a resource of the name <i>antlib.xml</i> in
      the package directory in the default classpath.
    </p>
    <p>
      For example, assuming that the file <i>antcontrib.jar</i> has been placed
      in the directory <i>${ant.home}/lib</i> and it contains the resource
      <i>net/sf/antcontrib/antlib.xml</i> which has all antcontrib's definitions
      defined, the following build file will automatically load the antcontrib
      definitions at location <i>HERE</i>:
    </p>
    <blockquote>
      <pre>
 &lt;project default="deletetest" xmlns:antcontrib="antlib:net.sf.antcontrib"&gt;
   &lt;macrodef name="showdir"&gt;
      &lt;attribute name="dir"/&gt;
      &lt;sequential&gt;
         &lt;antcontrib:shellscript shell="bash"&gt;  &lt;!-- HERE --&gt;
            ls -Rl ${dir}
         &lt;/antcontrib:shellscript&gt;
      &lt;/sequential&gt;
   &lt;/macrodef&gt;
   &lt;target name="deletetest"&gt;
      &lt;delete dir="a" quiet="yes"/&gt;
      &lt;mkdir dir="a/b"/&gt;
      &lt;touch file="a/a.txt"/&gt;
      &lt;touch file="a/b/b.txt"/&gt;
      &lt;delete&gt;
         &lt;fileset dir="a"/&gt;
      &lt;/delete&gt;
      &lt;showdir dir="a"/&gt;
   &lt;/target&gt;
 &lt;/project&gt;
      </pre>
    </blockquote>
    <p>
      The requirement that the resource is in the default classpath
      may be removed before Ant 1.6 is released.
    </p>
    <h3><a name="currentnamespace">Current namespace</a></h3>
    <p>
      Definitions defined in antlibs may be used in antlibs. However
      the namespace that definitions are placed in are dependent on
      the &lt;typedef&gt; that uses the antlib. To deal with this
      problem, the definitions are placed in the namepace URI <i>ant:current</i>
      for the duration of the antlib execution.
      For example the following antlib defines the task &lt;if&gt;, the
      type &lt;isallowed&gt; and a macro
      &lt;ifallowed&gt; that makes use of the task and type:
    </p>
    <blockquote>
      <pre>
 &lt;antlib xmlns:current="ant:current"&gt;
   &lt;taskdef name="if" classname="org.acme.ant.If"/&gt;
   &lt;typedef name="isallowed" classname="org.acme.ant.Isallowed"/&gt;
   &lt;macrodef name="ifallowed"&gt;
      &lt;attribute name="action"/&gt;
      &lt;element name="do"/&gt;
      &lt;sequential&gt;
         &lt;current:if&gt;
            &lt;current:isallowed test="${action}"/&gt;
            &lt;then&gt;
               &lt;do/&gt;
            &lt;/then&gt;
         &lt;/current:if&gt;
      &lt;/sequential&gt;
   &lt;/macrodef&gt;
 &lt;/antlib&gt;
      </pre>
    </blockquote>
    <h3>Other examples and comments</h3>
    <p>
      Althought the primary use of antlibs are ant definitions, one
      may use any task or type in an antlib. This should
      be treated with caution.
    </p>
    <p>
      Antlibs may make use of other antlibs.
    </p>
    <p>
      As the names defined in the antlib are in the namespace uri as
      specified by the calling &lt;typedef&gt; or by automatic element
      resolution, one may reuse names from core ant types and tasks,
      provided the caller uses a namespace uri. For example, the
      following antlib may be used to define defaults for various
      tasks:
    </p>
    <blockquote>
      <pre>
 &lt;antlib xmlns:antcontrib="antlib:net.sf.antcontrib"&gt;
   &lt;presetdef name="javac"&gt;
      &lt;javac deprecation="${deprecation}"
             debug="${debug}"/&gt;
   &lt;/presetdef&gt;
   &lt;presetdef name="delete"&gt;
      &lt;delete quiet="yes"/&gt;
   &lt;/presetdef&gt;
   &lt;presetdef name="shellscript"&gt;
      &lt;antcontrib:shellscript shell="bash"/&gt;
   &lt;/presetdef&gt;
 &lt;/antlib&gt;
      </pre>
    </blockquote>
    <p>
      This may be used as follows:
    </p>
    <blockquote>
      <pre>
 &lt;project xmlns:local="localpresets"&gt;
   &lt;typedef file="localpresets.xml" uri="localpresets"/&gt;
   &lt;local:shellscript&gt;
      echo "hello world"
   &lt;/local:shellscript&gt;
 &lt;/project&gt;
      </pre>
    </blockquote>
 <hr>
 <p align="center">Copyright &copy; 2003 Apache Software
 Foundation. All rights Reserved.</p>
 </body>
 </html>
--- a/docs/manual/conceptstypeslist.html
+++ b/docs/manual/conceptstypeslist.html
@@ -36,10 +36,17 @@
 <a href="OptionalTypes/extension.html">Extension Package</a><br>
 <a href="OptionalTypes/extensionset.html">Set of Extension Packages</a><br>
 <h3>Antlib</h3>
 <a href="CoreTypes/antlib.html">Antlib</a><br>
 <a href="CoreTypes/antlib.html#antlibnamespace">Antlib namespace</a><br>
 <a href="CoreTypes/antlib.html#currentnamespace">Current namespace</a><br>
 <h3>Custom Components</h3>
 <a href="CoreTypes/custom-programming.html">Custom Components</a><br>
 <a href="CoreTypes/custom-programming.html#customconditions">Conditions</a><br>
 <a href="CoreTypes/custom-programming.html#customselectors">Selectors</a><br>
 <a href="CoreTypes/custom-programming.html#filterreaders">FilterReaders</a><br>
 </body>
 </html>