VERSION

version 0.926

SYNOPSIS

# don't use this, use a subclass

DESCRIPTION

This is a base class for different dist formats.

The following methods must be defined by subclasses:

• ``file_content''
• ``find_files''

METHODS

new

Simple constructor that subclasses can inherit. Ensures the presence of ``required_attribute'' if defined by the subclass.

default_file_spec

Defaults to 'Native' in the base class which will let File::Spec determine the value.

determine_name_and_version

Some dist formats may define a way to determine the name and version.

determine_packages

  $packages = $dist->determine_packages(@files);

Search the specified files (or all files if unspecified) for perl packages.

Extracts the files to a temporary directory if necessary and uses Module::Metadata to discover package names and versions.

extract_into

  $ddir = $dist->extract_into($dir);
  ($ddir, @dfiles) = $dist->extract_into($dir, @files);

Extracts the specified files (or all files if not specified) into the specified directory.

In list context this returns a list of the directory (which may be a subdirectory of the $dir passed in) and the files extracted (in native OS (on-disk) format).

In scalar context just the directory is returned.

file_content

Returns the content for the specified file from the dist.

This must be defined by subclasses.

file_checksum

  $dist->file_checksum('lib/Mod/Name.pm', 'sha256');

Returns a checksum (hex digest) of the file content.

The Digest module is used to generate the checksums. The value specified should be one accepted by "Digest->new". A small effort is made to translate simpler names like "md5" into "MD5" and "sha1" into "SHA-1" (which are the names Digest expects).

If the type of checksum is not specified "md5" will be used.

find_files

Determine the files contained in the dist.

This is called from ``list_files'' and cached on the object.

This must be defined by subclasses.

file_spec

Returns the OS name of the File::Spec module used for this format. This is mostly so subclasses can define a specific one (as ``default_file_spec'') if necessary.

A "file_spec" attribute can be passed to the constructor to override the default.

NOTE: This is used for the internal format of the dist. Tar archives, for example, are always in unix format. For operations outside of the dist, the format determined by File::Spec will always be used.

full_path

  $dist->full_path("lib/Mod.pm"); # "root-dir/lib/Mod.pm"

Used internally to put the ``root'' directory back onto the file.

list_files

Returns a list of the files in the dist starting at the dist root.

This calls ``find_files'' to get a listing of the contents of the dist, determines (and caches) the root directory (if any), caches and returns the list of files with the root dir stripped.

  @files = $dist->list_files;
  # something like qw( README META.yml lib/Mod.pm )

name

The dist name if it could be determined.

packages_from_directory

  $provides = $dist->packages_from_directory($dir, @files);

Determines the packages provided by the perl modules found in a directory. This is thin wrapper around ``package_versions_from_directory'' in Module::Metadata. It returns a hashref like ``provides'' in CPAN::Meta::Spec.

NOTE: $dir must be a physical directory on the disk, therefore @files (if specified) must be in native OS format. This function is called internally from ``determine_packages'' (which calls physical_directory (which calls ``extract_into'')) which manages these requirements.

parse_name_and_version

  ($name, $version) = $dist->parse_name_and_version($path);

Attempt to parse name and version from the provided string. This will work for dists named like ``Dist-Name-1.0''.

path_class_dir

Returns the class name used for Path::Class::Dir objects.

path_class_file

Returns the class name used for Path::Class::File objects.

path_classify_dir

This is a shortcut for returning an object representing the provided dir utilizing ``path_class_dir'' and ``file_spec''.

path_classify_file

This is a shortcut for returning an object representing the provided file utilizing ``path_class_file'' and ``file_spec''.

perl_files

Returns the subset of ``list_files'' that look like perl files. Currently returns anything matching "/\.pm$/"

TODO: This should probably be customizable.

physical_directory

  $dir = $dist->physical_directory();
  ($dir, @dir_files) = $dist->physical_directory(@files);

Returns the path to a physical directory on the disk where the specified files (if any) can be found.

For in-memory formats this will make a temporary directory and write the specified files (or all files) into it.

The return value is the same as ``extract_into'': In scalar context the path to the directory is returned. In list context the (possibly adjusted) paths to any specified files are appended to the return value.

remove_root_dir

  my ($dir, @rel) = $dm->remove_root_dir(@files);

If all the @files are beneath the same root directory (as is normally the case) this will strip the root directory off of each file and return a list of the root directory and the stripped files.

If there is no root directory the first element of the list will be "undef".

required_attribute

A single attribute that is required by the class. Subclasses can define this to make ``new'' "croak" if it isn't present.

root

Returns the root directory of the dist (if there is one).

set_name_and_version

This is a convenience method for setting the name and version if they haven't already been set. This is often called by ``determine_name_and_version''.

version

Returns the version if it could be determined from the dist.

AUTHOR

Randy Stauner <[email protected]>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Randy Stauner.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.