1 package IO::Uncompress::AnyUncompress ;
7 use IO::Compress::Base::Common 2.024 qw(createSelfTiedObject);
9 use IO::Uncompress::Base 2.024 ;
14 our ($VERSION, @ISA, @EXPORT_OK, %EXPORT_TAGS, $AnyUncompressError);
17 $AnyUncompressError = '';
19 @ISA = qw( Exporter IO::Uncompress::Base );
20 @EXPORT_OK = qw( $AnyUncompressError anyuncompress ) ;
21 %EXPORT_TAGS = %IO::Uncompress::Base::DEFLATE_CONSTANTS ;
22 push @{ $EXPORT_TAGS{all} }, @EXPORT_OK ;
23 Exporter::export_ok_tags('all');
25 # TODO - allow the user to pick a set of the three formats to allow
26 # or just assume want to auto-detect any of the three formats.
30 eval ' use IO::Uncompress::Adapter::Inflate 2.024 ;';
31 eval ' use IO::Uncompress::Adapter::Bunzip2 2.024 ;';
32 eval ' use IO::Uncompress::Adapter::LZO 2.024 ;';
33 eval ' use IO::Uncompress::Adapter::Lzf 2.024 ;';
34 eval ' use IO::Uncompress::Adapter::UnLzma 2.020 ;';
35 eval ' use IO::Uncompress::Adapter::UnXz 2.020 ;';
37 eval ' use IO::Uncompress::Bunzip2 2.024 ;';
38 eval ' use IO::Uncompress::UnLzop 2.024 ;';
39 eval ' use IO::Uncompress::Gunzip 2.024 ;';
40 eval ' use IO::Uncompress::Inflate 2.024 ;';
41 eval ' use IO::Uncompress::RawInflate 2.024 ;';
42 eval ' use IO::Uncompress::Unzip 2.024 ;';
43 eval ' use IO::Uncompress::UnLzf 2.024 ;';
44 eval ' use IO::Uncompress::UnLzma 2.024 ;';
45 eval ' use IO::Uncompress::UnXz 2.024 ;';
51 my $obj = createSelfTiedObject($class, \$AnyUncompressError);
52 $obj->_create(undef, 0, @_);
57 my $obj = createSelfTiedObject(undef, \$AnyUncompressError);
58 return $obj->_inf(@_) ;
63 use IO::Compress::Base::Common 2.024 qw(:Parse);
64 return ( 'RawInflate' => [1, 1, Parse_boolean, 0] ,
65 'UnLzma' => [1, 1, Parse_boolean, 0] ) ;
73 # any always needs both crc32 and adler32
74 $got->value('CRC32' => 1);
75 $got->value('ADLER32' => 1);
88 if (defined $IO::Uncompress::RawInflate::VERSION )
90 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Inflate::mkUncompObject();
92 return $self->saveErrorString(undef, $errstr, $errno)
95 *$self->{Uncomp} = $obj;
97 my @possible = qw( Inflate Gunzip Unzip );
98 unshift @possible, 'RawInflate'
99 if $got->value('RawInflate');
101 $magic = $self->ckMagic( @possible );
104 *$self->{Info} = $self->readHeader($magic)
111 if (defined $IO::Uncompress::UnLzma::VERSION && $got->value('UnLzma'))
113 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::UnLzma::mkUncompObject();
115 return $self->saveErrorString(undef, $errstr, $errno)
118 *$self->{Uncomp} = $obj;
120 my @possible = qw( UnLzma );
121 #unshift @possible, 'RawInflate'
122 # if $got->value('RawInflate');
124 if ( *$self->{Info} = $self->ckMagic( @possible ))
130 if (defined $IO::Uncompress::UnXz::VERSION and
131 $magic = $self->ckMagic('UnXz')) {
132 *$self->{Info} = $self->readHeader($magic)
135 my ($obj, $errstr, $errno) =
136 IO::Uncompress::Adapter::UnXz::mkUncompObject();
138 return $self->saveErrorString(undef, $errstr, $errno)
141 *$self->{Uncomp} = $obj;
146 if (defined $IO::Uncompress::Bunzip2::VERSION and
147 $magic = $self->ckMagic('Bunzip2')) {
148 *$self->{Info} = $self->readHeader($magic)
151 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Bunzip2::mkUncompObject();
153 return $self->saveErrorString(undef, $errstr, $errno)
156 *$self->{Uncomp} = $obj;
161 if (defined $IO::Uncompress::UnLzop::VERSION and
162 $magic = $self->ckMagic('UnLzop')) {
164 *$self->{Info} = $self->readHeader($magic)
167 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::LZO::mkUncompObject();
169 return $self->saveErrorString(undef, $errstr, $errno)
172 *$self->{Uncomp} = $obj;
177 if (defined $IO::Uncompress::UnLzf::VERSION and
178 $magic = $self->ckMagic('UnLzf')) {
180 *$self->{Info} = $self->readHeader($magic)
183 my ($obj, $errstr, $errno) = IO::Uncompress::Adapter::Lzf::mkUncompObject();
185 return $self->saveErrorString(undef, $errstr, $errno)
188 *$self->{Uncomp} = $obj;
203 my $keep = ref $self ;
204 for my $class ( map { "IO::Uncompress::$_" } @names)
206 bless $self => $class;
207 my $magic = $self->ckMagic();
211 #bless $self => $class;
215 $self->pushBack(*$self->{HeaderPending}) ;
216 *$self->{HeaderPending} = '' ;
219 bless $self => $keep;
230 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop file/buffer
234 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
236 my $status = anyuncompress $input => $output [,OPTS]
237 or die "anyuncompress failed: $AnyUncompressError\n";
239 my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
240 or die "anyuncompress failed: $AnyUncompressError\n";
242 $status = $z->read($buffer)
243 $status = $z->read($buffer, $length)
244 $status = $z->read($buffer, $length, $offset)
245 $line = $z->getline()
250 $data = $z->trailingData()
251 $status = $z->nextStream()
252 $data = $z->getHeaderInfo()
254 $z->seek($position, $whence)
260 $AnyUncompressError ;
266 read($z, $buffer, $length);
267 read($z, $buffer, $length, $offset);
269 seek($z, $position, $whence)
277 This module provides a Perl interface that allows the reading of
278 files/buffers that have been compressed with a variety of compression
281 The formats supported are:
287 =item RFC 1951 (optionally)
289 =item gzip (RFC 1952)
305 The module will auto-detect which, if any, of the supported
306 compression formats is being used.
308 =head1 Functional Interface
310 A top-level function, C<anyuncompress>, is provided to carry out
311 "one-shot" uncompression between buffers and/or files. For finer
312 control over the uncompression process, see the L</"OO Interface">
315 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
317 anyuncompress $input => $output [,OPTS]
318 or die "anyuncompress failed: $AnyUncompressError\n";
320 The functional interface needs Perl5.005 or better.
322 =head2 anyuncompress $input => $output [, OPTS]
324 C<anyuncompress> expects at least two parameters, C<$input> and C<$output>.
326 =head3 The C<$input> parameter
328 The parameter, C<$input>, is used to define the source of
331 It can take one of the following forms:
337 If the C<$input> parameter is a simple scalar, it is assumed to be a
338 filename. This file will be opened for reading and the input data
339 will be read from it.
343 If the C<$input> parameter is a filehandle, the input data will be
345 The string '-' can be used as an alias for standard input.
347 =item A scalar reference
349 If C<$input> is a scalar reference, the input data will be read
352 =item An array reference
354 If C<$input> is an array reference, each element in the array must be a
357 The input data will be read from each file in turn.
359 The complete array will be walked to ensure that it only
360 contains valid filenames before any data is uncompressed.
362 =item An Input FileGlob string
364 If C<$input> is a string that is delimited by the characters "<" and ">"
365 C<anyuncompress> will assume that it is an I<input fileglob string>. The
366 input is the list of files that match the fileglob.
368 If the fileglob does not match any files ...
370 See L<File::GlobMapper|File::GlobMapper> for more details.
374 If the C<$input> parameter is any other type, C<undef> will be returned.
376 =head3 The C<$output> parameter
378 The parameter C<$output> is used to control the destination of the
379 uncompressed data. This parameter can take one of these forms.
385 If the C<$output> parameter is a simple scalar, it is assumed to be a
386 filename. This file will be opened for writing and the uncompressed
387 data will be written to it.
391 If the C<$output> parameter is a filehandle, the uncompressed data
392 will be written to it.
393 The string '-' can be used as an alias for standard output.
395 =item A scalar reference
397 If C<$output> is a scalar reference, the uncompressed data will be
398 stored in C<$$output>.
400 =item An Array Reference
402 If C<$output> is an array reference, the uncompressed data will be
403 pushed onto the array.
405 =item An Output FileGlob
407 If C<$output> is a string that is delimited by the characters "<" and ">"
408 C<anyuncompress> will assume that it is an I<output fileglob string>. The
409 output is the list of files that match the fileglob.
411 When C<$output> is an fileglob string, C<$input> must also be a fileglob
412 string. Anything else is an error.
416 If the C<$output> parameter is any other type, C<undef> will be returned.
420 When C<$input> maps to multiple compressed files/buffers and C<$output> is
421 a single file/buffer, after uncompression C<$output> will contain a
422 concatenation of all the uncompressed data from each of the input
425 =head2 Optional Parameters
427 Unless specified below, the optional parameters for C<anyuncompress>,
428 C<OPTS>, are the same as those used with the OO interface defined in the
429 L</"Constructor Options"> section below.
433 =item C<< AutoClose => 0|1 >>
435 This option applies to any input or output data streams to
436 C<anyuncompress> that are filehandles.
438 If C<AutoClose> is specified, and the value is true, it will result in all
439 input and/or output filehandles being closed once C<anyuncompress> has
442 This parameter defaults to 0.
444 =item C<< BinModeOut => 0|1 >>
446 When writing to a file or filehandle, set C<binmode> before writing to the
451 =item C<< Append => 0|1 >>
453 The behaviour of this option is dependent on the type of output data
460 If C<Append> is enabled, all uncompressed data will be append to the end of
461 the output buffer. Otherwise the output buffer will be cleared before any
462 uncompressed data is written to it.
466 If C<Append> is enabled, the file will be opened in append mode. Otherwise
467 the contents of the file, if any, will be truncated before any uncompressed
468 data is written to it.
472 If C<Append> is enabled, the filehandle will be positioned to the end of
473 the file via a call to C<seek> before any uncompressed data is
474 written to it. Otherwise the file pointer will not be moved.
478 When C<Append> is specified, and set to true, it will I<append> all uncompressed
479 data to the output data stream.
481 So when the output is a filehandle it will carry out a seek to the eof
482 before writing any uncompressed data. If the output is a filename, it will be opened for
483 appending. If the output is a buffer, all uncompressed data will be appened to
486 Conversely when C<Append> is not specified, or it is present and is set to
487 false, it will operate as follows.
489 When the output is a filename, it will truncate the contents of the file
490 before writing any uncompressed data. If the output is a filehandle
491 its position will not be changed. If the output is a buffer, it will be
492 wiped before any uncompressed data is output.
496 =item C<< MultiStream => 0|1 >>
498 If the input file/buffer contains multiple compressed data streams, this
499 option will uncompress the whole lot as a single data stream.
503 =item C<< TrailingData => $scalar >>
505 Returns the data, if any, that is present immediately after the compressed
506 data stream once uncompression is complete.
508 This option can be used when there is useful information immediately
509 following the compressed data stream, and you don't know the length of the
510 compressed data stream.
512 If the input is a buffer, C<trailingData> will return everything from the
513 end of the compressed data stream to the end of the buffer.
515 If the input is a filehandle, C<trailingData> will return the data that is
516 left in the filehandle input buffer once the end of the compressed data
517 stream has been reached. You can then use the filehandle to read the rest
520 Don't bother using C<trailingData> if the input is a filename.
522 If you know the length of the compressed data stream before you start
523 uncompressing, you can avoid having to use C<trailingData> by setting the
524 C<InputLength> option.
530 To read the contents of the file C<file1.txt.Compressed> and write the
531 uncompressed data to the file C<file1.txt>.
535 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
537 my $input = "file1.txt.Compressed";
538 my $output = "file1.txt";
539 anyuncompress $input => $output
540 or die "anyuncompress failed: $AnyUncompressError\n";
542 To read from an existing Perl filehandle, C<$input>, and write the
543 uncompressed data to a buffer, C<$buffer>.
547 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
550 my $input = new IO::File "<file1.txt.Compressed"
551 or die "Cannot open 'file1.txt.Compressed': $!\n" ;
553 anyuncompress $input => \$buffer
554 or die "anyuncompress failed: $AnyUncompressError\n";
556 To uncompress all files in the directory "/my/home" that match "*.txt.Compressed" and store the compressed data in the same directory
560 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
562 anyuncompress '</my/home/*.txt.Compressed>' => '</my/home/#1.txt>'
563 or die "anyuncompress failed: $AnyUncompressError\n";
565 and if you want to compress each file one at a time, this will do the trick
569 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
571 for my $input ( glob "/my/home/*.txt.Compressed" )
574 $output =~ s/.Compressed// ;
575 anyuncompress $input => $output
576 or die "Error compressing '$input': $AnyUncompressError\n";
583 The format of the constructor for IO::Uncompress::AnyUncompress is shown below
585 my $z = new IO::Uncompress::AnyUncompress $input [OPTS]
586 or die "IO::Uncompress::AnyUncompress failed: $AnyUncompressError\n";
588 Returns an C<IO::Uncompress::AnyUncompress> object on success and undef on failure.
589 The variable C<$AnyUncompressError> will contain an error message on failure.
591 If you are running Perl 5.005 or better the object, C<$z>, returned from
592 IO::Uncompress::AnyUncompress can be used exactly like an L<IO::File|IO::File> filehandle.
593 This means that all normal input file operations can be carried out with
594 C<$z>. For example, to read a line from a compressed file/buffer you can
595 use either of these forms
597 $line = $z->getline();
600 The mandatory parameter C<$input> is used to determine the source of the
601 compressed data. This parameter can take one of three forms.
607 If the C<$input> parameter is a scalar, it is assumed to be a filename. This
608 file will be opened for reading and the compressed data will be read from it.
612 If the C<$input> parameter is a filehandle, the compressed data will be
614 The string '-' can be used as an alias for standard input.
616 =item A scalar reference
618 If C<$input> is a scalar reference, the compressed data will be read from
623 =head2 Constructor Options
625 The option names defined below are case insensitive and can be optionally
626 prefixed by a '-'. So all of the following are valid
633 OPTS is a combination of the following options:
637 =item C<< AutoClose => 0|1 >>
639 This option is only valid when the C<$input> parameter is a filehandle. If
640 specified, and the value is true, it will result in the file being closed once
641 either the C<close> method is called or the IO::Uncompress::AnyUncompress object is
644 This parameter defaults to 0.
646 =item C<< MultiStream => 0|1 >>
648 Allows multiple concatenated compressed streams to be treated as a single
649 compressed stream. Decompression will stop once either the end of the
650 file/buffer is reached, an error is encountered (premature eof, corrupt
651 compressed data) or the end of a stream is not immediately followed by the
652 start of another stream.
654 This parameter defaults to 0.
656 =item C<< Prime => $string >>
658 This option will uncompress the contents of C<$string> before processing the
661 This option can be useful when the compressed data is embedded in another
662 file/data structure and it is not possible to work out where the compressed
663 data begins without having to read the first few bytes. If this is the
664 case, the uncompression can be I<primed> with these bytes using this
667 =item C<< Transparent => 0|1 >>
669 If this option is set and the input file/buffer is not compressed data,
670 the module will allow reading of it anyway.
672 In addition, if the input file/buffer does contain compressed data and
673 there is non-compressed data immediately following it, setting this option
674 will make this module treat the whole file/bufffer as a single data stream.
676 This option defaults to 1.
678 =item C<< BlockSize => $num >>
680 When reading the compressed input data, IO::Uncompress::AnyUncompress will read it in
681 blocks of C<$num> bytes.
683 This option defaults to 4096.
685 =item C<< InputLength => $size >>
687 When present this option will limit the number of compressed bytes read
688 from the input file/buffer to C<$size>. This option can be used in the
689 situation where there is useful data directly after the compressed data
690 stream and you know beforehand the exact length of the compressed data
693 This option is mostly used when reading from a filehandle, in which case
694 the file pointer will be left pointing to the first byte directly after the
695 compressed data stream.
697 This option defaults to off.
699 =item C<< Append => 0|1 >>
701 This option controls what the C<read> method does with uncompressed data.
703 If set to 1, all uncompressed data will be appended to the output parameter
704 of the C<read> method.
706 If set to 0, the contents of the output parameter of the C<read> method
707 will be overwritten by the uncompressed data.
711 =item C<< Strict => 0|1 >>
713 This option controls whether the extra checks defined below are used when
714 carrying out the decompression. When Strict is on, the extra tests are
715 carried out, when Strict is off they are not.
717 The default for this option is off.
719 =item C<< RawInflate => 0|1 >>
721 When auto-detecting the compressed format, try to test for raw-deflate (RFC
722 1951) content using the C<IO::Uncompress::RawInflate> module.
724 The reason this is not default behaviour is because RFC 1951 content can
725 only be detected by attempting to uncompress it. This process is error
726 prone and can result is false positives.
730 =item C<< UnLzma => 0|1 >>
732 When auto-detecting the compressed format, try to test for lzma_alone
733 content using the C<IO::Uncompress::UnLzma> module.
735 The reason this is not default behaviour is because lzma_alone content can
736 only be detected by attempting to uncompress it. This process is error
737 prone and can result is false positives.
753 $status = $z->read($buffer)
755 Reads a block of compressed data (the size the the compressed block is
756 determined by the C<Buffer> option in the constructor), uncompresses it and
757 writes any uncompressed data into C<$buffer>. If the C<Append> parameter is
758 set in the constructor, the uncompressed data will be appended to the
759 C<$buffer> parameter. Otherwise C<$buffer> will be overwritten.
761 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
762 or a negative number on error.
768 $status = $z->read($buffer, $length)
769 $status = $z->read($buffer, $length, $offset)
771 $status = read($z, $buffer, $length)
772 $status = read($z, $buffer, $length, $offset)
774 Attempt to read C<$length> bytes of uncompressed data into C<$buffer>.
776 The main difference between this form of the C<read> method and the
777 previous one, is that this one will attempt to return I<exactly> C<$length>
778 bytes. The only circumstances that this function will not is if end-of-file
779 or an IO error is encountered.
781 Returns the number of uncompressed bytes written to C<$buffer>, zero if eof
782 or a negative number on error.
788 $line = $z->getline()
793 This method fully supports the use of of the variable C<$/> (or
794 C<$INPUT_RECORD_SEPARATOR> or C<$RS> when C<English> is in use) to
795 determine what constitutes an end of line. Paragraph mode, record mode and
796 file slurp mode are all supported.
804 Read a single character.
810 $char = $z->ungetc($string)
816 $hdr = $z->getHeaderInfo();
817 @hdrs = $z->getHeaderInfo();
819 This method returns either a hash reference (in scalar context) or a list
820 or hash references (in array context) that contains information about each
821 of the header fields in the compressed data stream(s).
830 Returns the uncompressed file offset.
839 Returns true if the end of the compressed input stream has been reached.
843 $z->seek($position, $whence);
844 seek($z, $position, $whence);
846 Provides a sub-set of the C<seek> functionality, with the restriction
847 that it is only legal to seek forward in the input file/buffer.
848 It is a fatal error to attempt to seek backward.
850 The C<$whence> parameter takes one the usual values, namely SEEK_SET,
851 SEEK_CUR or SEEK_END.
853 Returns 1 on success, 0 on failure.
862 This is a noop provided for completeness.
868 Returns true if the object currently refers to a opened file/buffer.
872 my $prev = $z->autoflush()
873 my $prev = $z->autoflush(EXPR)
875 If the C<$z> object is associated with a file or a filehandle, this method
876 returns the current autoflush setting for the underlying filehandle. If
877 C<EXPR> is present, and is non-zero, it will enable flushing after every
878 write/print operation.
880 If C<$z> is associated with a buffer, this method has no effect and always
883 B<Note> that the special variable C<$|> B<cannot> be used to set or
884 retrieve the autoflush setting.
886 =head2 input_line_number
888 $z->input_line_number()
889 $z->input_line_number(EXPR)
891 Returns the current uncompressed line number. If C<EXPR> is present it has
892 the effect of setting the line number. Note that setting the line number
893 does not change the current position within the file/buffer being read.
895 The contents of C<$/> are used to to determine what constitutes a line
903 If the C<$z> object is associated with a file or a filehandle, C<fileno>
904 will return the underlying file descriptor. Once the C<close> method is
905 called C<fileno> will return C<undef>.
907 If the C<$z> object is is associated with a buffer, this method will return
915 Closes the output file/buffer.
917 For most versions of Perl this method will be automatically invoked if
918 the IO::Uncompress::AnyUncompress object is destroyed (either explicitly or by the
919 variable with the reference to the object going out of scope). The
920 exceptions are Perl versions 5.005 through 5.00504 and 5.8.0. In
921 these cases, the C<close> method will be called automatically, but
922 not until global destruction of all live objects when the program is
925 Therefore, if you want your scripts to be able to run on all versions
926 of Perl, you should call C<close> explicitly and not rely on automatic
929 Returns true on success, otherwise 0.
931 If the C<AutoClose> option has been enabled when the IO::Uncompress::AnyUncompress
932 object was created, and the object is associated with a file, the
933 underlying file will also be closed.
939 my $status = $z->nextStream();
941 Skips to the next compressed data stream in the input file/buffer. If a new
942 compressed data stream is found, the eof marker will be cleared and C<$.>
945 Returns 1 if a new stream was found, 0 if none was found, and -1 if an
946 error was encountered.
952 my $data = $z->trailingData();
954 Returns the data, if any, that is present immediately after the compressed
955 data stream once uncompression is complete. It only makes sense to call
956 this method once the end of the compressed data stream has been
959 This option can be used when there is useful information immediately
960 following the compressed data stream, and you don't know the length of the
961 compressed data stream.
963 If the input is a buffer, C<trailingData> will return everything from the
964 end of the compressed data stream to the end of the buffer.
966 If the input is a filehandle, C<trailingData> will return the data that is
967 left in the filehandle input buffer once the end of the compressed data
968 stream has been reached. You can then use the filehandle to read the rest
971 Don't bother using C<trailingData> if the input is a filename.
973 If you know the length of the compressed data stream before you start
974 uncompressing, you can avoid having to use C<trailingData> by setting the
975 C<InputLength> option in the constructor.
979 No symbolic constants are required by this IO::Uncompress::AnyUncompress at present.
985 Imports C<anyuncompress> and C<$AnyUncompressError>.
988 use IO::Uncompress::AnyUncompress qw(anyuncompress $AnyUncompressError) ;
996 L<Compress::Zlib>, L<IO::Compress::Gzip>, L<IO::Uncompress::Gunzip>, L<IO::Compress::Deflate>, L<IO::Uncompress::Inflate>, L<IO::Compress::RawDeflate>, L<IO::Uncompress::RawInflate>, L<IO::Compress::Bzip2>, L<IO::Uncompress::Bunzip2>, L<IO::Compress::Lzma>, L<IO::Uncompress::UnLzma>, L<IO::Compress::Xz>, L<IO::Uncompress::UnXz>, L<IO::Compress::Lzop>, L<IO::Uncompress::UnLzop>, L<IO::Compress::Lzf>, L<IO::Uncompress::UnLzf>, L<IO::Uncompress::AnyInflate>
998 L<Compress::Zlib::FAQ|Compress::Zlib::FAQ>
1000 L<File::GlobMapper|File::GlobMapper>, L<Archive::Zip|Archive::Zip>,
1001 L<Archive::Tar|Archive::Tar>,
1002 L<IO::Zlib|IO::Zlib>
1006 This module was written by Paul Marquess, F<pmqs@cpan.org>.
1008 =head1 MODIFICATION HISTORY
1010 See the Changes file.
1012 =head1 COPYRIGHT AND LICENSE
1014 Copyright (c) 2005-2010 Paul Marquess. All rights reserved.
1016 This program is free software; you can redistribute it and/or
1017 modify it under the same terms as Perl itself.