Dist::...::Dist(3pm)

💖 Dist::...::Dist(3pm) 💖

okay bestie, welcome to the Dist::...::Dist(3pm) manual page — straight outta the User Contributed Perl Documentation, iykyk 💫 this one's a whole vibe, so let's get into it ✨

---

🌸 NAME 🌸

Dist::Metadata::Dist — the base class for all the format-specific implementations 🎀

🌟 VERSION 🌟

version 0.927 💅

✨ SYNOPSIS ✨

# don't use this, use a subclass

that's literally the whole thing. do not use this directly, use a subclass, ok? 🙈

🦋 DESCRIPTION 🦋

This is a base class for different dist formats. it's giving parent energy, main character of the class hierarchy 👑

The following methods must be defined by subclasses:

• file_content
• find_files

no cap, if your subclass doesn't define these two, it's not it 💀

👑 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. important bestie, don't skip this one 🫶

💜 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 a 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. yes that's a whole chain of calls, she's nested like that 😭

💜 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. dramatic but fair 💅

💜 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> — iconic, honestly 🫶

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

---

and that's a wrap bestie! 🦋 this page came from perl v5.34.0, dated 2022-06-13, filed under Dist::...::Dist(3pm) — go forth and subclass responsibly, ily 💖✨