Dist::Metadata::Dist(3pm)

1Dist::Metadata::Dist(3)User Contributed Perl DocumentatioDnist::Metadata::Dist(3)
2
3
4

NAME

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

VERSION

9       version 0.927
10

SYNOPSIS

12         # don't use this, use a subclass
13

DESCRIPTION

15       This is a base class for different dist formats.
16
17       The following methods must be defined by subclasses:
18
19       •   "file_content"
20
21       •   "find_files"
22

METHODS

24   new
25       Simple constructor that subclasses can inherit.  Ensures the presence
26       of "required_attribute" if defined by the subclass.
27
28   default_file_spec
29       Defaults to 'Native' in the base class which will let File::Spec
30       determine the value.
31
32   determine_name_and_version
33       Some dist formats may define a way to determine the name and version.
34
35   determine_packages
36         $packages = $dist->determine_packages(@files);
37
38       Search the specified files (or all files if unspecified) for perl
39       packages.
40
41       Extracts the files to a temporary directory if necessary and uses
42       Module::Metadata to discover package names and versions.
43
44   extract_into
45         $ddir = $dist->extract_into($dir);
46         ($ddir, @dfiles) = $dist->extract_into($dir, @files);
47
48       Extracts the specified files (or all files if not specified) into the
49       specified directory.
50
51       In list context this returns a list of the directory (which may be a
52       subdirectory of the $dir passed in) and the files extracted (in native
53       OS (on-disk) format).
54
55       In scalar context just the directory is returned.
56
57   file_content
58       Returns the content for the specified file from the dist.
59
60       This must be defined by subclasses.
61
62   file_checksum
63         $dist->file_checksum('lib/Mod/Name.pm', 'sha256');
64
65       Returns a checksum (hex digest) of the file content.
66
67       The Digest module is used to generate the checksums.  The value
68       specified should be one accepted by "Digest->new".  A small effort is
69       made to translate simpler names like "md5" into "MD5" and "sha1" into
70       "SHA-1" (which are the names Digest expects).
71
72       If the type of checksum is not specified "md5" will be used.
73
74   find_files
75       Determine the files contained in the dist.
76
77       This is called from "list_files" and cached on the object.
78
79       This must be defined by subclasses.
80
81   file_spec
82       Returns the OS name of the File::Spec module used for this format.
83       This is mostly so subclasses can define a specific one (as
84       "default_file_spec") if necessary.
85
86       A "file_spec" attribute can be passed to the constructor to override
87       the default.
88
89       NOTE: This is used for the internal format of the dist.  Tar archives,
90       for example, are always in unix format.  For operations outside of the
91       dist, the format determined by File::Spec will always be used.
92
93   full_path
94         $dist->full_path("lib/Mod.pm"); # "root-dir/lib/Mod.pm"
95
96       Used internally to put the "root" directory back onto the file.
97
98   list_files
99       Returns a list of the files in the dist starting at the dist root.
100
101       This calls "find_files" to get a listing of the contents of the dist,
102       determines (and caches) the root directory (if any), caches and returns
103       the list of files with the root dir stripped.
104
105         @files = $dist->list_files;
106         # something like qw( README META.yml lib/Mod.pm )
107
108   name
109       The dist name if it could be determined.
110
111   packages_from_directory
112         $provides = $dist->packages_from_directory($dir, @files);
113
114       Determines the packages provided by the perl modules found in a
115       directory.  This is thin wrapper around
116       "package_versions_from_directory" in Module::Metadata.  It returns a
117       hashref like "provides" in CPAN::Meta::Spec.
118
119       NOTE: $dir must be a physical directory on the disk, therefore @files
120       (if specified) must be in native OS format.  This function is called
121       internally from "determine_packages" (which calls physical_directory
122       (which calls "extract_into")) which manages these requirements.
123
124   parse_name_and_version
125         ($name, $version) = $dist->parse_name_and_version($path);
126
127       Attempt to parse name and version from the provided string.  This will
128       work for dists named like "Dist-Name-1.0".
129
130   path_class_dir
131       Returns the class name used for Path::Class::Dir objects.
132
133   path_class_file
134       Returns the class name used for Path::Class::File objects.
135
136   path_classify_dir
137       This is a shortcut for returning an object representing the provided
138       dir utilizing "path_class_dir" and "file_spec".
139
140   path_classify_file
141       This is a shortcut for returning an object representing the provided
142       file utilizing "path_class_file" and "file_spec".
143
144   perl_files
145       Returns the subset of "list_files" that look like perl files.
146       Currently returns anything matching "/\.pm$/"
147
148       TODO: This should probably be customizable.
149
150   physical_directory
151         $dir = $dist->physical_directory();
152         ($dir, @dir_files) = $dist->physical_directory(@files);
153
154       Returns the path to a physical directory on the disk where the
155       specified files (if any) can be found.
156
157       For in-memory formats this will make a temporary directory and write
158       the specified files (or all files) into it.
159
160       The return value is the same as "extract_into": In scalar context the
161       path to the directory is returned.  In list context the (possibly
162       adjusted) paths to any specified files are appended to the return
163       value.
164
165   remove_root_dir
166         my ($dir, @rel) = $dm->remove_root_dir(@files);
167
168       If all the @files are beneath the same root directory (as is normally
169       the case) this will strip the root directory off of each file and
170       return a list of the root directory and the stripped files.
171
172       If there is no root directory the first element of the list will be
173       "undef".
174
175   required_attribute
176       A single attribute that is required by the class.  Subclasses can
177       define this to make "new" "croak" if it isn't present.
178
179   root
180       Returns the root directory of the dist (if there is one).
181
182   set_name_and_version
183       This is a convenience method for setting the name and version if they
184       haven't already been set.  This is often called by
185       "determine_name_and_version".
186
187   version
188       Returns the version if it could be determined from the dist.
189

AUTHOR

199       Randy Stauner <rwstauner@cpan.org>
200

COPYRIGHT AND LICENSE

202       This software is copyright (c) 2011 by Randy Stauner.
203
204       This is free software; you can redistribute it and/or modify it under
205       the same terms as the Perl 5 programming language system itself.
206
207
208
209perl v5.36.0                      2023-01-20           Dist::Metadata::Dist(3)