Variety: |
procedure |
Syntax: |
method(identifier1,integer1,integer2, integer3,integer4,integer5,sequence1) |
Context: |
Class definition. |
Description: |
Defines a method named identifier1 in the class currently being
defined. Integer1 specifies the number of parameters. Integer2 is INSTANCE or
CLASS to specify the method's target. Integer 3 specifies a |
Errors: |
Program termination if:
|
Variety: |
constant |
Description: |
The integer 0 used in the sense of "no meaningful data", typically the return value of a method which is logically a procedure. |
Variety: |
constant |
Description: |
The empty sequence. A notational convenience, particularly when a sequence is intended as a list. |
Variety: |
constant |
Description: |
Used in class() or method() to declare a normal class or method. |
NULL_CLASS
Variety: |
constant |
Description: |
Possible return value of class_type(). |
Variety: |
constant |
Description: |
Used in place of a routine id in link_handler() to specify a do-nothing event handler. |
Variety: |
constant |
Description: |
Pre-created instance of Null_Class, used in error reporting. |
Variety: |
constant |
Description: |
Used in place of a routine id in method() to specify a do-nothing method which returns a value specified by the default parameter of method(). |
Variety: |
procedure |
Syntax: |
package(string1) |
Contexts: |
Main program; no pending exception. |
Description: |
Defines a package named string1. All classes, interfaces, and exceptions defined until the next package() is encountered will be part of this package. Leading and trailing spaces are stripped and multiple intermediate spaces are reduced to single spaces; so " My Package " and "My Package" are the same package. If string1 is the empty string, the package is set to "Diamond Default". |
Errors: |
Program termination if string1 contains characters < ASCII 32. |
Variety: |
constant |
Description: |
Used in property() to specify a persistent property--a property which can be saved and restored. |
Variety: |
constant |
Description: |
Used in property(), method(), or event() to specify private access for a property, method, or event. |
Variety: |
function |
Syntax: |
sequence1=program_stack() |
Contexts: |
All. |
Description: |
Returns a sequence representing all pending methods and events, beginning with the currently executing method or event. Each element of the sequence will be a three-element sequence in the format {target,"Method_Name#0",NONE} or {target,NONE,"Event_Name#0}, where target is the target entity upon which the method was called or the event was raised. In main program or class definition contexts, returns NONE. |
Errors: |
None. |
Variety: |
procedure |
Syntax: |
property(identifier1,integer1,object1, object2,integer2,object3) |
Contexts: |
Class definition. |
Description: |
Defines a property named identifier1 in the class currently being defined.. Integer1 is INSTANCE or CLASS to specify the type of property. Object1 is either an integer which specifies PUBLIC, PROTECTED, or PRIVATE read access or a two-element sequence: the first element is an integer which specifies read access, the second element is the routine id of the property's getter function. Object2 is either an integer which specifies PUBLIC, PROTECTED, or PRIVATE write access or a two-element sequence: the first element is an interger which specifies write access, the second element is the routine id of the property's setter function. Integer2 is PERSISTENT or TRANSIENT to specify whether or not the property can be saved and restored. Object3 is the initial value of the class property of the class and of its subclasses, or the initial value of the instance property for each newly-created instance of the class and of its subclasses, as the case may be. See Accessors. |
Errors: |
Program termination if:
|
Variety: |
constant |
Description: |
Used in property(), method(), or event() to specify protected access for a property, method, or event. |
Variety: |
constant |
Description: |
Used in property(), method(), or event() to specify public access for a property, method, or event. |
Variety: |
procedure |
Syntax: |
raise_event (entity1,identifier1,sequence1) |
Contexts: |
Main program, method, event; no pending exception. |
Description: |
Raises the appropriate event of entity1's class with entity1 as its target. If entity1 is an instance, an instance event is raised; if a class, class event is raised. Identifier1 gives the name of the event and the number of parameters is the length of sequence1. Sequence1 is passed to the event handlers as their parameters (if any). The prehandler method is called first. Each handler if there are any will be called in the order specified with link_handler(). The posthandler method will be called last. If cancel_event() is executed, an exception is thrown or the target is deleted, no further handlers are called. |
Note: |
Be careful of one parameter events when passing a sequence or entity. For example: raise_event(x,"DoThis","ABC") does not pass ABC to x's DoThis#1 event handlers--it passes 'a', 'b', and 'c' to x's DoThis#3 event handlers. The correct syntax is raise_event(x,"DoThis",{"ABC"}). Similarly, if y is an entity, then raisel_event(x,"DoThat",y) will split y into the components of its handle and pass them to x's DoThat#3 event handlers. Correct syntax to pass y to x's DoThat#1 event handlers is raise_event(x,"DoThat",{y}). |
Errors: |
Program termination if:
|
Variety: |
function |
Syntax: |
sequence1=restore_entity(string1) |
Contexts: |
Main program, method, event; no pending exception. |
Description: |
String1 is a coded byte string created by save_entity(). If it is possible to restore the entity encoded in the string, restores the entity with all of its persistent property values (including other entities). If a value is provided for a property which is not a persistent property of the entity, the value is ignored. If a persistent property of the entity has no value provided for it, the initial value defined by the property() procedure defining the property is used for an instance, the current value is used for a class; this initial value or current value is also used for a transient properties. Returns the handle of the restored entity. If restoration fails (string1 is not a coded byte sequence or has become corrupt; or string1 encodes an entity of a class not defined in the current program), returns Null_Instance. In the same run of the same program which saved the entity, if the entity's class implements Do_Not_Clone, restores the entity as Null_Instance or Null_Class. This limitation does not apply to different programs or different runs of the same program. If an instance entity is being restored, automatically calls the entity's class' After_Restore#0 instance method after restoring the instance. If a class entity is being restored, calls the class' Before_Restore#0 class method before restoring the class, then calls the class' After_Restore#0 class method after restoring the class. This process is also applied to any property values which are entities. |
Note: |
There is no way to distinguish a failed restore_entity() from a successful restore_entity() of a byte string which encodes Null_Instance. |
Errors: |
Program termination if:
|
Variety: |
function |
Syntax: |
boolean1=same_class(object1,object2) |
Contexts: |
All. |
Description: |
Returns TRUE if object1 and object2 are entities and both belong to the same class; otherwise returns FALSE. |
Errors: |
None. |
Variety: |
function |
Syntax: |
string1=save_entity(entity1) |
Contexts: |
Main program, method, event; no pending exception. |
Description: |
Transforms an entity into a coded byte string. All persistent property values of the entity are saved, including other entities; transient properties are not saved. If an instance entity is being saved, automatically calls the entity's class' Before_Save#0 instance method before saving the instance, then calls the entity's class' After_Save#0 instance method after saving the instance. If a class entity is being saved, calls the class' Before_Save#0 class method before saving the class, then calls the class' After_Save#0 class method after saving the class. This process is also applied to any property values which are entities. |
Errors: |
Program termination if:
|
Variety: |
procedure |
Syntax: |
set_property(entity1,identifier1,object1) |
Contexts: |
Main program, method, event. |
Description: |
If entity1 is an instance, sets the instance property named identifier1 of the instance. If entity1 is a class, sets the class property named identifier1 of the class. Object1 is the value to which the property is set. If a setter is defined for this property, passes the current property value and object1 to the setter and sets the property to the setter's return value. See Accessors. |
Errors: |
Program termination if:
|
Variety: |
function |
Syntax: |
Class_entity1=simple_class(identifier1,integer1,object1,object2) |
Contexts: |
Main program; no pending exception. Class definition for inner classes. |
Description: |
Passes its parameter to class(), calls end_class(), then returns the class entity returned by class(). |
Note: |
This allows a single function to define a class which has only the properties, methods, and events inherited from its superclass. |
Errors: |
Variety: |
function |
Syntax: |
boolean1=success() |
Contexts: |
Main program, method, event. |
Description: |
Returns TRUE if no exception is currently pending, otherwise FALSE. |
Errors: |
None. |
Variety: |
function |
Syntax: |
integer1=super() |
Contexts: |
Method. |
Description: |
Returns a specially modified entity handle. When used as the target of call_method(), calls an instance method or class method with this() as its target. The method will be an instance or class method of the immediate superclass of the class which defines the method currently executing. This allows an overridden method to be called by the overriding method (or any other method of the class which overrides the method). |
Note: |
Do not use super() for any other purpose; while it is not an error to use super() in any other way in a method, only call_method() will interpret it correctly. |
Errors: |
None. |
Variety: |
function |
Syntax: |
integer1=super_class() |
Contexts: |
Method. |
Description: |
Returns a specially modified entity handle. When used as the target of call_method(), calls a class method with this_class() as its target. The method will be a class method of the immediate superclass of the class which defines the method currently executing. This allows an overridden method to be called by the overriding method (or any other method of the class which overrides the method). |
Note: |
Do not use super_class() for any other purpose; while it is not an error to use super_class() in any other way in a method, only call_method() will interpret it correctly. |
Errors: |
None. |
Variety: |
constant |
Description: |
Used in method() in place of a routine id to specify a method which simply passes its parameters to the superclass method it overrides. |
Variety: |
function |
Syntax: |
entity1=this() |
Contexts: |
Method, event. |
Description: |
Returns the target of the method or event currently executing. |
Errors: |
None. |
Variety: |
function |
Syntax: |
class_entity1=this_class() |
Contexts: |
Method, event. |
Description: |
Returns the class of the target of the method or event currently executing. |
Note: |
Faster-executing syntactic sugar for get_class(this()). Intended for instance methods and events; in class methods and events, this_class() is legal but redundant, having the same value as this(). |
Errors: |
None. |
Variety: |
function |
Syntax: |
string1=this_event() |
Contexts: |
All. |
Description: |
Returns the name of the currently executing event in Event_Name#0 format. If no event is currently executing, returns the empty string. |
Errors: |
None. |
Variety: |
function |
Syntax: |
string1=this_method() |
Contexts: |
All. |
Description: |
Returns the name of the currently executing method in Method_Name#0 format. If no method is currently executing, returns the empty string. |
Errors: |
None. |
Variety: |
procedure |
Syntax: |
throw(class_entity1) |
Contexts: |
All except class definition. |
Description: |
Sets the pending exception to class_entity1, which must be an exception. |
Errors: |
Program termination if:
|
Variety: |
constant |
Description: |
Used in property() to specify a transient property--a property which cannot be saved and restored. |
Variety: |
constant |
Description: |
The integer 1 used as a boolean. |
Variety: |
function |
Syntax: |
sequence1=try_call (entity1,identifier1,sequence2) OR |
Contexts: |
All, but never succeeds in Class Definition. |
Description: |
Attempts to execute call_method(entity1,identifier1,sequence2). Returns a two-element sequence. The first element is a boolean indicating the success or failure of the attempt. In case of success, the second element is the return value of the method. In case of failure, the second element is an error message. |
Errors: |
None. |
Variety: |
function |
Syntax: |
sequence1=try_get(entity1,identifier1) |
Contexts: |
All, but never succeeds in Class Definition. |
Description: |
Attempts to execute get_property(entity1,identifier1). Returns a two-element sequence. The first element is a boolean indicating the success or failure of the attempt. In case of success, the second element is the property value. In case of failure, the second element is an error message. |
Errors: |
None. |
Variety: |
procedure |
Syntax: |
sequence1=try_link(entity1,sequence2,object1) |
Contexts: |
All, but never succeeds in Class Definition. |
Description: |
Attempts to execute link_handler(entity1,sequence2,object1). Returns a two-element sequence. The first element is a boolean indicating the success or failure of the attempt. In case of success, the second element is NIL. In case of failure, the second element is an error message. |
Errors: |
None. |
Variety: |
function |
Syntax: |
sequence1=try_raise (entity1,identifier1,sequence2) |
Contexts: |
All, but never succeeds in Class Definition. |
Description: |
Attempts to execute raise_event(entity1,identifier1,sequence2). Returns a two-element sequence. The first element is a boolean indicating the success or failure of the attempt. In case of success, the second element is NIL. In case of failure, the second element is an error message. |
Errors: |
None. |
Variety: |
function |
Syntax: |
sequence1=try_set(entity1,identifier1,object1) |
Contexts: |
All, but never succeeds in Class Definition. |
Description: |
Attempts to execute set_property(entity1,identifier1,object1). Returns a two-element sequence. The first element is a boolean indicating the success or failure of the attempt. In case of success, the second element is NIL. In case of failure, the second element is an error message. |
Errors: |
None. |
Variety: |
variable |
Description: |
Used to discard unwanted return values, particularly the return values of a method which is logically a procedure and has no meaningful return value. Do not use VOID for any other purpose. |
Note: |
If your program attempts to read VOID, it will always have a value of 0. |