NAME

Kelp::Generator - Generation templates

SYNOPSIS

use Kelp::Generator;

my $gen = Kelp::Generator->new;
# get available templates
my @template = $gen->list_templates;

# get parsed files (ready to be saved)
my $files_aref = $gen->get_template($template, 'App::Name');

for my $file (@$files_aref) {
    my ($file_name, $file_contents) = @$file;
}

DESCRIPTION

This is a class for discovery and parsing of generation templates for Kelp. A generation template is a set of files that can be parsed using Template::Tiny and inserted into a given directory. This class only handles the discovery and parsing of these templates. The kelp-generator script or custom script should handle saving them in a destination directory.

TEMPLATE CREATION

Discovery

This class will look into a directory in its installation tree to discover available templates. The folder is Kelp/templates by default and can be changed by constructing the object with different templates_dir attribute. This means that CPAN modules can add templates to "templates" in Kelp and they will be discovered as long as they have been installed in the same root directory as Kelp without changing the contents of the package variable. Any template that can be discovered in the default directory will be usable in the kelp-generator script.

Contents

The directory structure of Kelp/templates directory is as follows:

+ templates
| + template_name
  | - template
  | - file1.pl.gen
  | - NAME.pm.gen
| + another_template_name
  | - template
  | - file1.tt

Each template directory must have a file named template, which lists all the files in that template like this:

file1.pl.gen
NAME.pm.gen

Any file that is not listed will not be used.

Template files

Each template file can contain Template code:

My::App::Name eq [% name %]
Name eq [% module_file %]
My/App eq [% module_path %]

It will be replaced accordingly, but only if the file ends with .gen extension. This extension also allows template files not to be confused with real files, so should be used most of the time. The only case where the .gen extension should not be used in when generating template files using the same syntax as Template, because there's no way to tell which directives should not be interpreted right away.

Files can also contain NAME, FILE, PATH and DOT in their name, which will be replaced by name, module_file, module_path and ..

INTERFACE

Methods

new

my $gen = Kelp::Generator->new(templates_dir => $dir);

Constructs a Kelp::Generator instance. templates_dir is optional.

templates_dir

Returns the current templates directory. Can be changed by passing an argument of this name to new

get_template

my $template_aref = $gen->get_template($template_name, $application_name, %more_vars);

Finds and parses template with Template::Tiny, returning an array reference of files:

['file1.pl', 'contents'],
['replaced_name.pm', 'contents'],
...

Filenames will have directories and .gen suffix stripped and all placeholders replaced. File contents will be ready for saving.

%more_vars can be specified to insert more variables into the template.

list_templates

my @templates = $gen->list_templates;

Discovers and returns all the generation template names as a list.

get_template_files

my @files = $gen->get_template_files($template_name);

Returns the list of template files for a given template. Will return full paths, not just file names.

cpanm Kelp

perl -MCPAN -e shell
install Kelp