Hamster-Scripts: Modules

Creating modules

Modules are just scripts containing a set of often used functions. It is suggested to use the file-extension ".hsm" for modules to separate them from normal scripts (".hsc").

The only notable thing about modules compared to normal scripts is, that they also contain a mechanism for initializing and finalizing things automatically when the module is used by a script.

#!initialize

The initialization-mechanism of a module is just a piece of script-code, which is marked by an initial "#!initialize"-line. The code directly after this marker is executed automatically when the module is used by a script.

The initialization-code must return an integer-value. A value of 0 shows a successful initialization, values other than zero prevent the script from starting (e.g. if a file needed by the module is missing).

	#!initialize
	   debug( 255, "<<< module 'modulename.hsm' >>>" )
	return( 0 )

The initialization-code is executed within the global context of the started script, so all variables created and used in the initialization-code are global afterwards.

	#!initialize
	   debug( 255, "<<< module douglas_adams.hsm' >>>" )
	   var( $THE_ANSWER )
	   $THE_ANSWER = 42
	return( 0 )

As it is not possible to protect module-wide variables from being changed by the calling script, it is suggested to at least use names which rarely should be used by someone else. A convention, that might also be used for script-internal functions, is to precede such names with the name of the module like in the following example:

	#!initialize
	   debug( 255, "<<< module 'modulename.hsm' >>>" )
	   var( $modulename_hsm_Counter )
	   $module_name_hsm_Counter = 0
	return( 0 )

	sub modulename_hsm_ThisSubOnlyNeededWithinModule
	   # ...
	endsub

#!finalize

Finalization looks like and works similar to initialization. The script code following the "#!finalize" line is executed when the script terminates, regardless if it was stopped by an error or due to normal termination.

	#!initialize
	   # initialization code here
	return( 0 )

	#!finalize
	   # finalization code here
	return( 0 )

Finalization can be used to clean up ressources allocated by the module, i. e. closing open files, free lists or allocated memory etc.

Note: If "#!finalize" is used, the module must also have an "#!initialize" (but not vice versa), and "#!initialize" must be located before the "#!finalize". If there's a "#!finalize" without prior "#!initialize", the script will not start and report an appropriate error message.

Using modules

To use existing modules within a script, they have just to be loaded by "#!load"-commands:

	#!load hamster.hsm
	#!load htime.hsm

If one of the loaded modules also contains "#!load"-commands, these dependant modules will also be loaded automatically. Each module will only be loaded once, regardless of how often and where it is loaded.

After all requested modules are loaded and before the actual script-code is executed, the initialization code of all modules is executed in reverse order of loading them.

[www.elbiah.de Hamster Playground Documentation]