This is the README file for Archive::Tar, the Perl module for creation
and in-memory manipulation of tar files.

* Installation

Archive::Tar uses the standard perl module install process

perl Makefile.PL
make
make test (optional but recommended)
make install

This module uses no C-coded parts in itself, but it will try to use
the IO::Zlib module to read and write gzipped tarfiles.
Archive::Tar will still work without IO::Zlib, it will just complain 
when you try to use a compressed archive or write one, since it 
obviously can't. 

A snapshot of the latest development version of Archive::Tar may be 
optained at: http://p4.elixus.org/snap/Archive-Tar.tar.gz

* important changes in version 1.22 21/11/2004:

This release holds only bugfixes.
-   Make list_files() also return full_path() rather than name(),
    as that would ignore the prefix field. This was found to break
    PPM (bug #8537)

* important changes in version 1.21 9/11/2004:

This release holds only bugfixes.
-   Make the size of symlinks be 0 in tar headers, so the next entry
    is not interpreted as contents of the symlink (bug #7937)
-   Strip high bits from the mode of the file, as they are stored 
    differently in the tar header
-   Make Archive::Tar be kinder to archives that contain garbage,
    proceeding anyway as long as that's possible.

* important changes in version 1.20 8/11/2004:

This release holds mostly bugfixes, in the form of a rewrite of 
the handling of the 'prefix' header field.
-   Rewrote 02_methods.t to be more independant
-   Rewrote the way 'prefix' headers are dealt with
-   Require IO::String now to do archive stringification
-   Add new method 'full_path' to A::T::Item objects
    - this is used to fix bug 6938
-   A::T->new now accepts both a class and an object to be friendlier
    to users
-   On tar read errors, binary chunks are no longer dumped to STDOUT,
    but instead the error offset is reported

* important changes in version 1.09 22/5/2004:

This release holds some bugfixes and also the return of bin/ptar
-   Make new() comply with the documentation and return undef on
    a read() failure.
-   Re-adds bin/ptar, which disappeared from this distribution after
    0.22 (sorry about that).
-   Makes 'IO::Zlib' a default prerequisite. You can still disable 
    this by supplying the -n option to 'perl Makefile.PL'.    

* important changes in version 1.08 5/1/2004:

This release holds some bugfixes and extra tests over the 1.07 release:
-   Fix a file renaming bug that forgot to carry over path info
-   Fix a bug where adding dirs on win32 gave 'permission denied'
-   Fix some documentation typos
-   Add extra tests explicilty for Archive::Tar::File
-   Move completely from FileHandle to IO::File

* important changes in version 1.07 17/10/2003:

This release holds some bugfixes over the 1.06 release:
-   Quell some annoying warnings about binmode on unopened filehandles
-   Add tests for binary files included in a tarball

* important changes in version 1.06 15/10/2003:

This release holds some bugfixes and new features over the 1.05 release.
-   The chown() code somehow didn't make it into the 1.05 release
-   Patch _get_handle() to treat all IO::File handles as binary.
    This should make win32 users happy
    
New feature added:
-   A method called 'contains_file' that will tell you if a certain file
    is already in the archive.    

* important changes in version 1.05 23/8/2003:

This release holds some bugfixes and new features over the 1.04 release.
-   The Test::Harness that came with perl 5.6.0 was buggy, require
    a higher version in the Makefile.PL
-   Add a global variable $CHOWN that controls whether Archive::Tar
    should attempt to chown() files or not when it can.    

* important changes in version 1.04 27/7/2003:

This release hold a bugfix over the 1.03 release:
-   NULL-byte padding was done also on files that had no real content,
    like symlinks, thus ending up with a number of bytes not dividable
    by 512.

* important changes in version 1.03 26/6/2003:

This release holds some bugfixes over the 1.02 release, mainly these:
-   Always do a readlink on the full path, never just the file
-   Make Archive::Tar write proper headers when dealing with symlinks
    For this $Archive::Tar::FOLLOW_SYMLINKS is introduced

* important changes in version 1.02 12/6/2003:

This release holds some bugfixes over the 1.01 release, mainly these:
-   Silly thinko fix in File.pm
-   Quell some warnings if files are empty
-   The cache of previously added files was not being emptied

Also, some new features are added:

-   Archive::Tar::File objects now have a C<has_content> method.

* important changes in version 1.01 5/6/2003:

This release holds some bugfixes over the 1.00 release, mainly these:

-   Silence some warnings when writing directories to disk.
-   A { } inside a map was interpreted as a block rather than a hashref 
    constructor -- now fixed.
-   Fix write() to work again as advertised when passed no arguments.
-   This also means glob support to write is now definitely not
    available.
-   Silly thinko of where splitpath() instead of splitdir() was used.

Some new features/changes:

-   Add a new method 'has_content' to Archive::Tar::File.
-   Cygwin's tests will now also use the 'short' files, since cygwin
    is built on top of an Win32 filesystem.

* important changes in version 1.00 31/5/2003:

This release marks the new development track as 'stable'. Version got
upped to '1.00'. Not many changes, merely lots of successful test 
reports constitute this version. However, a tiny fix regarding the
reserved string 'VERSION' has been applied, as well as a few more FAQ
entries have been added.

* important changes in version 0.99_06 5/5/2003:

This release only entails a bug fix on 0.99_05 -- C<extract_archive>
was dealing wrongly with special files such as hardlinks etc. This
is now fixed.

* important changes in version 0.99_05 30/4/2003:

Apparently windows has some issues with long path names.
This version introduces an adapted test suite for Win32 machines.

* important changes in version 0.99_04 28/4/2003:

Make Archive::Tar work happily on perl 5.005_03

* important changes in version 0.99_03 28/4/2003:

This release only has bug fixes on 0.99_02.

Fixed handling of long file names when extracting with 
C<extract_archive>

Fixed handling of prefixes in tar headers that contain regex meta-
characters.

Fixed a few spurious warnings about comparing non-numbers.

Expanded the test cases accordingly.


* important changes in version 0.99_02 26/3/2003:

Added options to be passed to read, namely:
	- extract (to extract while reading)
	- limit (to limit the amount of files read from the archive)

Implemented the '././@LongLink' support, which is GNU's way of
dealing with filenames that are longer than 255 chars.

Added a global variable $WARN which controls whether warnings get
printed or just stored.

Fixed a few small bugs that considered files named '0' or '' to not
really be files and refuse to package them.

* important changes in version 0.99_01 16/3/2003:

Total rewrite from the ground up. Removed as many as the nasty 
bits (no pun intended) as possible and tucked them away. 
No code from the old distribution remains.

Cleaned up the API, introduced clean error handling and just 
generally removed a lot of cruft.

Note that Archive::Tar now requires perl version 5.005_03 or higher 
to run.

Introduced 2 new submodules:
Archive::Tar::Constant
    Simply holds all constants, like block length, tar headers etc
    
Archive::Tar::File
    Object class for all files in a tar archive, to make for easier
    manipulataion of the archive in-memory.
    See perldoc Archive::Tar::File after installation.

Added a few features:
write() now takes an optional 3rd paramater (prefix) which will allow
you to tuck away all files in that sub directory.

rename() is introduced, allowing for easy renaming of files in the
archive.

get_files() returns a file of all Archive::Tar::File objects in the
current read-in archive.

* important changes in version 0.23, 21/1/2003:

Bundled 0.072 and 0.22 to be able to work on Win32 and non-Win32
platforms. Since the previous version is almost 3 years old, bundling
seemed like the quickest way to get a working solution again.

Archive::Tar now transparently Does The Right Thing depending what
platform you are on -- Win32 users, read the Archive::Tar::Win32
documentation!

I also suppose this makes me the new maintainer...

* important changes in version 0.20:

New class methods create_archive, extract_archive & list_archive.

Archive::Tar no longer keeps the entire archive in memory after
reading it.  This results in a major reduction in memory consumption.

Added suport for character & block special files.  These files are
currently created using mknod, so they will only be available on UNIX
platforms.

See the file ChangeLog for more complete details.

* important changes for version 0.08

Fixed (again) the MacOS support and included alpha support for
block/character special files as well as improving symlink handling.

NOTE: Archive::Tar is undergoing major work to extend the interface
and lower memory consumpton.  Any changes to the existing interface
should be extensions only.

* important changes for version 0.072.

Fixes a problem with systems that don't like open files being deleted.
It also has an explicit copyright notice so folks like Debian can
redistribute it in peace, and an new custodial maintainer due to
Calle's suffering Carpal Tunnel Syndrome.

Get better soon, Calle!

* important changes for version 0.071

It fixes a bunch of bugs, implements POSIX-style long pathnames and
adds a couple of useful methods.  It has also been verified to work on
Win32.

This version also includes a small tar-lookalike program, ptar. There
is no documentation beyond a usage message, but if you've ever used at
Unix-style tar program it should be very familiar.

Unless something really strange and terrible shows up, this will be
the last alpha-test version, and the next release will be beta-test
and v0.50 or something like that.

If you use this module at all, please mail Calle
<calle@lysator.liu.se> or Stephen <gibreel@pobox.com> and tell us what
you think of it.

Calle Dybedahl,
33 Aftermath, 3163 (mundanely known as 21 November 1997)

Gurusamy "stand-in maintainer" Sarathy,
-697 Millennium, 2 (mundanely known as  1 February 1998)

Stephen Zander (new custodial maintainer)
Day 9, Year 90 of Our Ford (mundanely known as 9 January 1999)

Jos Boumans (bundler),
1043188048 (mundanely known as 21st of January 2003)
