New <uses> tag for declaring script dependencies

[Jeff T. <jef...@us...>]

Hi,

I've added a new DataType tag, <uses>, which lets a script specify what
Anteater version and 'features' it needs. For example:

<uses version="0.9.13">
  <feature name="jelly"/>
  <feature name="xhtml-schema"/>
</uses>

specifies that the script needs Anteater 0.9.13 capabilities, with the
'jelly' and 'xhtml-schema' updates installed.

To keep things declarative, the <uses> tag is a data type, not a task,
and simply states what the script is known to work with. In particular,
the 'version' attribute does not imply that the script can _only_ run on
the specified version. That is why the tag is called 'uses', not
'requires'.

Current behaviour is:
 - Check the version number, and iff it is known to be incompatible,
   throws a BuildException. In the future we could be more sophisticated:
    - If version number is lower, apply an XSLT stylesheet to bring the
      script up to the latest format
    - If the version is higher, automatically fetch and apply an update
      to the Anteater installation.
 - Check the 'feature' list, and for any feature not present, throw a
   BuildException, telling the user to run 'anteater-update <feature>'
   In future, we could do the update automatically.


I implemented this while writing Cocoon test scripts. Some of them need
XHTML and SVG schemas, which are available as optional downloads, but
there was no way to indicate this requirement to the user. Now, running
without a required extension produces an error like:


BUILD FAILED
file:/home/jeff/sf/Anteater/examples/uses.xml:29: Missing feature:
Anteater feature 'xhtml-schema' not present. Please run 'anteater-update
xhtml-schema' to install this feature, or just 'anteater-update' to list
all features available for download.

The 'uses' tag is scoped by group and cumulatively inherited. Eg:

<group id="default">
  <uses version="0.9.14"/>  <!-- Known to run with 0.9.14 -->

  <group id="xhtml-tests">
    <uses>
      <feature name="xhtml-schema"/>
    </uses>
    <group id="xhtml+mathml-tests">
       <uses>
         <feature name="mathml-schema"/>
       </uses>
    </group>
  </group>
</group>

Here, tasks in group 'xhtml-tests' will fail unless 'xhtml-schema' is installed,
and tasks in group 'xhtml+mathml-tests' will fail unless both 'xhtml-schema' and
'mathml-schema' are installed.

(I just added that example to the docs)


I hope to make a 0.9.14 release shortly, containing this feature and a
number of bugfixes. It should be available as a download or by typing
something like 'anteater-update anteater-0_9_14'


--Jeff

PS: My emails always come out as fait accompli, "here's a new
feature", but that's not the intention.. feedback on design issues and
new ideas are very welcome.