Functions.pm

This page describes the module Functions.pm that is part of the Universaltext Interpreter as of UText/1.2.

Function Support

The module Functions.pm supports the definition of functions that extend the UText script language. To implement new functions in Perl scripts or add-in modules use the following methods of the script interpreter object.

set_function_binding

$scr->set_function_binding($module,$op,$func)

$scr->set_function_binding($module,$op,$func,$source)

Defines a new function under the name $op for the given module. If a function already exists for this name, the old binding is overwritten. The parameter $func can be a scalar or a function reference. If it is a scalar, the execution of this function in a script returns this value. If it is a function reference, the execution causes the function to be called and its result to be passed back.

The referred function is expected to have this signature:

sub func
{
my ($scr,$cmd,$op,$mod,$param,$str)=@_;
[...]
return $ret;
}

The parameters are the following:

$scr the script interpreter object (class Script). Use $scr->{ut} to get the current UText object.

$cmd the whole script instruction that is being executed.

$op the name of the current operation (useful if the same Perl function implements a family of script functions)

$mod the modifier the function was called with, '' if none.

$param the call parameters.

$str the call body.

Sample function calls:

function.modifier parameters do body
function.modifier parameters begin body end

The parameter $source is optional. Its purpose is to get the source code in plain text when using get function at the interactive shell instead of getting an expression such as CODE(0x26c2d80).

set_binding

$scr->set_binding($op,$func)

$scr->set_binding($op,$func,$source)

The same as set_function_binding assuming the module from which it is being called.

remove_function_binding

$scr->remove_function_binding($module,$op)

Removes the function binding under the operation name $op for the given module.

remove_function_bindings

$scr->remove_function_bindings($module)

Removes the function bindings from all operations for the given module.

remove_binding

$scr->remove_binding($op)

The same as remove_binding assuming the module from which it is being called.

remove_bindings

$scr->remove_bindings()

The same as remove_bindings assuming the module from which it is being called.

exists_function_binding

$scr->exists_function_binding($op)

Returns whether a function for operation $op is currently bound.

get_function_bindings

@l = $scr->get_function_bindings()

Returns the names of all currently bound operations in an array.

split_comma_list

@l = split_comma_list($str)

Auxiliar parse function. Given a comma separated list of values (possibly spanning over more than one line), it returns an array of the single values.

Basic Functions

The following script functions are implemented by this module (s. Functions for details):

• select: traverse text
• cu: change unit
• out: output with tag expansion
• save: save a file
• case: conditional evaluation group
• when: conditional evaluation
• else: conditional evaluation
• for: iterate through argument values
• ln: separate with new line
• sp: separate with space
• lnsp: separate with space and new line
• cd: change directory
• !: operating system shell call
• print: console output
• reset: reset UText object
• erase: delete the text repository