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

ATTRIBUTES

31   name
32       This is the name of the dist.  It will usually look like "Foo-Bar".
33
34   version
35       This is the version of the dist, usually some kind of versiony string
36       like 1.234 or maybe 1.2.3.
37
38   abstract
39       The abstract!  This is a short, pithy description of the distribution,
40       usually less than a sentence.
41
42   release_status
43       This is the dist's release status.  (See CPAN::Meta::Spec.)  It
44       defaults to "stable" but "unstable" and "testing" are valid values.
45
46   cpan_author
47       This is the PAUSE id of the author, like "RJBS".
48
49   archive_ext
50       This is the extension of the archive to build, when you build an
51       archive.  This defaults to "tar.gz".  "zip" should work, but right now
52       it doesn't.  So probably stuck to "tar.gz".  It would be cool to
53       support more attributes in the future.
54
55   append
56       This is an arrayref of hashrefs, each of which looks like:
57
58         { file => $filename, content => $character_string }
59
60       The content will be UTF-8 encoded and put into a file with the given
61       name.
62
63       This feature is a bit weird.  Maybe it will go away eventually.
64
65   mtime
66       If given, this is the epoch seconds to which to set the mtime of the
67       generated file.  This is useful in rare occasions.
68
69   x_authority
70       This is the "X_Authority" header that gets put into the META files.
71
72   license
73       This is the meta spec license string for the distribution.  It defaults
74       to "perl_5".
75
76   authors
77       This is an array of strings who are used as the authors in the dist
78       metadata.  The default is:
79
80         [ "AUTHOR <AUTHOR@cpan.local>" ]
81
82       ...where "AUTHOR" is the "cpan_author" of the dist.
83
84   include_provides_in_meta
85       This is a bool.  If true, the produced META files will include a
86       "provides" key based on the packages in the dist.  It defaults to
87       false, to match the most common behavior of dists in the wild.
88
89   provides
90       This is a hashref that gets used as the "provides" in the metadata.
91
92       If no provided, it is built from the "packages" provided in
93       construction.
94
95       If no packages were provided, for a dist named Foo-Bar, it defaults to:
96
97         { 'Foo::Bar' => { version => $DIST_VERSION, file => "lib/Foo/Bar.pm" } }
98
99   archive_basename
100       If written to disk, the archive will be written to...
101
102         $dist->archive_basename . '.' . $dist->archive_ext
103
104       The default is:
105
106         $dist->name . '.' . ($dist->version // 'undef')
107
108   omitted_files
109       If given, this is an arrayref of filenames that shouldn't be
110       automatically generated and included.
111
112   packages
113       This is an array of Module::Faker::Package objects.  It's built by
114       "provides" if needed, but you might want to look at using the
115       "from_struct" method to set it up.
116
117   more_metadata
118       This can be given as a hashref of data to merge into the CPAN::Meta
119       files.
120
121   meta_munger
122       If given, this is a coderef that's called just before the CPAN::Meta
123       data for the dist is written to disk, an can be used to change things,
124       especially into invalid data.  It is expected to return the new content
125       to serialize.
126
127       It's called like this:
128
129         $coderef->($struct, { format => $format, version => $version });
130
131       ...where $struct is the result of "$cpan_meta->as_struct".  $version is
132       the version number of the target metafile.  Normally, both version 1.4
133       and 2 are requested.  $format is either "yaml" or "json".
134
135       If the munger returns a string instead of a structure, it will be used
136       as the content of the file being written.  This lets you put all kinds
137       of nonsense in those meta files.  Have fun, go nuts!
138

METHODS

140   modules
141       This produces and returns a list of Module::Faker::Module objects,
142       representing modules.  Modules, if you're not as steeped in CPAN
143       toolchain nonsense, are the ".pm" files in which packages are defined.
144
145       These are produced by combining the packages from "packages" into files
146       based on their "in_file" attributes.
147
148   "make_dist_dir"
149         my $directory_name = $dist->make_dist_dir(\%arg);
150
151       This returns the name of a directory into which the dist's contents
152       have been written.  If a "dir" argument is provided, the dist will be
153       written to a directory beneath that dir.  Otherwise, it will be written
154       below a temporary directory.
155
156   make_archive
157         my $archive_filename = $dist->make_archive(\%arg);
158
159       This writes the dist archive file, like a tarball or zip file.  If a
160       "dir" argument is given, it will be written in that directory.
161       Otherwise, it will be written to a temporary directory.  If the
162       "author_prefix" argument is given and true, it will be written under a
163       hashed author dir, like:
164
165         U/US/USERID/Foo-Bar-1.23.tar.gz
166
167   from_file
168         my $dist = Module::Faker::Dist->from_file($filename);
169
170       Given a filename with dist configuration, this builds the dist
171       described by the file.
172
173       Given a file ending in "yaml" or "yml" or "json", it's treated as a
174       CPAN::Meta file and interpreted as such.  The key "X_Module_Faker" can
175       be present to provide attributes that don't match data found in a meta
176       file.
177
178       Given a file ending in "dist", all the configuration comes from the
179       filename, which should look like this:
180
181         AUTHOR_Dist-Name-1.234.tar.gz.dist
182
183   from_struct
184         my $dist = Module::Faker::Dist->from_struct(\%arg);
185
186       This is sugar over "new", working like this:
187
188       •   packages version defaults to the dist version unless specified
189
190       •   packages for dist Foo-Bar defaults to Foo::Bar unless specified
191
192       •   if specified, packages is an optlist
193

AUTHOR

195       Ricardo Signes <rjbs@cpan.org>
196

198       This software is copyright (c) 2008 by Ricardo Signes.
199
200       This is free software; you can redistribute it and/or modify it under
201       the same terms as the Perl 5 programming language system itself.
202
203
204
205perl v5.34.0                      2022-01-21            Module::Faker::Dist(3)
Impressum