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







































== *engine* TCL engine command
















































[[engine_mode]]
=== *engine mode* [[+-]'modespec'] ...

Configures various engine operating modes. `engine mode` can be invoked
without argument to retrieve the current settings for all supported
modes. The command can also be invoked with one or more mode
specification to set these modes (see 'modespec' argument below).

.Arguments
[horizontal]
'modespec'::
A mode specification string. If `mode` string is prefixed with a
dash (`-`), it is turned off. If mode is prefixed with a plus
(`+`) or not prefixed, it is turned on. Supported 'modespec'
are:
  'overwrite'::: when turned on, newly generated files will overwrite
  existing files without warning. When turned off, the engine will stop
  with an error if a newly generated file would overwrite an existing
  file. `overwrite` is by default off.

  'move-if-change'::: when turned on, an existing file with the same
  content as a newly generated file will not be modified (preserving the
  last modification timestamp). When off, files are systematically
  updated. `move-if-change` is on by default.

  'merge-if-change'::: when turned on, existing destination files will be
  merged with new content by the engine, instead of being overwritten
  (<<engine_merge_tool,`engine merge tool`>>). `merge-if-change` is off by
  default.

  'silent'::: when on, this mode avoids scattering standard output with
  informative messages from the code generator.

  'debug'::: when on, this mode preserves temporary files and tcl
  programs generated in the temporary directory. Useful only for
  debugging the template.

.Return value
When called without arguments, the command returs the current
configuration of all engine modes.

.Example
----
engine mode -overwrite +move-if-change
----




































[[engine_merge_tool]]
=== *engine merge-tool* 'tool'

Changes the engine merge tool. When the engine is in 'merge-if-change'
mode (see <<engine_mode,`engine mode`>>), a merge tool is inkoked with
the two conflicting versions of the destination file. If the merge tools
exits successfuly, the generated file is replaced by the merged version.

There are two builtin tools: `interactive` and `auto`. `interactive`
interactively prompts the user for each patch to be applied to merge the
final destination. The user can accept or reject the patch, or leave the
destination file unchanged. The `auto` builtin tool automatically merges
the two files and places conflict markers (`<<<<<<<` and `>>>>>>>`) were
appropriate in the destination file.

.Arguments
[horizontal]
'tool'::
The path to the merge tool executable (e.g. `meld`), or one of
the builtin keywords `interactive` or `auto`.











[[engine_chdir]]
=== *engine chdir* 'dir'

Change the engine output directory. By default, files are generated in
the current directory. This command can be used to generate output in
any other directory.

.Arguments
[horizontal]
'dir'::
The new output directory, absolute or relative to the current working
directory.














=== *engine pwd*

The current engine output directory.


































[[args]]
=== *args* 'variable1' ['variable2'...]

Assign each argument passed to a template source file to named
variables `variable1`, `variable2` ..., in the spirit of `lassign $argv
variable ...`. Raises an error if the number of arguments does not match
the expected number. This function is only available in a parsed template
source file, not from the main `template.tcl` file.

.Examples
----
args var1 var2
----




































































































































































































































































































































































































































































































































// eof
