Tags.pm

This module supports the transformation of ustring data into a string by expanding the [...] tags. For more information read the manual page Output Processors.

Tag Expansion

out

This function is used in all scripts to expand ustring data as a string. A UText script call out <ustring> and a Perl script call $ut->out($ustring) return a string at which each occurrence of a mark enclosed in square brackets gets expanded.

A call $ut->out($ustring,1) postprocesses the results (calling the .POST bound functions), which is otherwise only done at the outermost out call.

preprocess_cleanup

$ut->preprocess_cleanup($pstr1,$pstr2,...);

This function performs the postprocessing of the given strings expanding them with the .POST bound functions. The parameters are references to the strings. Sample usage:

$ut->preprocess_cleanup(\$param,\$str);

This cleanup is automatically done by the outermost out call or explicitally by out with the option dopost. A call to $ut->preprocess_cleanup is only needed inside a tag expanding function that uses the strings received directly without expanding them with out.

The standard pre- and postprocessing can be partially disabled (see preprocessing).

Tag Definition

The processing of the ustring tags is modular designed. Some tags are supported out of the boy by the modules UText, script or cms. Tags can be defined by a UText script (see Output Processors). A Perl script can define its own tags and handle them with the following methods:

set_out_binding

$ut->set_out_binding($module,$op,$function) sets an output binding processor. For a particular operation each module can only set one output processor. Parameters:

• $module - a string identifying the module that sets the binding. The name is arbitrary but it should be consistent and not conflict with other modules.
• $op - the name of the tag to be bound. All calls to [$op] will be processed by the $function.
• $function - a reference to a callback function. This function is called with these parameters:
  • $self - the current UText object
  • $all the whole string being expanded including tags
  • $op - the tag operation
  • $mod - the tag modifier
  • $param - the tag parameters
  • $str - the content enclosed between opening and closing tag

Alternative one can pass a scalar expression instead of a function reference: $ut->set_out_binding($module,$op,$expression)

The tag expands then as the given expression.

This sets the binding for the current UText object. If this object is cloned, the new object will still have this binding. If a new UText object is instantiated, it will no more have this binding but the default ones instead.

remove_out_binding

$ut->remove_out_binding($module,$op) removes the binding for the given module and operation.

remove_out_bindings

$ut->remove_out_bindings($module) removes all the existing bindings for the given module.

Module bindings

To set bindings for an add-in module there are the following functions available:

$ut->set_binding($op,$function)

$ut->remove_binding($op)

$ut->remove_bindings()

These are the same as above but the module is assumed to be the module from which this functions are being called.

Preprocessing

The property $ut->{PREPROCESS} determines whether a shortcut preprocessing of the source UTL strings takes place before expanding them for the current UText object. For example, replacing _word_ by [i word], 'word' by ”word“, etc. (see Tags for details). By default this is inactive, to activate it use:

set preprocess out to 1

in a UText script or in a Perl script:

$ut->{PREPROCESS}=1

and set it to 0 to deactivate it again. To preprocess the character ^ (literal mark) set it to 2.

If you instantiate a new UText object or reset it, it will have the value 0 again. If you clone a UText object, this value is preserved.

UString Tags

The following tags are set by this module (s. Tags for details):

• .pre: shortcut preprocess
• .post: output postprocess
• foreach: traverse text
• v: get value
• vv: get literal value
• u: get unit information
• cnum: child number
• if: conditional values
• load: load module
• bind: set module bindings
• unbind: remove module bindings
• read: read file
• feed: feed UTL
• print: console output
• lit: literal output
• utl: express in UTL
• save: save a file
• dump: dump text repository
• sb: output square brackets
• lf: newline
• perl: execute perl code

Add-In Hooks

The following hooks are set by this module (s. Add-In Hooks for details):

• bind: set output bindings
• unbind: remove output bindings