The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Module-Cooker-v0.1.4
River stage zero No dependents
++
/ modcooker

NAME

modcooker - Create skeleton module packages from templates

SYNOPSIS

Create a skeleton module named "My::New::Module" in the current directory: Note: the module name must conform to the following regex pattern: /[A-Z_a-z][0-9A-Z_a-z]*(?:::[0-9A-Z_a-z]+)*/

 $ modcooker [module parameters] My::New::Module

Create a basic configuration file (ready for editing) in $HOME/modcook:

 $ modcooker --setup

List all available templates, both standard and local:

 $ modcooker [--localdirs local1 [--localdirs local2]] --available
  
 (list of available profiles)

Place a standard template profile directory in $HOME/modcook:

 $ modcooker --copy default

OPTIONS

The following are options that can be specified on the command line.

NOTE! They are mutually exclusive and will throw an exception if used in a configuration file.

--setup

Creates a basic configurtion file in $HOME/modcook. modcook will be created if it does not already exist.

Any error is fatal and an appropriate message will be printed.

--available

Lists all available profiles. The localdirs parameter will be included in the search path if specified in either the configuration file or on the command line.

Any standard profile that has been overridden in a local profile directory will be noted as such in the output. The output will be similar to below (assuming "localdirs ~/modcook" was specified in the configuration file):

 $ modcooker --available    
 Searching for Available Profiles
   
 Search Order:
   /home1/nortxcom/modcook
   /home1/nortxcom/projects/Module-Cooker/lib/Module/Cooker
  
 Profile      - Type
   h2xs       - standard
   modmaker   - standard
   myprofile  - local
   default    - overridden
   modstarter - standard

--copy

Module::Cooker PARAMETERS

The following paramters can be specified on the command line when creating a new package or be placed in a configuration file (without the '--').

--minperl

A string representing the minimum version of Perl require to use the module. Default: '' (empty string)

--version

A string representing the version of the new module. Default: 'v0.1_1'

--author

A string with the author's name. Default: '' (empty string);

--email

A string with the author's email. Default: '' (empty string);

--profile

The profile from which the module should be built from. Default: 'default'

--nosubs

Boolean flag indicating that subdirectories in the profile should NOT be searched for template files. (Will probably be removed in the next release.) Default: 0

--localdirs

The directory (or directories if specified multiple times) to search in addition to the standard distrubution profile directory for the profile named by the '--profile' parameter. This is built as an array ref. Default: []

--extravars

This option creates a hash ref that is eventually passed as part of the data structure that Template will use as substitution variables. Any element in the hash ref can be accessed as extra.element_name in a template file.

NOTE! Due to a bug in AppConfig (see "KNOWN BUGS") this can NOT be used on the command line at this time, but only in the config file.

CONFIGURATION FILE

The copy option will create a file named $HOME/modcook/modcooker.cg with the following contents:

 # NOTE! This configuration file is used by the modcooker script and NOT
 # by the module (Module::Cooker) itself.
  
 # These string variables are most likely the ones you will want to
 # uncomment and set. Quotes are not needed, everything following the
 # '=' character up to a newline or '#' will be read in.
  
 #author = A. Uthor
 #email  = author@example.com
  
 # this parameter specifies what profile to use by default.
  
 #profile = default
  
 # this parameter controls what directories should be searched for profiles.
 # it can be listed multiple times to specify more than one.
 #
 # NOTE: any values listed on the command line for modcooker will ADD to
 # the list unless you specify the keyword 'replace' as one of the values.
 # If you do that, then any values for localdirs in this file will be ignored.
  
 localdirs ~/modcook
  
 # this parameter is a hash reference that will be passed to Template as
 # additional variables to be used for substitution.
 #
 # NOTE! Due to a bug in AppConfig you can not specify values for this
 # parameter on the command line! See the following for details:
 #
 # https://rt.cpan.org/Public/Bug/Display.html?id=32954
  
 #extravars extra1 = foo
 #extravars extra2 = bar
  
 # The following are simple Boolean flags.
  
 #nosubs = 0

Any of the Module::Cooker may be place in the configuration file.

LOCAL PROFILES

One can create custom profiles, and override the standard profiles, simply by creating a directory with the appropriate name and then letting modcooker (and by extension, Module::Cooker) know what the parent directory is.

The common use-case is to create custom profiles in $HOME/modcook. The copy option will automatically create this directory for you if it does not exist.

If you are overriding a standard profile, any of the standard files that are NOT in the local profile will be used. This means that you do not need to re-create a full standard profile, but only those files that you wish to be different or to add to a standard profile.

If you create a custom profile that does not have a name that coincindes with one of the standard profiles then obviously only the files in that profile directory will be processed.

Profile templates are processed with Template. You can see a full list of of the available substitution parameters in the POD for "template_data" in Module::Cooker. Plus, you can specify addtional items by means of the extravars parameter.

KNOWN BUGS

Due to this bug in AppConfig it is not possible to update values for extravars from the command line. It has no effect upon setting them in a local config file, however.

AUTHOR

Jim Bacon, <jim at nortx.com>

SEE ALSO

Module::Cooker, AppConfig, Jose's Guide for Creating Perl modules

LICENSE AND COPYRIGHT

Copyright 2013 Jim Bacon.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.