new-from-template.pl

NAME

new-from-template.pl - Generates new code from templatized sources and variable definition files.

SYNOPSIS

new-from-template.pl

-t FILE [-o DIRECTORY] [-f[d]] [-h] [-?]

DESCRIPTION

new-from-template.pl is used to generate new code from templatized source files. new-from-template.pl takes a file containing a list of variables as input, combines those variable values with source files containing variable references, and produces a new set source files with the variable references replaced by their values.

Templatized source files can be found in the templates/<template-name> directory. These files contain a skeletal version of the application that the template is intended to produce. Variables in the format ${variable-name} can be used in these files to refer to values that should be filled out by new-from-template.pl when the template is processed

Files containing variable lists usually have the extension .tpl, although this is not an actual requirement. These .tpl files contain lists of variables in the format variable-name = variable-value. The variable-value may refer to the value of other variables by using the syntax ${other-variable-name}. Note that this is the same way a templatized source file would refer to a variable. The order of declaration is not significant, as new-from-template.pl loads the entire list of variables before it it begins dereferencing them.
In addition to setting variables to plain text, and values derived from other variables, there are two special functions can be used to set the value of a variable. These functions must appear alone in the variable definition in order to take effect.

Function	Description
file("<file-name>")	The file function is used to set the variable to the contents of another file.
eval("<perl-code>")	The eval function is used to set the variable to the result of executing arbitrary perl code.

.tpl files can include other .tpl files via include "<filename.tpl>". This will include filename.tpl as if it were part of the .tpl at the position of the include. If filename.tpl declares any variables that had been set before the include, they will be overridden. Any variables you define after the include will remain intact.

new-from-template.pl defines a variable called top_wizard_dir that can be used to locate files relative to the new-from-template.pl script. Any file references that are not explicitly relative to this variable will be relative to the user's working directory.

To rename templatized source file names during template processing, use rename ("<templatized-source-name>", "<target-source-name>"). When new-from-template.pl process the template, any filename matching templatized-source-name will be renamed to target-source-name. This has the side effect of setting the value of the filename:templatized-source-name variable to target-source-name.

Any undefined variable that matches the pattern filename:* will return the value following the filename: as its default value. This allows you to refer to filename: variables in your templatized source files, instead of the actual filenames.

OPTIONS

-d

Recursively delete the output directory before starting, requires the -f option.

-f

Force overwriting of files in the output directory.

-h

Display a description of the template specified with -o. The Template will not be processed. The template description is taken from the value of the variable template_description in the template file. template_descriptions provided by template file(s) includeed by the main template file will not be displayed.

-o DIRECTORY

Generate the template into the directory specified by DIRECTORY. If this directory exists already, new-from-template.pl will fail. This is to prevent you from accidentally overwriting an existing application. Use the -f option to continue anyway. Use -fd to force DIRECTORY to be deleted before the template is processed.

-t TEMPLATE

Process the template specified by TEMPLATE. This is usually a file ending in .tpl.

-?

Show usage information and exit.

SEE ALSO

build-example-app.pl README, new-from-template.pl source, xul-app.tpl, sample.xul-app.tpl, xpcom-component.tpl, sample.xpcom-component.tpl

REQUIREMENTS

new-from-template.pl requires the Getopt::Std perl package, standard in most perl distributions.

EXAMPLES

perl new-from-template.pl -t templates/xul-app.tpl -h
Shows a description of the XUL App template.

perl new-from-template.pl -t sample-app/sampleapp.tpl
Generates a new XUL Application from the variables defined by sample.xul-app.tpl into the default output directory, nft-results.

perl new-from-template.pl -t my/sample.xpcom-component.tpl -o ~/src/cvs/mozilla/extensions/jsdebugger/
Generates a new XPCOM component from the variables defined by sample.xpcom-component.tpl into the directory ~/src/cvs/mozilla/extensions/jsdebugger/