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

  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.

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

• 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
          * 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_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

  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, <bdfoy@cpan.org>

COPYRIGHT AND LICENSE

Copyright © 2008-2021, brian d foy <bdfoy@cpan.org>. All rights reserved.

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