Functions

Predefined Script Functions

This page describes the predefined functions in Universaltext Script as of UText/1.2.

Functions.pm module

Basic functions supported by the the script interpreter.

select

traverse text

1. select

Describes the current unit.

2. select <selector>

Describes all units returned by the given selector.

3. select <selector> do <instruction>

select <selector> begin <instructions> end

Loops over all units returned by the given selector. For each visited text unit, the current UText object is positioned at this unit and then the given instructions are executed.

This function is the script counterpart to the ustring tag foreach.

See Text Selectors for a description of selectors.

cu

change unit

cu <selector>

Changes the location of the current UText object to the first unit returned by the selector.

out

output with tag expansion

out <string>

Returns the string after expanding its embedded tags. Corresponds to the Perl function $ut->out.

Use lit to return a string without expanding the tags.

save

save a file

1. save <file name>

Stores the results of the last command under the given file name.

2. save <file name> do <instruction>

save <file name> begin <instructions> end

Executes the instructions and stores their results under the given file name.

If a file with this name does not exist, it is created. If it already exists and has a different content, it is replaced. If it already exists with the same content, it is not touched.

case

conditional evaluation group

case begin <instructions> end

case <selector> begin <instructions> end

The case operation allows conditional execution of script instructions. The conditional when operations are evaluated for the given selector. If no selector was given, the current unit at the time of executing the case is assumed.

Example:

case begin
  when type h1 do out <h1>[v]</h1>
  when type p do out <p>[v]</p>
  else do v
end

If there are some instructions that are not protected with a conditional operator, they are always executed.

case begin
  print Evaluating Case
  when [...]
end

The conditional operators are when and else.

when

conditional evaluation

when <condition> do <instruction>

when <condition> begin <instructions> end

This operator is used inside a case group. The instructions are executed if the text unit refered to in case meets the condition. The condition is one of the following:

• unit <name> whether the unit has this name
• role <name> whether the unit has this role name
• type <name> whether the unit has this type or an ancestor type of it
• bin present whether the unit has binary data
• bin missing whether the unit is binary but has no binary data
• bin NA whether the unit is not binary
• eq <string> whether the unit's binary data is equal to the string
• ne <string> whether the unit's binary data is not equal to the string
• lt <string> whether the unit's binary data is lesser than the string
• gt <string> whether the unit's binary data is greater than the string

If there are more than one when inside a case group, they are independent, that is, more than one of them can be executed, if they meet the condition. To get mutually exclusive conditions use else when instead.

else

conditional evaluation

This operator is used inside a case group.

else <instruction>

else begin <instructions> end

else when [...]

The instructions (respectively the when) are executed if no other condition in the current case-group has yet been met.

for

iterate through argument values

1. for <argument> as <value> do <instruction>

for <argument> as <value> begin <instructions> end

The argument gets the given value and the instructions are executed.

Example:

ut> for directory as projects/geneaweb do read \%directory/*.utl

The above reads all files with extension .utl under the directory:

<current directory>/projects/geneaweb

Note that in the instructions to call the parameter is not %directory but \%directory, otherwise it would be expanded when parsing the for instruction, not when performing the read.

2. for <argument> in <value1>, <value 2>, ... do <instruction>

for <argument> in <value1>, <value 2>, ... begin <instructions> end

Same as above, but the instructions are executed once for each of the given values.

ln

separate with new line

1. ln

Outputs a new line character.

2. ln <instruction>

ln do <instruction>

ln begin <instructions> end

Executes the instructions and appends a new line after each instruction's output. It returns nothing if the instructions do not return nothing.

sp

separate with space

1. sp

Outputs a space character.

2. sp <instruction>

sp do <instruction>

sp begin <instructions> end

Executes the instructions and appends a space character after each instruction's output. It returns nothing if the instructions do not return nothing.

lnsp

separate with space and new line

lnsp <instruction>

lnsp do <instruction>

lnsp begin <instructions> end

Executes the instructions and appends a space between each single instruction's output and a new line at the end. It returns nothing if the instructions do not return nothing.

cd

change directory

Changes the current working directory at operating system level. This is the default directory for all read and write operations on files. The initial current working directory of a script is the directory of the file that contains it.

!

operating system shell call

! <os command>

Executes the given command at the operating system shell. Examples:

! ls lists the files at the current working directory in Unix systems.

! dir the same in Windows systems.

What the command writes into the standard output stream is returned back as result. Example:

ut> ! ls
[...]
ut> save files.txt

After that the file files.txt contains the names of the files found at the current directory.

print

console output

1. print <string>

Prints out the string after expanding it.

2. print do <instruction>

print begin <instructions> end

Executes the instructions and prints out their results.

See the ustring tag print for more information.

reset

reset UText object

The current UText object is cloned and the script interpreter attached to the new instance. See clone.

erase

delete the text repository

The text repository is completely deleted. The current UText object is reset.

Settings.pm module

Generic functions to manage settings for all setting providers.

declare

add a setting

1. declare <provider> <name>

Instructs the provider to instantiate a new setting with the given name. After that the function clear is applied to it in order to initialize its value.

2. declare <provider> <name> to <value>

declare <provider> <name> do <body>

declare <provider> <name> begin <body> end

The setting is declared and after that the function set is called with the given value or body. Example:

declare tag parenth to (\%param)

is the same as:

declare tag parenth
set parenth to (\%param)

3. declare <provider> <name1>, <name2>, ..., <nameN> to <value>

More than one setting can be declared and even given a value at once.

may-declare

add a setting, if it does not exist

Same as declare, but it does not fail if the setting is already defined.

1. may-declare <provider> <name>

2. may-declare <provider> <name> to <value>

3. may-declare <provider> <name1>, <name2>, ..., <nameN> to <value>

undeclare

remove a setting

undeclare <provider> <name>

undeclare <name>

Deletes the setting. If the provider is missing it removes the setting from the first provider that has a setting with this name.

get

output a setting value

get <provider> <name>

get <name>

Returns the current value of the setting. If the provider is missing it gets the setting from the first provider that has a setting with this name.

This operation can be embedded in any script instruction with the percent character. Syntax:

%{<provider> <name>}

%{<name>}

%<name>

The curly brackets are not necessary when no provider is given and the setting name consists of a single word.

Example:

ut> declare var x to Hello
ut> print %x, World
Hello, World

Such replacement can be used in function names, too. Continuing the last example:

ut> set x to print
ut> x Hello, World
Script error: Unknown function 'x'.
ut> %x Hello, World
Hello, World

set

assign a setting value

set <provider> <name> to <value>

set <name> do <body>

set <name> begin <body> end

Instructs the setting provider to assign the setting's value. How the value and the body are used depends on the specific provider.

If the provider is missing the first provider that has a setting with this name is invoked.

clear

remove a setting value

clear <provider> <name>

clear <name>

Initializes the setting's value. What value the setting receives depends on the specific provider.

If the provider is missing the first provider that has a setting with this name is invoked.

show

show defined settings

1. show

Prints out some usage information and then lists the current available setting providers.

2. show <provider>

Lists the settings currently available through this provider.

This function returns the settings by default in a comma separated list as returned by the provider's get_declared implementation. Exception: if the provider implements show, this provider's function is called instead. See Settings.pm for more information about provider implementation.