Textantrieb | UText/1 | UText/1.2 Manual

Settings.pm

This page describes the module Settings.pm that is part of the Universal-Text Interpreter as of UText/1.2.

The module Settings.pm supports the definition of setting providers that extend the UText script language. It also implements some setting providers that are available out of the box.

Basic Providers

The following setting providers are implemented by this module:

• Variables
• System Settings
• Tags
• Functions
• Arguments
• Modules

Variables

The provider var supports variables. Variables are named string containers that retain the last given value as long as the current script interpreter object runs. Any script can create variables and change their values. There is a single name space for variables of every script object. Example interactive shell session:

ut> declare var my name
ut> set my name to Pat
ut> get my name
Pat
ut> out Hello, %{my name}
Hello, Pat
ut> clear my name
ut> get my name
ut> undeclare my name
ut> get my name
Script error: get failed.
   Unknown setting 'my name' executing: get my name

System Settings

The provider system gives access to the following system settings:

lang: sets or gets the current language (see setlang and $LANG)

preprocess out: enables or disables string preprocessing (see Tags.pm). Valid operations are set, get and clear (set to 0).

summary: gets or initializes the file generation summary (see FILE.pm). Valid operations: get, clear.

last command: returns the last script instruction that was successfully executed. Valid operation: get.

last result: returns the result of the last command. Valid operation: get.

current command: returns the script instruction that is being executed. Valid operation: get.

debug: sets or gets the current debug level. Possible values: say, files, status, none (see UText.pm)

trace out: activates or deactivates tracing string output calls (see UText.pm). Valid operations: get, set.

trace functions: activates or deactivates tracing script function calls (see UText.pm). Valid operations: get, set.

trace bind: activates or deactivates tracing binding and unbinding calls for tags (see UText.pm). Valid operations: get, set.

Tags

The provider tag is an interface to the output tags. Tags can be defined, changed and removed through setting operations. For example to declare a tag that returns the HTML entity for copyright:

declare tag copyright to ©

Internally this tag is bound to the script instruction out ©.

The tags defined in a UText script are bound to the module name currently stored in the variable current module. By default it is ”main“ until changed. Example:

ut> set current module to my module
ut> declare tag name to John
ut> show tags
.BASE: .POST .PRE bind cnum dump feed foreach [...]
Script: script
main: help
my module: name
ut> unbind my module
ut> show tags
.BASE: .POST .PRE bind cnum dump feed foreach [...]
Script: script
main: help
ut>

One can use arguments that represent the tag occurrence arguments. For example the argument str has the tag contents:

ut> declare tag i to <i>\%str</i>
ut> out <i>hello</i>
<i>hello</i>

The argument name str was escaped at the declaration statement in order for the interpreter not to expand it once when running the declare, but each time when expanding the tag itself. The stored tag has the argument unescaped:

ut> get i
out <i>%str</i>

These arguments are available, see Output Processors for more information on each argument:

• op: operation
• mod: modifier
• param: parameters
• str: content

A tag can be bound to any script instruction using do or begin...end when assigning it a value:

set tag <name> do <instruction>
set tag <name> begin <instructions> end

When expanding the tag, the given instructions are executed and their output is the expanded value.

Functions

The provider function makes it possible to define functions inside a script. It makes the same as the provider tag, see above for the details. Sample session:

ut> declare function ls do ! ls \%param
ut> ls ~/UText/samples
contact.html
file.pl
file.utl
geneaweb1.pl
[...]

Tags can be used in a script as functions, but functions cannot be used as tags: f.e. you cannot use [ls] in a string. Most time one uses to <value> for tags and do <instruction> for functions, but both setting providers admit both of them and have the same syntax.

The difference between functions and tags is that each function must have a unique name for all modules, but there can be tags with the same name in different modules.

Arguments

The provider argument supplies named string containers that have the scope of the instruction currently being executed. This settings are implicit and cannot be declared or set explicitly through a UText script. Their value can be queried via a get instruction or a setting substitution %name or, for names that have more than one word, %{name}.

Arguments are automatically passed through to nested function calls. Arguments of outer functions are also visible in inner functions, if they do not override them with another value.

These arguments are available by default in UText scripts:

• op: operation
• mod: modifier
• param: parameters
• str: body

These refer to the function or tag that is currently being executed.

A add-in module can add arguments via the following Perl methods of the Script class:

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

Modules

The provider module at present only supports one operation, show, which returns a list of the modules that are currently loaded.

ut> show modules
Script, odt

Implementing Setting Providers

As an example this add-in module (env add-in, saved as file env.pm) implements a read-only setting provider for environment variables:

package env;
sub init
{
my $ut = shift;
$ut->get_script->may_register_provider(
 name=>'env',
 get=>\&get_env,
 is_declared=>\&is_declared_env,
 get_declared=>\&get_declared_env,
);
}
sub get_env
{
my ($self,$function,$provider,$name)=@_;
return $ENV{$name};
}
sub is_declared_env
{
my ($self,$function,$provider,$name)=@_;
return exists $ENV{$name};
}
sub get_declared_env
{
my ($self,$function,$provider)=@_;
return sort keys %ENV;
}
1;

To implement new providers in Perl scripts or add-in modules use the following methods of the script interpreter object.

register_provider

$scr->register_provider(
 name=>...,
 alias=>...,
 declare=>...,
 undeclare=>...,
 set=>...,
 get=>...,
 clear=>...,
 is_declared=>...,
 get_declared=>...,
 show=>...,
);

This binds a provider for the current session, not just for the current script interpreter object, but for all of them. The provider name must be given and must be unique, otherwise the call fails. The alias is optional, if given scripts can refer to the provider by its name or its alias indifferently.

The rest of the parameters contain a reference to a Perl function that implements the correspondant functionality. The following functions are mandatory, the registration aborts if they are not present:

• is_declared: called by the interpreter to find out whether a particular setting currently exists in this provider
• get_declared: called by the interpreter to get all settings currently defined in this provider

The following functions are optional. A provider can be registered without them, but the execution aborts if a script is missing them. They are called by the Script class method of the same name whenever a UText script or a Perl script requires them on this provider. See the method definition for information about how each function must be implemented by the provider. Functions:

• declare (see declare)
• undeclare (see undeclare)
• set (see set)
• get (see get)
• clear (see clear)
• show (see show)

may_register_provider

Same as register_provider but it does nothing instead of failing if a provider with this name already exists.

get_providers

$scr->get_providers

Returns an array with the names of the currently registered providers.

is_provider

$scr->is_provider($name)

Returns whether a provider with the given name is currently registered.

declare

$scr->declare($provider,$name,$body)

Calls the function with the same name and signature in this provider, that must create a setting with this name. This function call fails:

• if the parameter $provider is missing,
• if no provider with this name is registered,
• if the provider already has a setting with this name, or
• if the provider does not implement this function.

may_declare

$scr->may_declare($provider,$name,$body)

Same as declare but does not fail if a setting with the given name already exists, in this case it does nothing.

undeclare

$scr->undeclare($provider,$namey)

Calls the function with the same name and signature in this provider, that must remove the setting with this name. If the provider is missing, the first provider that has a setting with this name is called. This function call fails:

• if the parameter $provider is missing and there is no setting with this name in any provider,
• if the provider name is given but no provider with this name is registered,
• if the provider name is given but it has no setting with this name, or
• if the provider does not implement this function.

is_declared

$scr->is_declared($provider,$name)

Calls the function with the same name and signature in this provider, that must return whether the setting with this name exists. This function call fails:

• if the parameter $provider is missing, or
• if no provider with this name is registered.

get_declared

$scr->get_declared($provider)

Calls the function with the same name and signature in this provider, that must return an array of the currently declared settings. This function call fails:

• if the parameter $provider is missing, or
• if no provider with this name is registered.

get

$scr->get($provider,$name,$body)

Calls the function with the same name and signature in this provider, that must return the current value for this setting. If the provider is missing, the first provider that has a setting with this name is called. This function call fails:

• if the parameter $provider is missing and there is no setting with this name in any provider,
• if the provider name is given but no provider with this name is registered,
• if the provider name is given but it has no setting with this name, or
• if the provider does not implement this function.

set

$scr->set($provider,$name,$body,$value)

Calls the function with the same name and signature in this provider, that must assign the current value for this setting. If the provider is missing, the first provider that has a setting with this name is called. This function call fails:

• if the parameter $provider is missing and there is no setting with this name in any provider,
• if the provider name is given but no provider with this name is registered,
• if the provider name is given but it has no setting with this name, or
• if the provider does not implement this function.

When using a script instruction, the $value is the part of the parameters that follow the ”to“ keyword, and the $body is the body of the instruction. Examples:

set my setting to value
set my setting do body
set my setting begin
  body
  [...]
end

clear

$scr->clear($provider,$namey)

Calls the function with the same name and signature in this provider, that must initialize the current value for this setting. If the provider is missing, the first provider that has a setting with this name is called. This function call fails:

• if the parameter $provider is missing and there is no setting with this name in any provider,
• if the provider name is given but no provider with this name is registered,
• if the provider name is given but it has no setting with this name, or
• if the provider does not implement this function.

show

$scr->show($provider,$name,$value)

Calls the function with the same name and signature in this provider, that must return an array of the currently declared settings. This function call fails:

• if the parameter $provider is missing,
• if no provider with this name is registered, or
• if the provider does not implement this function.

can_provider

$scr->can_provider($provider,$function)

Returns whether a provider with this name exists and it implements a function with this name. Example:

$flag = $scr->can_provider($provider1,'declare');

After that the flag contains whether the given provider supports declaring settings.

Function Reference

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

• declare: add a setting
• may-declare: add a setting, if it does not exist
• undeclare: remove a setting
• get: output a setting value
• set: assign a setting value
• clear: remove a setting value
• show: show defined settings