Textantrieb | UText/1 | UText/1.2 Manual

UTL.pm

This module defines the class UTL, which supports the Universal-Text Language. The class UText is a subclass of UTL, so one does not instantiate UTL directly in scripts, but one gets all its functionality through a UText object.

This class is used for three purposes:

1. for parsing Universal-Text Language files or strings,
2. for generating Universal-Text Language code.

It also provides some basic localization functionality.

UTL to UText

Used to create text from UTL files. See Feeding Text for more information.

read

$ut->read($string) creates a text reading the given string and parsing it. Example:

$ut = new UText;
$ut->read(<<'EOF');
^webpage {
    ^title : string
    ^content {
        ^p : string
        ^h1 : string
    }
}
~webpage =index Overview
~content
~h1 My Site
Welcome to my site!
This site is under construction.
EOF

setfiletime

$ut->setfiletime($filename)

After calling this the creation and update time for the nodes that are appended are set to the creation and update time of the given file.

setnodetime

$ut->setnodetime($unit)

After calling this the creation and update time for the nodes that are appended are set to the creation and update time of the given unit. The unit is a unit name, it can contain more than one level separed by a period. Example: $ut->setnodetime('myWeb.myPage');

Localization Support

setlang

This method sets the current language for a UText object and the corresponding locale at operating system level, too. This affects what characters are accepted in output tags and determines the collation when sorting.

For example $ut->setlang('de'); sets the language to German and the OS locale to ”de_DE.UTF8“. Currently supported languages and their locale codes:

• en (English): en_GB.UTF8
• de (German): de_DE.UTF8
• es (Spanish): es_ES.UTF8
• ca (Catalan): ca_ES.UTF8

The locale can also be specified with a language and culture combination. Example:

$ut->setlang('en_US'); 
$ut->setlang('en_US.ISO88591');

If no character set is specified, UTF8 is assumed.

getlocale

A call to $ut->getlocale() returns the current OS locale.

$LANG

The property $UText::LANG can be used to retrieve the current language code (”de“, ”en“ etc.).

UText to UTL

Used to generate UTL files that correspond to text structure current in memory.

High level functions

save($filename) - writes current unit as UTL text to file $filename

save($filename,$select) - selects unit and saves it

toString() - returns current unit as UTL string

toString($link,$select) - selects unit and returns it

Low level functions

writefile($filename) - opens file to write into

writestring(\$string) - opens a string to write into

writeclose() - closes file/string

The following functions output to the above opened file/string

toUTL() - output current unit with children as UTL

toUTL($level) - include only children up to $level

Requirements

Input requirements

(Note that these methods are the ones of the UText API: UTL is just a parser!)

The object rises on itself events enter(), set() and leave() which are expected

to be catched by a UText class method in order to create a Universal-Text.

enter() - each time a new block { } is entered

leave() - each time the last open block is leaved

set($pm) - for each read line (not blank line, not when block to be ignored). $pm is a reference to a hash with fields found at current line. %pm = { unit=>..., role=>..., etc. }

parser() - each time a new alternate parser block [ ] is entered.

• The parser can read the source lines through $ut->readline.
• The parser can left lines unread. The UTL will ignore all lines up to the end of the parse block ].
• See Alternative Parsers for more information.

Output requirements

Class UText to read data from.