Special Symbols in WebLord, the Document Assembly Tool
Logo WebLord v2.2
The Document Assembly Tool

Special Symbols

Special Objects & Properties

The following special objects are defined, as well as built-in properties that every object supports.

Keyword Description

this

The current object, which could differ from the object whose property references this. To be kept in mind is that this refers to the current object.


parent

The object that referenced (invoked) the current object.


page

The Page Object currently being built, i.e. the current page.


rootpage

The top-most Page Object of which the current page is a part. The rootpage will differ from the current page only if the current page is part of a set of subpages.


objectname

The name of the object as defined.

Example:

	text Silly-Example
	{
	    value =
	        "This object is named '" this.objectname "'\n"
	        "The parent's name is '" parent.objectname "'\n"
	        "HTML-Header value is '" header.value "'\n";
	}

objecttype

The type of the object as defined. The main use of this is, perhaps, testing if the immediate parent object is a page object.

	text brown-cow
	{
	    if =    parent.objecttype "eq" "page";
	    then =  "It's a page!";
	    else =  "It's not a page; we're more deeply nested...";
	}

objectdefinition

Produces a complete (and nicely formatted!) reproduction of the object's definition, suitable to be parsed right back into WebLord! This is useful when an error occurred and you want to display the offending object in its full glory.

The following example is lifted straight out of the html-image.wl (and no, the ^ symbols have no special meaning; they're only used to nearly "guarantee" that conflicts with your own symbols will not occur :-)

    text = html-image
    {
        # did the conversion process produce
	 # an 'image-src' property?
        if    = isdef image-src;
        then  = ^html-image-center-start
                ^html-image-link-start
                    "<img" ^html-image-spec ">"
                ^html-image-link-end
                ^html-image-center-end;
        else  = html-image-error(
                text = "Object '" parent.objectname
                "' defines no 'image-src' property; "
                "you may need to convert this manually. "
                "The object is defined thus:\n"
                parent.objectdefinition );
    }
    
    text html-image-error
    {
        echo    = ERROR++ text;
        value   = "";
    }

See also: objectstatus


objectstatus

Produces a complete (and nicely formatted!) reproduction of the object's definition including all inherited properties, suitable to be parsed into WebLord. This is useful when an error occurred and you want to display the object's current status, including all of its inherited properties.

See also: objectdefinition


Properties of Objects

Object properties are specified before the object's type and name.

Keyword Description

Actor

TEXT objects with an actor attribute return no value, but their properties are evaluated as if they did. This makes it possible to have an object produce a value, output it to a file, then use exec-cleanup to take action on this value (perhaps email it somewhere, enter it into a database, etc.), but not enter the result into the page that's being produced!

The following example demonstrates this:

text user-feedback
{
	value = email-user-feedback
		'<h1>Thanks!</h1>';
}
actor text email-user-feedback
{
	value =	cgivar-name ' <' cgivar-email '> had this to say:\n'
		cgivar-comment '\n';
	output =	'/tmp/foobar';
	exec-cleanup =	'mail me@localhost -s "Web Feedback" </tmp/foobar';
}

The example above is geared towards a Unix system; more elaborate system-independent methods would enable cross-system compatibility of this construct.


Sequence

TEXT objects offer a special numeric sequence-generating capability, starting with version 2.3: Any reference to the current-sequence-value property within the object (do not define this property yourself) causes the current sequence value to be substituted. Here is an example:

sequence text bg-color
{
	start =    "1";
	end =      "5";
	step =     "1";
	pingpong = "1";

	select-case = current-sequence-value;
	case:1 =   "#000000";
	case:2 =   "#333333";
	case:3 =   "#666666";
	case:4 =   "#999999";
	case:5 =   "#cccccc";
}
sequence text fg-color
{
	start =	   "1";
	end =      "5";
	step =     "1";
	pingpong = "1";

	select-case = current-sequence-value;
	case:1 =   "#ffffff";
	case:2 =   "#ffffff";
	case:3 =   "#ffffff";
	case:4 =   "#000000";
	case:5 =   "#000000";
}

The above defines two sequence objects, both generating the same sequence of values for each reference to the current-sequence-value symbol: 1, 2, 3, 4, 5, 4, 3, 2, 1, 2, 3, etc. Note that if the 'pingpong' property were undefined, the sequence would instead be: 1, 2, 3, 4, 5, 1, 2, 3, etc.

You can now reference bg-color and fg-color symbols to construct a series of rows in a table, for example, that have a nice spread of colours.

The 'start', 'end', 'step', and 'pingpong' properties are inherited.


Static

TEXT objects may be either dynamic (the default) or static. Their value becomes fixed after the first time they are used, avoiding the cost of all evaluations when used again. Objects that are intended to inherit values should never be static. Consider the following Example:

     static text foo
     {
       select-case = _OS;
       case:Amiga  = "the Amiga OS";
       case:Unix   = "the Unix operating system";
       case:       = "something else";
     }

The object above references the _OS symbol, whose value depends on the operating system where WebLord is being run. This value will not change. No other references to any symbols are made, so the value of this object will always resolve to the same. It makes sense, therefore, that the object be declared static so that additional references need not re-evaluate the object. This becomes an especially valuable technique as such objects grow increasingly more complex.

Let's look at another object:

     static text foo
     {
       value = "Hello, how are you, " test;
     }

In the example above, the value of the object, which depends on another object (or property) named test, is evaluated only the first time it is named. Thereafter, and independent of any change in the value of test (which might be inherited with different values), the object foo always returns the same value. Be careful of such cases!


Modifiers for Properties

Modifiers for the properties of objects are specified before the property name. All property modifiers begin with a % (percent) symbol to reduce or eliminate possible conflicts with common property names.

Keyword Description

%inheritable

When this symbol precedes a property name that is ordinarily restricted, such as those marked in the 'inherited?' column as explicit, then the property is explicitly made inheritable for those objects that would otherwise not be able to "see" the property.

The value property of the TEXT object, for example, has restricted inheritance: if a TEXT object defines no VALUE property then it can inherit a VALUE property only from parent objects that define a VALUE property with the %inheritable attribute.

Example: %inheritable value = header body footer;

Note: It is up to you to ensure that the VALUE property being inherited by a TEXT object is really suitable for it. PAGE objects also define VALUE properites, and if such a property is given the %inheritable attribute, then this may come into conflict with a TEXT object's VALUE properties.


%private

When this symbol precedes a property name that is ordinarily inheritable, such as properties marked in the 'inherited?' column as yes, then this property is explicitly prevented from being inherited by child objects that might otherwise inherit it. Properties that are marked as explicit in the 'inherited?' column are implicitly private and need not be marked so.

The value property of the TEXT object, for example, has restricted inheritance: if a TEXT object defines no VALUE property then it can inherit a VALUE property only from parent objects that define a VALUE property with the inheritable attribute (see above.).

Example: %private width = "128";


Special Symbols

Special symbols always have precedence over any and all other symbols. In other words, it is not possible to redefine these properties or override them in any way.

Keyword Description

copyright-notice

WebLord really wants to insert an (HTML) comment on your page to indicate what software was used to help build the page. To give you the choice where to place this comment, you should reference the copyright-notice symbol somewhere on your page. If you reference the html-page.wl, then this is already done for you!

Beginning with WebLord 2.0 the use of this symbol on every page has become optional. WebLord will still issue a notice to remind you, but will in no other way prevent the construction of pages that lack the reference.


_isCGI

When WebLord is operating in CGI mode (i.e. with the cgi argument on the command line) then this symbol will produce a value of '1', otherwise it is '0'


_OS

The _OS symbol produces a character string that represents the fundamental operating system type of the WebLord binary (executable) that is processing the current definition. Use of this symbol can greatly enhance the portability of your definition between different operating systems.

The following values can be expected to be returned with a reference to the _OS property:

Amiga
The Amiga computer's operating system
Macintosh
The Macintosh operating system
Unix
A Unix operating system, such as FreeBSD, Linux, Solaris, etc.
Win32
A Microsoft Windows 32-bit operating system, such as MS-Windows 95 or MS-Windows NT

Not all of the above may be supported at this time. Additional symbols may be available in the future to provide distinctions between operating system versions, but an object with an exec property can be used to construct your own extensions to this scheme.

Example: select-case = _OS;


_Author-Email

Produces the email address of WebLord's author: support@ringlord.com


_Homepage-URL

Produces the URL of the WebLord home page: http://Ringlord.com/products/weblord/


_VER

Produces WebLord's current version number. You can use this in a variety of ways, such as putting a message on your pages that the page was constructed with the help of WebLord 2.3.0 :-)

See also: _VERMAJOR, _VERMINOR, _VERLEAST

_VERMAJOR

Returns only the major version number, i.e. the first integer of the version (2.3.0) number, which is, in this case, '2'

See also: _VER, _VERMINOR, _VERLEAST

_VERMINOR

Returns only the minor version number, i.e. the second integer of the version (2.3.0) number, which is, in this case, '3'

See also: _VER, _VERMAJOR, _VERLEAST

_VERLEAST

Returns only the least version number, i.e. the third integer of the version (2.3.0) number (if any), which is, in this case, '0'

See also: _VER, _VERMAJOR, _VERMINOR

weblord-link

Generates a string of HTML containing an anchor / link to the WebLord home page along with a copyright notice. You are encouraged (but certainly not required!) to make use of this notice somewhere on your page to help spread the word about WebLord! :-)


_AMIGA

Produces a value of '1' if running on an Amiga computer, '0' otherwise.


_UNIX

Produces a value of '1' if running on an Unix computer, '0' otherwise.


_MAC

Produces a value of '1' if running on an Macintosh computer, '0' otherwise.


_WIN32

Produces a value of '1' if running on a Wintel computer, '0' otherwise.


Action Symbols

References to action symbols cause some change in the program's behavior. They usually do not, however, produce output in and of themselves.

Keyword Description

ERROR++

Referencing this symbol generates an error. While this may seem like a rather boneheaded idea, there actually is a use for this: When used as part of the echo property of a TEXT object, an object can generate error messages of its own, thus extending WebLord's internal set of errors.

This is demonstrated in the file html-image.wl, which defines an object to generate a meaningful error message if an image definition is missing a critical part.

Note: The ERROR++ symbol itself generates no message, no output, no information of its own at all. If you were to reference it somewhere in your definition, without a meaningful message being output, then WebLord could terminate with a supposed error, but no indication of where the problem lies. Be careful of unconsidered use of ERROR++


WARNING++

Referencing this symbol generates a warning. While this may seem rather pointless, there are occasions where this is useful: When used as part of the echo property of a TEXT object, for example, an object can generate warnings of its own, thus extending WebLord's internal set of warnings.

Something similar is demonstrated in the file html-image.wl, which defines an object to generate a meaningful error (not warning) message if an image definition is missing a critical part. A warning could be issued instead of an error. The method is the same.

Note: The ERROR++ symbol itself generates no message, no output, no information of its own at all. If you were to reference it somewhere in your definition, without a meaningful message being output, then WebLord could terminate with a supposed error, but no indication of where the problem lies. Be careful of unconsidered use of ERROR++


Unique-ID

The use of this symbol produces a 32-character (128-bit) unique identification, such as: '37db3cd3ce23f1d9218e8e4efb3cdbd8'

Unique in this context refers to uniqueness within the context of a single execution of WebLord. This is not to be confused with a UUID (a Universally Unique Identifier) or a GUID (a Globally Unique Identifier), which both also are 128-bit strings and that can be expressed in that manner.

Repeated use of this symbol will not produce a new string!

See also: Unique-ID++, ++Unique-ID


Unique-ID++

The use of this symbol produces a 32-character (128-bit) unique identification, such as: 'bac9ba22f743f874c39b04643ffdf8cb'

Unique in this context refers to uniqueness within the context of a single execution of WebLord. This is not to be confused with a UUID (a Universally Unique Identifier) or a GUID (a Globally Unique Identifier), which both also are 128-bit strings and that can be expressed in that manner.

The next use of this symbol will produce a new string

See also: Unique-ID, ++Unique-ID


++Unique-ID

The use of this symbol produces a 32-character (128-bit) unique identification, such as: '88f1c33f519a05555e7816d910692e3d'

Unique in this context refers to uniqueness within the context of a single execution of WebLord. This is not to be confused with a UUID (a Universally Unique Identifier) or a GUID (a Globally Unique Identifier), which both also are 128-bit strings and that can be expressed in that manner.

The use of this symbol will produce a new string

See also: Unique-ID, Unique-ID++


UC++

Enables uppercase-conversion of the output until the next UC-- symbol is encountered. Multiple UC++ symbols must be "countered" with an equal number of UC-- symbols. If there are more UC-- symbols than UC++ symbols, then the conversion will actually produce lower-cased characters!


UC--

Deactivates uppercase-conversion of the output until the next UC++ symbol is encountered. Multiple UC++ symbols must be "countered" with an equal number of UC-- symbols. If there are more UC-- symbols than UC-- symbols, then the conversion will actually produce lower-cased characters!



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