template TCL engine command

## Contents

- Your rights

- Introduction

- Component model

- Component description file

- GenoM IDL mappings

- Running GenoM

- Tutorials

- Templates

  - Skeleton

  - Mappings

  - Interactive

  - Creating Templates

    - `template` command

    - `engine` command

    - `dotgen` command

    - `language` command

    - `$type` command

    - `$component` command

    - `$port` command

    - `$task` command

    - `$service` command

    - `$codel` command

    - `$param` command

## template TCL engine command

### 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 [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

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 [args 'list'] [{file|string|raw}] 'file' …​]

This is a convenience shortcut for `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 '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

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 [{next|files|names|components}]

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

Arguments

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 ['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 ['string']

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

### template fatal ['string']

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