method

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 NORMAL, FINAL, or ABSTRACT method. Integer4 specifies PUBLIC, PROTECTED, or PRIVATE access. Integer5 is the routine id of the method or SUPER_METHOD or NULL_METHOD or ABSTRACT_METHOD. Sequence1 is a sequence of default parameters (may be empty) to be appended to the parameters passed by call_method when the method is called. (When integer5 is NULL_METHOD, sequence1 must be empty, or have a length of 1. The single element specifies the return value; an empty sequence specifies a return value of NIL. When integer5 is ABSTRACT_METHOD or SUPER_METHOD, sequence1 must be empty.)

Errors:

Program termination if:

  • The class is an exception.
  • The class is an interface and integer3 is not ABSTRACT or integer4 is not PUBLIC.
  • Identifer1 duplicates an instance method name or class method name (as the case may be) of the class and integer1 duplicates the number of parameters of that instance or class method.
  • Integer1 is negative.
  • Integer2 is not INSTANCE or CLASS.
  • Integer3 is not NORMAL, FINAL, or ABSTRACT.
  • Integer3 is ABSTRACT and the class is not an abstract class or an interface.
  • Integer4 is not PUBLIC, PROTECTED, or PRIVATE.
  • Integer5 is NULL_METHOD and sequence1 has a length greater than 1.
  • Integer5 is ABSTRACT_METHOD or SUPER_METHOD and sequence1 has a length greater than 0.
  • In a normal or final method, integer5 is not a valid routine id or SUPER_METHOD or NULL_METHOD.
  • In an abstract method, integer5 is not ABSTRACT_METHOD.
  • The method does not override a superclass method and integer5 is SUPER_METHOD.
  • The method overrides a superclass method and:
    • The overridden method is a final method.
    • Integer3 is ABSTRACT and the overridden method is not an abstract method.
    • Integer4 specifies more restrictive access than the overridden method.
    • Integer5 is SUPER_METHOD and the overridden method is private or abstract.

 

NIL

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.

 

NONE

Variety:

constant

Description:

The empty sequence. A notational convenience, particularly when a sequence is intended as a list.

 

NORMAL

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

 

NULL_HANDLER

Variety:

constant

Description:

Used in place of a routine id in link_handler() to specify a do-nothing event handler.

 

Null_Instance

Variety:

constant

Description:

Pre-created instance of Null_Class, used in error reporting.

 

NULL_METHOD

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

 

package

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.

 

PERSISTENT

Variety:

constant

Description:

Used in property() to specify a persistent property--a property which can be saved and restored.

 

PRIVATE

Variety:

constant

Description:

Used in property(), method(), or event() to specify private access for a property, method, or event.

 

program_stack

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.

 

property

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:

  • The class is an interface or an exception.
  • Identifier1 duplicates an instance property name or class property name (as the case may be) of the class or of any of its superclasses.
  • Integer1 is not INSTANCE or CLASS.
  • Object1 or Object2 are not formatted as above.
  • Integer2 is not PERSISTENT or TRANSIENT.

 

PROTECTED

Variety:

constant

Description:

Used in property(), method(), or event() to specify protected access for a property, method, or event.

 

PUBLIC

Variety:

constant

Description:

Used in property(), method(), or event() to specify public access for a property, method, or event.

 

raise_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:

  • Entity1 is a deleted instance, an interface, or an exception.
  • The event to be raised is not defined by entity1's class.
  • The currently executing method, event, or main program has inadequate access rights to raise the event.

 

restore_entity

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:

  • Any method called or event raised attempts to call restore_entity() or save_entity(), directly or indirectly.

 

same_class

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.

 

save_entity

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:

  • Any method called or event raised attempts to call save_entity() or  restore_entity(), directly or indirectly.

 

set_property

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:

  • Entity1 is a deleted instance, an interface, or an exception.
  • The property to be written is not defined by entity1's class.
  • The currently executing method, event, or main program has inadequate access rights to write the property.

 

 

simple_class

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:

See class() and end_class().

 

 

success

Variety:

function

Syntax:

boolean1=success()

Contexts:

Main program, method, event.

Description:

Returns TRUE if no exception is currently pending, otherwise FALSE.

Errors:

None.

 

super

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.

 

super_class

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.

 

SUPER_METHOD

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.

 

this

Variety:

function

Syntax:

entity1=this()

Contexts:

Method, event.

Description:

Returns the target of the method or event currently executing.

Errors:

None.

 

this_class

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.

 

this_event

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.

 

 

this_method

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.

 

throw

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:

  • Class_entity1 is not an exception.
  • An exception is already pending. (But throwing Type_Check_Failure does not terminate if the pending exception is also Type_Check_Failure.)

 

 

TRANSIENT

Variety:

constant

Description:

Used in property() to specify a transient property--a property which cannot be saved and restored.

 

 

TRUE

Variety:

constant

Description:

The integer 1 used as a boolean.

 

try_call

Variety:

function

Syntax:

sequence1=try_call (entity1,identifier1,sequence2) OR
sequence1=try_call(super(),identifier1,sequence2) OR
sequence1=try_call(super_class(),identifier1,sequence2)

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.

 

try_get

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.

 

try_link

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.

 

try_raise

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.

 

try_set

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.

 

VOID

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.

 

PREV PAGE ----- NEXT PAGE