NAME¶
Dist::Metadata::Dist - Base class for format-specific implementations
VERSION¶
version 0.923
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.
$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.
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
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.
SEE ALSO¶
- •
- Dist::Metadata::Tar - for examining a tar file
- •
- Dist::Metadata::Dir - for a directory already on the
disk
- •
- Dist::Metadata::Struct - for mocking up a dist with perl
data structures
AUTHOR¶
Randy Stauner <rwstauner@cpan.org>
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.