== Description
  A simple tar interface using external system calls.

== Synopsis
  # Assuming we have three .txt files, t1.txt, t2.txt, t3.txt ...
  require 'archive/tar/external'
  include Archive

  t = Tar::External.new("myfile.tar")
 
  t.create_archive("*.txt")
  t.compress_archive("bzip2") # 'myfile.tar.bz2' now exists

  t.uncompress_archive("bunzip2")

  t.archive_name # "myfile.tar"
  t.archive_info # ["t1.txt","t2.txt","t3.txt"]

  t.add_to_archive("t4.txt","t5.txt")
  t.expand_archive

== Constants
VERSION
  Current version number of this library. This is a string.

== Class Methods
Archive::Tar::External.new(archive_name, pattern=nil, program=nil)
   Creates an instance of an Archive::Tar::External object.  The +archive_name+ is
   the name of the tarball.  While a '.tar' extension is recommended based on
   years of convention, it is not enforced.
   
   If +pattern+ is provided, then the Archive#create_archive method is called
   internally.
   
   If +program+ is provided, then the Archive#compress_archive method is
   called internally.

   Note that +archive_name+ name must be a String, or a TypeError is raised.

Archive::Tar::External.expand_archive(archive_name, *files)
   Identical to the instance method of the same name, except that you must
   specify the +archive_name+, and the tar program is hard coded to 'tar xf'.

Archive::Tar::External.uncompress_archive(archive_name, program='gunzip')
   Identical to the instance method of the same name, except that you must
   specify the +archive_name+ as the first argument.

== Instance Methods
Archive;:Tar#add(file1 [, file2, ...])
Archive::Tar::External#add_to_archive(file1 [, file2, ...])
   Adds a list of files to the current archive.  At least one file must be
   provided or a Tar::Error is raised.

Archive::Tar::External#archive_info
Archive::Tar::External#info
   Returns an array of file names that are included within the tarball.

Archive::Tar::External#archive_name
   Returns the current archive name.

Archive::Tar::External#archive_name=
   Sets the current archive name.

Archive::Tar::External#compress(program="gzip")
Archive::Tar::External#compress_archive(program="gzip")
   Compresses the tarball using the program you pass to this method. The
   default is "gzip".

   Note that any arguments you want to be passed along with the program can
   simply be included as part of the program, e.g. "gzip -f".

Archive::Tar::External#create(file_pattern)
Archive::Tar::External#create_archive(file_pattern)
   Creates a new tarball, including those files which match 'file_pattern'.

Archive::Tar::External#expand_archive(files=nil)
Archive::Tar::External#extract_archive(files=nil)
   Expands the contents of the tarball. Note that this method does NOT delete
   the tarball.

   If file names are provided, then only those files are extracted.

Archive::Tar::External#tar_program
   Returns the name of the tar program used.  The default is "tar".

Archive::Tar::External#tar_program=(program_name)
   Sets the name of the tar program to be used.

Archive::Tar::External#uncompress(program="gunzip")
Archive::Tar::External#uncompress_archive(program="gunzip")
   Uncompresses the tarball using the program you pass to this method.  The
   default is "gunzip".

   As for compress_archive(), you can pass arguments along as part of the
   argument.

Archive::Tar::External#update(files)
Archive::Tar::External#update_archive(files)
   Updates the given +files+ in the archive, i.e they are added if they
   are not already in the archive or have been modified.

== Exceptions
Tar::Error
   Raised if something goes wrong during the execution of any methods that
   use the tar command internally.

Tar::CompressError
   Raised if something goes wrong during the Tar#compress_archive or
   Tar#uncompress_archive methods.