ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From peterrei...@apache.org
Subject cvs commit: ant/docs/manual/CoreTypes antlib.html
Date Mon, 01 Sep 2003 14:22:04 GMT
peterreilly    2003/09/01 07:22:04

  Modified:    docs/manual conceptstypeslist.html
               docs/manual/CoreTasks typedef.html
  Added:       docs/manual/CoreTypes antlib.html
  Log:
  manual page for antlib
  
  Revision  Changes    Path
  1.13      +7 -0      ant/docs/manual/conceptstypeslist.html
  
  Index: conceptstypeslist.html
  ===================================================================
  RCS file: /home/cvs/ant/docs/manual/conceptstypeslist.html,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- conceptstypeslist.html	27 Aug 2003 14:23:16 -0000	1.12
  +++ conceptstypeslist.html	1 Sep 2003 14:22:04 -0000	1.13
  @@ -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>
  
  
  
  1.10      +3 -25     ant/docs/manual/CoreTasks/typedef.html
  
  Index: typedef.html
  ===================================================================
  RCS file: /home/cvs/ant/docs/manual/CoreTasks/typedef.html,v
  retrieving revision 1.9
  retrieving revision 1.10
  diff -u -r1.9 -r1.10
  --- typedef.html	13 Aug 2003 13:22:58 -0000	1.9
  +++ typedef.html	1 Sep 2003 14:22:04 -0000	1.10
  @@ -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>
  
  
  
  1.1                  ant/docs/manual/CoreTypes/antlib.html
  
  Index: antlib.html
  ===================================================================
  <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>
  
  
  
  

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message