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 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 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 and PATH in their name, which will be replaced by name, module_file and module_path.

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