Textantrieb | UText/1 | UText/1.2 Manual

Script.pm

The module Script is an add-in module that is always loaded at startup. It provides an interpreter for the UText script language.

Script Add-In

load hook

The module defines the following text unit when being loaded:

=unit {
  ~parser =script
}

This installs a parser that can be called explicitaly in a UTL expression with:

[*script
[... script instructions here ...]
]

The parser lets the script interpreter that is bound to the current UText object execute the read lines. The script lines must be complete instructions, otherwise the parsing fails.

Output Tags

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

• script: UText Script interpreter
• get: return setting value

Script Interpreter

The following methods in the Script class can be invoked in a Perl script or add-in module in order to execute UText script. Usage synopsis:

use UText::Script;
my $scr = new Script;
$scr->execute(<<'END');
[... script instructions ...]
END
$scr = undef;

new

$scr = new Script;

$scr = new Script($ut);

Script interpreter constructor. The interpreter is bound to the given UText object, or to a new one (with autodump to 0) if no $ut was given.

execute

1. $scr->execute($instructions);

The given instructions are parsed by the interpreter and executed. The program is aborted if an instruction fails. The parameter can be a whole line (trailing newline character is assumed if not present) or more than one line.

The interpreter retains the state between successive calls to execute. Each call does not need to be a self-contained instruction. Example:

$scr->execute('select article begin');
$scr->execute('sp v title');
$scr->execute('ln out by [v author]');
$scr->execute('end');

On each call to execute above the parameter is parsed, the whole instruction gets executed at once only when it is complete, that is after end was given.

The method execute returns the result of the execution. For example:

my $title = $scr->execute('v title');

stores the value of the role ”title“ into the variable $title. If more than one instruction are executed in a single call, execute returns an array of results in list context and a string with all results concatenated in scalar context.

Execute returns undef if none of the instructions returned a defined value. If some instructions returned defined values, undefined values returned by other instructions are discarded.

2. $scr->execute($instructions,$new);

If $new is not defined or 0, same as execute($instructions). If $new is 1, the given instructions are executed in a new context, separated from status left by the last executed line. This is useful when executing independent subcommands.

Note: The instructions must be self contained and cannot continue at the next execute call. If you need to call execute more than once in an own context, do this:

$scr->push();
[... execute ...]
$scr->pop();

3. $scr->execute($instructions,$new, {name=>value,...});

Arguments with the given names and values are defined and then the instructions are executed. The arguments are after the execution removed. For example:

$scr->execute('select (1-%n)p do ln v %field',,{n=>10,field=>'title'})

This executes select (1-10) do ln v title.

push

$scr->push();

Opens a new execution level, internal state variables are initialized to receive a new instruction.

pop

$scr->pop();

Closes the current execution level and returns to the prior level, internal state variables are restored.

continue

$scr->continue;

It returns whether the last execute left an incomplete instruction open. For exeample, after:

$scr->execute('select article begin');

it returns 1, then after performing:

$scr->execute('ln v title end');

it returns 0.

evaluate

$scr->evaluate($string,{name=>value,...});

Arguments with the given names and values are defined, then all parameters calls in the string are substituted by their values and the result returned. The arguments are after the execution removed. Example:

print $scr->evaluate('hello, %name',{name=>'Mary'});

prints ”hello, Mary.“

set_data

$scr->set_data($tag,$data);

The given data reference $data is stored for the given tag. This data is available through get_data in the current instruction and all instructions called by it, but no more after the current instruction has been done.

Example:

$scr->set_data('user', { name=>'Jane', status=>0 });

This is useful when implementing functions to store intermediate data that will be used later by the same function or by subordinated functions. The ”$tag“ is the name of the function that is being implemented or another unambiguous name. For each instruction level this name is unique (and overriden if used more than once), but data for different levels can coexist without interference. The $data is a reference to the data, usually a hash reference.

See for example the implementation of case, when and else in the module Functions.pm: data about matches and the object the condition applies to are shared between function calls at the same level, more than one indented levels having independent data.

get_data

$data = $scr->get_data($tag);

Returns a reference to the data stored with set_data for the current interpreter under the name $tag, or undef if no data was found.

Example:

my $data = $scr->get_data('user');
my $name = $$data{name};
my $status = $$data{status};

If no data in the current instruction level is found, the level above is checked, until one finds data. For example consider these instructions:

func1 begin func2 end

When implementing func2, data defined for func2 is returned, and if none present data defined for func1 is returned.

get_data_all

@data = $scr->get_data_all($tag);

Returns an array of data stored with set_data for the given tag. Each item of the array returns a reference to the data stored at one instruction level. For example when executing:

func1 begin func2 end

if data for a particular tag was defined under func1 and under func2, the function returns an array having as first item the data for func1 and as second item the data for func2 for this tag.

ut

$ut = $scr->{ut};

Returns the UText object that is bound to the current script interpreter.

Variables

The variable ”last command“ contains the value of the last single instruction that was executed (or that is currently being executed).

The variable ”last result“ contains the results of the last single execute call (each one at a separate line if there are more than one).