function varargout = untar(tarFilename, varargin)
%UNTAR Extract the contents of a TAR-file.
%   UNTAR(TARFILENAME) extracts the archived contents of TARFILENAME into
%   the current directory. 
%
%   TARFILENAME is a string specifying the name of the TAR-file.
%   TARFILENAME is gunzipped to a temporary directory and deleted if its
%   extension ends in '.tgz' or '.gz'.  If an extension is omitted, UNTAR
%   searches for TARFILENAME appended with '.tgz', '.tar.gz' or '.tar'
%   until a file exists. TARFILENAME may include the directory name;
%   otherwise, the file must be in the current directory or in a directory
%   on the MATLAB path.
%
%   UNTAR(TARFILENAME,OUTPUTDIR) extracts the archived contents of
%   TARFILENAME into the directory OUTPUTDIR. OUTPUTDIR is created if it
%   does not exist.
%
%   FILENAMES = UNTAR(...) extracts the tar archive and returns the
%   relative path names of the extracted files into the string cell array,
%   FILENAMES.
%
%   [...] = UNTAR(URL, ...) extracts the tar archive from an  Internet URL.
%   The URL must include the protocol type (e.g., 'http://' or 'ftp://').
%   The URL is downloaded to the temp directory and deleted.
%
%   Examples
%   --------
%   % Copy all *.m files in the current directory to the directory 'backup'
%   tar('mymfiles.tar.gz','*.m');
%   untar('mymfiles','backup');
%
%   % Untar and list Cleve Moler's Numerical Computing with MATLAB examples
%   % to the output directory 'ncm'.
%   url ='http://www.mathworks.com/moler/ncm.tar.gz';
%   ncmFiles = untar(url,'ncm')
%
%   See also GZIP, GUNZIP, TAR, UNZIP, ZIP.

%   Copyright 2004 The MathWorks, Inc.
%   $Revision: 1.1.6.1 $ $Date: 2004/11/23 20:40:03 $

error(nargchk(1,2,nargin,'struct'));
error(nargoutchk(0,1,nargout,'struct'));

% Argument parsing.
[tarFilename, outputDir, url, urlFilename, uncompressFcn] = ...
   parseUnArchiveInputs(mfilename, tarFilename, ...
                        {'tgz', 'tar.gz', 'tar'},  ...
                        'TARFILENAME', varargin{:});

if ~isempty(uncompressFcn)
   try
      tarFilename = uncompressFcn(tarFilename,tempdir);
   catch
      [msg, id] = lasterr;
      % If the tar file is a URL, the HTTP client may have 
      % uncompressed the file.  If so, allow the file to pass.
      if ~(url && isequal('MATLAB:gunzip:notGzipFormat', id))
         rethrow(lasterror)
      end
   end
end

% Extract tar contents
tarJavaFile  = java.io.File(tarFilename);
fileInStream = java.io.FileInputStream(tarJavaFile);
tarInStream  = com.ice.tar.TarInputStream(fileInStream);
try
  files = extractArchive( outputDir, tarInStream, mfilename);
catch
  cleanup;
  rethrow(lasterror)
end

cleanup;
if nargout == 1
   varargout{1} = files;
end

%--------------------------------------------------------------------------
   function cleanup
      fileInStream.close;
      tarInStream.close;
      if ~isempty(uncompressFcn)
         tarJavaFile.delete;
      end
      if url && ~isempty(urlFilename) && exist(urlFilename,'file')
         delete(urlFilename)
      end
   end
end