template TCL engine command
template require: Source additional template code
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 (dotgen template dir).
Arguments
- file
-
Tcl input file to source. Any procedure that it creates is made available to the template files.
template parse: Generate template content
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 optional arguments by using the special args list construction as the first argument of the template parse command. The list given after args can be retrieved from within the processed template source files from the usual argv variable.
Arguments
- args list
-
This optional argument should be followed by a list of arguments to pass to the template source file. It should be the very first argument, otherwise it is ignored. Each element of the list is available from the template source file in the argv array.
- perm mode
-
This optional argument may be set to specify the permissions to be set for the created 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 link: Create symbolic links
template link src dst
Link source file src to destination file dst. If relative, the source file src is interpreted as relative to the template directory and dst is interpreted as relative to the current output directory. Absolute file name can be given to override this behaviour.
template options: Define 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 dependencies
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: Retrieve options passed to templates
template arg
Return the next argument passed to the template, or raise an error is no argument remains.
template usage: Define template help string
template usage [string]
With a string argument, this procedure defines the template "usage" message. Unless the template redefines a -h option with 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: Print runtime information
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: Abort template processing
template fatal [string]
Print an error message and stop. The message indicates the error location as reported by the TCL command [info frame].