upCast Processing Language (UPL) Specification

UPL knows two kinds of escape sequences being used to allow authors to refer to characters they can't easily put in a UPL specification in specific situations. These are character escapes and unicode escapes.

First, character escapes cancel the meaning of special characters in UPL. Any character (except a hexadecimal digit) can be escaped with a backslash to remove its special meaning.

"\"" 

Secondly, unicode escapes allow authors to refer to characters they can't easily put in a UPL specification because the encoding they use (e.g. ISO-8859-1) does not provide the desired character (e.g. a chinese character). Unicode escapes consist of a backslash \ followed by a hexadecimal number (consisting of at most six hexadecimal digits (0-9, a-f, A-F)), which stands for the Unicode character at that code-point. If a hexadecimal digit follows the hexadecimal number, the end of the hexadecimal number needs to be made clear. There are two ways to do that: with a white space character or by providing exactly 6 hexadecimal digits. In fact, these two methods may be combined. Exactly one white space character is ignored after a hexadecimal escape.

"\22"

"\22 "

"\""

"\000022"

"\000022 "

The transliterated Unicode characters read from input sources are divided into lines by recognizing line terminators. This definition of lines determines the line numbers produced by the UPL processor e.g. in case of issued warning and error messages. It also specifies the termination of the end-of-line form of a comment.

There are three line terminators defined in UPL: the ASCII LF character (also known as line feed or newline, U+000A), the ASCII CR character (also known as carriage return or simply return, U+000D) and the combination of the ASCII CR character immediately followed by the ASCII LF character.

Thus, lines in UPL are terminated by the ASCII characters LF or CR or CR LF.

The input characters and line terminators that result from transliteration, escape processing and line recognition are scanned and produce a sequence of input elements. Those input elements that are not white space or comments are so-called tokens. Tokens are the terminal symbols that are used to describe how syntactically correct UPL specifications may be written.

White space and comments can serve to separate tokens that, if adjacent, might be tokenized in another manner.

White space is defined as the ASCII characters space (U+0020), horizontal tab (U+0009), form feed (U+000C), as well as the line terminators (U+000A, U+000D).

Like Java and other modern languages UPL knows two different types of comments, traditional comments and end-of-line comments. As usual in both cases the content of comments is completely discarded by a UPL processor.

A traditional comment consists of all the text from the start-marker /* up to the end-marker */.

/* stop(); /* stop execution */ */

The second supported comment type are end-of-line comments. They comprise all the text from the start-marker // up to the end of the line, designated by the next line terminator.

A UPL identifier is made from the following characters, but has to start with a letter:

Letters: a-z, A-Z, and other alphabetic characters from other languages

Digits: 0-9

Specials: - (minus) and _ (underscore)

Colon: An identifier may also contain the colon (:) character, which is used to separate a namespace prefix part from the local name part e.g. when using an identifier to designate namespaced element nodes.

Additionally, UPL identifiers may contain character and unicode escape sequences.

No identifier can have the same name as a UPL keyword, a boolean literal or the null literal.

The following character sequences are reserved for use as keywords and cannot be used as identifiers:

and
as
break
case
catch
continue
default
div
do
else
elseif
finally
for
for-each
function
goto
if
javaclass
method
mod
or
parameter
return
switch
then
try
variable
while

While true, false, void and null might appear to be keywords, they are technically literals.

A literal is the source code representation of a value of one of the data types defined in UPL.

Boolean literals

The UPL type Bool has two values, represented by the literals true and false.

String literals

A string literal consists of zero or more characters enclosed in double or single quotes (both quotes, the starting and the ending one, for a string have to be of the same kind). Each character in the string may be represented by an escape sequence.

Numeric literals

In UPL all values dealing with numbers (like integers and floats known from other programming languages) are of the same sort: Numeric. Even lengths with dimensions are of sort Numeric.

A Numeric has the following parts: a whole-number part, a decimal point (represented by a period character), a fractional part and a dimension identifier. Not all parts of a Numeric are mandatory for a numeric Literal. A Numeric representing a number may consist of any combination of the whole-number-part, the decimal point and the fractional part as long as at least one digit contributes to the literal. A Numeric literal may end with a dimension identifier, but does not have to.

The following dimension identifiers are defined in UPL: tw (twips), px (pixel), cm, mm, in, pt, pc.

A pt is 1/72 inch.

A px is 1/96 inch.

A cm is 1/2.54 inch.

Color literals

The basic color literal construct is the well known hexadecimal notation: a # immediately followed by either three or six hexadecimal digits. In a given context where a Color is expected (e.g. in an assignment or a comparison) colors may also be indentified by one of the Ids aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, orange, purple, red, silver, teal, white, and yellow (see http://www.w3.org/TR/CSS21/syndata.html#color-units).

List literals

A list literal is denoted by a {}-pair enclosing the elements of the list. The single list elements are separated by a comma ','.

Null literal

null is the literal for the value of type Null.

Void literal

void is the literal for the one single value of type Void.

The following characters are separators (punctuators) known in UPL:

(  )  {  }  [  ]  ;  ,  :

The following tokens are the operators known in UPL (ordered by precedence as specified from highest at the top to lowest at the bottom):


$i--; /* wrong! */

$i --; /* correct */

The Bool type represents a logical quantity with two possible values, indicated by the literals true and false. Besides the literals the additional constructors true() and false() are available.

The cast function to-bool() may be used to convert values of other types to Bool.

The data type Color is used to represent colors in UPL. Values for colors may either be written in the well known hexadecimal notation: a # immediately followed by either three or six hexadecimal characters. Colors may also be indentified by one of the Ids aqua, black, blue, fuchsia, gray, green, lime, maroon, navy, olive, orange, purple, red, silver, teal, white, and yellow (see http://www.w3.org/TR/CSS21/syndata.html#color-units).

The cast function to-color() may be used to convert values of selected other types to Color.

The data type Id represents either named values as used as parameters for functions (which you'll find listed with that function's documentation), or element or attribute names. An Id therefore allows using a namespace resp. the declared namespace prefix with it. The syntax for an Id is:

(nsprefix ':')? name

Both, the nsprefix and name components of an Id must be UPL identifiers with the exception that nsprefix must not contain a colon (':').

The cast function to-id() may be used to convert values of selected other classes to an Id.

The data type List is used to represent an ordered sequence of values of any type (including List itself). The syntax for a constant List is:

'{' value? (',' value)* '}'

The empty list is therefore created by writing {}.

value can be either a constant value represented by a literal, a variable reference or any other expression yielding a value result. Values are inserted with their respective type into the list. A list can be heterogenous, i.e. it can contain elements of different types at the same time. A UPL List is therefore similar to Java's ArrayList class (on which it is also based internally).

The cast function to-list() may be used to convert values of other classes to a List.

{}

{ 1, 2, 5.5 }

{ "Error: ", $code }

{ { 1, 1 }, { 2, 4 }, {3, 9 } }

{ { 1, square(1) }, { 2, square(2) }, { 3, square(3) } }

The data type Null is used to represent exceptional values or non-existing values.

@color

The data type Numeric is used to represent dimensionless or dimensioned numbers, e.g. 42, 3.1415, 2.54cm, -360tw.

They are either the result of function calls or can be created using Numeric literals.

The cast function to-numeric() may be used to convert values of selected other classes to a Numeric.

The data type String is used to represent strings in UPL. As usual, string literals are characters enclosed in double or single quotes.

The following operators are defined for the data type String: = (equals), != (not-equals), < (less than), > (greater than), <= (less than or equal to), >= (greater than or equal to), + (addition, string concatenation), * (multiplication, concatenates the string n times).

“number:” + 10 + 1 

“number:101”

“number:” + (10+1)

The cast function to-string() may be used to convert values of other classes to a String.

The data type Void is used to declare functions that do not return a value.

function hello-world() as Void {
  print( "Hello, world!" );
}

+ : addition    ⊕: concatenation

The operators <= and >= are calculated as follows, according to the matrices above:

A<=B ::= (A=B) or (A<B)

where an exception during evaluation of (A=B) is treated as false.

A>=B ::= (A=B) or (A>B)

where an exception during evaluation of (A=B) is treated as false.

The evaluation is succeed-fast, i.e. if (A=B) is true, the second operand of the or-expression is not evaluated.

The order of evaluation for the operators or and and is from left to right, and it is guaranteed that only that many operands are evaluated as necessary to determine the final result.

For xor, both operands are always evaluated, and the order of evaluation is not defined.

The if statement is the most basic of all the control flow statements. It tells your program to execute a certain section of code only if a particular test evaluates to true.

if($number = 1) 
{
  print("unicycle");
}

The if … else statement provides a secondary path of execution when the test evaluates to false.

if($number = 1) 
{
  print("unicycle");
} else {
  print("bike");
}

There is also a variant of the if … else statement that knows more than two sections of code using the elseif keyword:

if($number = 1) 
{
  print("unicycle"); 
} elseif($number = 2)
{ 
  print("bike"); 
} else { 
  print("trike"); 
}

The while statement continually executes a block of statements while a particular condition is true.

while( $number > 0 ) 
{ 
  $number := $number - 1; 
}

while( true() ) {
  /* place your code here */ 
}

UPL also includes a do … while statement.

do { 
  $number := $number - 1; 
} while( $number > 0 );

The difference between do … while and while is that do … while evaluates its expression at the bottom of the loop instead of the top. Therefore, the statements within the do block are always executed at least once.

The for statement provides a compact way to iterate over a range of values. Programmers often refer to it as the "for loop" because of the way in which it repeatedly loops until a particular condition is satisfied. The general form of the for statement can be expressed as follows:

for (initialization; termination; post-iteration) {
  /* your code goes here */
}

When using this version of the for statement, keep in mind that:

variable $number as Numeric;
for( $number := 0 ; $number < 5 ; $number++ ) 
{ 
  /* place your code here */ 
}

The three expressions of the for loop are optional. An infinite loop can be created as follows:

for ( ; ; ) {
  /* your code goes here */ 
}

The for-each statement provides a compact way to iterate over all the items contained in a list.

variable $number as Numeric;
for-each( $number in {1,4,5} )
{
  print($number); 
}

A break statement terminates the innermost while, do … while, for or for-each statement.

for-each( $number in {1,4,5} ) 
{
  if($number = 4) 
  { break; }
}

The return statement exits from the current function or method and control flow returns to where the function/method was invoked. The return statement has two forms: one that returns a value, and one that doesn't. To return a value, simply put the value (or an expression that calculates the value) after the return keyword.

return $number;

The data type of the returned value must match the type of the function's declared return value. For methods, use the form of return that doesn't return a value:

return;

A variable is defined as follows:

'variable' varname 'as' type ( ':=' init-expression )? ';'

For varname, you can use any valid variable name, e.g. $counter or $i.

For type, any UPL type (except Void) is allowed, including the generic Value type which allows storing any of the specific types in the variable.

For the optional initialization part, init-expression can be any expression that evaluates to a value whose type is the same as the declared type for the variable.

variable $s as String := "";

To refer to the contents of a variable, you simply write the variable's name, e.g.:

print( $s );

To assign a new value to a variable, you use

varname ':=' expression ';'

$s := "Hello world!";

A parameter is defined as follows:

'parameter' parname 'as' type ( 'default' default-expression )? ';'

For parname, you can use any valid variable name, e.g. $mode or $p.

For type, any UPL type (except Void) is allowed, including the generic Value type which allows storing any of the specific types in the variable. It is up to the implementation how parameter values of a specific type are created.

For the optional default part, default-expression can be any expression that evaluates to a value whose type is the same as the declared type for the parameter. Note that the default-expression is only relevant (and used) in the case where the surrounding environment does not provide a value for that specific parameter at all. In all other cases, the supplied value is used instead of the default-expression's value.

To refer to the contents of a parameter, you simply write the parameter's name, e.g.:

print( $mode );

A function definition takes the following form:

'function' funcname '(' ( param 'as' type )? (',' param 'as' type )* ')' 'as' restype '{' body '}'

with

function hello( $name as String ) as String {
  variable $result as String := "Hello ";
  if( $name = "" ) {
    $result := $result + "you!";
  } else {
    $result := $result + $name + "!";
  }
  return $result;
}

function greeting( $name as String ) as Void {
  print( "Hello " + $name );
}

To call a built-in or user-defined function, use:

name '(' param? (',' param)* ')'

greeting( "Christian" );        /* prints "Hello Christian" on the console */
log( INFO, hello( "Steven" ) ); /* writes "Hello Steven!" to the logfile */
print( hello( "" ) );           /* prints "Hello you!" on the console */
$res := hello( 5 );             /* throws a TypeConversionException: parameter type does not match */

Function definitions are looked up based on the actual types of parameters used in the call at the time of the call. As a consequence, when the actual types do not exactly match one of the available function definitions, UPL throws a TypeConversionException (which can be caught in a try … catch construct).

You can overload functions of the same name by specifying different signatures.

You cannot overload a function on its return type only.

A Java function binding takes the following form:

'javafunction' prefix:funcname '(' ( param 'as' type )? (',' param 'as' type )* ')' 'as' restype ';'

with

To call a bound Java function, use:

prefix:funcname '(' param? (',' param)* ')'

package com.example;
import de.infinityloop.upcast.upl.val.UPLString;

public class StringReverser {
  public static UPLString reverse( UPLString source ) {
    return new UPLString( new StringBuffer( source.getAsString() ).reverse().toString() );    }
}

#namespace sr "java:com.example.StringReverser";
javafunction sr:reverse( $source as String ) as String;

...
println( sr:reverse("never odd or even") ); // a palindrome :-)
...

neve ro ddo reven

This directive allows you to declare the encoding (or character set) used for the following UPL program (including the #charset directive). The use of the #charset directive has the same requirements as the @charset rule defined in CSS2.1. We therefore just include the relevant parts of section 4.4 of the Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification by reference, the only difference being that in UPL, the directive is #charset (with a hash at the beginning) instead of @charset.

The generic #set directive allows setting options for processing the UPL program at hand in a certain way. The syntax for the #set directive is as follows:

'#set' option ':=' value ';'

with:

The following options are available (default value when not specified printed in bold):

#set IDAttributes := "figure/@figid @elemid";

The #include directive allows including UPL code verbatim from external files. The result of an #include directive is exactly the same as if itself was replaced by the contents of the included file.

The syntax of the #include directive is as follows:

'#include(' 'source:' srcfile ('encoding:' encodingname)? ('encrypted:' cryptkey)? ');'

with

#include( source:"file:///C:/functions.upl" encoding:"UTF-8" );

To be able to use namespace prefixes in identifiers, you need to bind them to their respective namespace name. This is accomplished usind the #namespace directive, which declares namespaces and their prefixes for use in UPL:

'#namespace' nsprefix '"' nsname '";'

with

#namespace uci "http://www.infinity-loop.de/namespace/2006/upcast-internal";
#namespace css "http://www.infinity-loop.de/namespace/2006/upcast-css";
#namespace cssc "http://www.infinity-loop.de/namespace/2006/upcast-cssclass";
#namespace csso "http://www.infinity-loop.de/namespace/2006/upcast-cssoverride";

#namespace application "http://www.infinity-loop.de/namespace/upcast-realm/application";
#namespace environment "http://www.infinity-loop.de/namespace/upcast-realm/environment";
#namespace pipeline "http://www.infinity-loop.de/namespace/upcast-realm/pipeline";
#namespace module "http://www.infinity-loop.de/namespace/upcast-realm/module";
#namespace javaproperty "http://www.infinity-loop.de/namespace/upcast-realm/javaproperty";

A UPL Tree Processor program can contain any constructs of UPL Core.

A UPL Tree Processor program typically also contains rules. Rules are a pair consisting of a selector and an action block. The selector specifies a condition the context node must satisfy before the actions specified in the action block are applied to it.

The syntax for a rule is

(label ':')? selectorlist actionblock

where selectorlist is a list of selectors separated by a comma (',')and actionblock is an action block.

[element(heading) and exists(@level)]
{
  print( @level );
}

[element(inline) and string()=''],
[element(span) and string()="empty"]
{
  set-attr( delete, true );
}

('[' expression ']')+

'{' statements '}'

If the UPL Tree Processor program defines a function of the signature

function initialize() as Value

then it is run.

If the function returns the Numeric zero (0), the next step in the processing model is executed, i.e. the tree traversal is started.

If the function returns a non-zero Numeric value, UPL Tree Processor execution is aborted and the following steps are not executed.

Next, the document tree is traversed in a depth-first traversal. The document tree is the internal upCast document tree. It is usually constructed in an earlier running importer module like the RTF Importer or the XML Importer.

The starting node of the traversal is the Document node, which is then the first context node. The context node changes during the tree traversal. Many pre-defined functions require that context node to be defined to be useful.

For the context node, the set of rules defined in the UPL Tree Processor program are considered in the same order as they are written (=defined), from top to bottom. The first rule for which the selector expression yields true on the context node is chosen and the action block is executed.

This process continues until all nodes have been visited.

After the tree traversal has finished without any errors, and if it is defined, the UPL Tree Processor tries to call the function

function finalize() as Value

The result of this function is set as the upCast UPL Tree Processor module's result value in the pipeline variable ModuleResult.

If errors occurred during UPL Tree Processor execution, however, it will try to call the function

function error-finalize() as Value

instead. The result of this function is set as the upCast UPL Tree Processor module's result value in the pipeline variable ModuleResult.

to-bool(value as Value) as Bool

Casts its argument to a Bool value.

The boolean value of a Bool is its own value.

The boolean value of a Color is always true.

The boolean value of an Id is true if the identifier length is greater zero (0), false otherwise.

The boolean value of a List is true only if it has at least one item and if all of its items cast to Bool are true.

The boolean value of a Null is false.

The boolean value of a Numeric is false if it is zero (0), true otherwise.

The boolean value of a String is true if its length is greater zero (0), false otherwise.

to-bool( "test" )

to-bool( { "abc", 0 } )

to-color(value as Value) as Color

Casts its argument to a Color value. The argument must be a valid CSS 2.1 color value string. Additionally, rgba() from the CSS 3 Color Module is supported.

The Color value of an Id is its value parsed to a color as described above.

The Color value of a String is its value parsed to a color as described above.

If a value cannot be parsed into a color as described above, a TypeConversionException is thrown.

Trying to cast Bool, List, Numeric or Null to a Color throws a TypeConversionException.

to-color( red )

to-color( "#F00" )

to-color( "#ff0000" )

to-color( "rgb(255,0,0)" )

to-color( "rgb(100%,0%,0%)" )

to-color( "rgba(255,0,0, 1.0)" )

to-id(value as Value) as Id

Casts its argument to an Id value.

The Id value of an Id is its own value.

The Id value of a String is its contents.

Trying to cast a Bool, Color, List, Numeric or Null to an Id throws a TypeConversionException.

to-id( "uci:par" )

to-list(value as Value) as List

Casts its argument to a List value.

The list value of a List is itself.

The list value of a Numeric, Color, Id, List, String and Null is a one-element list with value as its element.

to-null(value as Value) as Null

Casts its argument to a Null value, i.e. it effectively returns the Null value null always.

to-numeric(value as Value) as Numeric

Casts its argument to a Numeric value.

The numeric value of a Bool is 1 (if it is true), or 0 (if it is false).

The numeric value of a Numeric is itself.

The numeric value of a String is its value parsed as a decimal number (either with or without a dimension specification). If the value cannot be parsed, a TypeConversionException is thrown.

For Color, Id, List and Null a TypeConversionException is thrown.

to-string(value as Value) as String

Casts its argument to a String value.

The string value of a Bool is "true" or "false", respectively.

The string value of a Color is the hex notation of the represented color as defined in HTML, format: #rrggbb

The string value of an Id is its value.

The string value of a List is the concatenation of its member elements cast to String, with U+0020 (space character) as a separator added between two individual values.

The string value of a Numeric is its human readable representation.

The string value of a String is itself.

Trying to cast Null to a String throws an TypeConversionException.

to-string( 5 )

to-string( { "ab", 2, someId } )

get-color-component(color as Color, component as Id) as Numeric

Returns an individual color component value of the Color value passed as argument color. The component to return is determined by the component parameter, which can take the Id values RED, GREEN, BLUE and ALPHA.

The Numeric value returned is between 0 and 255 for the components RED, GREEN and BLUE, and between 0.0 (=fully transparent) and 1.0 (opaque) for ALPHA.

get-color-component( to-color( red ), RED )

get-color-component( to-color( red ), ALPHA )

get-color-component( to-color( "#123456" ), GREEN )

current-dateTime() as String

Returns the current date and time in form of an ISO date string.

current-dateTime()

"2008-07-31T23:49:22.599Z"

format-dateTime(dateTime as String, format as String) as String

This retuns a formatted ISO date string. dateTime must be an ISO date and time string. format is a formatting string for the individual components in the passed ISO date string.

The formatting options are the same as for the Java class java.text.SimpleDateFormat – please see there for details.

format-dateTime( "2008-07-31T23:44:20.923Z", "h:mm a")

"11:44 PM"

add-to-zipfile(zipfile as String, pathPrefix as String, fileOrFolder as String) as Void

This function lets you add files or complete folders to an existing ZIP file.

The parameter zipfile specifies the absolute path of the ZIP file to add files or folders to.

pathPrefix specifies a path prefix to use within the ZIP file for the added content.

fileOrFolder specifies the file or folder (including all of its contents) to be added to the ZIP file.

The ZIP file must already exist. To create a new, empty ZIP file, use create-zipfile() .

add-to-zipfile( "/dist/files.zip", "input", "/data/in/sample.xml" );

copy-file(fromFile as String, toFile as String) as Bool

This method copies the file fromFile to the file toFile. Returns true when the copy was successful, false otherwise. The paths need to be absolute, but can be specified either using URL notation (preferred for platform independence) or in local file system naming convention.

create-zipfile(zipfile as String) as Void

This function creates a new, empty ZIP with name and location as specified by the absolute path in zipfile. If that file already exists, it is overwritten.

You can add files to a ZIP file using add-to-zipfile() .

delete-file(filepath as String) as Bool

Deletes the file with absolute path filepath.

file-exists(file as String) as Bool

This method checks whether the specified file exists in the local file system. The path must be absolute, but can be specified either using URL notation (preferred for platform independence) or in local file system naming convention.

fs-copy(mode as Id, src as String, dest as String) as Bool

This function lets you copy file system objects (files or complete folders). You can choose from several modes specifying how the copy operation should be performed and how the passed absolute paths src and dest are to be interpreted.

fs-copy( FILE-TO-FILE, "/usr/dev/draft.rtf", "/usr/project/final.rtf" );

fs-copy( FILE-TO-FOLDER, "/usr/dev/manual.rtf", "/usr/dist/doc/" );

fs-copy( FOLDER-TO-FOLDER, "/usr/dev/doc", "/usr/dist" );

fs-copy( CONTENTS-TO-FOLDER, "/usr/dev/doc", "/usr/dist/documentation" );

fs-create(type as Id, abspath as String) as Bool

This function lets you create a new file system object, i.e. a new empty file or a folder.

Parameter type specifies what to create using which semantics:

fs-delete(mode as Id, fsobject as String) as Bool

This function deletes a file system object (file or complete folder). You can choose from several modes specifying how the deletion operation should be performed and how the passed absolute path fsobject is to be interpreted.

fs-delete( SELF, "/usr/dev/draft.rtf" );

fs-delete( SELF, "/usr/dist/doc/" );

fs-delete( CONTENTS, "/usr/dev/doc/" );

fs-move(mode as Id, src as String, dest as String) as Bool

This function lets you move file system objects (files or complete folders) from one location to another. You can choose from several modes specifying how the move operation should be performed and how the passed absolute paths src and dest are to be interpreted.

fs-move( FILE-TO-FILE, "/usr/dev/draft.rtf", "/usr/project/final.rtf" );

fs-move( FILE-TO-FOLDER, "/usr/dev/manual.rtf", "/usr/dist/doc/" );

fs-move( FOLDER-TO-FOLDER, "/usr/dev/doc", "/usr/dist" );

fs-move( CONTENTS-TO-FOLDER, "/usr/dev/doc", "/usr/dist/documentation" );

get-path-component(path as String, component as Id) as String

This method can extract a certain component of a file path. The component can be one of:

LOCAL return the value of the variable in local file system format

URL return the value of the variable in URL format

LOCALPATH return only the path component (without filename and without trailing file separator) of the value of the variable. If the variable is a folder, the value is returned unchanged.

URLPATH same as localpath, but returns the value in URL format

LOCALNAME returns only the file name component of the variable value in local format

URLNAME same as localname, but returns the value in URL format

LOCALEXTENSION returns the file extension of the variable value in local format or the empty string, if it hasn't an extension

URLEXTENSION same as localextension, but returns the value in URL format

LOCALBASENAME returns the same value as localname, but with trailing dot and extension stripped if it exists

URLBASENAME same as localbasename, but returns value in URL format

LOCALBASENAMEPATH essentially, this is localpath + localbasename, i.e. the value of the variable minus extension (including trailing dot)

URLBASENAMEPATH same as localbasenamepath, but returns value in URL format

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, LOCAL )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, URL )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, LOCALPATH )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, URLPATH )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, LOCALNAME )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, URLNAME )

get-path-component( “C:\Documents and Settings\upCast\The file.x m l”, LOCALEXTENSION )

get-path-component( “C:\Documents and Settings\upCast\The file.x m l”, URLEXTENSION )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, LOCALBASENAME )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, URLBASENAME )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, LOCALBASENAMEPATH )

get-path-component( “C:\Documents and Settings\upCast\The file.xml”, URLBASENAMEPATH )

is-file(path as String) as Bool

Tests if the object found under the specified path is a file. The object must exist for the result to be correct.

is-filetype(type as Id, file as String) as Bool

Returns whether file is of the specified type or not. This function looks into the file's content for making the best possible decision, i.e. it does not rely on the file extension.

When file does not exist, false is returned.

When an unsupported type is specified, an exception is thrown.

The following values for type are supported:

is-filetype( DOC, "/test/somefile.ext" )

is-folder(path as String) as Bool

Tests if the object found under the specified path is a folder. The object must exist for the result to be correct.

list-files(baseDir as String) as List

This method generates a list of all flat files (i.e., only the direct file children, no directories, only files that are visible) within baseDir in the file system hierarchy.

Each list element contains the absolute path to a found file as an URL string (file protocol).

list-files(baseDir as String, flags as Id) as List

This method generates a list of all file system objects (i.e., only direct children) within baseDir in the file system hierarchy.

Each list element contains the absolute path to a found file system object as an URL string (file protocol).

You must specify the search algorithm using the additional flags parameter by concatenating the desired flags to an Id (in any order):

list-files( "/Users/test/", HF );

list-files( "/Users/test/", D );

list-files( "/Users/test/", FDH );

list-files-recursively(baseDir as String) as List

This method generates a list of all visible flat files that are descendants of baseDir in the file system hierarchy.

Each list element contains the absolute path to a found file as an URL string (file protocol). Invisible files or folders are neither included in the list nor traversed.

list-files-recursively(baseDir as String, flags as Id) as List

This method generates a list of all file system objects that are descendants of baseDir in the file system hierarchy.

Each list element contains the absolute path to a found file system object as an URL string (file protocol).

You must specify the search algorithm using the additional flags parameter by concatenating the desired flags to an Id (in any order):

list-files-recursively( "/Users/test/", HF );

list-files( "/Users/test/", D );

list-files( "/Users/test/", FDH );

move-file(src as String, dest as String) as Bool

Moves the file src to a new location dest. This can be used to do both, actually move a file to some other location or just rename it.

write(filename as String, encoding as String, mode as Id, data as String) as Void

This method allows you to write its data argument to the specified file with name filename. You can set the encoding to be used (e.g. "UTF-8"), and set the writing mode to either replace the existing content in that file (WRITE) or get appended at the end (APPEND).

writeln(filename as String, encoding as String, mode as Id, data as String) as Void

This method allows you to write its data argument to the specified file with name filename. The platform-specific line separator code sequence is automatically appended.

You can set the encoding to be used (e.g. "UTF-8"), and set the writing mode to either replace the existing content in that file (WRITE) or get appended at the end (APPEND).

is-painted(paintColor as Id) as Bool

Returns true when the context node is painted with the specified paintColor.

mark-end(paintColor as Id) as Void

This function places an end marker of the specified paintColor on the context node.

For details, see the section on Painters in the upCast Manual.

mark-end( address );

mark-start(paintColor as Id) as Void

This function places a start marker of the specified paintColor on the context node.

For details, see the section on Painters in the upCast Manual.

mark-start( address );

paint-adjacent(paintColor as Id, siblingCount as Numeric) as Numeric

This function paints the context node and (siblingCount – 1) following sibling nodes with the specified paintColor.

This function places a start marker of the specified paintColor on the context node, and an end marker of the specified paintColor on the last node that was painted.

The function returns the number of nodes actually painted (which may be smaller than siblingCount when there are less sibling nodes).

For details, see the section on Painters in the upCast Manual.

paint-adjacent( address, 2 );

paint-following(paintColor as Id, condition as BoolExpression, endMode as Id) as Numeric

This function paints all contiguously following siblings of the context node with the specified paintColor for which condition matches or until the end of the following-sibling axis of the context node is reached.

endMode can have the following values:

The method returns the number of nodes that were painted.

For details, see the section on Painters in the upCast Manual.

paint-following( address, @css:font-family="Times", END );

paint-preceding(paintColor as Id, condition as BoolExpression, endMode as Id) as Numeric

This function paints all contiguously preceding siblings of the context node with the specified paintColor for which condition matches or until the end of the preceding-sibling axis of the context node is reached.

endMode can have the following values:

The method returns the number of nodes that were painted.

For details, see the section on Painters in the upCast Manual.

paint-preceding( address, @uci:class="addr", START );

set-paint-attr(paintColor as Id, attrQName as Id, attrValue as String) as Void

This method lets you set an attribute (with qualified name attrQName) with associated value attrValue on the context node that will be promoted to the immediate grouping parent of the context node during grouping (if that exists) for the specified paintColor.

During grouping of a sequence of nodes, the attrValue (among all attributes of the same attrQName) of the node that last (in document order) specifies a value for it is used for the value of that attribute on the grouping element.

Paint attributes, though set on the grouped nodes, will not be serialized on the individual nodes, only on the created grouping element.

set-paint-attr( address, uci:language, @xml:lang );

<uci:block uci:type="address" uci:language="en">
   ...
</uci:block>

set-paint-value(paintColor as Id, name as Id, value as Value) as Void

This method lets you set an UPL value (with name name) with associated value value on the context node that will be promoted to the immediate grouping parent of the context node during grouping (if that exists) for the specified paintColor.

During grouping of a sequence of nodes, the value (among all values of the same name) of the node that last (in document order) specifies a value for it is used for the value of that UPL value on the grouping element.

Paint values are never serialized. They can be queried in subsequent UPL module runs on the grouping elements that have been created in the internal document tree using the get-value() function.

set-paint-value( address, cdata, string() );

set-painter(paintColor as Id, painterTypes as List) as Void

This function lets you set a painter of specified paintColor and painterTypes on the context node.

paintColor is the value which will be used as the type attribute value of the grouping element created by a subsequent Grouper module. When you set a qualified name, the resulting value will be its expanded name.

painterTypes is an ordered (from start to end) list of painter types and fallback painter types to be used if a painter fails.

This method does not actually paint any nodes, unless painterTypes also contains the type "this", in which case the context node is immediately painted.

For details, see the section on Painters in the upCast Manual.

set-painter( address, { "start-end", "this" } );

set-progress(curval as Numeric, maxval as Numeric) as Void

Lets you set progress information for the currently running (UPL-) module. The current state is defined as the current progress value curval compared to the maximum progress value maxval.

set-progress( 4.0, 8.0 );

set-ui-text(elementId as Id, labeltext as String) as Void

This method lets you set the text in various components of upCast's user interface. The text is updated immediately in the UI, so you can e.g. provide the user with more detailed progress information while a lengthy UPL code sequence is taking place.

You specify the element for which you want to set the text using a symbolic constant in elementId, and the text is passed in the labeltext parameter.

The following symbolic constants are available:

function initialize() as Numeric {
  set-ui-text( PROGRESS-SUBLABEL, "Initializing UPL...");
}

show-dialog(dialogType as Id, windowTitle as String, dialogText as String, buttonDescription as String) as Numeric

This function displays a customizable dialog with up to three buttons.

The dialogType determines the overall style of the dialog:

You can specify the dialog window's title in the parameter windowTitle.

The body text of the dialog is passed in the dialogText parameter.

Finally, the buttonDescription parameter takes a specially formatted string specifying the button(s) you want to be displayed, and which one should be the default button. The syntax is as follows:

buttonDescription ::= button ('|' button){0,2}
           button ::= [*]?[^|]+

In other words, button text specifications are separated by the pipe character '|', and you specify the default button by prefixing it with an asterisk '*'. The maximum number of buttons is 3. Note that buttons are specified in a virtual OK, Cancel, Alternative order, which means that depending on the OS you are running on, the displayed order of the buttons may vary from the specification order.

The function returns the number of the button clicked, with closing the dialog by its window decoration (instead of one of its buttons) returns the value 1.

The show-dialog() function will only work when running in a GUI environment. When running in commandline or API mode where there is no GUI available, the function immediately returns the value (-1).

Example 5.26. 

show-dialog( WARNING, "Warning Dialog", "This is a warning dialog.", "OK|*Cancel|Abort");

will display the following dialog when running in GUI mode:

resulting dialog

append(list as List, element as any) as List

Appends the value in element to the List list so that it becomes the new last element.

The function returns the value passed in list, which is the List modified as described.

append-all(list as List, appendList as List) as List

Appends all elements in appendList to the List list so that they become the new last elements. The elements are appended in the order they are stored in appendList.

The function returns the value passed in list, which is the List modified as described.

count(list as List) as Numeric

Returns the number of elements in list.

flatten(source as List) as List

Returns a List where all items in source of type List have been (recursively) flattened.

A List that has one or more Lists as its members is considered flattened when all its items of type List have been replaced by the individual elements in order of that List, possibly recursively. The result is a List that does no longer contain any elements of type List. This is best shown with an

flatten( { a, { b1, b2 }, c } )

flatten( { a, { b1, { b2i, b2ii }, b3 }, c, { d1, d2 } } )

flatten( { a, b, c } )

index-of(list as List, value as any) as Numeric

Returns the index within list of the first occurrence of value. If value is not a member of list, -1 is returned.

is-in(searchString as String, listValue as List) as Bool

Determines if the List list contains an element that, after having been cast to a String as if applying the to-string() function, is equal to the string searchString.

remove(list as List, index as Numeric) as List

Removes the element with index index from the List list.

The function returns the value passed in list, which is the List modified as described.

value-at(list as List, index as Numeric) as Value

Extracts the value at position index of the passed list. The index is 1-based, i.e. the first element has index 1, the second has index 2 etc.

If the requested index position does not exist, the Null value is returned.

clear-log-messages(logRealm as Id) as Void

This functions clears the internally collected log messages. With the logRealm parameter, you decide which log event collector to clear. This can be one of:

Possible values are:

This function can be useful if you want to periodically clear collected log messages you no longer need in long-running or looping pipelines to prevent excessive or indefinitely increasing memory usage.

forward-log-message(level as Id, messagecode as Numeric, logmessage as Value, ...) as Void

This method lets you create a new custom log message and place it into the logical parent component (module or pipeline) of the current component (module or pipeline).

If the logical parent is the application (in other words: if called from the top-level pipeline component), this method does nothing.

In level, you specify the log message level you want to set for that message. This can be any of the following levels: FATAL, ERROR, WARN, INFO, DEBUG, VERBOSE, DETAIL.

messagecode lets you specify a custom message code. You can use this to find your own specific messages in a logger later using the get-log-messages() function by specifying the respective codes in its includeCodes list.

Finally, you can add an arbitrary list of Value objects to be output as the logmessage.

forward-log-message( WARN, 5, "The value ", $number, " is not equal to 5." );

forward-log-messages(levels as List, includeCodes as List, excludeCodes as List) as Numeric

Currently, there is no documentation available for this function.

get-log-messages(name as Id, levels as List, includeCodes as List, excludeCodes as List) as List

This method lets you retrieve a (possibly) filtered list of log messages for the currently running module, the whole worfklow or a custom logger created with start-logger(). The result is a list of two-element lists as described below.

The name parameter specifies the logger from which to retrieve the log messages. Possible values are:

With levels, you specify the list of log message levels you are interested in. This can be any of the following levels: FATAL, ERROR, WARN, INFO, DEBUG, VERBOSE, DETAIL. If the list is the empty list, all types are considered.

Each log message has a numerical code, which is defined in the class de.infinityloop.msg.Msg. With includeCodes, you can specify the list of numerical codes or symbolic names (ids) that should be included in the result. With excludeCodes, you can specify the list of numerical codes or symbolic names (ids) that should be excluded from the result. In both cases, when the list is the empty list, no respective filtering is applied.

The algorithm (=order) in which the described filters are applied is as follows:

The resulting set of log messages after step 3 is the final result set of size N and used for building the result of the function, which is a list of two-element lists as follows:

{
  { message-level1 as String, message-text1 as String }
  { message-level2 as String, message-text2 as String }
    ...
  { message-levelN as String, message-textN as String }
}

get-log-messages( MODULE, {ERROR, WARN}, {}, { -12, -14});

get-log-messages( PIPELINE, {WARN}, {-2, -3, -5}, {});

get-log-messages( sub, {}, {}, {});

log(level as Id, message as Value, ...) as Void

Outputs the specified message via upCast's logging system. The type of log entry to be generated can be set using the level parameter, which can take the values DETAIL, VERBOSE, DEBUG, INFO, WARN, ERROR or FATAL.

log-custom(name as Id, level as Id, messagecode as Numeric, logmessage as Value, ...) as Void

This method lets you add your own, attributed log messages to a pre-defined or custom logger.

name designates the logger to add the message to. Possible values are:

In level, you specify the log message level you want to set for that message. This can be any of the following levels: FATAL, ERROR, WARN, INFO, DEBUG, VERBOSE, DETAIL.

messagecode lets you specify a custom message code. You can use this to find your own specific messages in a logger later using the get-log-messages() function by specifying the respective codes in its includeCodes list.

Finally, you can add an arbitrary list of Value objects to be output as the logmessage.

log-custom( sub, WARN, 5, "The value ", $number, " is not equal to 5." );

start-logger(name as Id, level as Id) as Void

This method starts a custom logger with name name at the current code nesting level, accepting log messages of the specified level and higher-level messages.

If the named custom logger does already exist, it is not cleared, but newly generated log messages are appended if they satisfy the – possibly changed in comparison to the one specified at its creation – level condition. You can also use this to resume collecting log events in this logger after a call to stop-logger().

The following logger names are not allowed (in any combination of uppercase and lowercase characters), since they designate loggers pre-defined by upCast: PIPELINE, MODULE

stop-logger(name as Id) as Void

This method stops adding log messages to the custom logger of name name name. Logging to this logger can be resumed by calling start-logger() again.

exists(value as any) as Bool

Returns true when the passed value is not Null.

exists-var(varname as Id) as Bool

Returns true when an in-scope UPL variable with the same name as the Id passed in varname exists.

If (and only if) the namespace of the Id is one of the variable realm namespaces, this returns true when a realm variable of the same name as varname exists. When this function returns true, $varname and get-var( varname ) will not fail, although the returned value could still be of type Null when the respective realm variable's value is null.

See: get-var()

false() as Bool

Returns a Bool with value false.

is-null(value as any) as Bool

Returns true when the passed value is Null.

not(value as Bool) as Bool

Returns the negated value of the passed Bool value.

true() as Bool

Returns a Bool with value true.

attach-value(key as Id, value as Value) as Void

This method lets you attach an UPL value (with name key) and associated value value to the context node. This value can be queried using the get-value() function.

The function returns always true.

However, attached values are never serialized to XML.

attach-value(target as String, ..., key as Id, value as Value) as Void

This method lets you attach an UPL value (with name key) and associated value value to all nodes selected by the target XPath 1.0 expression (evaluated relative from the context node). This value can later be queried using the get-value() function.

The function returns true when the target expression selects at least one target node, false otherwise.

#namespace uci "http://www.infinity-loop.de/namespace/2006/upcast-internal";

[element(uci:par) and @uci:heading-level > 0] {
  attach-value( "descendant::text()", heading-text, true() );
}

comment() as Bool

Tests whether the context node is a Comment node.

delete() as Void

This function deletes the context node (including all of its children) from the internal document tree.

detach-values(valNamePatt as Id) as Bool

Removes a named single attached value or a number of values matching a pattern from the context node. The value name or pattern can be specified in valNamePatt.

When valNamePatt is a qualified name, that value is removed.

When valNamePatt is nsprefix:* , all values in the specified namespace with prefix nsprefix are removed.

When valNamePatt is *:key, all values with the local name key are removed from the node, regardless of the namespace they might be in. This does not include the null namespace!

When valNamePatt is :*, all values are removed from the context node that are in the null namespace.

The method returns a List of IDs representing the qualified names of all values that were actually removed from the context node.

To remove all values from the context node, regardless of name and/or namespace, use the function detach-values().

If valNamePatt does not exist or does not match any value present on the context node, the method does nothing.

detach-values() as Bool

This method removes all attached valuea from the context node.

The method returns a List of Ids representing the qualified names of all values that were actually removed from the context node.

element() as Bool

Tests whether the context node is an element.

element(qname as Id) as Bool

Tests whether the context node has the same namespace and local name as the passed qualified name.

filter-attrs(filterSpec as List) as Void

This function should only be used in an XML Exporter's attribute filter program. This method lets you filter attributes by name or pattern from an element before it is serialized to a file or character stream. Since upCast internally produces a huge number of attributes (mostly by exploding CSS style properties into real attributes), the result can get unmanageable large. Mostly, however, you are actually only interested in a small set of attributes for further processing, and this function helps you specify which attributes to keep in the serialized XML tree and which to discard.

The filterSpec is a List of two-element Lists. Each two-element List consists of two bits of info:

The second element supports the following patterns:

Each attribute present on the context node is filtered against the list of inclusion/exclusion patterns. The matching is done in order of listing.

The workings of this function are best described with an example:

filter-attrs(
  {
    { EXCLUDE, "*" }, // "only include..." means we start with nothing, i.e. exclude all
    { INCLUDE, uci:* }, // "...all attributes in the uci namespace..."
    { EXCLUDE, uci:fullStyle }, // "...except for uci:fullStyle..."
    { EXCLUDE, uci:diffStyle } // "...and uci:diffStyle."
  } );

get-attr(attrName as Id) as String

Gets the value of the attribute attrName on the context node. When the attribute does not exist or the context node is not an element, a Null value is returned.

This method backs the shortcut @attrName in UPL Core.

@uci:class

get-attr( uci:class )

get-value(key as Id) as Value

This method retrieves any value with name key from the context node that was previously set on that node using the attach-value() function.

If such a value does not exist on the context node, the method returns Null.

insert-nodes(mode as Id, xmlsource as String) as Bool

This function inserts the parsed XML xmlsource document fragment in accordance with the specified mode relative from the context node.

The mode parameter can have the following values:

Since xmlsource is parsed before being inserted into the document tree, it must be well-formed.

Any namespaces and prefixes used in the xmlsource string must be declared and in-scope in the UPL program at the calling position of the function.

The function returns true when the target expression selects at least one target node, false otherwise.

#namespace uci "http://www.infinity-loop.de/namespace/2006/upcast-internal";

[element(uci:item)] {
  insert-nodes( BEFORE, "<uci:marker>" + @uci:numberingtext + "</uci:marker>" );
}

…
<uci:item uci:numberingtext="(a)">Item a</uci:item>
<uci:item uci:numberingtext="(b)">Item a</uci:item>
…

…
<uci:marker>(a)</uci:marker><uci:item uci:numberingtext="(a)">Item a</uci:item>
<uci:marker>(b)</uci:marker><uci:item uci:numberingtext="(b)">Item a</uci:item>
…

insert-nodes(target as String, mode as Id, xmlsource as String) as Bool

This function inserts the parsed XML xmlsource document fragment in accordance with the specified mode relative from each of the target nodes selected by the target XPath 1.0 expression.

The mode parameter can have the following values:

Since xmlsource is parsed before being inserted into the document tree, it must be well-formed.

Any namespaces and prefixes used in the xmlsource string must be declared and in-scope in the UPL program at the calling position of the function.

The function returns true when the target expression selects at least one target node, false otherwise.

#namespace uci "http://www.infinity-loop.de/namespace/2006/upcast-internal";

[element(uci:par)] {
  insert-nodes( "descendant::uci:inline", BEFORE, "<uci:start/>" );
  insert-nodes( "descendant::uci:inline", AFTER, "<uci:end/>" );
}

<uci:par>This is 
  <uci:inline csso:font-weight="bold">bold and 
    <uci:inline csso:font-style="italic">bold-italic</uci:inline>
  </uci:inline> text.</uci:par>

<uci:par>This is 
  <uci:start/><uci:inline csso:font-weight="bold">bold and 
    <uci:start/><uci:inline csso:font-style="italic">bold-italic</uci:inline></uci:end/>
  </uci:inline><uci:end/> text.</uci:par>

mark-split(where as Id, condition as BoolExpression, mode as Id) as Void

This function puts a split marker onto the context node which indicates various properties of a tree splitting action to be performed after the tree traversal of this UPL Tree Processor run.

The parameter where indicates where in relation to the context node the split should be performed:

The parameter condition identifies the point up to which node in the ancestor chain the tree should be split. That node is identified as the first node in the ancestor axis (starting from the context node) for which the specified condition evaluates to true.

The mode parameter determines how the node identified by the condition expression is to be interpreted:

<document>
  <par>ABC<br/>DEF.</par>
  <par>AB<span class="a">C<br/>D</span>EF.</par>
  <par>AB<i class="b"><br/>C</i>DEF.</par>
  <par>AB<em class="c">C<br/></em>DEF.</par>
</document>

[element(br)] {
  mark-split( AFTER, element(span) or element(par), SPLIT );
}

1  <document>
2    <par>ABC<br/></par><par>DEF.</par>
3    <par>AB<span class="a">C<br/></span><span class="a">D</span>EF.</par>
4    <par>AB<i class="b"><br/></i></par><par><i class="b">C</i>DEF.</par>
5    <par>AB<em class="c">C<br/></em></par><par>DEF.</par>
6  </document>

name() as String

Returns the qualified name of the context node.

processing-instruction() as Bool

Tests whether the context node is a Processing Instruction node.

remove-attrs(attrNamePattern as Id) as List

Removes a named single attribute or a number of attributes matching a pattern from the context node. The attribute name or pattern can be specified in attrNamePatt.

When attrNamePatt is a qualified attribute name, that attribute is removed.

When attrNamePatt is nsprefix:* , all attributes in the specified namespace with prefix nsprefix are removed.

When attrNamePatt is *:attname, all attributes with the local name attname are removed from the node, regardless of the namespace they might be in. This does not include the null namespace!

When attrNamePatt is :*, all attributes are removed from the context node that are in the null namespace.

The method returns a List of Ids representing the qualified names of all attributes that were actually removed from the context node.

If attrNamePatt does not exist or does not match any value present on the context node, the method does nothing.

To remove all attributes, regardless of name and/or namespace, use the function remove-attrs() with no parameters.

remove-attrs() as List

Removes all attributes from the context node, regardless of (local) name and/or namespace.

The method returns a List of Ids representing the qualified names of all attributes that were actually removed from the context node.

rename-element(newName as Id) as Void

When the context node is an element, renames that element to the specified newName.

replace-with-children() as Void

This function replaces the context node by its children, i.e. it effectively removes the context node from the tree, moving its children onto its parent.

replace-with-text(data as String) as Void

This function replaces the context node (including its descendants, if any), by a single Text node with the string contents as specified in the data parameter.

<city>M<entity name="uuml"/>nchen</city>

[element(entity)] {
  if( @name="auml" ) {
    replace-with-text( "ä" );
  } else if( @name="ouml" )
    replace-with-text( "ö" );
  } else if( @name="uuml" )
    replace-with-text( "ü" );
  }
}

<city>München</city>

set-attr(attrName as Id, attrValue as any) as Void

Creates or sets an attribute of name attrName with value attrValue on the context element. The value is converted to a String before being set as if using the to-string() function on the value.

The function returns always true.

Calling this method on a non-element context node will throw an exception.

set-attr(target as String, attrName as Id, attrValue as any) as Void

Creates or sets an attribute of name attrName with value attrValue on all element nodes selected by the target XPath 1.0 expression (evaluated relative from the context node). The value is converted to a String before being set as if using the to-string() function on the value.

The function returns true when the target expression selects at least one target element, false otherwise.

Calling this method on a non-element context node will throw an exception.

#namespace uci "http://www.infinity-loop.de/namespace/2006/upcast-internal";

[element(uci:par)] {
  set-attr( "descendant::uci:image", inPara, true() );
}

specifies(propertyName as Id) as Bool

This function returns true when on the current context node, the given attribute or CSS property propertyName is actually specified (in contrast to the value being also available by inheritance when it was specified at some ancestor element), and false otherwise.

The special upCast namespaces for CSS properties are handled in the following manner:

<uci:inline uci:diffStyle="color: red;">
  <uci:inline uci:diffStyle="font-weight: bold;">Text that is red and bold.</uci:inline>
</uci:inline>

specifies( csso:color )

@css:color

string() as String

Returns the concatenated PCDATA content of the descendant Text nodes of the context node (i.e. "the text content").

text() as Bool

Tests whether the context node is a Text node.

abs(val as Numeric) as Numeric

Returns the absolute value of the Numerics val.

abs( -3 )

abs( -1.5in )

abs( 12.67 )

max(v1 as Numeric, v2 as Numeric) as Numeric

Returns the maximum of the two Numerics v1 and v2. Both must have the same power.

max( -3, 5.2 )

max( 1in, 15mm )

max( 10, 20mm )

min(v1 as Numeric, v2 as Numeric) as Numeric

Returns the minimum of the two Numerics v1 and v2. Both must have the same power.

min( -3, 5.2 )

min( 3cm, 1in )

min( 10, 20mm )

app-buildnumber() as Numeric

This function returns the build number (as integer) of the upCast application running it.

You can use this to determine whether the build is high enough (or within a range) in which all required functions will be available, or you can make sure that you are running on a build where some important bug fix your code relies on is implemented.

debug(items as Value, ...) as Void

Outputs the string values of the individual elements in items in a special debug format on the system console.

delay(milliseconds as Numeric) as Void

This method pauses execution for the specified number of milliseconds.

function watchFolder( $folder as String ) {
  while( true() ) { // Loop forever until user clicks Stop
    variable $files as List := { };
    variable $f as String :="";

    $files := list-files( $folder );
    for-each( $f in $files ) {
      process-file( $f );
    }

    delay( 60000 ); // Wait 60 seconds
  }
}

entering() as Bool

This function lets you query the processing state of the rule for the current node. It returns true when the processing state is on entering the node, i.e. before processing its children, and false otherwise.

eval-xpath(xpathExpression as String) as List

This function lets you evaluate an XPath 1 expression against the internal document tree, the the XPath context node being the same as the UPL context node.

The result is always a List.

It contains an element for each of the list of items selected by the XPath expression.

When no items have been selected by the XPath expression, an empty List is returned.

The items returned by the XPath engine are converted to UPL values as follows:

The implementation currently uses the Jaxen XPath engine.

get-environment-value(key as String) as Value

This function lets you query several environment variables. Available key values and their meaning are described here.

get-outline-level() as Numeric

Returns the outline level (as specified in an RTF document imported by the RTF Importer) of the context node, if it is a paragraph. The returned value is an integer between 1 and 9 for a paragraph if it has an outline level assigned.

The function returns 0 for a paragraph at body text level or if the context node is not a paragraph element.

get-realm-value-names(realm as Id) as List

Returns a List of all variable names stored and available in the specified realm.

This method is only defined for the realms pipeline and module.

get-rulemode() as String

Returns the currently set rule mode. See set-rulemode().

get-var(varname as Id) as Value

Returns the value of the in-scope UPL variable with the same name as the Id passed in varname.

If (and only if) the namespace of the Id is one of the variable realm namespaces, the value returned is the same as $varname would have returned. This construction is useful when the variable's name to fetch was calculated at runtime or retrieved from get-realm-value-names(). When the specified realm variable does not exist, an EvalException is thrown. You can test for the existence of a realm variable using exists-var(). The method performs a type coercion for realm variables according to the following table:

get-var( pipeline:SourceFile )

hoist-single-listpar() as Void

This method, when called a uci:par element context node and for which single-listpar-level returns a value greater than zero, removes all surrounding list structures and moves the leaf paragraph to the top (replacing the former top-level uci:list item).

hoist-single-listpar()

<uci:list>
    <uci:item>
        <uci:par>Heading 1</uci:par>
    </uci:item>
</uci:list>

<uci:par>Heading 1</uci:par>

[element(uci:par) and single-listpar-level() > 0]
{
  set-heading-level( single-listpar-level() );
  hoist-single-listpar();
}

leaving() as Bool

This function lets you query the processing state of the rule for the current node. It returns true when the processing state is on leaving the node, i.e. after having processed its children, and false otherwise.

markup-regex(regExpr as String, markupActions as List) as Bool

This function evaluates the regular expression on the plain character content of all descendants of the context node, optionally creating markup over the matched character sequences. This is similar to matches-list() with the source string being the CDATA content of the context node, but you can additionally specify one of several predefined actions to perform for each matching group. These actions are:

For actions replace-custom-shallow() and replace-custom-deep(), the custom UPL function whose name is specified is parameter must have the following signature:

function functionname( $current-group as String, $position as Numeric, $groups as List) as String

where:

The function must return a (well-formed, if elements are contained) XML fragment serialized to a String. That returned value is then parsed into an internal XML tree representation and replaces the complete group (incl. its children) that would have been created at that position in the tree.

For actions other than replace-…(), on grouping, the function will wrap the character run to be grouped by either an uci:inline element (when currently at inline level) or a uci:block element (when currently at block level) with an uci:type attribute that has the value of the specified type id.

The function returns true when there was at least one match for the regular expression, false otherwise.

<uci:par>1.2.3.</uci:par>

markup-regex( "([0-9]\\.)*", { "ignore()", "group-shallow(levelnum)" } )

<uci:par>1.2.<uci:inline uci:type="levelnum">3.</uci:inline></par>

The workings of this function is best described with an example. Suppose we have the following XML fragment, the context node being the <p> element:

<p>[ID42] A paragraph with an <link>http://www.abc.de/<ins>new/ link</ins></link>.</p>

Let's have a look at some example applications of markup-regex():