1Module::Faker::Dist(3)User Contributed Perl DocumentationModule::Faker::Dist(3)
2
6 Module::Faker::Dist - a fake CPAN distribution
7
9 version 0.025
10
12 Building one dist at a time makes plenty of sense, so
13 Module::Faker::Dist makes it easy. Building dists from definitions in
14 files is also useful for doing things in bulk (see CPAN::Faker), so
15 there are a bunch of ways to build dists from a definition in a file.
16 # Build from a META.yml or META.json file, or the delightful
18 # AUTHOR_Foo-Bar-1.234.tar.gz.dist file, which can be zero bytes and gets
19 # all the relevant data from the filename.
20 my $dist = Module::Faker::Dist->from_file($filename);
21 META files can contain a key called X_Module_Faker that contains
23 attributes to use in constructing the dist. "dist" files can contain
24 anything you want, but the contents won't do a thing.
25 You can use the "new" method on Module::Faker::Dist, of course, but
27 it's a bit of a pain. You might, instead, want to use "from_struct",
28 which is very close to "new", but with more sugar.
29
31 This module should work on any version of perl still receiving updates
32 from the Perl 5 Porters. This means it should work on any version of
33 perl released in the last two to three years. (That is, if the most
34 recently released version is v5.40, then this module should work on
35 both v5.40 and v5.38.)
36 Although it may work on older versions of perl, no guarantee is made
38 that the minimum required version will not be increased. The version
39 may be increased for any reason, and there is no promise that patches
40 will be accepted to lower the minimum required perl.
41
43 name
44 This is the name of the dist. It will usually look like "Foo-Bar".
45 version
47 This is the version of the dist, usually some kind of versiony string
48 like 1.234 or maybe 1.2.3.
49 abstract
51 The abstract! This is a short, pithy description of the distribution,
52 usually less than a sentence.
53 release_status
55 This is the dist's release status. (See CPAN::Meta::Spec.) It
56 defaults to "stable" but "unstable" and "testing" are valid values.
57 cpan_author
59 This is the PAUSE id of the author, like "RJBS".
60 archive_ext
62 This is the extension of the archive to build, when you build an
63 archive. This defaults to "tar.gz". "zip" should work, but right now
64 it doesn't. So probably stuck to "tar.gz". It would be cool to
65 support more attributes in the future.
66 append
68 This is an arrayref of hashrefs, each of which looks like:
69 { file => $filename, content => $character_string }
71 The content will be UTF-8 encoded and put into a file with the given
73 name.
74 This feature is a bit weird. Maybe it will go away eventually.
76 mtime
78 If given, this is the epoch seconds to which to set the mtime of the
79 generated file. This is useful in rare occasions.
80 x_authority
82 This is the "X_Authority" header that gets put into the META files.
83 license
85 This is the meta spec license string for the distribution. It defaults
86 to "perl_5".
87 authors
89 This is an array of strings who are used as the authors in the dist
90 metadata. The default is:
91 [ "AUTHOR <AUTHOR@cpan.local>" ]
93 ...where "AUTHOR" is the "cpan_author" of the dist.
95 include_provides_in_meta
97 This is a bool. If true, the produced META files will include a
98 "provides" key based on the packages in the dist. It defaults to
99 false, to match the most common behavior of dists in the wild.
100 provides
102 This is a hashref that gets used as the "provides" in the metadata.
103 If no provided, it is built from the "packages" provided in
105 construction.
106 If no packages were provided, for a dist named Foo-Bar, it defaults to:
108 { 'Foo::Bar' => { version => $DIST_VERSION, file => "lib/Foo/Bar.pm" } }
110 archive_basename
112 If written to disk, the archive will be written to...
113 $dist->archive_basename . '.' . $dist->archive_ext
115 The default is:
117 $dist->name . '.' . ($dist->version // 'undef')
119 omitted_files
121 If given, this is an arrayref of filenames that shouldn't be
122 automatically generated and included.
123 packages
125 This is an array of Module::Faker::Package objects. It's built by
126 "provides" if needed, but you might want to look at using the
127 "from_struct" method to set it up.
128 more_metadata
130 This can be given as a hashref of data to merge into the CPAN::Meta
131 files.
132 meta_munger
134 If given, this is a coderef that's called just before the CPAN::Meta
135 data for the dist is written to disk, an can be used to change things,
136 especially into invalid data. It is expected to return the new content
137 to serialize.
138 It's called like this:
140 $coderef->($struct, { format => $format, version => $version });
142 ...where $struct is the result of "$cpan_meta->as_struct". $version is
144 the version number of the target metafile. Normally, both version 1.4
145 and 2 are requested. $format is either "yaml" or "json".
146 If the munger returns a string instead of a structure, it will be used
148 as the content of the file being written. This lets you put all kinds
149 of nonsense in those meta files. Have fun, go nuts!
150
152 modules
153 This produces and returns a list of Module::Faker::Module objects,
154 representing modules. Modules, if you're not as steeped in CPAN
155 toolchain nonsense, are the ".pm" files in which packages are defined.
156 These are produced by combining the packages from "packages" into files
158 based on their "in_file" attributes.
159 "make_dist_dir"
161 my $directory_name = $dist->make_dist_dir(\%arg);
162 This returns the name of a directory into which the dist's contents
164 have been written. If a "dir" argument is provided, the dist will be
165 written to a directory beneath that dir. Otherwise, it will be written
166 below a temporary directory.
167 make_archive
169 my $archive_filename = $dist->make_archive(\%arg);
170 This writes the dist archive file, like a tarball or zip file. If a
172 "dir" argument is given, it will be written in that directory.
173 Otherwise, it will be written to a temporary directory. If the
174 "author_prefix" argument is given and true, it will be written under a
175 hashed author dir, like:
176 U/US/USERID/Foo-Bar-1.23.tar.gz
178 from_file
180 my $dist = Module::Faker::Dist->from_file($filename);
181 Given a filename with dist configuration, this builds the dist
183 described by the file.
184 Given a file ending in "yaml" or "yml" or "json", it's treated as a
186 CPAN::Meta file and interpreted as such. The key "X_Module_Faker" can
187 be present to provide attributes that don't match data found in a meta
188 file.
189 Given a file ending in "dist", all the configuration comes from the
191 filename, which should look like this:
192 AUTHOR_Dist-Name-1.234.tar.gz.dist
194 from_struct
196 my $dist = Module::Faker::Dist->from_struct(\%arg);
197 This is sugar over "new", working like this:
199 • packages version defaults to the dist version unless specified
201 • packages for dist Foo-Bar defaults to Foo::Bar unless specified
203 • if specified, packages is an optlist
205
207 Ricardo Signes <cpan@semiotic.systems>
208
210 This software is copyright (c) 2008 by Ricardo Signes.
211 This is free software; you can redistribute it and/or modify it under
213 the same terms as the Perl 5 programming language system itself.
214perl v5.38.0 2023-07-20 Module::Faker::Dist(3)