--- name: "Dist::Metadata::Dist" section: "3pm" platform: "linux" package: "libdist-metadata-perl" version: "0.927-2" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Dist::Metadata::Dist" --- # Dist::Metadata::Dist(3pm) Base class for format-specific implementations ## NAME Dist::Metadata::Dist - Base class for format-specific implementations ## VERSION version 0.927 ## 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. ## 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 \ ## 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.