From 62e36bbd118163cfd874f398c33a387ff86e7ffa Mon Sep 17 00:00:00 2001 From: Peter Reilly Date: Mon, 1 Sep 2003 14:22:04 +0000 Subject: [PATCH] manual page for antlib git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@275164 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/CoreTasks/typedef.html | 28 +--- docs/manual/CoreTypes/antlib.html | 204 +++++++++++++++++++++++++++++ docs/manual/conceptstypeslist.html | 7 + 3 files changed, 214 insertions(+), 25 deletions(-) create mode 100644 docs/manual/CoreTypes/antlib.html diff --git a/docs/manual/CoreTasks/typedef.html b/docs/manual/CoreTasks/typedef.html index 0a2b4df29..a85e6148a 100644 --- a/docs/manual/CoreTasks/typedef.html +++ b/docs/manual/CoreTasks/typedef.html @@ -42,7 +42,8 @@

- The xml format is described below in the Antlib + The xml format is described in the + Antlib section.

@@ -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 Antlib. + to Antlib. 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"/> -

Antlib xml format

- An antlib file is an xml file with a root element of "antlib". - Antlib is actually a Sequential task with - special treatment for tasks that are ant definition tasks - like typedef - and Taskdef. - - A group of tasks and types may be defined together in an antlib - file. For example the file sample.xml contains the following: - 
-    <?xml version="1.0"?>
-    <antlib>
-      <typedef name="if" classname="org.acme.ant.If"/>
-      <typedef name="scriptpathmapper"
-               classname="org.acme.ant.ScriptPathMapper"
-               onerror="ignore"/>
-    </antlib>
-
- It defines two types or tasks, if and scriptpathmapper. - This antlib file may be used in a build script as follows: - 
-      <typedef file="sample.xml"/>
-
-

Copyright © 2001-2003 Apache Software Foundation. All rights Reserved.

diff --git a/docs/manual/CoreTypes/antlib.html b/docs/manual/CoreTypes/antlib.html new file mode 100644 index 000000000..5f2e164a1 --- /dev/null +++ b/docs/manual/CoreTypes/antlib.html @@ -0,0 +1,204 @@ + + + + + AntLib + + + +

Antlib

+

+ EXPERIMENTAL: 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 + <macrodef> and <presetdef> which may not be in + Ant1.6. +

+

Description

+

+ An antlib file is an xml file with a root element of "antlib". + Antlib is actually a Sequential task with + special treatment for tasks that are ant definition tasks - like + Typedef + and Taskdef. +

+

+ A group of tasks and types may be defined together in an antlib + file. For example the file sample.xml contains the following: +

+
+ 
+<?xml version="1.0"?>
+<antlib>
+   <typedef name="if" classname="org.acme.ant.If"/>
+   <typedef name="scriptpathmapper"
+            classname="org.acme.ant.ScriptPathMapper"
+            onerror="ignore"/>
+</antlib>
+
+
+

+ It defines two types or tasks, if and scriptpathmapper. + This antlib file may be used in a build script as follows: +

+
+ 
+<typedef file="sample.xml"/>
+
+
+

+ The other attributes of <typedef> may be used as well. + For example, assuming that the sample.xml is in a jar + file sample.jar also containing the classes, the + following build fragment will define the if and scriptpathmapper + tasks/types and place them in the namespace uri samples:/acme.org. +

+
+ 
+<typedef resource="org/acme/ant/sample.xml"
+         uri="samples:/acme.org"/>
+
+
+

+ The definitions may then be used as follows: +

+
+ 
+<sample:if valuetrue="${props}" xmlns:sample="samples:/acme.org">
+   <sample:scriptpathmapper language="beanshell">
+      some bean shell
+   </sample:scriptpathmapper>
+</sample:if>
+
+
+

Antlib namespace

+

+ The name space URIs with the pattern antlib:java package + are given special treatment. +

+

+ 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 antlib.xml in + the package directory in the default classpath. +

+

+ For example, assuming that the file antcontrib.jar has been placed + in the directory ${ant.home}/lib and it contains the resource + net/sf/antcontrib/antlib.xml which has all antcontrib's definitions + defined, the following build file will automatically load the antcontrib + definitions at location HERE: +

+
+ 
+<project default="deletetest" xmlns:antcontrib="antlib:net.sf.antcontrib">
+   <macrodef name="showdir">
+      <attribute name="dir"/>
+      <sequential>
+         <antcontrib:shellscript shell="bash">  <!-- HERE -->
+            ls -Rl ${dir}
+         </antcontrib:shellscript>
+      </sequential>
+   </macrodef>
+
+   <target name="deletetest">
+      <delete dir="a" quiet="yes"/>
+      <mkdir dir="a/b"/>
+      <touch file="a/a.txt"/>
+      <touch file="a/b/b.txt"/>
+      <delete>
+         <fileset dir="a"/>
+      </delete>
+      <showdir dir="a"/>
+   </target>
+</project>
+
+
+

+ The requirement that the resource is in the default classpath + may be removed before Ant 1.6 is released. +

+

Current namespace

+

+ Definitions defined in antlibs may be used in antlibs. However + the namespace that definitions are placed in are dependent on + the <typedef> that uses the antlib. To deal with this + problem, the definitions are placed in the namepace URI ant:current + for the duration of the antlib execution. + For example the following antlib defines the task <if>, the + type <isallowed> and a macro + <ifallowed> that makes use of the task and type: +

+
+ 
+<antlib xmlns:current="ant:current">
+   <taskdef name="if" classname="org.acme.ant.If"/>
+   <typedef name="isallowed" classname="org.acme.ant.Isallowed"/>
+   <macrodef name="ifallowed">
+      <attribute name="action"/>
+      <element name="do"/>
+      <sequential>
+         <current:if>
+            <current:isallowed test="${action}"/>
+            <then>
+               <do/>
+            </then>
+         </current:if>
+      </sequential>
+   </macrodef>
+</antlib>
+
+
+

Other examples and comments

+

+ 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. +

+

+ Antlibs may make use of other antlibs. +

+

+ As the names defined in the antlib are in the namespace uri as + specified by the calling <typedef> 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: +

+
+ 
+<antlib xmlns:antcontrib="antlib:net.sf.antcontrib">
+   <presetdef name="javac">
+      <javac deprecation="${deprecation}"
+             debug="${debug}"/>
+   </presetdef>
+   <presetdef name="delete">
+      <delete quiet="yes"/>
+   </presetdef>
+   <presetdef name="shellscript">
+      <antcontrib:shellscript shell="bash"/>
+   </presetdef>
+</antlib>
+
+
+

+ This may be used as follows: +

+
+ 
+<project xmlns:local="localpresets">
+   <typedef file="localpresets.xml" uri="localpresets"/>
+   <local:shellscript>
+      echo "hello world"
+   </local:shellscript>
+</project>
+
+
+ +
+

Copyright © 2003 Apache Software +Foundation. All rights Reserved.

+ + + + diff --git a/docs/manual/conceptstypeslist.html b/docs/manual/conceptstypeslist.html index 9f6da09b7..3ec9ed6b2 100644 --- a/docs/manual/conceptstypeslist.html +++ b/docs/manual/conceptstypeslist.html @@ -36,10 +36,17 @@ Extension Package
Set of Extension Packages
+

Antlib

+Antlib
+Antlib namespace
+Current namespace
+ +

Custom Components

Custom Components
Conditions
Selectors
FilterReaders
+