User-defined classes

User-defined classes

A user class is defined in a file of such a format:

@CLASS
name_of_class

# optional
@OPTIONS   [3.3.0]
locals
partial
dynamic or static   [3.4.1]

# optional
@USE
file_with_parent_class

# optional
# user-defined class can't be based on system classes [3.4.0]
@BASE
name_of_parent_class

# recommended way to name method-constructor of the class
@create[parameters]

# other methods are defined
@method1[parameters]
…

Module can be linked (see "Linking modules") to any file, which will then be able to use the class defined here.
If unknown class was specified, the method autouse of class MAIN will be called and specified class name will be passed to it as the only parameter. [3.4.0]

If @CLASS is not specified, the file will define a number of additional operators.

If method
@auto[]

is defined, it will be automatically called as a static method (so-called static constructor) each time the class is loaded. It is used to initialize static fields of the class.

Note: result of the method's work is ignored, i.e. doesn't get anywhere.
Note: method @auto[] is not inherited . [3.4.1]

If method is defined to receive the parameter:
@auto[filespec]
In that parameter Parser will pass full name of file containing the method.

Created classes inherit methods of parent classes. Inherited methods can be redefined.

In case one user class must use another one as parent, the file with the parent class should be linked to it, and parent class - declared as base (@BASE).

To use methods and fields of parent classes, the following constructions should be used:

^class:method[parameters]-to call a method of parent class (note: although the syntax of calling such a method looks like the syntax of calling a static method, in fact, in case of dynamic method, the method of parent class will be called dynamically). To refer to the nearest parent class (base class) you may use constructions ^BASE:constructor[parameters] and ^BASE:method[parameters].
Note: similary base class properties can be accessed - $BASE:property è $BASE:property[value].   [3.4.5]

Using @OPTIONS you can set additional class behaviour.
Thus option locals automatically declare all variables in all methods of this class as local. If this option specified you must use system variable self for accessing to class or object's field.

With partial option you can allow future class modifications. If specified and you load new file with use operator which contain the same class name and the same option, the methods from this file will be added to previously loaded class instead of creating a new one with the same name. This option can be useful for loading huge and seldom used methods to the class by demand.

With static and dynamic options you can specify the allowed methods' call types. All methods could be called statically or dynamically by default which could be unsafe.

Note: trailing white-space characters in meta-comands @USE, @CLASS, @BASE, @OPTIONS will be ignored [3.4.1]

Working with variables in static methods
Value of the variable ($name) is searched for in:

·	the list of local variables;

·	the current class or its parent classes.

The value will be assigned ($name[value]) to already existing variable (see the search area given above), if it does exist. Otherwise, a new variable (field) will be created within the current class.

Working with variables in dynamic methods
Value of the variable ($name) is searched for in:

·	the list of local variables;

·	the current object;

·	the current object class or its parent classes.

The value will be assigned ($name[value]) to already existing local variable, if it does exist. Otherwise, the value will be assigned to a variable (field) within the current object. [3.4.5]

Note: try to avoid using fields of class beyond the methods of the class except simplest cases. We should try to communicate with an object through its methods only.

Object's system field: CLASS
$class:CLASS-contains reference to the object's class

You may need this value to specify the scope of code's compilation (cf. "Process. Compiling and processing string").

This reference can also be used to retrieve static fields of the class, for example:

@main[]
^method[$cookie:CLASS]

@method[storage]
$storage.field

As a result, value of $cookie:field be output.

Object's class name: CLASS_NAME [3.2.2]
$object.CLASS_NAME-contains object's class name

Example:
$var[123]
$var.CLASS_NAME

This example prints 'string'.

Last updated: 14.04.2017