Distribution::Cooker - Create a Perl module directory from your own templates
# The dist_cooker is a wrapper for the module % dist_cooker Foo::Bar "This module does that" repo_slug # The dist_cooker can prompt for what's missing % dist_cooker Foo::Bar Description> This module does that Repo name> foo-bar # the script just passes @ARGV to the module use Distribution::Cooker; Distribution::Cooker->run( @ARGV ); # if you don't like something, subclass and override package Local::Distribution::Cooker { use parent qw(Distribution::Cooker); sub config_file_path { ... } }
This module takes a directory of templates and processes them with Mojo::Template. It's specifically tooled toward Perl modules, and the templates are given a set of variables.
The templates have special values for line_start, tag_start, and tag_end since the default Mojo::Template values get confused when there's Perl code outside them.
line_start
tag_start
tag_end
Tags use « (U+00AB) and » (U+00BB), and whole lines use ϕ (U+03D5):
This is the « $module » module ϕ This is a line of Perl code
My own templates are at https://github.com/briandfoy/module_templates.
cook
Take the templates and cook them. This version uses Mojo::Template Toolkit, but you can make a subclass to override it. See the notes about Mojo::Template.
I assume my own favorite values, and haven't made these customizable yet.
Your distribution template directory is ~/.templates/dist_cooker
Your module template name is lib/Foo.pm, which will be moved into place later
This uses Mojo::Template to render the templates, and various settings. The values from template_vars are passed to the templates and its keys are available as named variables.
template_vars
By default, these tag settings are used because these characters are unlikely to appear in Perl code:
* the line_start is ϕ (U+03D5) * the tag start is » * the line start is «
For example:
This is module « $module »
When cook processes the templates, it provides definitions for these template variables listed for template_vars.
While processing the templates, cook ignores .git, .svn, and CVS directories.
init
Initialize the object. There's nothing fancy here, but if you need something more powerful you can create a subclass and run some info here.
This step happens right after object create and configuration handling and before the pre_run step. By default, this does nothing.
pre_run
new
Creates the bare object with the name and email of the module author, looking for values in this order, with any combination for author and email:
* take values from the env: DIST_COOKER_AUTHOR and DIST_COOKER_EMAIL * look at git config for C<user.name> and C<user.email> * use default values from the method C<default_name> and C<default_email>
This looks for ~/.dist_cooker.ini to read the INI config and add that information to the object.
Override config_file_name to use a different name.
config_file_name
Runs right before cook does its work.
run() calls this method immediately after it creates the object and after it initializes it. By default, this does nothing.
post_run
run() calls this method right after it processes the template files. By default, this does nothing.
run()
report
run( [ MODULE_NAME, [ DESCRIPTION ] ] )
The run method kicks off everything, and gives you a chance to do things between steps/.
run
* create the object * run init (by default, does nothing) * run pre_run (by default, does nothing) * collects information and prompts interactively for what it needs * cooks the templates (~/.templates/modules by default) * run post_run (by default, does nothing) * create cooker_report.txt (it's in .gitignore)
If you don't specify the module name, it prompts you. If you don't specify a description, it prompts you.
These provide information the processing needs to do its work.
Return the filename (the basename) of the config file. The default is .dist_cooker.ini.
default_author_email
default_author_name
Returns the last resort values for author name or email. These are Frank Serpico and serpico@example.com.
Frank Serpico
serpico@example.com
description( [ DESCRIPTION ] )
Returns the description of the module. With an argument, it sets the value.
The default name is TODO: describe this module. You can override this in a subclass.
TODO: describe this module
template_dir
Returns the path for the distribution templates. The default is $ENV{HOME}/.templates/modules. If that path is a symlink, this returns that target of that link.
default_config
Returns a hash reference of the config values.
* author_name * email * line_start * tag_end * tag_start
This looks for values in this order, and in any combination:
* take values from the env: DIST_COOKER_AUTHOR and DIST_COOKER_EMAIL * look at git config for C<user.name> and C<user.email> * use default values from the method C<default_author_name> and C<default_author_email>
dist( [ DIST_NAME ] )
Return the dist name. With an argument, set the module name.
module( [ MODULE_NAME ] )
Return the module name. With an argument, set the module name.
module_path()
Return the module path under lib/. You must have set module already.
module
module_to_distname( MODULE_NAME )
Take a module name, such as Foo::Bar, and turn it into a distribution name, such as Foo-Bar.
Foo::Bar
Foo-Bar
module_template_basename
Returns the name of the template file that is the module. The default name is Foo.pm. This file is moved to the right place under lib/ in the cooked templates.
repo_name
Returns the repo_name for the project. This defaults to the module name all lowercased with :: replaced with -. You can override this in a subclass.
::
-
template_files
Return the list of templates to process. These are all the files in the template_dir excluding .git, .svn, CVS, and .infra.
.infra
Returns a hash reference of values to fill in the templates. This hash is passed to the Mojo::Template renderer.
config_file_path
Returns the path to the config file. By default, this is the value of config_file_name under the home directory.
get_config
Returns a hash reference of the config values. These are the values that apply across runs.
First, this populates a hash with default_config, then replaces values from the config file (config_file_path).
This version uses Config::IniFiles
[author] name=... email=... [templates] line_start=... tag_end=... tag_start=...
prompt( MESSAGE )
Show the user MESSAGE, grap a line from STDIN, and return it. If the session is not interactive, this returns nothing.
Most things that prompt should have a default value in the case that prompt cannot work.
prompt
Right now, Distribution::Cooker uses the defaults that I like, but that should come from a configuration file.
Distribution::Cooker
Other modules, such as Module:Starter, do a similar job but don't give you as much flexibility with your templates.
Module:Starter
This module is in Github:
http://github.com/briandfoy/distribution-cooker/
brian d foy, <briandfoy@pobox.com>
<briandfoy@pobox.com>
Copyright © 2008-2024, brian d foy <briandfoy@pobox.com>. All rights reserved.
You may redistribute this under the same terms as Perl itself.
To install Distribution::Cooker, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Distribution::Cooker
CPAN shell
perl -MCPAN -e shell install Distribution::Cooker
For more information on module installation, please visit the detailed CPAN module installation guide.