Textantrieb | UText/1 | UText/1.2 Manual

Add-In Modules

This page describes the add-in module support implemented in UText/1.2.

Add-in modules can provide output tags, script functions and settings, and can define type drivers for reading files. Add-in modules are written in Perl. They are dynamically loaded on demand. UText ships with some add-in modules, you can write your own, too.

Using a Module

To load a module use the operation load:

load odt

load odt : load cms

To bind the output tags of a module or unbind them:

bind cms
unbind cms

Or, to load and bind a module:

load.bind cms

The operation bind calls the function bind($ut) at the module and expects it to set the output bindings. If the module does not exist or it does not provide this function, the call will fail.

The operation unbind calls the module function unbind($ut) if it is present. If the module does not provide a function unbind, all his bindings are automatically removed. If there are no bindings currently set for this module, nothing happens.

It is up to each module to decide whether a call to bind is necessary for the module bindings to take place or if it binds itself. Some modules such as Script bind themselves automatically to each UText object that is being instantiated. Other modules such as cms must explicitally be bound to each UText object that needs them.

Custom Modules

Creating a Module

A UText add-in module is a Perl module. This is the minimal add-in, stored at a file ”minimal.pm“:

package minimal;
1;

This module will load with load minimal.

The file must contain a package with the same base name (case is relevant). Otherwise the add-in won't load.

The module file can be stored at any directory included in the Perl @INC list, at the directory that contains the running UText interpreter oder at its subdirectory modules.

In order for the module to be called by the UText interpreter, it must use the hooks provided. To register a hook, the module must have a function with the hook's name at the module's main namespace. Example:

package minimal;
sub load
{
}
1;

The function load will be called once when loading the module. This function has no parameters and no return value.

Other useful hooks are bind and unbind, which are triggered respectively by the operations bind and unbind. Their signature:

sub bind
{
my ($ut,$str)=@_;
}
sub unbind
{
my ($ut,$str)=@_;
}

$ut is the current UText object, $str corresponds to the contents of the call, for example ”some parameters“ when called with a script instruction

bind minimal begin some parameters end

or with a tag

[bind/ minimal]some parameters[/bind]

To handle the instantiation of UText objects there are the hooks init and clone available.

sub init
{
my $ut = shift;
}

The function init gets the new UText object as $ut. This hook is called each time a UText object is created.

sub clone
{
my ($ut,$source) = @_;
}

The clone hook is triggered each time a UText object is cloned. The newly created object is $ut and the previously existing UText object that was cloned is $source. The hook clone is activated after the hook init for the same object.

If the UText interpreter finds an error, it will stop execution. An interactive shell session however still runs after the previous instruction stopped. If your module needs to do something each time execution aborts, you can catch the hook aborting.

sub aborting
{
my $ut = shift;
[... do some clean up here ...]
}

Your module should call the function $ut->abort("error message") if it finds an error in order to abort execution.

Through the hook getfile an add-in module can provide a driver for reading files of a specific type. See the function getfile for more information.

Creating Add-In Hooks

To create a new hook that other add-in modules can attach to, it suffices to activate it when needed, a registration is not needed.

Use call_modules to activate all add-in modules that listen to a particular hook. Example:

$ut->call_modules('myhook')

This calls the function sub myhook in all add-in modules that are currently loaded and that define them, if there are some.

You can pass additional parameters to the function appending them after the function name.

$ut->call_modules('myhook',$p1,$p2)

In this case the add-in functions should have this signature:

sub myhook
{
my ($ut,$p1,$p2)=@_;
return $ret;
}

The call to call_modules returns a list of values, each of them returned by another add-in module.

One can also call a function from a particular module with call_module:

$ut->call_module('mymodule','myhook')

This call fails if this module is not loaded or if it does not have such a function. Use may_call_module instead if you do not want the call to fail but do nothing in this case.

More

For a reference of all Perl functions related to the add-in modules see UText.pm.

For a reference of the predefined add-in hooks see Add-In Hooks.