tar - Ticket [65767447de] - EF - Added gzip support based on patch by Christian Werner, with thanks.

Internal refactoring to be more clear wrt semantics. Docs added.
Docs regenerated.
Bumped to version 0.13.

Author: andreas-kupries

embedded/md/tcllib/files/modules/tar/tar.md

@@ -1,7 +1,7 @@
 
 [//000000001]: # (tar \- Tar file handling)
 [//000000002]: # (Generated from file 'tar\.man' by tcllib/doctools with format 'markdown')
-[//000000003]: # (tar\(n\) 0\.12\.1 tcllib "Tar file handling")
+[//000000003]: # (tar\(n\) 0\.13 tcllib "Tar file handling")
 
 <hr> [ <a href="../../../../toc.md">Main Table Of Contents</a> &#124; <a
 href="../../../toc.md">Table Of Contents</a> &#124; <a
@@ -35,12 +35,12 @@ tar \- Tar file creation, extraction & manipulation
 # <a name='synopsis'></a>SYNOPSIS
 
 package require Tcl 8\.5 9  
-package require tar ?0\.12\.1?  
+package require tar ?0\.13?  
 
-[__::tar::contents__ *tarball* ?__\-chan__?](#1)  
-[__::tar::stat__ *tarball* ?file? ?__\-chan__?](#2)  
+[__::tar::contents__ *tarball* ?__\-chan__? ?__\-gzip__?](#1)  
+[__::tar::stat__ *tarball* ?file? ?__\-chan__? ?__\-gzip__?](#2)  
 [__::tar::untar__ *tarball* *args*](#3)  
-[__::tar::get__ *tarball* *fileName* ?__\-chan__?](#4)  
+[__::tar::get__ *tarball* *fileName* ?__\-chan__? ?__\-gzip__?](#4)  
 [__::tar::create__ *tarball* *files* *args*](#5)  
 [__::tar::add__ *tarball* *files* *args*](#6)  
 [__::tar::remove__ *tarball* *files*](#7)  
@@ -78,9 +78,27 @@ For all commands, when using __\-chan__ \.\.\.
      unstack the transformation before seeking the channel back to a suitable
      position, and \(b\) for restacking it after\.
 
+Regarding support for gzip compression:
+
+  1. Errors are thrown when attempting to read from compressed tar archives
+     while compression support \(i\.e\. __::zlib__\) is not available\.
+
+  1. Errors are thrown when attempting to read an uncompressed tar archive when
+     compression is requested by the user \(__\-gzip__\)\.
+
+     No errors are thrown when attempting to read a compressed tar archive when
+     compression was not requested, and is supported\. In that case the commands
+     automatically activate the code handling the compression\.
+
+  1. Errors are thrown when attempting to edit compressed tar archives\. See the
+     commands __tar::add__, and __tar::remove__\. This is not supported\.
+
+  1. Creation of compressed tar archives however is supported, as this
+     sequentially writes the archive, allowing for streaming compression\.
+
 # <a name='section3'></a>COMMANDS
 
-  - <a name='1'></a>__::tar::contents__ *tarball* ?__\-chan__?
+  - <a name='1'></a>__::tar::contents__ *tarball* ?__\-chan__? ?__\-gzip__?
 
     Returns a list of the files contained in *tarball*\. The order is not
     sorted and depends on the order files were stored in the archive\.
@@ -89,7 +107,7 @@ For all commands, when using __\-chan__ \.\.\.
     channel\. It is assumed that the channel was opened for reading, and
     configured for binary input\. The command will *not* close the channel\.
 
-  - <a name='2'></a>__::tar::stat__ *tarball* ?file? ?__\-chan__?
+  - <a name='2'></a>__::tar::stat__ *tarball* ?file? ?__\-chan__? ?__\-gzip__?
 
     Returns a nested dict containing information on the named ?file? in
     *tarball*, or all files if none is specified\. The top level are pairs of
@@ -151,7 +169,7 @@ For all commands, when using __\-chan__ \.\.\.
         puts "Extracted $file ($size bytes)"
         }
 
-  - <a name='4'></a>__::tar::get__ *tarball* *fileName* ?__\-chan__?
+  - <a name='4'></a>__::tar::get__ *tarball* *fileName* ?__\-chan__? ?__\-gzip__?
 
     Returns the contents of *fileName* from the *tarball*\.
 

idoc/man/files/modules/tar/tar.n

@@ -1,7 +1,7 @@
 '\"
 '\" Generated from file 'tar\&.man' by tcllib/doctools with format 'nroff'
 '\"
-.TH "tar" n 0\&.12\&.1 tcllib "Tar file handling"
+.TH "tar" n 0\&.13 tcllib "Tar file handling"
 .\" The -*- nroff -*- definitions below are for supplemental macros used
 .\" in Tcl/Tk manual entries.
 .\"
@@ -275,15 +275,15 @@ tar \- Tar file creation, extraction & manipulation
 .SH SYNOPSIS
 package require \fBTcl 8\&.5 9\fR
 .sp
-package require \fBtar ?0\&.12\&.1?\fR
+package require \fBtar ?0\&.13?\fR
 .sp
-\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR?
+\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR? ?\fB-gzip\fR?
 .sp
-\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR?
+\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR? ?\fB-gzip\fR?
 .sp
 \fB::tar::untar\fR \fItarball\fR \fIargs\fR
 .sp
-\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR?
+\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR? ?\fB-gzip\fR?
 .sp
 \fB::tar::create\fR \fItarball\fR \fIfiles\fR \fIargs\fR
 .sp
@@ -324,17 +324,36 @@ example \fBgunzip\fR, then it is the responsibility of the user to (a)
 unstack the transformation before seeking the channel back to a suitable
 position, and (b) for restacking it after\&.
 .PP
+Regarding support for gzip compression:
+.IP [1]
+Errors are thrown when attempting to read from compressed tar archives
+while compression support (i\&.e\&. \fB::zlib\fR) is not available\&.
+.IP [2]
+Errors are thrown when attempting to read an uncompressed tar archive
+when compression is requested by the user (\fB-gzip\fR)\&.
+.sp
+No errors are thrown when attempting to read a compressed tar archive
+when compression was not requested, and is supported\&. In that case the
+commands automatically activate the code handling the compression\&.
+.IP [3]
+Errors are thrown when attempting to edit compressed tar archives\&.
+See the commands \fBtar::add\fR, and \fBtar::remove\fR\&.
+This is not supported\&.
+.IP [4]
+Creation of compressed tar archives however is supported, as this
+sequentially writes the archive, allowing for streaming compression\&.
+.PP
 .SH COMMANDS
 .TP
-\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR?
+\fB::tar::contents\fR \fItarball\fR ?\fB-chan\fR? ?\fB-gzip\fR?
 Returns a list of the files contained in \fItarball\fR\&. The order is not sorted and depends on the order
 files were stored in the archive\&.
 .sp
 If the option \fB-chan\fR is present \fItarball\fR is interpreted as an open channel\&.
 It is assumed that the channel was opened for reading, and configured for binary input\&.
 The command will \fInot\fR close the channel\&.
 .TP
-\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR?
+\fB::tar::stat\fR \fItarball\fR ?file? ?\fB-chan\fR? ?\fB-gzip\fR?
 Returns a nested dict containing information on the named ?file? in \fItarball\fR,
 or all files if none is specified\&. The top level are pairs of filename and info\&. The info is a dict with the keys
 "\fBmode\fR \fBuid\fR \fBgid\fR \fBsize\fR \fBmtime\fR \fBtype\fR \fBlinkname\fR \fBuname\fR \fBgname\fR
@@ -394,7 +413,7 @@ puts "Extracted $file ($size bytes)"
 
 .CE
 .TP
-\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR?
+\fB::tar::get\fR \fItarball\fR \fIfileName\fR ?\fB-chan\fR? ?\fB-gzip\fR?
 Returns the contents of \fIfileName\fR from the \fItarball\fR\&.
 .sp
 .CS

idoc/www/tcllib/files/modules/tar/tar.html

@@ -107,7 +107,7 @@
 &#124; <a href="../../../../toc2.html">Applications</a>
  ] <hr>
 <div class="doctools">
-<h1 class="doctools_title">tar(n) 0.12.1 tcllib &quot;Tar file handling&quot;</h1>
+<h1 class="doctools_title">tar(n) 0.13 tcllib &quot;Tar file handling&quot;</h1>
 <div id="name" class="doctools_section"><h2><a name="name">Name</a></h2>
 <p>tar - Tar file creation, extraction &amp; manipulation</p>
 </div>
@@ -127,13 +127,13 @@ <h1 class="doctools_title">tar(n) 0.12.1 tcllib &quot;Tar file handling&quot;</h
 <div class="doctools_synopsis">
 <ul class="doctools_requirements">
 <li>package require <b class="pkgname">Tcl 8.5 9</b></li>
-<li>package require <b class="pkgname">tar <span class="opt">?0.12.1?</span></b></li>
+<li>package require <b class="pkgname">tar <span class="opt">?0.13?</span></b></li>
 </ul>
 <ul class="doctools_syntax">
-<li><a href="#1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
-<li><a href="#2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
+<li><a href="#1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></li>
+<li><a href="#2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></li>
 <li><a href="#3"><b class="cmd">::tar::untar</b> <i class="arg">tarball</i> <i class="arg">args</i></a></li>
-<li><a href="#4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span></a></li>
+<li><a href="#4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></li>
 <li><a href="#5"><b class="cmd">::tar::create</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></li>
 <li><a href="#6"><b class="cmd">::tar::add</b> <i class="arg">tarball</i> <i class="arg">files</i> <i class="arg">args</i></a></li>
 <li><a href="#7"><b class="cmd">::tar::remove</b> <i class="arg">tarball</i> <i class="arg">files</i></a></li>
@@ -165,16 +165,31 @@ <h1 class="doctools_title">tar(n) 0.12.1 tcllib &quot;Tar file handling&quot;</h
        unstack the transformation before seeking the channel back to a suitable
        position, and (b) for restacking it after.</p></li>
 </ol>
+<p>Regarding support for gzip compression:</p>
+<ol class="doctools_enumerated">
+<li><p>Errors are thrown when attempting to read from compressed tar archives
+       while compression support (i.e. <b class="cmd">::zlib</b>) is not available.</p></li>
+<li><p>Errors are thrown when attempting to read an uncompressed tar archive
+       when compression is requested by the user (<b class="option">-gzip</b>).</p>
+<p>No errors are thrown when attempting to read a compressed tar archive
+       when compression was not requested, and is supported. In that case the
+       commands automatically activate the code handling the compression.</p></li>
+<li><p>Errors are thrown when attempting to edit compressed tar archives.
+       See the commands <b class="cmd">tar::add</b>, and <b class="cmd">tar::remove</b>.
+       This is not supported.</p></li>
+<li><p>Creation of compressed tar archives however is supported, as this
+       sequentially writes the archive, allowing for streaming compression.</p></li>
+</ol>
 </div>
 <div id="section3" class="doctools_section"><h2><a name="section3">COMMANDS</a></h2>
 <dl class="doctools_definitions">
-<dt><a name="1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
+<dt><a name="1"><b class="cmd">::tar::contents</b> <i class="arg">tarball</i> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></dt>
 <dd><p>Returns a list of the files contained in <i class="arg">tarball</i>. The order is not sorted and depends on the order
 files were stored in the archive.</p>
 <p>If the option <b class="option">-chan</b> is present <i class="arg">tarball</i> is interpreted as an open channel.
 It is assumed that the channel was opened for reading, and configured for binary input.
 The command will <em>not</em> close the channel.</p></dd>
-<dt><a name="2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
+<dt><a name="2"><b class="cmd">::tar::stat</b> <i class="arg">tarball</i> <span class="opt">?file?</span> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></dt>
 <dd><p>Returns a nested dict containing information on the named <span class="opt">?file?</span> in <i class="arg">tarball</i>,
 or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys
 &quot;<b class="const">mode</b> <b class="const">uid</b> <b class="const">gid</b> <b class="const">size</b> <b class="const">mtime</b> <b class="const">type</b> <b class="const">linkname</b> <b class="const">uname</b> <b class="const">gname</b>
@@ -218,7 +233,7 @@ <h1 class="doctools_title">tar(n) 0.12.1 tcllib &quot;Tar file handling&quot;</h
 }
 </pre>
 </dd>
-<dt><a name="4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span></a></dt>
+<dt><a name="4"><b class="cmd">::tar::get</b> <i class="arg">tarball</i> <i class="arg">fileName</i> <span class="opt">?<b class="option">-chan</b>?</span> <span class="opt">?<b class="option">-gzip</b>?</span></a></dt>
 <dd><p>Returns the contents of <i class="arg">fileName</i> from the <i class="arg">tarball</i>.</p>
 <pre class="doctools_example">
 % set readme [::tar::get tarball.tar doc/README] {

modules/tar/pkgIndex.tcl

@@ -1,2 +1,2 @@
 if {![package vsatisfies [package provide Tcl] 8.5 9]} { return }
-package ifneeded tar 0.12.1 [list source [file join $dir tar.tcl]]
+package ifneeded tar 0.13 [list source [file join $dir tar.tcl]]

modules/tar/tar.man

@@ -1,5 +1,5 @@
 [comment {-*- mode: tcl ; fill-column: 80 -*- doctools manpage}]
-[vset PACKAGE_VERSION 0.12.1]
+[vset PACKAGE_VERSION 0.13]
 [manpage_begin tar n [vset PACKAGE_VERSION]]
 [keywords archive]
 [keywords {tape archive}]
@@ -15,7 +15,7 @@
 (contents, stats, get, untar) support the GNU LongName extension (header type
 'L') for large paths.
 
-[para] 
+[para]
 
 [section BEWARE]
 
@@ -48,11 +48,34 @@ For all commands, when using [option -chan] ...
 
 [list_end]
 
+Regarding support for gzip compression:
+
+[list_begin enumerated]
+
+[enum] Errors are thrown when attempting to read from compressed tar archives
+       while compression support (i.e. [cmd ::zlib]) is not available.
+
+[enum] Errors are thrown when attempting to read an uncompressed tar archive
+       when compression is requested by the user ([option -gzip]).
+
+[para] No errors are thrown when attempting to read a compressed tar archive
+       when compression was not requested, and is supported. In that case the
+       commands automatically activate the code handling the compression.
+
+[enum] Errors are thrown when attempting to edit compressed tar archives.
+       See the commands [cmd tar::add], and [cmd tar::remove].
+       This is not supported.
+
+[enum] Creation of compressed tar archives however is supported, as this
+       sequentially writes the archive, allowing for streaming compression.
+
+[list_end]
+
 [section COMMANDS]
 
 [list_begin definitions]
 
-[call [cmd ::tar::contents] [arg tarball] [opt [option -chan]]]
+[call [cmd ::tar::contents] [arg tarball] [opt [option -chan]] [opt [option -gzip]]]
 
 Returns a list of the files contained in [arg tarball]. The order is not sorted and depends on the order
 files were stored in the archive.
@@ -62,7 +85,7 @@ If the option [option -chan] is present [arg tarball] is interpreted as an open
 It is assumed that the channel was opened for reading, and configured for binary input.
 The command will [emph not] close the channel.
 
-[call [cmd ::tar::stat] [arg tarball] [opt file] [opt [option -chan]]]
+[call [cmd ::tar::stat] [arg tarball] [opt file] [opt [option -chan]] [opt [option -gzip]]]
 
 Returns a nested dict containing information on the named [opt file] in [arg tarball],
 or all files if none is specified. The top level are pairs of filename and info. The info is a dict with the keys
@@ -117,7 +140,7 @@ puts "Extracted $file ($size bytes)"
 }
 }]
 
-[call [cmd ::tar::get] [arg tarball] [arg fileName] [opt [option -chan]]]
+[call [cmd ::tar::get] [arg tarball] [arg fileName] [opt [option -chan]] [opt [option -gzip]]]
 
 Returns the contents of [arg fileName] from the [arg tarball].