add some examples

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

docs/manual/CoreTasks/local.html

@@ -36,6 +36,9 @@ level effectively makes the property local to the "anonymous target" in which
 top-level operations are carried out; it will not be defined for other targets
 in the buildfile. <b>Since Ant 1.8</b></p>
 
+<p>A property is made local if the <code>&lt;local&gt;</code> task
+  preceedes its definition.  See the examples section.</p>
+
 <h3>Parameters</h3>
 <table border="1" cellpadding="2" cellspacing="0"> 
   <tr>
@@ -50,6 +53,134 @@ in the buildfile. <b>Since Ant 1.8</b></p>
   </tr>
 </table>
 
+<h3>Examples</h3>
+
+<h4>Temporarily shadow a global property's value</h4>
+
+<pre>
+    &lt;property name="foo" value="foo"/&gt;
+
+    &lt;target name="step1"&gt;
+        &lt;echo&gt;Before local: foo is ${foo}&lt;/echo&gt;
+        &lt;local name="foo"/&gt;
+        &lt;property name="foo" value="bar"/&gt;
+        &lt;echo&gt;After local: foo is ${foo}&lt;/echo&gt;
+    &lt;/target&gt;
+
+    &lt;target name="step2" depends="step1"&gt;
+        &lt;echo&gt;In step2: foo is ${foo}&lt;/echo&gt;
+    &lt;/target&gt;
+</pre>
+
+<p>outputs</p>
+
+<pre>
+step1:
+     [echo] Before local: foo is foo
+     [echo] After local: foo is bar
+
+step2:
+     [echo] In step2: foo is foo
+</pre>
+
+<p>here the local-task shadowed the global definition
+  of <code>foo</code> for the remainder of the target step1.</p>
+
+<h4>Creating thread local properties</h4>
+
+<pre>
+    &lt;property name="foo" value="foo"/&gt;
+
+    &lt;parallel&gt;
+        &lt;echo&gt;global 1: foo is ${foo}&lt;/echo&gt;
+        &lt;sequential&gt;
+            &lt;local name="foo"/&gt;
+            &lt;property name="foo" value="bar.1"/&gt;
+            &lt;echo&gt;First sequential: foo is ${foo}&lt;/echo&gt;
+        &lt;/sequential&gt;
+        &lt;sequential&gt;
+            &lt;sleep seconds="1"/&gt;
+            &lt;echo&gt;global 2: foo is ${foo}&lt;/echo&gt;
+        &lt;/sequential&gt;
+        &lt;sequential&gt;
+            &lt;local name="foo"/&gt;
+            &lt;property name="foo" value="bar.2"/&gt;
+            &lt;echo&gt;Second sequential: foo is ${foo}&lt;/echo&gt;
+        &lt;/sequential&gt;
+        &lt;echo&gt;global 3: foo is ${foo}&lt;/echo&gt;
+    &lt;/parallel&gt;
+</pre>
+
+<p>outputs something similar to</p>
+
+<pre>
+     [echo] global 3: foo is foo
+     [echo] global 1: foo is foo
+     [echo] First sequential: foo is bar.1
+     [echo] Second sequential: foo is bar.2
+     [echo] global 2: foo is foo
+</pre>
+
+<h4>Use inside macrodef</h4>
+
+<p>This probably is where local can be applied in the most useful
+  way.  If you needed a "temporary property" inside a macrodef in Ant
+  prior to Ant 1.8.0 you had to try to come up with a property name
+  that would be unique across macro invocations.</p>
+
+<p>Say you wanted to write a macro that created the parent directory
+  of a given file.  A naive approach would be:</p>
+
+<pre>
+    &lt;macrodef name="makeparentdir"&gt;
+        &lt;attribute name="file"/&gt;
+        &lt;sequential&gt;
+            &lt;dirname property="parent" file="@{file}"/&gt;
+            &lt;mkdir dir="${parent}"/&gt;
+        &lt;/sequential&gt;
+    &lt;/macrodef&gt;
+    &lt;makeparentdir file="some-dir/some-file"/&gt;
+</pre>
+
+<p>but this would create a global property "parent" on the first
+  invocation - and since properties are not mutable, any subsequent
+  invocation will see the same value and try to create the same
+  directory as the first invocation.</p>
+
+<p>The recommendation prior to Ant 1.8.0 was to use a property name
+  based on one of the macro's attributes, like</p>
+
+<pre>
+    &lt;macrodef name="makeparentdir"&gt;
+        &lt;attribute name="file"/&gt;
+        &lt;sequential&gt;
+            &lt;dirname property="parent.@{file}" file="@{file}"/&gt;
+            &lt;mkdir dir="${parent.@{file}}"/&gt;
+        &lt;/sequential&gt;
+    &lt;/macrodef&gt;
+</pre>
+
+<p>Now invocations for different files will set different properties
+  and the directories will get created.  Unfortunately this "pollutes"
+  the global properties space.  In addition it may be hard to come up
+  with unique names in some cases.</p>
+
+<p>Enter <code>&lt;local&gt;</code>:</p>
+
+<pre>
+    &lt;macrodef name="makeparentdir"&gt;
+        &lt;attribute name="file"/&gt;
+        &lt;sequential&gt;
+            &lt;local name="parent"/&gt;
+            &lt;dirname property="parent" file="@{file}"/&gt;
+            &lt;mkdir dir="${parent}"/&gt;
+        &lt;/sequential&gt;
+    &lt;/macrodef&gt;
+</pre>
+
+<p>Each invocation gets its own property name "parent" and there will
+  be no global property of that name at all.</p>
+
 </body>
 </html>