/ 
Distribution-Cooker-2.004
River stage zero No dependents
⭐ Starred 2 GitHub stars
/ Distribution::Cooker

NAME

Distribution::Cooker - Create a Perl module directory from your own templates

SYNOPSIS

# 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  { ... }
	}

DESCRIPTION

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.

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.

Process methods

  • cook

    Take the templates and cook them. This version uses Mojo::Template, 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/modules

    • Your module template name is lib/Foo.pm, which will be moved into place later

    When cook processes the templates, it provides definitions for these template variables listed for template_vars.

    While processing the templates, dist_cooker 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.

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

  • pre_run

    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.

  • report

  • run( [ MODULE_NAME, [ DESCRIPTION ] ] )

    The run method kicks off everything, and gives you a chance to do things between steps/.

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

Informative methods

These provide information the processing needs to do its work.

  • config_file_name

    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.

  • default_github_user

    Returns GITHUB_USER, which should be easy to find for global search and replace.

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

  • 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
* github_user
* 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>
* look in the env for DIST_COOKER_GITHUB_USER
* use default values from the method C<default_author_name>,
C<default_author_email>, or C<default_github_user>

  • 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_to_distname( MODULE_NAME )

    Take a module name, such as Foo::Bar, and turn it into a distribution name, such as 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.

  • template_vars

    Returns a hash reference of values to fill in the templates. This hash is passed to the Mojo::Template renderer.

    author_name => the name of the module author
    cooker_version => version of Distribution::Cooker
    cwd => the current working directory of the new module
    description => the module description
    dir => path to module file
    dist => dist name (Foo-Bar)
    email => author email
    github_user => the GitHub account name
    module => the package name (Foo::Bar)
    module_path => module path under lib/ (Foo/Bar.pm)
    repo_name => lowercase module with hyphens (foo-bar)
    template_path => the source of the template files
    year => the current year

Utility methods

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

TO DO

Right now, Distribution::Cooker uses the defaults that I like, but that should come from a configuration file.

SEE ALSO

Other modules, such as Module:Starter, do a similar job but don't give you as much flexibility with your templates.

SOURCE AVAILABILITY

This module is in Github:

http://github.com/briandfoy/distribution-cooker/

AUTHOR

brian d foy, <briandfoy@pobox.com>

COPYRIGHT AND LICENSE

Copyright © 2008-2025, brian d foy <briandfoy@pobox.com>. All rights reserved.

You may redistribute this under the same terms as Perl itself.