Textantrieb | UText/1 | UText/1.2 Manual

Add-In Hooks

This page describes the hooks available by default in add-in modules in UText/1.2. Add-in modules can add custom hooks.

UText.pm module

Hooks defined by the kernel.

load: loading module

module::load()

This is triggered once for each module when it is being loaded. If the module needs to add some text units into the repository, it should do this here instantiating a new UText object.

init: instantiating UText object

module::init($ut)

This event ocurs each time a UText object is being instanciated, in order for the add-in modules to perform any initialization they might require. Add-in modules are also free to bind some output processor tags here, thus not requiring additional calls to bind.

clone: cloning UText object

module::clone($ut,$source)

This event takes place when a UText object is being cloned. This event occurs after the event init for the same object. $ut is the UText object being instantiated, $source is the original UText object that is being duplicated.

getfile: reading a UTL source file

module::getfile($ut,$pcnt,$type,$file)

This event is raised whenever an operation getfile takes place. Any event listener can process the response or add content to it.

To catch this hook in your add-in module just define a function with this signature:

sub getfile
{
my ($ut,$cntp,$type,$file) = @_;
[...]
}

This function has no return value. The parameters are:

$ut the current UText object
$type the type parameter of the original call to getfile
$file a full file name of a single file to be read
$cntp is a reference to the file contents

If there are more than one loaded add-in module that support this function, each of them is called once and can process the contents given by others or add new content.

The typical event handler, say for file type ”customtype“, would look like this:

sub getfile
{
my ($ut,$cntp,$type,$file) = @_;
return if defined($$cntp) || $type ne 'customtype';
my $cnt=<get contents of file $file, which has the type "customtype">
$$cntp = $cnt;
}

The returned content $$cntp will be then parsed by the UTL parser and be fed into the text repository.

aborting: aborting script execution

module::aborting($ut)

This event ocurs when executing aborts because of a run time error. A module should catch this if it has to perform some clean up before running again in a interactive session. See function abort.

Tags.pm module

Hooks regarding output processors.

bind: set output bindings

module::bind($ut, $str)

This hook is triggered for a particular add-in module when the operation bind on it takes place. The module is expected to set the output bindings, if it has not already done it on initialization. The operation fails if the module does not implement this.

Invoqued by:

Functions $ut->set_bindings($str) and $ut->set_out_bindings($module,$str)

Output Tag [bind <module>] or [bind/ <module>]<str>[/bind]

Script function bind <module> or bind <module> do <str>

unbind: remove output bindings

module::unbind($ut, $str)

This hook is triggered for a particular add-in module when the operation unbind on it takes place. The module is expected to remove the output bindings. The operation does not fail if the module does not implement this. If the module does not remove his bindings, they are removed by the UText kernel.

Invoqued by:

$ut->remove_bindings($str), $ut->remove_out_bindings($module,$str)

Output Tag [unbind <module>] or [unbind/ <module>]<str>[/bind]

Script function unbind <module> or unbind <module> do <str>