gecko-dev/tools/wizards/README-new-from-template.html
rginda%netscape.com afc5f27f50 fix seealso section
2001-09-28 00:43:23 +00:00

209 lines
8.7 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>new-from-template.pl</title>
</head>
<body bgcolor="white">
<h1 align="right">new-from-template.pl</h1>
<dl>
<dt><b>NAME</b></dt>
<dd>
<b>new-from-template.pl</b> - Generates new code from templatized sources and
variable definition files.
<br>
<br>
<dt><b>SYNOPSIS</b></dt>
<dd>
<table>
<tr>
<td align="right" valign="top">
<code>
<b>new-from-template.pl</b>
</code>
</td>
<td>
<code>
-t FILE [-o DIRECTORY] [-f[d]] [-h] [-?]
</code>
</td>
</tr>
</table>
<br>
<br>
<dt><b>DESCRIPTION</b></dt>
<dd>
<b>new-from-template.pl</b> is used to generate new code from templatized source
files. <b>new-from-template.pl</b> 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.<br>
<br>
Templatized source files can be found in the
<tt>templates/&lt;template-name&gt;</tt> directory. These files contain
a skeletal version of the application that the template is intended
to produce. Variables in the format <code>${variable-name}</code> can
be used in these files to refer to values that should be filled out by
<b>new-from-template.pl</b> when the template is processed<br>
<br>
Files containing variable lists usually have the extension
<tt>.tpl</tt>, although this is not an actual requirement. These
<tt>.tpl</tt> files contain lists of variables in the format
<code>variable-name = variable-value</code>. The
<code>variable-value</code> may refer to the value of other variables
by using the syntax <code>${other-variable-name}</code>. Note that
this is the same way a templatized source file would refer to a
variable. The order of declaration is not significant, as
<b>new-from-template.pl</b> loads the entire list of variables before it
it begins dereferencing them.
<br>
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.
<center>
<table border="1" width="85%">
<tr>
<th>Function</th><th>Description</th>
</tr>
<tr>
<td>
<code>file("&lt;file-name&gt;")</code>
</td>
<td>
The <code>file</code> function is used to set the variable to
the contents of another file.
</td>
</tr>
<tr>
<td>
<code>eval("&lt;perl-code&gt;")</code>
</td>
<td>
The <code>eval</code> function is used to set the variable to
the result of executing arbitrary perl code.
</td>
</tr>
</table>
</center>
<br>
<tt>.tpl</tt> files can include other <tt>.tpl</tt> files via
<code>include "&lt;filename.tpl&gt;"</code>. This will include
<tt>filename.tpl</tt> as if it were part of the <tt>.tpl</tt> at the
position of the <code>include</code>. If <tt>filename.tpl</tt> declares
any variables that had been set before the <code>include</code>,
they will be overridden. Any variables you define after the
<code>include</code> will remain intact.<br>
<br>
<b>new-from-template.pl</b> defines a variable called
<code>top_wizard_dir</code> that can be used to locate files relative to
the <b>new-from-template.pl</b> script. Any file references that are not
explicitly relative to this variable will be relative to the user's
working directory.<br>
<br>
To rename templatized source file names during template processing, use
<code>rename ("&lt;templatized-source-name&gt;", "&lt;target-source-name&gt;")</code>.
When <b>new-from-template.pl</b> process the template, any filename matching
<code>templatized-source-name</code> will be renamed to
<code>target-source-name</code>. This has the side effect of setting
the value of the <code>filename:templatized-source-name</code> variable
to <code>target-source-name</code>.<br>
<br>
Any undefined
variable that matches the pattern <code>filename:*</code> will return
the value following the <code>filename:</code> as its default value.
This allows you to refer to <code>filename:</code> variables in your
templatized source files, instead of the actual filenames.<br>
<br>
<dt><b>OPTIONS</b></dt>
<dd>
<dl>
<dt><b>-d</b></dt>
<dd>
Recursively delete the output directory before starting, requires
the <tt>-f</tt> option.
<br>
<br>
<dt><b>-f</b></dt>
<dd>
Force overwriting of files in the output directory.
<br>
<br>
<dt><b>-h</b></dt>
<dd>
Display a description of the template specified with <tt>-o</tt>.
The Template will not be processed. The template description is
taken from the value of the variable
<code>template_description</code> in the template file.
<code>template_description</code>s provided by template file(s)
<code>include</code>ed by the main template file will <b>not</b>
be displayed.
<br>
<br>
<dt><b>-o DIRECTORY</b></dt>
<dd>
Generate the template into the directory specified by DIRECTORY. If
this directory exists already, <b>new-from-template.pl</b> will fail. This
is to prevent you from accidentally overwriting an existing
application. Use the <tt>-f</tt> option to continue anyway. Use
<tt>-fd</tt> to force DIRECTORY to be deleted before the template is
processed.
<br>
<br>
<dt><b>-t TEMPLATE</b></dt>
<dd>
Process the template specified by TEMPLATE. This is usually a
file in the <tt>my/</tt> sub-directory, ending in <tt>.tpl</tt>.
<br>
<br>
<dt><b>-?</b></dt>
<dd>
Show usage information and exit.
<br>
<br>
</dl>
<dt><b>SEE ALSO</b></dt>
<dd>
<a href="http://lxr.mozilla.org/mozilla/source/tools/wizards/new-from-template.pl">new-from-template.pl</a>,
<a href="http://lxr.mozilla.org/mozilla/source/tools/wizards/templates/xul-app.tpl">xul-app.tpl</a>,
<a href="http://lxr.mozilla.org/mozilla/source/tools/wizards/my/sample.xul-app.tpl">sample.xul-app.tpl</a>,
<a href="http://lxr.mozilla.org/mozilla/source/tools/wizards/templates/xpcom-component.tpl">xpcom-component.tpl</a>,
<a href="http://lxr.mozilla.org/mozilla/source/tools/wizards/my/sample.xpcom-component.tpl">sample.xpcom-component.tpl</a>
<br>
<br>
<dt><b>REQUIREMENTS</b></dt>
<dd>
<b>new-from-template.pl</b> requires the <b>Getopt::Std</b> perl package, standard
in most perl distributions.
<br>
<br>
<dt><b>EXAMPLES</b></dt>
<dd>
<p>
<code>perl new-from-template.pl -t templates/xul-app.tpl -h</code><br>
Shows a description of the XUL App template.
<p>
<code>perl new-from-template.pl -t my/sample.xul-app.tpl</code><br>
Generates a new XUL Application from the variables defined by
<tt>sample.xul-app.tpl</tt> into the default output directory,
<tt>nft-results</tt>.
<p>
<code>perl new-from-template.pl -t my/sample.xpcom-component.tpl
-o ~/src/cvs/mozilla/extensions/jsdebugger/</code><br>
Generates a new XPCOM component from the variables defined by
<tt>sample.xpcom-component.tpl</tt> into the directory
<tt>~/src/cvs/mozilla/extensions/jsdebugger/</tt>
</dl>
<hr>
<address><a href="mailto:rginda@netscape.com">Robert Ginda</a></address>
<!-- Created: Thu Dec 2 19:08:05 PST 1999 -->
<!-- hhmts start -->
Last modified: Thu Sep 27 17:42:49 PDT 2001
<!-- hhmts end -->
</body>
</html>