III. Classes and objects

III. 1. Classes

III. 1. a. Class declaration

Syntax.

One file contains exactly one class definition.

All other declarations (enumerations, functions, constants, fields) are located only  in classes and belong them.

The are no global (static) class fields, all the fields are members of certain objects.

• The AL-IV code is always located between lines containing symbols of the end and the start of multi-line comments: /* and */.
• Class names are enclosed into figure brackets.
• Class names always start from an uppercase letter.
• Class name can be separated onto two parts by the symbol '|'. Before the symbol a short name of the class is defined, after the '|' symbol - the rest of a long name of the class.
  E.g.: {My|_class} defines short name {My} and full name {My_class} for the same class.
• A long name must not be shorter then 8 characters.
• Class file name (w/o extension) should much the long class name (w/o figure brackets). But violating this rule leads only to a warning, not to an error.

The main part of a class declaration consists of declarations of fields and methods.

• Fields of a class are declared in form
  {type} names = value, modifier
• Type - is one of system simple types BOOL, BYTE, INT, REAL, STR or a class name in figure brackets (its name is starting from an uppercase letter) or a enumeration or a record name in figure brackets (name is starting from a lowercase letter).
• If field and method names are starting from an uppercase letter, then the name is Public.
• If the first letter of a name is in lowercase then the name is hidden. Such methods and fields are accessible only in the module where the class is declared, and in inherited classes.
• Groups of declarations in a class can be separated onto sections with a separator in form:
  ----------- 'separator label'
(at least two '-' signs)
• Each section should not contain more then 7 fields.
• Function declaration also ends a group of declarations.
• If the rule "maximum 7 fields in a section" is not satisfied, then such class must be marked with a modifier BAD.

III. 1. b. Inheritance, modifiers

To specify an ancestor for a class its declaration is written in a form (immediately after IMPORT):

BASE CLASS <Base class name 1>

• If a construction BASE CLASS ... is absent, then the class has no other ancestors except the common for all classes unnamed class {}.
• If the are methods in a class which are overriding correspondent methods of a base class then all those methods are declared starting from a keyword OVERRIDE:

  OVERRIDE some_name(paramer) ==> result_type:                 ... .

• To assign other initial values to fields of a base class and to do something else on a create time of an instance of a class, a procedure is used

  CONSTRUCT :                 ... .

• To do something special when an object is destroyed, a procedure is used

  DESTRUCT :                ... .

• If a destruction procedure is used in a class it is necessary to add a modifier DESTRUCTORS to the header of the class.

When a method is redefined in a class:

• A prefix OVERRIDE is used instead of the METHOD.
• Only one name of the method is specified.
• All the parameters of a base method are listed (in parenthesis, comma separated). First letters of correspondent parameter names must much. Types must be compatible by types and by dimensions (for arrays).
• For methods returning a value:
  • data type of a returning value is specified.
  • An example:
    OVERRIDE FUN enabled ==> BOOL :
      RESULT = o.Edit1.Text != "" .
 

A redefined method can call a base method (the same named method of the base class).

• To call explicitly a base method in a body of a redefined method a syntax is used: BASE.
• All the parameters are passing by a usual way, and the object itself is passed implicitly as usual : Base(parameters).
• A method not returning a value, should at least once call a base method (usually, at the start), else it is necessary to add a modifier REPLACE to the overriding method.

A modifier for a class is written following the class names. Such as:

• ABSTRACT - the class is intended only for deriving new classes on base of this class, it is not allowed to create objects of the class itself.
• BAD - the class is not satisfying requirements on code style (not more then 3 parameters for a function, not more then 3 nesting levels of block statements, not more then 7 fields in a section of a class, not more then 7 simple statement + 7 block statements in a section of a block in a function code).
• BITWISE - bitwise logical operations between integer values are used.
• BYTES - bytes are used in the class.
• DESTRUCTORS - the class has a destructor.
• NATIVE - there are native functions in the class.
• RECURSIVE - there are recursive functions in the class.
• SHORT_STRINGS - strings with a modifier MAXLEN[n] are used in the class.
• STOPPING - a STOP operation is used in the class.
• UNTESTED - there is an untested code in the class.
• SAFE - all is OK, class is tested fully and there are no warnings on a safety or style.
• DEPRECATED('text') - the class is still supported but its using is deprecated. The text in apostrophes contains information about an alternative which should be used as soon as possible still in future the class can become not supported.
• ABANDONED('text') - the class is abandoned. Any reference to it leads to a compilation error. The text contains information about an alternative.

III. 1. c. Objects. Strong and weak references

A variable of a class type (a class instance) is an object of the class.

• Objects are declared by specifying a correspondent class name in figure brackets as a type name of the variable.
  E.g.:
  {My Class} M|y_object = {My_class}
• A field or a variable not having trailing underscore characters in its names, is a keeping reference to an object.
• If an object_ name has a trailing underscore character, it is defined not to own an object but to be just a weak reference to to another object.
• Such weak object reference variable links to it just while it exist and there are object variables referencing such object strongly (or an owner of the object still exists).
• All the local variables in a function are strong references always.
• When a count of strongly referencing variables becomes zero, the object is destroyed and all the weak pointers start pointing to NONE value immediately.
• If at create time for an object an owner was specified explicitly (OWNED BY), then presence of strong references to it has no effect: it will be destroyed together with its owner, and at that moment all the references to it, either strong or weak will be redirected to the NONE object.
• NONE - is a special object of a class, having all the object fields equal to NONE (and 0 for numbers, "" - for strings, etc.). Writing to fields of such pseudo-object is always ignored, reading is always returning NONE and 0 values, calling its methods does not lead no any valuable operations.
• All the object variables initially are set to NONE, and if an object is read out of bounds of an array, also NONE is returned.

• A field F_A of a class A which is a strong reference to an object can not belong to a class B which is a direct ancestor of the class A.
• If a class A has an object field of class B which is a strong reference, then the class B can not have object fields which are strong references to class A
  or other classes which are direct ancestors or inheritances of A.
• When a class A1 references strongly an object of a class A2, and the class A2 references strongly an object of a class A3 and so on, and a class A(n-1) references strongly an object of a class A(n), then the class A(n) can not contain object fields which are strong references to any of previous classes A1, A2, ..., A(n-1).
• It is not possible to refer with a strong reference to an object of the same class, in part.
• As a result, it is not possible to create circled chains of strong references of objects to each others.
• Different kinds of peer networks of objects, graphs, lists etc. can be easy formed using weak_ only pointers.

• A variable is an external to a function if it is:
  • either is a field of the class itself,
  • or it is a field of an external variable,
  • or it is a pseudo-variable RESULT,
  • or it is a field of the RESULT,
  • or it is a field of an object parameter.
• If a newly created object at least once in a function body is assigned to the RESULT variable, then the function should be marked as NEW.
• Function marked as NEW can be called only in a standalone statement like a statement where a new object is created directly. And the new object created with a function marked as NEW, also must be assigned to an external variable, added to an external array or assigned to a temporary variable.
• For a NEW function result it is not allowed to use OWNED BY instruction.

III. 1. d. Methods (events)

All the class functions are virtual.

• The is a polymorphism there: calling a method leads to call a method assigned for a certain class instance, representing an object.

III. 2. Working with objects of classes

III. 2. a. Creating an object instance

Object construction:

variable = {Class_name}(
    Field1 = expression, Field2[] << expression, ...)

• If a value is assigned to a variable in a declaration statement and actually the same type object is created as the variable declared, then type name of the declared variable can be omitted:
  stream|_read_temp = {File_stream}(
       Path = source_path, Mode = 'READ')
• If fields initializations are not necessary, parentheses are omitted.
• If an operation OWNED BY expression is followed (comma separated), this assigns an owner for the object created.
  • For such object, its strong usage counter does not affect its life time: it exists until its owner is destroyed.
  • If at the creation time the object assigned as an owner is referencing NONE, then the object owner is not assigned and it is most possible that the object created will be destroyed on a function end.
• Either an operation of adding the object created to an array of strong references may follow (comma separated):
  , >> variable[]
• An object created should be either assigned to an external (for a function) object field or variable,
  or it should be added to an external array of strong references using postfix operation: , >> array[]
  or an owner should be assigned to an object using postfix operation: , OWNED BY value.

  In other cases a variable on the left side of an assignment should have a substring 'temp' in its name.

A direct creating of an object become impossible if a field is present in an object, which is mandatory to initialize (has a modifier INIT|IALIZE), but it is not accessible (hidden for other modules) or made read-only using a READ modifier. In such cases the only way to create such objects is using a special construction function.

III. 3. Class level operators

The first in a class (following the class header) should be specified a statement IMPORT if it is required. In an import statement classes are listed which are used (including an ancestor class if the class is not descending from the common class {Object}).
IMPORT : {Class1}, {Class2}, ... ;
(the semicolon or the dot can be used to end the IMPORT statement).

If the class has an ancestor in its hierarchy, this should be specified with the statement BASE CLASS {Name}, but after the IMPORT statement where the ancestor class is listed.

The BASE CLASS ... statement is not ended with a dot or semicolon.

A class is always ended with a standalone statement END located in a separate line.

Before the END statement following statements/blocks can be found:

• enumeration declarations
  ENUM {name|detailed} :
     'NAME|DETAILED1'
     'NAME|DETAILED2'
       ...  . 
• structure definitions
  RECORD {name|detailed} :
       Field1
       Field2
         ...   .
• table definitions
  TABLE Name|detailed : {запись}
    NAME "name"
    COUNTER(list)
    NOTNULL(list)
    NAMES(field = "name", ...) .
• field declarations
  TYPE Name|detailed [size] = initialization, modifier
• constructor declaration
  CONSTRUCT:
    BODY .
• destructor declaration
  DESTRUCT:
    BODY .
• static functions declarations
  FUNCTION Name|detailed(parameters) ==> RESULT_TYPE, modifier1,
modifier2, ... :
    BODY .
• methods declarations
  METHOD Name|detailed(parameters) ==> RESULT_TYPE, modifier1,
modifier2, ... :
    BODY .
• overridden methods
OVERRIDE Name(parameters) ==> TYPE, modifier1, ... :
    BODY .
• test functions
  TEST Name|detailed (parameters) ==> TYPE :
     BODY .
• block comments
  --------------------------------- 'text'
• native code directives
  NATIVE: "code specific for a platform" .
• to-do statements
  TODO "text" .