Language Specification

Hop into the future !

This document describes roo!™ programming language capabilities.

Observe: square brackets are used in two ways within this document. Generally, these indicate that the enclosed syntactic elements are optional. Alternatively, square brackets can be specified within expression syntax. These latter brackets are shown larger than the associated text, and in dark red. You will be able to easily recognize these larger square brackets. The normal size square brackets always enclose optional syntactic elements.


1 roo!™ language objectives


2 Rexx programs are roo!™ programs !

roo!™ is an object-oriented enhancement of r4™, which is Kilowatt Software's Classic Rexx language offering. All Rexx capabilities that are supported by r4™ are supported by roo!™. roo!™ supports all Classic Rexx instructions and built-in functions, as well as the invocation of Classic Rexx internal and external procedures as subroutines and functions.

roo!™ programs can differ from Classic Rexx programs by the use of a handful of object-oriented capabilities that are described below. An assortment of built-in classes are provided as well.


3 Program source files

roo!™ supports two types of source files.

  1. Program source files

  2. Class definition files

3.1 Program source file

A program source file consists of:

A program can optionally use roo!™'s language extensions. The csv2xml example program uses various roo!™'s language extensions, to convert a comma-separated value (CSV) file to an equivalent eXtended Markup Language (XML) file.

When additional roo!™ capabilities are not used the program can be interpreted by r4™ directly. In addition, if the program does not use any r4™ extensions, then the program should be executable by other Classic Rexx interpreters. The calc example program does not use any r4™ or roo!™ extensions.

Note: r4™ extensions are described in the separate R4.HTM document.


3.2 roo!™ object-oriented programming

Although roo!™ can interpret Classic Rexx programs, it can also do much more. With roo!™ you can develop object-oriented programs.


3.2.1 A class file "defines" a programming object

A roo!™ class definition is a source file that defines a new programming object. An object can encapsulate a collection of data values, that are accessible exclusively by the object's methods. In addition, an object can be defined by a hierarchy of classes. The bottommost class in the hierarchy is called the base class. The other classes in the hierarchy are derivations of base class capabilities. Each class can share variables with other classes in the class hierarchy. Derived classes can also override the methods of a base class. The base class can provide the fundamental behavior of a method, and a derived class can refine this behavior. Overriding a method is called polymorphism in object-oriented programming parlance. The base class can be either a class that you define, or it can be a roo!™ built-in class.


3.2.2 roo!™ class definition file

A roo!™ class definition file consists of:

The msgbox example is a roo!™ class definition file that exhibits various object-oriented capabilities.


3.2.3 Class definition instruction

This instruction defines the characteristics of class className. A class instruction is optional within a class source file. When the class instruction is absent, the class is a simple roo!™ class.

When present, the class instruction must be the first instruction in its source file. Only one class definition is permitted per class source file. The className label is recommended, although optional, on the class instruction. The class is instantiated by its source file name. To help other programmers, or yourself, the className label should correspond to the source file name. For example:

The file name portion of the class source file name, in upper case, symbolically references the class. For example, if the source file name is "c:\roo\secondBase.roo", the symbolic class name will be secondbase. A request for another class file that has the same symbolic class name will use the prior class definition, even if it is in another directory, or has a different extension. Thus, "c:\somewhereElse\secondBase.xyz" will use the class definition in "c:\roo\SECONDbase.roo" if it was previously activated. This is because the symbolic class names for both of these files match.

Suggestion: when you prepare a new class source file always check to see if another file with the same symbolic class name exists. Be aware the other file may be located in the directories associated with the ROOPATH environment variable.

When the extends phrase is specified the current class is a derivative of baseClass. The baseClass is located by a program search, with an implicit default class extension unless an explicit extension is specified within the baseClass term. The baseClass can also be an explicit file system name; such as, "c:\roo\first base.roo".

Normally, the base class is constructed before the current class is initialized. When the explicitly keyword is specified, the initialize method of the current class is activated before the base class is constructed. The base class is constructed explicitly when the following instruction is performed in the initialize method.

When the base class is not explicitly constructed, the same arguments are passed to the initialization methods of the base class, and then the deriving class, in the same sequence. When the base class is explicitly constructed the arguments that are passed to the base class initialization method can be dynamically prepared, or rearranged, by the deriving class.

None of the base class methods should be used until the base class is initialized. If an initialize method in a deriving class does not explicitly initialize the base class, then the base class is implicitly initialized when the initialize method of the deriving class concludes.

Observe: as mentioned earlier, class definitions are reused until all class instances conclude. Changes to the associated source file will not be effective while class instances are active. Often, it will be necessary to halt the roo!™ environment in order for class source file revisions to become effective.


3.2.4 Class variables

There are three types of roo!™ class variables. These are defined within local, shared, and static instructions. The value of a class variable persists from one method invocation to the next. If you have used other object-oriented programming languages you might refer to these as member variables, which might have various access specifiers; such as: public, private, protected, etc.

Note: unlike other programming languages, roo!™ class variables are never publicly accessible. This assures that the value of a class variable is always encapsulated.

3.2.4.1 Local class variable instruction

The local instruction identifies one or more variables that are locally persistent for the methods within the current class source file. A separate collection of local variables is established for each class instance. The variableName values are either simple variable names, or compound stem variable names. Simple variable names do not contain a period. Compound stem variable names contain one period, which is the last character in the name.

Multiple local instructions are permitted within a class source file. Often a single local instruction is present at the beginning of the file. However, a local instruction can be placed anywhere within the file. Local variables can be declared adjacent to the point of use. It is not an error to declare the same variable as a local variable multiple times.

3.2.4.2 Shared class variable instruction

The shared instruction identifies one or more variables that are persistently shareable by the methods of all classes within a class hierarchy. A separate collection of shared variables is established for each class instance. The variableName values are either simple variable names, or compound stem variable names. Simple variable names do not contain a period. Compound stem variable names contain one period, which is the last character in the name. A class that is a refinement of another class must declare the variables that it is sharing; otherwise, confounding problems would arise. For example, what had been a temporary variable, in a method of a derived class, could accidentally become a shared variable as a result of a subsequent addition of the variable to the list of shared variables within the base class.

Multiple shared instructions are permitted within a class source file. Often a single shared instruction is present at the beginning of the file. However, a shared instruction can be placed anywhere within the file. Shared variables can be declared adjacent to the point of use. It is not an error to declare the same variable as a shared variable multiple times.

3.2.4.3 Static class variable instruction

The static instruction identifies one or more variables that are shared by all instances of a class definition. Static variables have class scope, instead of instance scope. The variableName values are either simple variable names, or compound stem variable names. Simple variable names do not contain a period. Compound stem variable names contain one period, which is the last character in the name.

Multiple static instructions are permitted within a class source file. Often a single static instruction is present at the beginning of the file. However, a static instruction can be placed anywhere within the file. Static variables can be declared adjacent to the point of use. It is not an error to declare the same variable as a static variable multiple times.

Static variables can be initialized by a preinitialize method. A corresponding finalize method allows resources that are stored in static variables to be properly terminated.

3.2.4.4 Class variable usage errors

Note: it is erroneous to declare a variable in more than one class variable group. For example, it is incorrect for a variable to be declared both shared and local, or shared and static. When a conflicting variable definition is encountered the following syntax error condition is raised.

Note: when a local, shared, or static variable name is a compound symbol name the following syntax error condition is raised.


3.2.5 Method definition

A method definition is similar to a Classic Rexx internal procedure, without a variable exposure phrase. As indicated, the method instruction is optional, although recommended. When present, it is annotative, and helpful for program readers. All labels within the class source file are eligible for method invocation. These are also eligible targets for signal instructions. As in Classic Rexx programs, an unexpected method instruction is an error (code #17 -- unexpected procedure or method).

Observe: when the method instruction is absent, it is possible for program execution to flow into the method. This may introduce a logic flaw. Generally, you should use the method keyword, to avoid unexpected control flow transitions.

Unlike Classic Rexx internal procedures, methods are not invoked by the call instruction or by function calls. Methods are accessed by new invocation techniques. Methods can be invoked by either a prefix operator, or an infix operator.


4 Class instance creation request

The ^^ prefix operator creates an instance of the class that is defined in classFileName. The classFileName is located by a program search, with an implicit default class extension unless an explicit extension is specified within the classFileName term. The classFileName can also be an explicit, quoted file system name; such as, "c:\roo\first base.roo".

When the parenthesized argument list is omitted, and classFileName is unquoted, the class file name is the value of the variable named classFileName. The example program named qt.rooProgram creates a class which is the value of variable outputEmitter.

During instance creation the initialize method of the class is implicitly invoked. The optional arguments within the parentheses are passed as parameters to the initialize method. If the initialize method returns the empty string, the instance is created. Any other result from the initialize method is considered an error, and consequently the class instance is not created.

The resulting classInstanceReference is set to an error message if an error occurs during instance creation. Otherwise the classInstanceReference can be used to invoke various class methods.

The classInstanceReference can be assigned to multiple Rexx variables -- via assignment (=), arg, parse, and pull instructions. The classInstanceReference can also be passed as a parameter during a method invocation, or in a subroutine or function call. In turn, the parameter value can be assigned to variables in the target method, subroutine, or function. Each time the classInstanceReference is assigned to a Rexx variable, the number of uses of the class instance is incremented. When each of these variables is deactivated (via a drop instruction or method/procedure termination) the number of uses of the class instance is decremented. When the number of class instance uses is zero the class instance is discarded. The terminate method is implicitly invoked during class instance removal.


Note: there is no corollary to the ^^ operator -- i.e. a destroy operator. A class instance is only removed when the number of active instance uses reaches zero.

The ^^ operator is pronounced as the double-hop operator. The ^^ operator has the same precedence as other Rexx prefix operators.


4.1 Using a new instance directly in an expression

It is possible to use the resulting classInstanceReference directly in a Rexx expression wherever a term is expected, without assigning it to a variable. In this case, the number of class instance uses is temporarily incremented during the evaluation of the current instruction, and then decremented when the instruction completes.

Here are several examples that show how a classInstanceReference can be used directly in a Rexx expression.

The resulting classInstanceReference can be used in place:

Using a classInstanceReference directly in a Rexx expression is EXPOSED to potential syntax errors, if the class instance is not properly initialized. The syntax error can be avoided by enabling a signalled OBJECTION condition handler as shown in the example.


4.2 Initialization error message format

When the resulting classInstanceReference is set to an error message it is formatted as follows:

classFileName is the name of the class that was initialized.

initializationMethodReturnValue is the text that is returned by the initialize method.


5 Method invocation syntax

Methods are invoked with either a prefix ^ operator, or an infix ~ operator. A prefix ^ operator can be used to invoke methods within the current class context. These methods can be in the current class, a base class, or a derived class. An infix ~ operator is used to invoke instances in other class contexts. The an infix ~ operator is preceded by an instance reference.

Note: the caret and tilde characters are unused in Classic Rexx.

Hint: to help you distinguish between the ^ and ~ operators, the ^ and ^^ are both prefix operators, whereas a ~ is an infix operator. You learned about the ^^ prefix operator in the class instance creation section above.

The tilde operator has the same precedence as a Rexx power operator (**). This allows the classInstanceReference to be determined as the value of an expression. This precedence also allows the result of the method invocation to be used in an arithmetic expression.

Observe: prefix operators have a higher precedence than the tilde operator. Consequently, you will have to enclose the method invocation in parentheses to avoid having the method name processed by a prefix operator. Here is an example of an invalid invocation expression.

Here is the corrected version:

Hint: built-in aggregate classes, such as the stack class, also have an isNonEmpty method. This method is preferred for use in loops, because it avoids the difficulty associated with the not (\) prefix operator. Here is the code again, which uses the isNonEmpty method.

The classInstanceReference is a value that was returned from a class instance creation request.

The classInstanceReference can also be one of the following:

Observe: that the words self and base are enclosed in quotes above, because self and base are not reserved keywords. If these are unquoted, they are simple symbols. Unusual surprises could be in store if these symbols are assigned values!

The single caret operator has the same precedence as other Classic Rexx prefix operators -- i.e. the highest order of precedence. A prefix ^ operator is used to invoke methods in the current class, or a base class.

All methods are invoked as functions, and thus must return a result. If a result is not returned the following syntax error condition is raised: Error 44, Function (or method) did not return data.

A method in a derived class overrides a method with the same name in a base class. The base class provides a default implementation of the method. Note: the method in the derived class can explicitly invoke the base class method during processing, as follows:

The ^ operator is pronounced as the hop operator.

5.1 Another invocation circumstance -- treating a Rexx value as a String object instance

It is possible that the classInstanceReference in a method invocation could actually be a normal Rexx value instead. Rather than treating this situation as a syntax error, the expression is converted to a function call instead. For example:

is transformed to:

This allows the result of a method invocation to be passed to a built-in function, without embedding it within the first function parameter. Here is an example:

This invocation technique can also be used to invoke internal and external procedures as functions. Again, the value on the left side of the tilde becomes the first argument to the procedure.


6 Class preinitialization method

When a class is initially loaded the optional preinitialize method of the class is implicitly invoked. This method can initialize static variables. This method is invoked as a subroutine (as though CALLed), without any arguments. The preinitialize method can call other procedures within the class file as subroutines or functions. The preinitialize method does NOT have an instance context, so it cannot invoke other methods with the single caret operator (^). Also, the absence of an instance context, makes references to local, or shared variables improper. These will be resolved as normal Rexx procedure variables instead.

The preinitialize method can establish new instances with the double caret operator (^^). The returned instance values can be assigned to static variables. If returned instance values are assigned to local variables, these will be removed when the associated execution context concludes.

The preinitialize method must return a result. If the result is the empty string class creation is considered successful. Otherwise, an error string should be returned to indicate class pre-initialization was unsuccessful. The error string will be displayed to the console.


7 Class finalization method

When a class is removed the optional finalize method of the class is implicitly invoked, so that resources stored in static variables can be properly terminated. The finalize method can reference static variables. This method is invoked as a subroutine (as though CALLed), without any arguments. The finalize method can call other procedures within the class file as subroutines or functions. The finalize method does NOT have an instance context, so it cannot invoke other methods with the single caret operator (^). Also, the absence of an instance context, makes references to local, or shared variables improper. These will be resolved as normal Rexx procedure variables instead.

The finalize method can establish new instances with the double caret operator (^^). The returned instance values can be assigned to static variables.

The finalize method can return a result. This result is ignored.

Note: the finalize method is invoked when a class is being removed, not when a class instance is removed.


8 Class initialization method

Each class has an optional initialize method.

This method is particularly important for classes that are associated with named resources -- such as: disks, directories, streams, etc. If access to these resources is unsuccessful, the initialize method can return informative error text, and the instance will no longer be active.

When a class instance is created the initialize method of the class is implicitly invoked. This can process optional arguments that are passed from the instance creation request. The initialize method must return a result. If the result is the empty string instance creation is considered successful. Otherwise, an error string should be returned to indicate that class instance creation was unsuccessful, and an OBJECTION condition will be raised if it is enabled. The error string will be provided as the condition's description text. If the OBJECTION condition is not enabled, the error text is returned as part of the instance creation result error text.

Successful initialization of an instance can be determined by using the 'Instance' type of the datatype built-in function. An example is presented there, which shows how an incorrectly initialized class instance can be handled.


9 Class self method

Occasionally it is helpful to return a reference to the current class instance at the conclusion of a method. This allows the calling context to invoke other instance methods subsequently within the same instruction. Various built-in class methods return a reference to the current class instance. Within methods that you develop it is very easy to return a reference to the current class instance. Here is how:

This permits the invocation context to be programmed as follows:

If the special self method were unavailable, the invocation context would require multiple instructions, as follows:


10 Class termination method

When the number of uses of a class instance reaches zero the terminate method of the class is implicitly invoked. No arguments are available for the terminate method. The terminate method can reference and alter local, shared, and static class variables. The terminate method can create new class instances as well. The terminate method is optional.

Note: the terminate method is invoked when a class instance is removed.


11 Roo extensions to the Rexx language

This section describes extensions to the underlying Rexx language.

11.1 Additional reserved keyword instructions

The following reserved keyword instructions were added:

11.2 New expression operators

There are four new expression operators:

11.3 OBJECTION condition

The OBJECTION error condition was added. This condition is raised, if enabled, when the INITIALIZE method of a class returns an error string. The INITIALIZE method's error string is provided in the information that is returned by the condition built-in function's description string. The description string also includes information about the class that was accessed.

The OBJECTION error condition is processed analogously to the NOTREADY error condition. The condition is initially disabled. It can be enabled by using either the CALL ON or SIGNAL ON instructions. An example of its use is provided below.

The following is the syntax of the instructions that enable and disable OBJECTION conditions.

The following example shows how errors during class instance initialization can be bypassed by using a signal on OBJECTION instruction.

11.4 Datatype built-in function -- Instance data type

The datatype built-in function has a minor, but important, addition -- the Instance data type. This is used to conditionally perform instructions, only if the associated object instance was properly created.

An additional Instance type is supported for the datatype built-in function. This returns 1 if the possibleInstanceValue argument is a class instance, and 0 otherwise.

The following shows how to assure that an instance of class abc was properly initialized.

11.5 Revision of command instruction recognition

The usual Rexx technique for distinguishing commands from other instructions is generally in effect. However, when a potential command instruction contains special roo!™ operator characters the instruction is considered as a roo!™ object instruction instead. The special roo!™ operator characters are unquoted: square brackets ([ ]), caret (^), or tilde (~) characters. Thus, the following is not a command:

To perform the result of a method as a command, the instruction must begin with an unquoted exclamation point (!). Thus the following is performed as a command:

You can precede command lines, that do not contain special roo!™ operator characters, with an exclamation point as well. The leading exclamation point is discarded from the text before the command is performed.

Hint: if you need to start a command, that does not contain special operator characters, with an exclamation point then enclose it within quotes.

11.6 Shorthand vector expressions

A commonly used built-in class is a vector of items. A vector class instance is prepared by normal class construction and initialization. The following is an example:

roo!™ supports a shorter alternative that uses curly braces, as follows:

Methods can be applied after the right curly brace, as follows:

Vectors can be nested as follows:

A vector of vectors can be composed as follows:

An empty vector can be prepared as follows:

Hint: your use of curly braces is optional. When displayed with a small font, curly braces can be difficult to distinguish from parentheses. When defining a vector, that will receive items subsequently, you may prefer to use the long hand form instead, as follows:

Note: the curly braces are transformed to the alternative long hand vector notation during the initial scanning phase of a roo!™ source file. Consequently, the long hand format will appear in trace source display output. The original source text, with the braces, will appear in the result of a sourceline built-in function request.

11.7 Interactive trace context request

In an object-oriented environment it can be difficult to determine the calling context associated with an interactive trace prompt. You can request the calling context by entering the word context at an interactive trace prompt:

Note: #nnn ? is the text of the interactive trace prompt, which shows the current source line number (nnn).

The current procedure and method calling contexts are listed. The information that is displayed uses the ContextVector built-in class. Please refer to the description of the ContextVector built-in class to interpret the information that is displayed.

11.8 Additional built-in functions

Several built-in functions were added.

Observe: more built-in functions were added for NetRexx compatibility. These are described in another section below.

11.8.1 Callback built-in function -- roo!™ DLL execution mode only

A callback function was added. This function is only supported when roo!™ is operating in DLL execution mode. The syntax of the callback function is:

This function transfers control to a callback routine in the context that invoked the roo!™ DLL's 'PerformWithCallback', 'CreateClassWithCallback', or 'InvokeMethodWithCallback' entry.

Hint: a callback allows the roo!™ program to send information back to the calling context. In addition, the calling context can return information to the roo!™ program, via the result.

Click here to review the testRooDll.cpp example program that uses the DLL entry points described above.

11.8.2 Nap built-in function

A nap function was added. This function enables a program to pause temporarily. The syntax is:

numberOfMilliseconds is a non-negative number of milliseconds to nap.

The result is a time value, which is the number of milliseconds since system startup.

11.8.3 RaiseObjection built-in function

A RaiseObjection function was added. This enables a program to dynamically raise an OBJECTION condition, often to the calling procedure or method scope.

The RaiseObjection function is typically CALLed. The syntax is:

The RaiseObjection function returns "1" always.

conditionErrorText is a general description of the OBJECTION condition.

additionalInformation provides optional, detailed information regarding the OBJECTION condition.

Observe: if the OBJECTION condition is enabled in the current procedure or method execution scope, it is handled locally. If the OBJECTION condition is not enabled in the current procedure or method execution scope, the current scope is concluded and the OBJECTION is passed to the higher execution scope, if it is handled in the higher scope. If the OBJECTION condition is not handled at all, it is treated as a SYNTAX condition in the current execution scope.

Note: the NetRexx language uses the signal instruction to raise objections in a similar manner. roo!™ provides an implementation of the signal instruction which is compatible with Classic Rexx usages, consequently it could not be used for condition raising.

11.8.4 Split built-in function

The split function partitions a string into a vector of segments. The syntax is:

separator must not be an empty string.

The result is a vector, which contains the segments of string that are divided by separator.

The following is an example of usage of the split function.

The separator can contain more than one letter. For example:

Hint: join is an alias of the toDelimitedString method in the vector built-in class.

Observe:The split function is equivalent to:

Note: the split function emulates the function with the same name in JavaScript, and Perl. Similarly, the join method in the vector built-in class emulates the converse functionality that is used in these other languages. The join method prepares a delimited string from a vector of strings.

11.8.5 Square root built-in function

A squareroot function was added. The syntax is:

number must be non-negative.


11.9 NetRexx extensions

roo!™ provides the following capabilities which were innovations of the NetRexx programming language.


12 Built-in classes

There are numerous roo!™ built-in classes. These classes are implemented within the roo!™ interpreter, in a native programming language. Thus, the use of these classes provides improved performance for common programming constructs.

roo!™ programs that you develop can extend built-in classes. The randomSequence.roo example program shows how built-in classes can be extended. The randomSequence.roo program extends a vector explicitly, because class initialization parameters differ in structure from those that are used by a vector. When the class initialization parameters are the same as the built-in class, the explicitly keyword is unnecessary.

Descriptions are provided for the initialize method of each class. The initialize method is usually invoked during class construction. The class construction parameters are passed to the initialize method. The initialize method is only invoked directly by an explicitly derived class. The randomSequence example program explicitly invokes the initialize method of the vector class.

12.1 Built-in class index

The following built-in classes are provided.

12.2 Built-in class hierarchy

The following table uses indentation to indicate built-in class derivation structure. Methods in a base class can be used in a derived class.


12.3 Aggregate built-in classes

Numerous classes are aggregates that store an arbitrary number of other items. Each item is a Rexx value or an instance of another object.

A common set of methods are used within these classes. The methods, that are available for each aggregate class, are listed in their class description.

Observe: aggregate references often involve index values. The Rexx language consistently indexes arguments and string positions with an origin of 1. Consequently, within aggregate methods an index value of 1 references the first item stored in the aggregate. The index must be in the range 1 through size(), inclusive.

Warning: an objection condition is raised when an index is specified that is not within the aggregate's bounds.

12.3.1 Aggregate methods

(1) lines can be separated by an isolated carriage return ('0d'x), an isolated line feed ('0a'x), or a combination of these in either order.

Observe: the various methods that start with 'add', as well as the copyAggregate and removeAll methods, return a string which is a reference to the current instance. This allows the result of the operation to be processed directly as follows:


12.4 BitVector -- extends Object

The BitVector class is excellent for storing a a condensed vector of boolean values of a fixed sizes. The extent can not exceed 4096 bits. The default extent is 128 bits. The active extent can be revised to a more convenient size by using the resize method. When more bits are required, you can make a vector of bitvectors. A substring of bits can be extracted by the getMultiple and getMultipleBytes methods. Similarly, a substring can be assigned by the setMultiple and setMultipleBytes methods. Bits can be accessed with square brackets. You can also process the bits with the LOOP .. OVER instruction.

Bits are indexed using the normal Rexx method. An index of 1 references the first bit location.

Hint: generally you will use a bit vector that is shorter than 4096 bits. In this case, don't forget to use the resize method, otherwise you will get surprises when the toString method is invoked.

12.4.1 BitVector methods

12.4.2 BitVector example usage

The following shows various BitVector method uses. The quoted value in parentheses following the say keyword is the value of the expression to the right of the quoted value.

12.5 CharacterVector -- character values

The CharacterVector class is a vector of single byte values. A reduced set of the vector class methods are supported -- getAt, removeAt, removeAll, setAt, and size.

12.5.1 CharacterVector class methods, additional


12.6 Clipboard -- extends Object

The Clipboard class is used to get text from the system clipboard, or to replace the clipboard text.

Note: some system environments do not have clipboards, so the use of this class may introduce portability difficulties.

12.6.1 Clipboard class methods


12.7 Comparator -- extends Object, non-instantiable

Some built-in classes use an optional comparator object to compare two items. A comparator object extends class comparator and must implement the isLess method as described below. When the comparator object is absent the Rexx less-than ( < ) operator is used instead. The Rexx less-than operator performs a numeric comparison when both items are numeric, otherwise a fixed case string comparison is performed.

This is an abstract description of the interfaces of an actual comparator class instance.

12.7.1 Comparator class method

Note: if either item (or both) being compared is a class instance, then it is up to the isLess method to convert the item to a comparable value. For example, the toString method of the item could be invoked to obtain a comparison value.


12.8 Console -- extends Emitter

The console class is used to read and write characters or strings from or to the console.

12.8.1 Console class method


12.9 ContextVector -- extends Vector, unmodifiable

The ContextVector class is used to analyze active method and procedure invocations. Each line contains the name of an active method or procedure followed by a comma separated list of call arguments.

When method contexts are listed method names are preceded by the class name and a caret.

12.9.1 ContextVector class methods

Example of use:


12.10 DriveContext (aka DiskContext) -- extends Drive

The DriveContext class establishes a drive as the current disk drive. When activated a DriveContext is similar to invoking a command that changes the active disk; i.e. A:

Observe: the drive context that was in effect prior to DriveContext instance creation is always restored, when the instance is removed.

12.10.1 DriveContext class methods

A drive context has the same methods as a drive object.


12.11 Emitter -- extends Object, non-instantiable

The emitter class is used to write characters or strings to an arbitrary output stream. All emitter class derivatives should implement the methods listed below. This allows alternate emitters to be passed as parameters to procedures and methods. An example of a program that uses alternate emitters is qt.rooProgram.

12.11.1 Emitter class method

12.12 Exception -- extends Object, non-instantiable

Exception information that can be referenced by catch condition handlers

12.12.1 Object class methods

12.13 ExternalClass -- extends Object

An ExternalClass is a built-in class that invokes methods in an external program. In Windows system environments the program is a dynamic link library (DLL). An optional call back capability is also supported.

12.13.1 ExternalClass class methods

Note: the externalProgramName is automatically unloaded when all ExternalClass instance usages become inactive. The optional 'terminate' method of the external program is performed before unloading the program.

Note: the external program can call back to methods in a class that extends an ExternalClass instance. The WinList.rooProgram example, and WinList.roo class, illustrate the usage of ExternalClass with a program named WinList.dll.

The following diagram illustrates the components that are used in the WINLIST example.

The external module can optionally provide an entry point named 'SetCallback'. When this entry is present, its is invoked during instance initiation, with an instanceContextLocator argument. This allows the external module to callback to the roo!™ context. If the SetCallback entry is not defined, the external module will not be able to invoke a callback in the roo!™ context.


12.14 File

The File class is used to obtain information about a specific file

12.14.1 File class methods

For some of the following methods the example file name is:


12.15 FolderContext (aka DirectoryContext) -- extends Folder

The FolderContext class establishes a folder as the current folder for subsequent file. system activity. When activated a FolderContext is similar to invoking a CHDIR command.

Observe: the folder context that was in effect prior to FolderContext instance creation is always restored, when the instance is removed.

12.15.1 FolderContext class methods


12.16 InLineFile -- extends Vector

The InLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. When the class is initialized all lines are loaded, and the file is closed. Subsequently, the InLineFile instance can be accessed by any of the Vector class methods, that do not alter line contents.

Observe: a NOTREADY condition is signalled, if enabled, when an attempt is made to read more than the number of available lines.

12.16.1 InLineFile class methods, additional

Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:


12.17 InOutLineFile -- extends List

The InOutLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. The class is intended to revise an existing file. When the class is initialized all lines are loaded. Subsequently, the InOutLineFile instance can be accessed by any of the List class methods. When all instance uses are inactive lines are flushed to the external file associated with the stream, and the stream is closed.

The InOutLineFile class is intended for general file alterations; i.e. deletions and insertions. The related InLineFile and OutLineFile are more appropriate for sequential file access.

Separate line positions are maintained for reading and writing.

Observe: a NOTREADY condition is signalled, if enabled, when an attempt is made to read more than the number of available lines.

12.17.1 InOutLineFile class methods, additional

Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:


12.18 InStream -- extends Object

The outstream class is used to read characters or strings from the default input stream (standard input).

12.18.1 InStream class method


12.19 List -- extends Aggregate

The List class is excellent for storing an arbitrary collection of heterogeneous objects. The performance of getAt and setAt requests is worse than the corresponding vector class. Performance is better than the corresponding vector class when items are inserted or removed at the front or the middle of the list.

12.19.1 Methods:

The list class supports all aggregate class methods.


12.20 Map -- extends Object

The Map class is excellent for storing a keyed collection of heterogeneous items. Each item that is associated with a key can be a Rexx value or an instance reference. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

12.20.1 Methods:

12.21 Object -- non-instantiable

All classes are implicitly derived from the Object class.

12.21.1 Object class methods


12.22 OrderedVector -- extends Aggregate

The OrderedVector class is a vector, with the distinction that all items are ordered. Multiple items can have the same value. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

12.22.1 OrderedVector class methods

Observe: the union, intersection, difference, and nonIntersection methods are unavailable for an OrderedVector. These capabilities can be used by adding a orderedVector aggregate to a set instance, as shown in the first line in the example below.

Here is an example that shows the creation of an OrderedVector, which is immediately converted to a set. Then, various set computations are performed.

Here is an example that shows how the lines of a file can be sorted by an OrderedVector.

The first line above prepares an ordered vector. The second line reads inFileName, and adds the lines to the ordered vector. The final line adds the lines, which are now sorted, to the output file outFileName. The lines are written when the scope of the output LineFile instance concludes.

The above example could be programmed in one instruction as follows

Here is an example that shows how the lines of a file can be sorted in reverse collating order.

Here is an example that shows how the lines of a file can be sorted in a custom order.

Here is an example of a customSort class:


12.23 OutLineFile -- extends Vector

The OutLineFile class is a line-oriented encapsulation of Rexx input/output stream capabilities. The class is intended to prepare a new file, or completely replace an existing file. Subsequently, the OutLineFile instance can be accessed by any of the Vector class methods. When all instance uses are inactive lines are flushed to the external file associated with the stream, and the stream is closed.

The OutLineFile class is intended for sequential writing of lines to a file, rather than deletions and insertions. The related InOutLineFile is more efficient for deletions and insertions.

12.23.1 LineStream class methods, additional

Hint: the file is closed when all instances are no longer active. Often you can accomplish this by dropping the variable that has the file instance value. For example:


12.24 OutStream -- extends Emitter

The outstream class is used to write characters or strings to the default output stream (standard output).

12.24.1 OutStream class method


12.25 Pattern -- extends Object

The Pattern class establishes a regular expression pattern, and extended string search capabilities.

12.25.1 Methods:

Click here to review an example of a pattern match search, that also returns segments.


12.26 PatternMatch -- extends Object, non-instantiable

The PatternMatch class provides information describing matches that occurred during a regular expression pattern search. Instances of the PatternMatch class are created by the search method of the Pattern built-in class.

12.26.1 Methods:

The following is an example of a pattern match search, that also returns segments. There are 2 segments in the pattern. These are defined within the outermost level of paired parentheses. The segments are associated with the following portions of the pattern.

  1. (((1-)?([0-9]{3})-){1,2})

  2. ([0-9]{4})


12.27 Queue -- extends List

The Queue class is excellent for storing an arbitrary collection of heterogeneous objects. These are normally accessed at the beginning or the end. Other methods of the list class are also available; such as: isEmpty, isNonEmpty, size, setAt, and toString.

12.27.1 Methods:


12.28 Set -- extends Aggregate

The Set class is a Vector, with the distinction that all items are unique, and ordered. An optional comparator instance can be assigned to establish a custom ordering of items. When a comparator instance has not been assigned standard, non-strict, Rexx comparisons are used to establish the ordering. Thus, numeric values are in numeric order. String values are in collating order. When class instance values are encountered, their associated value is the result of their 'ToString' method. When the associated class lineage does not have a 'ToString' method, an implicit value is used which is the class name followed by the relative instance index -- i.e. SOMECLASS #3.

12.28.1 Set class methods

The set class supports all aggregate class methods, plus the following methods:

Observe: the union, intersection, difference, and nonIntersection methods compare one set instance versus another set instance, and return a new set class instance. If otherSet value is not a set instance, an OBJECTION condition is optionally raised. If the OBJECTION condition is not actively being trapped, the new instance that is returned will be empty.

Here is an example of the use of two sets.

Here is an example that shows how the set can be sorted in reverse collating order.

Here is an example that shows how a set can be sorted in a custom order. The customSort class is defined below.

Here is an example of a customSort class:


12.29 Stack -- extends Vector

The Stack class is excellent for storing an arbitrary collection of heterogeneous objects. These are normally accessed at the beginning or the end. Other methods of the vector class are also available; such as: isEmpty, isNonEmpty, setAt, size, and toString.

12.29.1 Methods:

12.30 System -- extends Object

The System class is used to access the system name, and other system information.

12.30.1 System class methods

12.31 SystemPropertyMap -- extends Map

The SystemPropertyMap class is used to reference and revise system properties (aka environment variables).

12.31.1 Methods:

The SystemPropertyMap class has the same methods as the map class. The following methods have additional considerations.

The following shows how all environment variables can be displayed.

You can prepare an HTML table containing all system properties as follows.

Observe: the addMap and copyMap methods are supported, but have no effect when applied to a SystemPropertyMap instance. This avoids accidental, undesired revisions to system properties.


12.32 Table -- extends List, non-instantiable

The Table class is a list of vectors. A set of column headings is defined when the table is constructed. Each list element is called a row. Each of the vectors in a row has a fixed number of items, which are called column values. The number of items in a row is the same as the number of column headings. Item values are Rexx values or instances of other objects. References to rows and columns are indexed. A request to 'getAt( 1, 1 )' retrieves the first column value in the first row.

The following diagram may help you understand the nature of a table.

12.32.1 Table class methods

(*) During an add operation, if there are fewer items than the column width, empty strings are added to the other columns. If there are more items in the aggregate, an OBJECTION condition is raised if it is enabled. Otherwise, the extraneous values are ignored.

12.33 Tree -- extends Object

The Tree class is an arbitrary hierarchical object element. It holds three items. A content item is the value associated with this hierarchical element. A child item locates an element that is subordinate to this element. A successor item locates an element that is a subsequent peer of this element.

12.33.1 Tree class methods, additional


12.34 Vector -- extends Aggregate

The Vector class is excellent for storing an arbitrary collection of heterogeneous objects. The performance of getAt and setAt requests is better than the corresponding list class. Performance is worse than the corresponding list class when items are inserted or removed at the front or the middle of the list.

12.34.1 Methods:

The vector class supports all aggregate class methods.

12.35 WideCharacterVector -- Unicode-16 character values

The WideCharacterVector class is a vector of two byte hexadecimal literals, in host byte order. It is particularly designed to be a vector of Unicode-16 character values. A reduced set of the vector class methods are supported -- getAt, removeAt, removeAll, setAt, and size.

12.35.1 WideCharacterVector class methods, additional


r o o ! ™
Copyright © 2002
All Rights Reserved.
E-Mail: rooSupport@kilowattsoftware.com

Last updated on: 6 Jan 2003