// Generated from template.tcl - manual changes will be lost
ifdef::sidebartoc[]
include::_Sidebar.adoc[]
endif::[]



























== *template* TCL engine command
























[[template_require]]
=== *template require* 'file'

Source tcl 'file' and make its content available to the template
files. The file name can be absolute or relative. If it is relative, it
is interpreted as relative to the template directory
(link:dotgen{outfilesuffix}#dotgen_template_dir[`dotgen template dir`]).

.Arguments
[horizontal]
'file'::
Tcl input file to source. Any procedure that it creates is made available
to the template files.




























[[template_parse]]
=== *template parse* [args 'list'] [perm 'mode'] [{file|string|raw}] 'file' ...]

This is the main template function that parses a template source file and
instanciate it, writing the result into the current template directory
(or in a global variable). This procedure should be invoked for each
source file that form a `genom` template.

When invoking `template parse`, the last two arguments are the
destination file or string. A destination file is specified as `file`
'file' (the filename is relative to the current template output
directory). Alternatively, a destination string is specified as `string`
'var', where 'var' is the name of a global variable in which the template
engine will store the result of the source instantiation.

The output destination file or string is generated by the template from
one or several input source. An input source is typically a source file,
but it can also be a string or raw (unprocessed) text. An input source
file is specified with `file` 'file', where 'file' is a file name
relative to the template directory. An input source read from a string is
specified as `string` 'text', where 'text' is the text processed by the
template engine. Finally, a raw, unprocessed source that is copied
verbatim to the destination is specified as `raw` 'text', where 'text' is
the text to be output.

Additionnaly, each input source, defined as above, can be passed a list
of arguments by using the special `args` 'list' construction. The list
given after `args` can be retrieved from within the processed template
source files from the usual `argv` variable. If the argument list
consists in a single '-', the previous arguments from a previous call are
reused. In any case, the `argv0` variable is set to the normalized path
of the input file, or '-' if the input is a string.

.Arguments
[horizontal]
+args+ 'list'::
This optional argument should be followed by a list of arguments to pass
to the template source file. Each element of the list is available from
the template source file in the 'argv' array. If 'list' is '-', arguments
set by a previous call are reused.

+perm+ 'mode'::
This optional argument may be set to specify the permissions to be set
for the created file. The special permission 0 means to delete the
destination file.

.Examples
----
template parse file mysrc file mydst
----
Will parse the input file `mysrc`, process it and save the result in
`mydst`.

----
template parse args {one two} file mysrc file mydst
----
Will do the same as above, but the template code in the input file
`mysrc` will have the list `{one two}` accessible via the
`argv` variable.

----
template parse string "test" file mydst
----
Will process the string "test" and save the result in `mydst`.

































































[[template_remove]]
=== *template remove* [args 'list'] [{file|string|raw}] 'file' ...]

This is a convenience shortcut
for <<template_parse,`template parse perm 0 [...]`>> and it takes the
same arguments. The destination file is deemed obsolete and removed if it
exists. The source file argument exists to ensure that the file to
delete is not locally modified.








[[template_options]]
=== *template options* 'pattern' 'body' ...

Define the list of supported options for the template. Argument is a Tcl
switch-like script that must define all supported options. It consists of
pairs of 'pattern body'. If an option matching the 'pattern' is passed to
the template, the 'body' script is evaluated. A special body specified as
"-" means that the body for the next pattern will be used for this
pattern.

.Examples
----
template options {
    -h - --help	{ puts "help option" }
}
----

This will make the template print the text "help option" whenever -h or
--help option is passed to the template.
























[[template_deps]]
=== *template deps*

Return the comprehensive list of template files processed so far. This
includes files processed via `template require`, `template
parse` and `template link`. This list is typically used to generate
dependency information in a Makefile.

















[[template_arg]]
=== *template arg* [{next|files|names|components}]

Process input arguments according to the optional command keyword. If no
command is given, it defaults to `next`.

.Arguments
[horizontal]
+next+::
Pops the next argument passed to the template, or raise an error if no
argument remains. Mostly useful within a `template options` body.

+files+::
Return a list of readable input files in the current argument list of
the template. If no readable file exists, return the first argument
(if any) so that ENOENT may eventually be reported by `template parse`.

+names+::
Return the list of arguments that are not readable input files.

+components+::
Interpret the list of arguments that are not readable input files
(`template arg names`) as component or interface names and return the
list of resolved objects. If none is given explicitly, the components and
interfaces defined in input files (`template arg files`) are returned.

Input files must have been parsed already by `template parse` for this
command to return meaningful data.




































































[[template_usage]]
=== *template usage* ['string']

With a 'string' argument, this procedure defines the template "usage"
message. Unless the template redefines a `-h` option with `template
options` (<<template_options,`temaplte options`>>), the default
behaviour of the template is to print the content of the `template usage`
string when `-h` or `--help` option is passed to the template.

`template usage`, when invoked without argument, returns the last
usage message defined.














[[template_message]]
=== *template message* ['string']

Print 'string' so that it is visible to the end-user. The text is
sent on the standard error channel unconditionnaly.












[[template_fatal]]
=== *template fatal* ['string']

Print an error message and stop. The message indicates the error location
as reported by the `TCL` command `[info frame]`.


































































// eof
