Hamster-Scripts: Preprocessor-Commands

Preprocessor-Commands are special commands that are execute before the script is started. If used, they should preferably be located at the very beginning of the script.

#!hs2

This command is ignored. It once was a marker for which script engine should be used.

#!trace 1

For testing-purposes, all lines will be displayed as they are executed. Although there's also a "trace"-command to enable and disable tracing, this preprocessor-command is the only way to trace the preprocessor-phase. It shows, for example, the initialization-sequences of loaded modules.

#!debug <level>

Sets the debug-level, with which the script is executed. Default is "#!debug 0", which means, that all "debug"-commands within the scripts should be ignored.

#!load module.hsm

This command loads and initializes the given module and its dependants (if any). See Modules for details.

#!initialize
#!finalize

These commands are mostly used in modules and mark an initialization or finalization code. See Modules for details.

#!profiler 1
#!profiler 2

Activates a simple, 'sub' based profiler for the script. Activated by a '#!profiler 1' line, it collects usage and timing information while the script is running and finally creates a report when script ends (saved to log file). If activated with '#!profiler 2', it also notes the call stack for each sub in the final report.

#!meta <keyword> <parameters>

Such "meta" commands are used to store additional information about the script within the script. This "meta information" does not affect a running script, but external programs like HControl might be able to make use of it.

HControl makes use of the following meta keywords to detect and ask for required start parameters:

Keyword Parameters
ParamTitle 1.) Title of the window, with which HControl asks for required parameters to start the script
If not given, "Start Script" is used.
ParamCount 1.) Number of required parameters
If not given, 0 (=none) is used.
ParamPrompt 1.) Parameter number (1...ParamCount)
2.) Prompt text for that parameter
If not given, "Parameter:" is used.
ParamDefault 1.) Parameter number (1...ParamCount)
2.) Initial value of that parameter
If not given, an empty string is used.

Example:

#!meta ParamTitle "The meaning of life"
#!meta ParamCount 1
#!meta ParamPrompt 1 "Your answer:"
#!meta ParamDefault 1 "42"

Note:
If you want to add your own meta information for any purpose, only use keywords starting with an "X" character like "X-MyKeyword", as other keywords might get a special meaning in future Hamster versions.

[www.elbiah.de Hamster Playground Documentation]