more docs and tests

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

docs/manual/CoreTasks/unpack.html

@@ -56,6 +56,31 @@ does not exist.</p>
 <p>expands <i>test.tar.gz</i> to <i>subdir/test.tar</i> (assuming
 subdir is a directory).</p>
 
+<h3>Related tasks</h3>
+
+<pre>
+&lt;gunzip src="some-archive.gz" dest="some-dest-dir"/&gt;
+</pre>
+
+is identical to
+
+<pre>
+&lt;copy todir="some-dest-dir"&gt;
+  &lt;gzipresource&gt;
+    &lt;file file="some-archive.gz"/&gt;
+  &lt;/gzipresource&gt;
+  &lt;mapper type="glob" from="*.gz" to="*"/&gt;
+&lt;/copy&gt;
+</pre>
+
+<p>The same is also true for <code>&lt;bunzip2&gt;</code> and
+<code>&lt;bzip2resource&gt;</code>.  <code>&lt;copy&gt;</code> offers
+additional features like <a
+href="../CoreTypes/filterchains.html">filtering files</a> on the fly,
+allowing a file to be mapped to multiple destinations, preserving the
+last modified time or a configurable file system timestamp
+granularity.</p>
+
 <hr>
 <p align="center">Copyright &copy; 2000-2001,2004-2005 The Apache Software Foundation. All rights
 Reserved.</p>

docs/manual/CoreTasks/unzip.html

@@ -117,6 +117,38 @@ nested element.</p>
     &lt;mapper type=&quot;flatten&quot;/&gt;
 &lt;/unzip&gt;
 </pre>
+
+<h3>Related tasks</h3>
+
+<pre>
+&lt;unzip src="some-archive" dest="some-dir"&lt;
+  &lt;patternset&gt;
+    &lt;include name="some-pattern"/&gt;
+  &lt;/patternset&gt;
+  &lt;mapper type=&quot;some-mapper&quot;/&gt;
+&lt;/unzip&gt;
+</pre>
+
+is identical to
+
+<pre>
+&lt;copy todir="some-dir" preservelastmodified="true"&lt;
+  &lt;zipfileset src="some-archive"&gt;
+    &lt;patternset&gt;
+      &lt;include name="some-pattern"/&gt;
+    &lt;/patternset&gt;
+  &lt;/zipfileset&gt;
+  &lt;mapper type=&quot;some-mapper&quot;/&gt;
+&lt;/copy&gt;
+</pre>
+
+<p>The same is also true for <code>&lt;untar&gt;</code> and
+<code>&lt;tarfileset&gt;</code>.  <code>&lt;copy&gt;</code> offers
+additional features like <a
+href="../CoreTypes/filterchains.html">filtering files</a> on the fly,
+allowing a file to be mapped to multiple destinations or a
+configurable file system timestamp granularity.</p>
+
 <hr>
 <p align="center">Copyright &copy; 2000-2005 The Apache Software Foundation. All rights
 Reserved.</p>

src/etc/testcases/taskdefs/bunzip2.xml

@@ -14,4 +14,13 @@
   <target name="prepare">
     <gunzip src="expected/asf-logo-huge.tar.gz"/>
   </target>
+
+  <target name="testDocumentationClaimsOnCopy">
+    <copy todir=".">
+      <bzip2resource>
+        <file file="expected/asf-logo-huge.tar.bz2"/>
+      </bzip2resource>
+      <mapper type="glob" from="*.bz2" to="*"/>
+    </copy>
+  </target>
 </project>

src/etc/testcases/taskdefs/gunzip.xml

@@ -24,4 +24,13 @@
     <gunzip src="expected/asf-logo.gif.gz" dest="asf-logo.gif" />
   </target>
 
+  <target name="testDocumentationClaimsOnCopy">
+    <copy todir=".">
+      <gzipresource>
+        <file file="expected/asf-logo.gif.gz"/>
+      </gzipresource>
+      <mapper type="glob" from="*.gz" to="*"/>
+    </copy>
+  </target>
+
 </project>

src/etc/testcases/taskdefs/untar.xml

@@ -4,6 +4,8 @@
 
   <target name="cleanup">
     <delete file="asf-logo.gif" />
+    <delete file="untartest.tar" />
+    <delete dir="untartestin"/>
     <delete dir="untartestout"/>
   </target>
 
@@ -59,4 +61,26 @@
       </zipfileset>
     </untar>
   </target>
+
+  <target name="prepareTestTar">
+    <mkdir dir="untartestin/1"/>
+    <mkdir dir="untartestin/2"/>
+    <touch file="untartestin/1/foo"/>
+    <touch file="untartestin/2/bar"/>
+    <copy todir="untartestin/2">
+      <fileset dir="expected" includes="*md5*"/>
+    </copy>
+    <tar destfile="untartest.tar" basedir="untartestin"/>
+  </target>
+
+  <target name="testDocumentationClaimsOnCopy" depends="prepareTestTar">
+    <copy todir="untartestout" preservelastmodified="true"> 
+      <tarfileset src="untartest.tar">
+        <patternset>
+          <include name="2/"/>
+        </patternset>
+      </tarfileset>
+    </copy>
+  </target>
+  
 </project>

src/testcases/org/apache/tools/ant/taskdefs/BUnzip2Test.java

@@ -48,4 +48,11 @@ public class BUnzip2Test extends BuildFileTest {
             FILE_UTILS.contentEquals(project.resolveFile("expected/asf-logo-huge.tar"),
                                     project.resolveFile("asf-logo-huge.tar")));
     }
+
+    public void testDocumentationClaimsOnCopy() throws java.io.IOException {
+        executeTarget("testDocumentationClaimsOnCopy");
+        assertTrue("File content mismatch after bunzip2",
+            FILE_UTILS.contentEquals(project.resolveFile("expected/asf-logo-huge.tar"),
+                                    project.resolveFile("asf-logo-huge.tar")));
+    }
 }

src/testcases/org/apache/tools/ant/taskdefs/GUnzipTest.java

@@ -58,4 +58,9 @@ public class GUnzipTest extends BuildFileTest {
                                            project.resolveFile("asf-logo.gif")));
     }
 
+    public void testDocumentationClaimsOnCopy() throws java.io.IOException {
+        executeTarget("testDocumentationClaimsOnCopy");
+        assertTrue(FILE_UTILS.contentEquals(project.resolveFile("../asf-logo.gif"),
+                                           project.resolveFile("asf-logo.gif")));
+    }
 }

src/testcases/org/apache/tools/ant/taskdefs/UntarTest.java

@@ -82,4 +82,10 @@ public class UntarTest extends BuildFileTest {
         assertTrue(FILE_UTILS.contentEquals(project.resolveFile("../asf-logo.gif"),
                                            project.resolveFile("asf-logo.gif")));
     }
+
+    public void testDocumentationClaimsOnCopy() {
+        executeTarget("testDocumentationClaimsOnCopy");
+        assertFalse(getProject().resolveFile("untartestout/1/foo").exists());
+        assertTrue(getProject().resolveFile("untartestout/2/bar").exists());
+    }
 }