TEXT Objects in WebLord, the Document Assembly Tool
Logo WebLord v2.2
The Document Assembly Tool

TEXT Objects

TEXT objects are the "work horse" of the system. They can be be evaluated based on various conditions, execute programs and retrieve their output, represent the current time in almost any format, include external files, etc.

TEXT objects define multiple key properties, but only one of these will be used to evaluate the object and produce a value! The key property chosen for evaluation depends on the key property's "priority" (the order in which it is listed in the table below.) Those key properties listed first will be selected in preference of those listed later. Only the first selected key property is used; the others are ignored!

Overview

Although it is possible to define multiple key properties for a TEXT object, only one of these is actually evaluated.
It is still possible to reference superfluous properties directly (by name) but they are otherwise ignored by WebLord. Which key property is examined and which are ignored is determined by the order of the properties listed in the table below, and marked KEY PROPERTY.

The value of the object (see then, else, select-case, translate, and value) can have special meanings.
The value-type property defines a variety of special interpretations for the object's value. Based on this, the object may return a date, the contents of a file, or an Environment Variable.

The behavior of text objects can be altered with object properties
Objects can be "frozen" after their first evaluation with a static property; they can perform actions, but return no value through the use of the actor property; and they can control the generation of sequential values through the use of the sequence property.

Properties

Property Name Inherited? Description

echo never

The value of this property is displayed when an object is evaluated.

A property is evaluated when it is refernced; referencing a property of an object does not, however, count as evaluating the object!

When used in conjunction with the WARNING++ and ERROR++ properties, such messages can be turned into errors and warnings to extend WebLord's own. For an example of how to achieve this, see the file html-image.wl

Example: echo = ERROR++ "You've got a problem!"


exec explicit

This property is evaluated into a command that is executed before most processing on the object is performed. This is quite similar to the pre-exec property of the PAGE object and can be used to similar effect.

Combining the EXEC property with the VALUE property and setting the VALUE-TYPE property to 'PLAINFILE' or 'VARFILE' will allow you to build a value externally, redirecting the output to a known file. The VALUE will then name this file, reading the result of the EXEC operation as the value of the object.

Example:

text processes
{
  exec       = "sys:bin/processes -a >" value;
  value      = "silly.data";
  value-type = "plainfile";
}

Note: the command is necessarily operating system dependent. If you need your definition to be functional across a range of operating systems (using appropriate distributions of WebLord for various platforms) you can use the _OS symbol to construct an object that returns a different command depending on the system on which the definition is being used.


link explicit

Specifies a destination (such as a URL or other type of anchor) described by the object's value. In the context of an HTML anchor, the VALUE of the object defines the human-readable text, and the LINK specifies the URL to which the reader is directed when clicking on the text.

The construction of the anchor is determined by two objects: anchor-begin and anchor-end. The file html-page.wl defines these to serve as HTML anchors. You are welcome to define others for other languages (AmigaGuide®, PDF, etc.)

We'll leave the execution of this task to you, the able reader! :-)


ifdef n/a

This property is deprecated and is automatically converted to an if property. Multiple combinations of ifdef, ifndef, and if will not conflict with each other.


ifndef n/a

This property is deprecated and is automatically converted to an if property. Multiple combinations of ifdef, ifndef, and if will not conflict with each other.


if explicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

This property defines a boolean expression, comparing objects, property names, and constant values to arrive at a true or a false result.

A result of true will then choose the then property; a result of false will choose the else property as the value of the object.

Note: If the expression evaluated to true and no then property is defined, but a value property is available, then the object will evaluate the value property instead.

It is perfectly "legal" to define only one of the two properties (then or else). The object will produce no value if the chosen property is undefined (and not inheritable from a parent object.)

Example:

text foo
{
  if   = ISDEF computer AND ISDEF amiga;
  then = "Let's show off our cool computer!";
  else = "Let's see what's on TV...";
}

See also: value-type, value-type


then explicit

The property selected to produce the object's value when the object's if property produced a result of true.

If this property is undefined (and not inheritable froma parent object, then the value of the object will be derived from the value property instead.


else explicit

The property selected to produce the object's value when the object's if property produced a result of false.


select-case explicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

This powerful multi-select property chooses a defined property name based on the result of the select-case property.

Example: select-case = _OS

If we assume that _OS produced a value of 'Unix' then WebLord will look for a property named 'case:Unix'

Careful: The syntax of these property names has been chosen to be similar to that of common programming languages, but the portion following the 'case:' part of the property name is not a variable. In fact, nothing on the left side of the equal sign (the property name) is ever evaluated by WebLord. As such, it would be wrong to assume that case:Unix is the same as case:"Unix" or even case:foo when 'foo' is a property that might evaluate to 'Unix' -- All of these assumptions are wrong!

A property named 'case:' acts as the default that is chosen when the selected property is not defined (and not inheritable.)

Note: Properties selected with the select-case mechanism may be inherited from parent objects if not defined by the current object. The parent must, however, define the property with a inheritable attribute, otherwise the current object will not be able to inherit such properties.

Example:

text os-full-name
{
  select-case  = _OS;
  case:Amiga = "Amiga OS";
  case:Unix  = "Unix";
  case:win32 = "Microsoft Windows (32-bit)";
  case:      = "Something else...";
}

See also: translate, value-type


translate explicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

The value of this property becomes the property name chosen for this object. This is quite similar to the way that the select-case property works, except that no 'case:' is prepended to the property name. The use of translate can be less restrictive, but may be more obtuse.

Example:

text os-name
{
  translate = _OS;
  amiga     = "Amiga OS";
  unix      = "Unix";
  win32     = "Microsoft Windows (32-bit)";
}

Notice that translate looks "cleaner" than the select-case but has no way of specifying a default property.

See also: value-type


foreach explicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

This property is not evaluated in the usual manner. Rather, each element is "assigned" to the property named by the using property, and then the do object/property is evaluated.

Hint: read this as "For each element, do (evaluate) the named object / property by using (substituting) the element for the named property."

Example:

text foo
{
  foreach = "Selina" "Roberta" "Maria" "Julia";
  using   = name;
  do      = name " is beautiful!\n";
}

Note: The operation of the 'foreach' property is altered by the presence of a delimiters property.

See also: delimiters, forrange, value-type


delimiters explicit

This property is evaluated only as part of the foreach property. When specified, the operation of the foreach property is modified:

The value of the 'foreach' property is evaluated (rather than processed one token at a time); the resulting string is then separated according the the delimiter character(s); the resulting list of tokens becomes the new property that the 'foreach' operation processes.

Breaking up the string into words
Specify delimiters as " \t\n\r"

Breaking up the string into lines
Specify delimiters as "\n\r"

The following example describes how the names of separate files can be processed, but please note that this example is specific to the Amiga. It should be obvious, however, how to adapt this example to other platforms:

Example:

# Get a listing of a set of files; by defining
# 'file-pattern' we could override the default
# (which is 'all files')
text list-files
{
  foreach    = get-files;
  delimiters = "\n";
  do         = file-format;
  using      = file-name;
#another way of defining the 'foreach' with a
#specific file-pattern:
# foreach=get-files(file-pattern="#?.text");
}

# retrieves a list of files; this will become a single
# string where each filename is separated from the next
# by a newline symbol; this is the way that the Amiga's
# "LIST" command produces files; only the filename is
# returned according to the LFORMAT argument to the LIST
# program. Notice that a reference to 'file-pattern' is
# made; if the caller does not define it, then the LIST
# command won't get an argument for the files to list;
# the LIST command will accept this as a default for all
# files; we can easily take advantage of this by
# overriding this default.
text get-files
{
  exec         = 'c:list ' file-pattern
                 ' lformat "%s" >' value;
  exec-cleanup = 'c:delete t:foo quiet';
  value        = 't:foo';
  value-type   = 'plainfile';
}

# This is the object that is used by the 'do' property
# of the 'list-files' object; it references the
# 'file-name' property named by the 'using' property.
text file-format
{
  value = "The filename is '" file-name "'\n";
}

See also: foreach, forrange, value-type


forrange exlicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

The forrange property is evaluated in exactly the same manner as the foreach property, except that its values are dynamically built as a sequence (range) of numeric values. You must specify either two or three values. The first two are the starting and ending values for the range and the optional third is the stepping size for the range.

Example: forrange = "1" "99";

The example will generate successive values 1, 2, 3, 4, ... 99

Example: forrange = "1" "99" "10";

The example will generate successive values 1, 11, 21, 31, ... 91 (and notice that the final value 99 is not in the range because the next step would be 101 which is outside the range.)

Example: forrange = "9" "1";

The example will generate successive values 9, 8, 7, ... 1 (no need to specify a negative stepping range (-1) in this case: WebLord is smart!)

Example: forrange = "01" "99";

The example will generate successive values 01, 02, 03, 04, ... 99 (note that the starting and ending values of the range are the same length, the "1" having been "padded" as "01" -- this tells WebLord to "pad" all other values in the range to be the same length.)

Example: forrange = "00000001" "00000099";

Example: forrange = "-7" "29";

Example: forrange = "-7" "-9";

See foreach for additional information, as well as value-type


do explicit

This property specifies either the name of a single object or is evaluated as an ordinary property; in either case this object / property is evaluated once for each element specified by a foreach or forrange.

See also: using


using explicit

This property names a single property name (not a constant, though) that is to receive each successive value of a foreach or forrange evaluation. The object / property named by the do property is then evaluated with this value.

See also: do


value explicit

KEY PROPERTY: Listed in the order given by this table, only the first such key property is evaluated: additional key properties (if any) will be ignored!

In the absence of any other key property, the value property is evaluated to supply a value for the object.

The result can optionally be interpreted in different ways by specifying a value-type; omitting a value-type simply returns the result of the evaluation as-is.


value-type explicit

If the result of an object's evaluation has a meaning other than plain text, then specifying a value-type allows you to treat the value in different ways. The value-type must evaluate to one of the following words (upper / lower case is not important):

env (envvar)
The value is actually the name of an (operating-system dependent) Environment Variable; the contents of this environment variable is returned.
date (date-pattern)
The value is actually a sequence of characters that will be interpreted so as to construct the current date and time in a highly configurable manner. See Date & Time for the set of character sequences that WebLord recognizes.
plainfile (plain-file, file)
The value is actually the name of a (text) file whose contents are retrieved and returned.
varfile (var-file)
The value is actually the name of a file whose contents are parsed for special sequences that are replaced according to various rules. The result becomes the value of the object. See varfile for syntactic details on these special sequences.
md5
The value is "converted" to an MD5 Digest. Although MD5 Digests can ordinarily be built on arbitrary (binary) data, WebLord is not equipped to handle binary data with grace. In fact, WebLord's idea of newline symbols (expressed within WebLord's object definitions as the two-character sequence \n) may differ between systems, so the digests are not guaranteed to be "portable" in a universal sense.

value-is-env never

This property is deprecated. Please use value-type instead.


value-is-date-pattern never

This property is deprecated. Please use value-type instead.


value-in-file never

This property is deprecated. Please use value-type instead.


trim-lines yes

Only plays a role when the value-type is set to a file type; Causes all whitespace (blanks and tabs) to be removed from the end of lines, although newlines are not removed.


trim-result yes

Only plays a role when the value-type is set to a file type; Causes whitespace (blanks, tabs, and newlines) to be removed from the end of the input file.


adjust-seconds yes

Only plays a role when the value-type is set to date; Adds the numeric equivalent to the current time stamp, thereby allowing a certain number of seconds to be added or (in the case of negative numbers) subtracted from the current time. 86400 seconds makes a day. 604800 seconds is 7 days. 2592000 seconds are 30 days. And about 31557600 seconds is a year (365.25 days).


html-quote-if-required explicit

If this property is defined (any value will do) then the object's value is examined after that value has been constructed. If this value is not already enclosed in quotes "..." and it contains any characters that require a string to be quoted (according to the HTML 3.2 specification) then WebLord will do this for you.

WebLord will also perform, if necessary, a translation of the &, < and > symbols to &amp; &lt; and &gt; sequences.

Note: the function of this property is strictly tied to HTML and has no meaningful equivalent in other output languages.


exec-cleanup explicit

This property is evaluated into a command that is executed after the object has been processed. This is quite similar to the post-exec property of the PAGE object and can be used to similar effect.

Note: the command is necessarily operating system dependent. If you need your definition to be functional across a range of operating systems (using appropriate distributions of WebLord for various platforms) you can use the _OS symbol to construct an object that returns a different command depending on the system on which the definition is being used.


output never

The value of the object is written to the file named by the evaluation of this property. If the file existed already, the original contents are lost, unless the output-append property is defined.


output-append never

Used only in conjunction with the output-append property, this property, when defined (any value will do) causes the value of the object to be appended to the output file, rather than replacing it.


start yes

Evaluated for sequence objects to initialize the sequence and define one end of the sequence. The default is 0.


end yes

Evaluated for sequence objects to define the end of the range of values that the sequence generates, opposite of the start. The default is 1.


step yes

Evaluated for sequence objects to define the increment step from one value generated to the next. The default is 1.


pingpong yes

Evaluated for sequence objects to define the behaviour of the sequence generator when the generated values reach one end of the range of values. When the 'pingpong' property has a non-zero numeric value the sequence generator will simply reverse the direction of the sequence; otherwise it will wrap back to the start.



This material is Copyright © 1997,1998,1999,2000,2001 RingLord Technologies and Udo Schuermann. All rights reserved. The latest versions of the WebLord software and (this) documentation can be obtained from the WebLord Home Page (the link will only function if you are connected to the internet.)