/ 
CPAN-Access-AdHoc-0.000_02
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_package_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.

encoding

This is the MIME encoding of the content. It is ignored if the content is not present. Subclasses are expected to support encodings 'gzip' and 'x-bzip2'.

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.

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 package. 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 package, as computed from the directories contained in the package.

extract

This method extracts the contents of the archive. 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().

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 appropriate datum (typically a CPAN::Access::AdHoc::Archive object, though it may simply be a string if the response object represents the contents of a single file). 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.

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 package. Only files are listed.

metadata

This method returns the package's metadata as a CPAN::Meta object. The return of this method is the decoding of the package'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.