.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Module::Faker::Dist 3pm" .TH Module::Faker::Dist 3pm "2023-06-21" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Module::Faker::Dist \- a fake CPAN distribution .SH "VERSION" .IX Header "VERSION" version 0.025 .SH "SYNOPSIS" .IX Header "SYNOPSIS" Building one dist at a time makes plenty of sense, so Module::Faker::Dist makes it easy. Building dists from definitions in files is also useful for doing things in bulk (see CPAN::Faker), so there are a bunch of ways to build dists from a definition in a file. .PP .Vb 4 \& # Build from a META.yml or META.json file, or the delightful \& # AUTHOR_Foo\-Bar\-1.234.tar.gz.dist file, which can be zero bytes and gets \& # all the relevant data from the filename. \& my $dist = Module::Faker::Dist\->from_file($filename); .Ve .PP \&\s-1META\s0 files can contain a key called X_Module_Faker that contains attributes to use in constructing the dist. \f(CW\*(C`dist\*(C'\fR files can contain anything you want, but the contents won't do a thing. .PP You can use the \f(CW\*(C`new\*(C'\fR method on Module::Faker::Dist, of course, but it's a bit of a pain. You might, instead, want to use \f(CW\*(C`from_struct\*(C'\fR, which is very close to \f(CW\*(C`new\*(C'\fR, but with more sugar. .SH "PERL VERSION" .IX Header "PERL VERSION" This module should work on any version of perl still receiving updates from the Perl 5 Porters. This means it should work on any version of perl released in the last two to three years. (That is, if the most recently released version is v5.40, then this module should work on both v5.40 and v5.38.) .PP Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. .SH "ATTRIBUTES" .IX Header "ATTRIBUTES" .SS "name" .IX Subsection "name" This is the name of the dist. It will usually look like \f(CW\*(C`Foo\-Bar\*(C'\fR. .SS "version" .IX Subsection "version" This is the version of the dist, usually some kind of versiony string like \&\f(CW1.234\fR or maybe \f(CW1.2.3\fR. .SS "abstract" .IX Subsection "abstract" The abstract! This is a short, pithy description of the distribution, usually less than a sentence. .SS "release_status" .IX Subsection "release_status" This is the dist's release status. (See CPAN::Meta::Spec.) It defaults to \&\f(CW\*(C`stable\*(C'\fR but \f(CW\*(C`unstable\*(C'\fR and \f(CW\*(C`testing\*(C'\fR are valid values. .SS "cpan_author" .IX Subsection "cpan_author" This is the \s-1PAUSE\s0 id of the author, like \f(CW\*(C`RJBS\*(C'\fR. .SS "archive_ext" .IX Subsection "archive_ext" This is the extension of the archive to build, when you build an archive. This defaults to \f(CW\*(C`tar.gz\*(C'\fR. \f(CW\*(C`zip\*(C'\fR should work, but right now it doesn't. So probably stuck to \f(CW\*(C`tar.gz\*(C'\fR. It would be cool to support more attributes in the future. .SS "append" .IX Subsection "append" This is an arrayref of hashrefs, each of which looks like: .PP .Vb 1 \& { file => $filename, content => $character_string } .Ve .PP The content will be \s-1UTF\-8\s0 encoded and put into a file with the given name. .PP This feature is a bit weird. Maybe it will go away eventually. .SS "mtime" .IX Subsection "mtime" If given, this is the epoch seconds to which to set the mtime of the generated file. This is useful in rare occasions. .SS "x_authority" .IX Subsection "x_authority" This is the \f(CW\*(C`X_Authority\*(C'\fR header that gets put into the \s-1META\s0 files. .SS "license" .IX Subsection "license" This is the meta spec license string for the distribution. It defaults to \&\f(CW\*(C`perl_5\*(C'\fR. .SS "authors" .IX Subsection "authors" This is an array of strings who are used as the authors in the dist metadata. The default is: .PP .Vb 1 \& [ "AUTHOR " ] .Ve .PP \&...where \f(CW\*(C`AUTHOR\*(C'\fR is the \f(CW\*(C`cpan_author\*(C'\fR of the dist. .SS "include_provides_in_meta" .IX Subsection "include_provides_in_meta" This is a bool. If true, the produced \s-1META\s0 files will include a \f(CW\*(C`provides\*(C'\fR key based on the packages in the dist. It defaults to false, to match the most common behavior of dists in the wild. .SS "provides" .IX Subsection "provides" This is a hashref that gets used as the \f(CW\*(C`provides\*(C'\fR in the metadata. .PP If no provided, it is built from the \f(CW\*(C`packages\*(C'\fR provided in construction. .PP If no packages were provided, for a dist named Foo-Bar, it defaults to: .PP .Vb 1 \& { \*(AqFoo::Bar\*(Aq => { version => $DIST_VERSION, file => "lib/Foo/Bar.pm" } } .Ve .SS "archive_basename" .IX Subsection "archive_basename" If written to disk, the archive will be written to... .PP .Vb 1 \& $dist\->archive_basename . \*(Aq.\*(Aq . $dist\->archive_ext .Ve .PP The default is: .PP .Vb 1 \& $dist\->name . \*(Aq.\*(Aq . ($dist\->version // \*(Aqundef\*(Aq) .Ve .SS "omitted_files" .IX Subsection "omitted_files" If given, this is an arrayref of filenames that shouldn't be automatically generated and included. .SS "packages" .IX Subsection "packages" This is an array of Module::Faker::Package objects. It's built by \&\f(CW\*(C`provides\*(C'\fR if needed, but you might want to look at using the \&\f(CW"from_struct"\fR method to set it up. .SS "more_metadata" .IX Subsection "more_metadata" This can be given as a hashref of data to merge into the CPAN::Meta files. .SS "meta_munger" .IX Subsection "meta_munger" If given, this is a coderef that's called just before the CPAN::Meta data for the dist is written to disk, an can be used to change things, especially into invalid data. It is expected to return the new content to serialize. .PP It's called like this: .PP .Vb 1 \& $coderef\->($struct, { format => $format, version => $version }); .Ve .PP \&...where \f(CW$struct\fR is the result of \f(CW\*(C`$cpan_meta\->as_struct\*(C'\fR. \&\f(CW$version\fR is the version number of the target metafile. Normally, both version 1.4 and 2 are requested. \f(CW$format\fR is either \f(CW\*(C`yaml\*(C'\fR or \f(CW\*(C`json\*(C'\fR. .PP If the munger returns a string instead of a structure, it will be used as the content of the file being written. This lets you put all kinds of nonsense in those meta files. Have fun, go nuts! .SH "METHODS" .IX Header "METHODS" .SS "modules" .IX Subsection "modules" This produces and returns a list of Module::Faker::Module objects, representing modules. Modules, if you're not as steeped in \s-1CPAN\s0 toolchain nonsense, are the \f(CW\*(C`.pm\*(C'\fR files in which packages are defined. .PP These are produced by combining the packages from \f(CW"packages"\fR into files based on their \f(CW\*(C`in_file\*(C'\fR attributes. .ie n .SS """make_dist_dir""" .el .SS "\f(CWmake_dist_dir\fP" .IX Subsection "make_dist_dir" .Vb 1 \& my $directory_name = $dist\->make_dist_dir(\e%arg); .Ve .PP This returns the name of a directory into which the dist's contents have been written. If a \f(CW\*(C`dir\*(C'\fR argument is provided, the dist will be written to a directory beneath that dir. Otherwise, it will be written below a temporary directory. .SS "make_archive" .IX Subsection "make_archive" .Vb 1 \& my $archive_filename = $dist\->make_archive(\e%arg); .Ve .PP This writes the dist archive file, like a tarball or zip file. If a \f(CW\*(C`dir\*(C'\fR argument is given, it will be written in that directory. Otherwise, it will be written to a temporary directory. If the \f(CW\*(C`author_prefix\*(C'\fR argument is given and true, it will be written under a hashed author dir, like: .PP .Vb 1 \& U/US/USERID/Foo\-Bar\-1.23.tar.gz .Ve .SS "from_file" .IX Subsection "from_file" .Vb 1 \& my $dist = Module::Faker::Dist\->from_file($filename); .Ve .PP Given a filename with dist configuration, this builds the dist described by the file. .PP Given a file ending in \f(CW\*(C`yaml\*(C'\fR or \f(CW\*(C`yml\*(C'\fR or \f(CW\*(C`json\*(C'\fR, it's treated as a CPAN::Meta file and interpreted as such. The key \f(CW\*(C`X_Module_Faker\*(C'\fR can be present to provide attributes that don't match data found in a meta file. .PP Given a file ending in \f(CW\*(C`dist\*(C'\fR, all the configuration comes from the filename, which should look like this: .PP .Vb 1 \& AUTHOR_Dist\-Name\-1.234.tar.gz.dist .Ve .SS "from_struct" .IX Subsection "from_struct" .Vb 1 \& my $dist = Module::Faker::Dist\->from_struct(\e%arg); .Ve .PP This is sugar over \f(CW\*(C`new\*(C'\fR, working like this: .IP "\(bu" 4 packages version defaults to the dist version unless specified .IP "\(bu" 4 packages for dist Foo-Bar defaults to Foo::Bar unless specified .IP "\(bu" 4 if specified, packages is an optlist .SH "AUTHOR" .IX Header "AUTHOR" Ricardo Signes .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2008 by Ricardo Signes. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.