extending scriptdef

1. nested text gets passed to self.text
 2. a fail(String) method takes on the work of throwing exceptions even in languages that dont make it easy to throw BuildExceptions

I have antunit tests for these in the antbook source tree, but not moved them into ant's codebase yet.

Issue: should nested text be something that must be enabled explicitly via a nestedText attribute in scriptdef?

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@415817 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -436,6 +436,9 @@ Other changes:
 
 * New deleteonexit attribute for the <tempfile> task. Bugzilla report 39842.
 
+* <scriptdef>-created scripts have support for nested text. All text
+  passed to a scripted task can be accessed via self.text.
+
 Changes from Ant 1.6.4 to Ant 1.6.5
 ===================================
 

docs/manual/OptionalTasks/scriptdef.html

@@ -27,6 +27,8 @@ Ant distribution. See
 <a href="../install.html#librarydependencies">Library Dependencies</a>
 for more information.</p>
 
+
+
 <p>The attributes and nested elements supported by the task may be defined
 using <code>&lt;attribute&gt;</code> and <code>&lt;element&gt;</code> nested elements. These are
 available to the script that implements the task as two collection style
@@ -42,8 +44,20 @@ lowercase names, so even if you use name="SomeAttribute", you'll have
 to use "someattribute" to retrieve the attribute's value from the
 <code>attributes</code> collection.</p>
 
-  <p>The name "self" (<i>since Ant 1.6.3</i>) is a pre-defined reference to the script def task instance.
-  It can be used for logging purposes</p>
+<p>The name "self" (<i>since Ant 1.6.3</i>) is a pre-defined reference to the
+    script def task instance.
+    It can be used for logging, or for integration with the rest of
+    ant. the <code>self.text attribute</code> contains
+    any nested text passed to the script</p>
+
+<p>If an attribute or element is not passed in, 
+then <code>attributes.get()</code> or <code>elements.get()</code> will 
+return null. It is up to the script to perform any checks and validation. 
+<code>self.fail(String message)</code>can be used to raise a 
+<code>BuildException</code>.
+</p>
+
+
 <p>The name "project" is a pre-defined reference to the Ant Project. For
 more information on writing scripts, please refer to the
 <a href="script.html"><code>&lt;script&gt;</code></a> task
@@ -196,10 +210,40 @@ statement (scriptdef <code>&lt;scripttest2&gt;</code>; line 10)</code></p>
 <p>
 Script errors are only detected when a script task is actually executed.
 </p>
+<p>
+    The next example does uses nested text in Jython. It also declares 
+    the script in a new xml namespace, which must be used to refer to 
+    the task. Declaring scripts in a new namespace guarantees that Ant will 
+    not create a task of the same (namespace,localname) name pair. 
+</p>
+
+<pre>
+    &lt;target name="echo-task-jython"&gt;
+  &lt;scriptdef language="jython"
+      name="echo"
+      uri="http://example.org/script"&gt;
+      &lt;![CDATA[
+self.log("text: " +self.text)
+    ]]&gt;
+    &lt;/scriptdef&gt;
+&lt;/target&gt;
+
+&lt;target name="testEcho" depends="echo-task-jython"
+    xmlns:s="http://example.org/script"&gt;
+  &lt;s:echo&gt;nested text&lt;/s:echo&gt;
+&lt;/target&gt;
+</pre>
+
+<h3>Testing Scripts</h3>
+
+<p>
+The easiest way to test scripts is to use the 
+<a href="http://ant.apache.org/antlibs/antunit/">AntUnit</a> ant library.
+This will run all targets in a script that begin with "test" (and their dependencies). </p>
 
 
 <hr>
-<p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
+<p align="center">Copyright &copy; 2000-2006 The Apache Software Foundation. All rights
 Reserved.</p>
 
 </body>

src/main/org/apache/tools/ant/taskdefs/optional/script/ScriptDef.java

@@ -309,7 +309,7 @@ public class ScriptDef extends DefBase {
      *
      * @param attributes collection of attributes
      * @param elements   a list of nested element values.
-     * @param instance   the script instance
+     * @param instance   the script instance; can be null
      */
     public void executeScript(Map attributes, Map elements, ScriptDefBase instance) {
         runner.addBean("attributes", attributes);

src/main/org/apache/tools/ant/taskdefs/optional/script/ScriptDefBase.java

@@ -1,5 +1,5 @@
 /*
- * Copyright  2000-2004 The Apache Software Foundation
+ * Copyright  2000-2006 The Apache Software Foundation
  *
  *  Licensed under the Apache License, Version 2.0 (the "License");
  *  you may not use this file except in compliance with the License.
@@ -38,13 +38,15 @@ public class ScriptDefBase extends Task implements DynamicConfigurator {
 
     /** Attributes */
     private Map attributes = new HashMap();
+    
+    private String text;
 
     /**
      * Locate the script defining task and execute the script by passing
      * control to it
      */
     public void execute() {
-        getScript().executeScript(attributes, nestedElementMap, this);
+        getScript().executeScript(attributes, nestedElementMap,this);
     }
 
     private ScriptDef getScript() {
@@ -94,5 +96,35 @@ public class ScriptDefBase extends Task implements DynamicConfigurator {
 
         attributes.put(name, value);
     }
+
+    /**
+     * Set the script text.
+     *
+     * @param text a component of the script text to be added.
+     * @since ant1.7
+     */
+    public void addText(String text) {
+        this.text=text;
+    }
+
+    /**
+     * get the text of this element; may be null
+     * @return text or null for no nested text
+     * @since ant1.7
+     */
+    public String getText() {
+        return text;
+    }
+
+    /**
+     * Utility method for nested scripts; throws a BuildException
+     * with the given message.
+     * @param message text to pass to the BuildException
+     * @throws BuildException always.
+     * @since ant1.7
+     */
+    public void fail(String message) {
+        throw new BuildException(message);
+    }
 }