1Module::Faker::Dist(3)User Contributed Perl DocumentationModule::Faker::Dist(3)
2
3
4

NAME

6       Module::Faker::Dist - a fake CPAN distribution
7

VERSION

9       version 0.023
10

SYNOPSIS

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
17           # 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
22       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
26       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

PERL VERSION

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
37       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

ATTRIBUTES

43   name
44       This is the name of the dist.  It will usually look like "Foo-Bar".
45
46   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
50   abstract
51       The abstract!  This is a short, pithy description of the distribution,
52       usually less than a sentence.
53
54   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
58   cpan_author
59       This is the PAUSE id of the author, like "RJBS".
60
61   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
67   append
68       This is an arrayref of hashrefs, each of which looks like:
69
70         { file => $filename, content => $character_string }
71
72       The content will be UTF-8 encoded and put into a file with the given
73       name.
74
75       This feature is a bit weird.  Maybe it will go away eventually.
76
77   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
81   x_authority
82       This is the "X_Authority" header that gets put into the META files.
83
84   license
85       This is the meta spec license string for the distribution.  It defaults
86       to "perl_5".
87
88   authors
89       This is an array of strings who are used as the authors in the dist
90       metadata.  The default is:
91
92         [ "AUTHOR <AUTHOR@cpan.local>" ]
93
94       ...where "AUTHOR" is the "cpan_author" of the dist.
95
96   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
101   provides
102       This is a hashref that gets used as the "provides" in the metadata.
103
104       If no provided, it is built from the "packages" provided in
105       construction.
106
107       If no packages were provided, for a dist named Foo-Bar, it defaults to:
108
109         { 'Foo::Bar' => { version => $DIST_VERSION, file => "lib/Foo/Bar.pm" } }
110
111   archive_basename
112       If written to disk, the archive will be written to...
113
114         $dist->archive_basename . '.' . $dist->archive_ext
115
116       The default is:
117
118         $dist->name . '.' . ($dist->version // 'undef')
119
120   omitted_files
121       If given, this is an arrayref of filenames that shouldn't be
122       automatically generated and included.
123
124   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
129   more_metadata
130       This can be given as a hashref of data to merge into the CPAN::Meta
131       files.
132
133   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
139       It's called like this:
140
141         $coderef->($struct, { format => $format, version => $version });
142
143       ...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
147       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

METHODS

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
157       These are produced by combining the packages from "packages" into files
158       based on their "in_file" attributes.
159
160   "make_dist_dir"
161         my $directory_name = $dist->make_dist_dir(\%arg);
162
163       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
168   make_archive
169         my $archive_filename = $dist->make_archive(\%arg);
170
171       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
177         U/US/USERID/Foo-Bar-1.23.tar.gz
178
179   from_file
180         my $dist = Module::Faker::Dist->from_file($filename);
181
182       Given a filename with dist configuration, this builds the dist
183       described by the file.
184
185       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
190       Given a file ending in "dist", all the configuration comes from the
191       filename, which should look like this:
192
193         AUTHOR_Dist-Name-1.234.tar.gz.dist
194
195   from_struct
196         my $dist = Module::Faker::Dist->from_struct(\%arg);
197
198       This is sugar over "new", working like this:
199
200       •   packages version defaults to the dist version unless specified
201
202       •   packages for dist Foo-Bar defaults to Foo::Bar unless specified
203
204       •   if specified, packages is an optlist
205

AUTHOR

207       Ricardo Signes <cpan@semiotic.systems>
208
210       This software is copyright (c) 2008 by Ricardo Signes.
211
212       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.
214
215
216
217perl v5.36.0                      2023-01-20            Module::Faker::Dist(3)
Impressum