Dist::Metadata::Dist: Base class for format-specific implementations

METHODS

new

Simple constructor that subclasses can inherit. Ensures the presence of \*(L"required_attribute\*(R" 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 \s-1OS\s0 (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 \*(C`Digest->new\*(C'. A small effort is made to translate simpler names like \*(C`md5\*(C' into \*(C`MD5\*(C' and \*(C`sha1\*(C' into \*(C`SHA-1\*(C' (which are the names Digest expects).

If the type of checksum is not specified \*(C`md5\*(C' will be used.

find_files

Determine the files contained in the dist.

This is called from \*(L"list_files\*(R" and cached on the object.

This must be defined by subclasses.

file_spec

Returns the \s-1OS\s0 name of the File::Spec module used for this format. This is mostly so subclasses can define a specific one (as \*(L"default_file_spec\*(R") if necessary.

A \*(C`file_spec\*(C' attribute can be passed to the constructor to override the default.

\s-1NOTE\s0: 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 \*(L"root\*(R" directory back onto the file.

list_files

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

This calls \*(L"find_files\*(R" to get a listing of the contents of the dist, determines (and caches) the root directory (if any), caches and returns the 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 \*(L"package_versions_from_directory\*(R" in Module::Metadata. It returns a hashref like \*(L"provides\*(R" in CPAN::Meta::Spec.

\s-1NOTE\s0: $dir must be a physical directory on the disk, therefore @files (if specified) must be in native \s-1OS\s0 format. This function is called internally from \*(L"determine_packages\*(R" (which calls physical_directory (which calls \*(L"extract_into\*(R")) 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 \*(L"Dist-Name-1.0\*(R".

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 \*(L"path_class_dir\*(R" and \*(L"file_spec\*(R".

path_classify_file

This is a shortcut for returning an object representing the provided file utilizing \*(L"path_class_file\*(R" and \*(L"file_spec\*(R".

perl_files

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

\s-1TODO\s0: 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 \*(L"extract_into\*(R": 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 \*(C`undef\*(C'.

required_attribute

A single attribute that is required by the class. Subclasses can define this to make \*(L"new\*(R" \*(C`croak\*(C' 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 \*(L"determine_name_and_version\*(R".

version

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

Dist::Metadata::Dist (3pm)

VERSION

SYNOPSIS

DESCRIPTION