/ 
CPAN-Access-AdHoc-0.000_04
River stage zero No dependents
/ CPAN::Access::AdHoc::Archive

NAME

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

SYNOPSIS

This class is not intended to be used directly.

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.

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.

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 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 LWP::MediaTypes::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_items

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.

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 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.