NAME

CPAN::Access::AdHoc::Archive - Common archive functionality for CPAN::Access::AdHoc

SYNOPSIS

This class is not intended to be used directly.

NOTICE

Effective with version 0.000_12:

Method wrap_archive() takes an optional leading hash. You can use either key {author} to specify the CPAN author ID for the archive, or key {directory} to specify its archive relative to the CPAN root. The argument after the file name is deprecated, and will be removed a week after the publication of 0.000_12.

DESCRIPTION

This class provides common functionality needed by the accessors for the various archive formats that are found in CPAN.

METHODS

This class supports the following public methods:

Instantiator

new

 my $arc = CPAN::Access::AdHoc::Archive->new(
     content => \$content,
     encoding => 'gzip',
 );

This static method instantiates the object. It is actually implemented on the subclasses, and may not be called on this class. In use, it is expected that the user will not call this method directly, but get the archive objects from CPAN::Access::AdHoc's fetch_distribution_archive() method. See that method's documentation for how it initialized this object.

This method takes arguments as name/value pairs. The following are supported:

content

This is the content to be loaded into the object. A scalar reference is assumed to be the literal content. A non-reference is assumed to be the file name. Any other value is unsupported.

Passing content to a subclass that is not designed to support that content is unsupported. That is to say, if you pass the contents of a Zip file to CPAN::Access::AdHoc::Archive::Tar->new(), nothing good will happen.

encoding

This is the MIME encoding of the content. It is ignored if the content is not present. If the content is not encoded, this argument can be omitted or passed a value of undef.

Subclasses are expected to support encodings 'gzip' and 'x-bzip2'.

Again, nothing good will happen if the content is not actually encoded this way.

mtime

This is the modification time of the archive.

path

This optional argument is intended to contain the path to the archive. Subclasses may (but need not) default it to the value of the content argument, provided the content argument is not a reference.

The intent is that the various components of this distribution should conspire to make this the path to the file relative to the CPAN URL.

If you do not specify at least content, you get an empty object, which is of limited usefulness.

Accessors/Mutators

These methods retrieve or modify the attributes of the class.

archive

This method is an accessor for the object representing the archive that actually contains the CPAN distribution.

This attribute is read-only, so it is an error to pass an argument.

mtime

This method is an accessor for the time the archive was last modified.

This attribute is read-only, so it is an error to pass an argument.

path

This method is an accessor for the path of the archive.

This attribute is read-only, so it is an error to pass an argument.

Other methods

These are either convenience methods or methods that provide a consistent interface to the underlying archive object.

base_directory

This method returns the natural base directory of the distribution, as computed from the directories contained in the distribution.

extract

This method extracts the contents of the archive to files. It simply wraps whatever the extraction method is for the underlying archiver.

get_item_content

 print "README:\n", $arc->get_item_content( 'README' );

This method returns the content of the named item in the archive. The name of the item is specified relative to $arc->base_directory().

get_item_mtime

 use POSIX qw{ strftime };
 print 'README modified ', strftime(
     '%d-%b-%Y %H:%M:%S',
      $arc->get_item_mtime( 'README' ) ), "\n";

This method returns the modification time of the named item in the archive. The name of the item is specified relative to $arc->base_directory().

__handle_http_response

This static method is private to the CPAN-Access-AdHoc package.

This method takes as its argument an HTTP::Response object. If this method determines that it can handle the response object, it does so, returning the CPAN::Access::AdHoc::Archive object derived from the content of the HTTP::Response object. Otherwise, it simply returns.

The method can do anything it wants to evaluate its argument, but typically it examines the Content-Type, Content-Encoding, and Content-Location headers. The expected values of these headers are those loaded by CPAN::Access::AdHoc::Util::__guess_media_type().

For this class (i.e. CPAN::Access::AdHoc::Archive), the method simply calls __handle_http_response() on all the CPAN::Access::AdHoc::Archive::* classes until one chooses to handle the HTTP::Response object by returning a CPAN::Access::AdHoc::Archive object. If none of the subclasses handles the HTTP::Response object, nothing is returned.

item_present

 $arc->item_present( 'Build.PL' )
   and say 'Archive buildable with Module::Build';

This method returns a true value if the named item is present in the archive, and a false value otherwise. The name of the item is specified relative to $self->base_directory().

list_contents

This method lists the items in the distribution. Only files are listed.

metadata

This method returns the distribution's metadata as a CPAN::Meta object. The return of this method is the decoding of the distribution's META.json or META.yml files, taken in that order. If neither is present, or neither contains valid metadata as determined by CPAN::Meta, nothing is returned -- this method makes no further effort to establish what the metadata are.

wrap_archive

 my $archive = CPAN::Access::AdHoc::Archive->wrap_archive(
     { author => 'MYCPANID' },
     'foo/MyDistrib-0.001.tar.gz' );

This method (either normal or static) makes a CPAN::Access::AdHoc::Archive object out of a local file, and returns it.

The leading hash before the file name is optional, and specifies the path to the item in a CPAN archive. This is combined with the base name of the file and the result is used to populate the path attribute of the archive. Possible keys are

 author => the CPAN author ID for the archive;
 directory => The directory relative to the CPAN archive root.

You may not specify both author and directory, since this is ambiguous.

If no option hash is specified, or neither author nor directory is specified in it, the full path name will be made into a file: URL, and any prefix before /authors/ or /modules/ is removed; if these are not found, the full path name of the file is used.

write

 $archive->write( $file_name );
 $archive->write();

This method writes the contents of the archive to the given file name. If the name indicates that the file should be encoded and the archiver supports that encoding, the encoding is applied. For example, a Tar archive written to a file whose name ends in .gz will be compressed with gzip.

If the file name is omitted, it defaults to the base name of $archive->path().

SUPPORT

Support is by the author. Please file bug reports at http://rt.cpan.org, or in electronic mail to the author.

AUTHOR

Thomas R. Wyant, III wyant at cpan dot org

COPYRIGHT AND LICENSE

Copyright (C) 2012-2013 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5.10.0. For more details, see the full text of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

cpanm CPAN::Access::AdHoc

perl -MCPAN -e shell
install CPAN::Access::AdHoc