Textantrieb | UText/1 | UText/1.2 Manual

Functions

Predefined Script Functions

This page describes the predefined functions in Universal-Text 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 output 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.

The file is saved through FILE.pm.

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.

The function save has a ”makefile“ behavior. If the file to be saved is already existing and has a newer timestamp than the current unit, the file is not saved (and their content is not expanded). If the unit timestamp is newer than the file but the file contents are unchanged, the file is touched to the unit timestamp. This behavior can be activated with set makefiles to 1 or calling the UText Shell with -F.

A call with a modifier save.name will compare to the timestamp of the unit with the given name instead of the current unit.

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 output 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.