# FreshLib object oriented programming library.

## Introduction

The latest versions of FreshLib, silently migrated to a new object oriented 
programming macro implementation. Now it implements real OOP architecture with 
inheritance, polymorphism, virtual methods and properties.

The implementation uses jump tables, so it is pretty fast, especially compared 
to the previous implementation.

The syntax is based on pseudo-instructions and is compatible with assembly 
language programming style.
 
The main target for this library is the programming of GUI interfaces, because 
the structure of GUI, usually fit very well in the OOP paradigm. But of 
course, the library can be used for general purpose OOP programming. 

## Object definition. Encapsulation
[#object] `object` macro
[#endobj] `endobj` macro

The definition of the object is provided by `object` / `endobj` macros. The 
syntax is very similar to `struct` macros, but the definition can be inherited 
and the body may contain more elements: 

;begin fasm
object NAME[, PARENT]
  BODY
endobj
;end

`PARENT` can be either other object type name or not be specified at all. If `PARENT` is 
missing the object has no parent and does not inherits any fields. If `PARENT` is specified, 
the object inherits all fields from the parent object.

All field names in the object definition must be local names related to the object name, i.e. 
must start with dot character.

The body may contain following elements:

* General FASM data definition fields:

;begin fasm
object TAnimal 
  .length dd ? 
  .height dd ? 
  .weight dd ? 
endobj 
;end

The fields are aimed to provide storage of private for the object data. Of 
course, it is assembly language and the fields are not hidden from the user, 
but a good practice is to not use them as an interface. (There are other 
members that are to be used as an interface - the parameters and methods). 

* object parameter definition through `param` directive. Will be described in 
details later.

* object method definition through `method` directive.  Will be described in 
details later.

### Object parameters; `param` directive;
[#param] `param` macro

The parameters (aka "properties") are object data fields, that are not 
necessary memory cells. Instead their values can be read and write by several 
flexible ways. These ways are transparent for the programmer. The FreshLib 
implementation allows 3 ways to reading writing parameter values:

* By direct read/write to a memory fields. 

* By calling object method that to read or write parameter value using any 
software method, for example computing the value, or reading it from a file or 
even from the network.

* Not reading/writing at all - the parameters can be read-only and/or 
write-only.

The syntax of the definition is:

;begin fasm
    param PARAM_NAME, GET_TARGET, SET_TARGET
;end

`PARAM_NAME` is the name of the parameter. It must be local related to the 
object name (to start with dot).

`GET_TARGET` defines how the value of the parameter will be get. This 
parameters can be either `NONE`, object field name or object method name. In 
the first case, the parameter can't be read. In the second, the read of the 
parameter becomes simple structure field read and in the third, the read of 
the parameter will cause the object method to be call and the return value of 
the method will be accepted as a value of the parameter.

The get method must have no arguments and must be defined in the object 
definition as normal method. 

`SET_TARGET` defines how the value will be write to the parameter. Again we 
can use `NONE`, field name or method name. The only difference with the 
`GET_TARGET` is that the set method has one argument - the new value of the 
parameter.

### Object methods; `method` directive; `abstract` directive;
[#method] `method` macro
[#abstract] `abstract` macro

This directive defines a method field in the object. The syntax is very 
similar to the `proc` macro directive:

;begin fasm
  method NAME, [ARGUMENTS]
or
  abstract NAME, [ARGUMENTS]
;end

`NAME` must be local related to the object name. The arguments can be 
arbitrary count and  also must start with dot (local).

Besides the explicitly defined arguments, one hidden argument `.self` is 
defined for every method, that contains a pointer to the object instance in 
the moment when the method is called. The `.self` argument is the first of all 
arguments in the method.

The only difference between `method` and `abstract` variants is that the 
methods defined with `abstract` keyword does not need to be implemented in the 
given class. The abstract methods are simply placeholders for the children 
object methods. They allow polymorphic calls of the method in the children 
objects.

Every non-abstract method, defined in the object need to be implemented later 
in the code. The implementation looks just like `proc` procedure definition, 
with the difference that `method` keyword is used. In the implementation, 
there is no arguments, because they are already defined in the object type 
definition.

The methods can be override in the children classes. The inherited method is 
still accessible through `inherided` command. This way the methods chains can 
be called when needed.

;begin fasm
method OBJ_NAME.METHOD_NAME
begin
  CODE
endp
;end

As is seen from the above description, the object type itself contains in the 
same container (capsule) all needed data and the code, needed to process this 
data. This property of the objects is called *Encapsulation*.

Some think that "encapsulation" is something about hiding data or code inside 
the objects, but this is not the case in the common case. 

And of course in assembly language hiding data or code is impossible at all. 
The user have always access to all data fields and code in the object. There 
is no private fields or methods. It is simply not the assembly way.  

## Example of object definition with inheritance.

  [!1:_images/catdog.png][Fig.1 Inheritance]

In the following example can be seen all the above syntax in practice. The 
type `TAnimal` defines several common data fields, the parameter `.Energy` 
that is read-only and gives the current kinetic energy of the animal and the 
abstract method `.Jump` that is not implemented for TAnimal, as long as the 
different animals jumps differently and need special implementation.

The children types `TCat` and `TDog` implements their own methods `.Jump`.

;begin fasm
        object TAnimal
          .length   dd ?
          .height   dd ?
          .weight   dd ?
          .speed    dd ?

          param    .Energy, .GetEnergy, NONE

          method   .GetEnergy
          abstract .Jump, .height
        endobj

        object TCat, TAnimal
          method .Jump, .height
        endobj

        object TDog, TAnimal
          method .Jump, .height
        endobj

        method TAnimal.GetEnergy
        begin
                push    ecx
                mov     ecx, [.self]
                mov     eax, [ecx+TAnimal.speed]
                imul    eax, eax
                imul    eax, [ecx+TAnimal.weight]
                sar     eax, 1                        ; E = m.v^2/2
                pop     ecx
                return
        endp

        method TCat.Jump
        begin
        ; code that makes the cat jump not as other animals.
                return
        endp

        method TDog.Jump
        begin
        ; code that makes the dog jump not as other animals.
                return
        endp
;end



## Object manipulation macros.

### Creating objects
[#create] `create` macro

Once the object is defined, the user can create object instances, using the 
macro instruction `create`. The syntax is:

;begin fasm
create DST, TYPE
;end

The macro allocates memory for the object instance, fills needed fields and 
executes the method Create if such is defined for the given object type.

`DST` is the destination where we want the pointer to the object instance to 
be stored. Can be register or memory location. Same as for `mov` instruction.

`TYPE` is an object type, previously defined with `object` macro.

### Destroy object.
[#destroy] `destroy` macro

The allocated object instance must be destroyed when not needed with the macro 
instruction `destroy`. The syntax is:

;begin fasm
destroy SRC
;end

`SRC` is a pointer to the object instance. Can be register or memory content. 

The macro will first call the Destroy method of the object if such is defined 
and then will free the allocated dynamic memory.

### Set/Get object parameters.
[#get] `get` macro
[#set] `set` macro

The value of object parameter can be get with the macro `get`. The syntax is:

;begin fasm
get DST, PTR_OBJ, TYPE:PARAM
;end 

The macro gets the value of `TYPE:PARAM` parameter of the object `PTR_OBJ` and 
store it in `DST`. 

`DST` and `PTR_OBJ` can be register or memory location, TYPE must be already 
defined object type and PARAM parameter, defined in this object or any of its 
predecessors.

Notice, the `TYPE` and `PARAM` must be separated by colon ":", not a dot.

The value of object parameter can be set to new value with the macto `set`. 
The syntax is similar to the previous, only in different order:

;begin fasm
  set PTR_OBJ, TYPE:PARAM, VALUE
;end

`PTR_OBJ` is the object which parameter have to be set.

`TYPE:PARAM` specifies the parameter name.

`VALUE` is the new value of the parameter.

### Executing object methods.
[#exec] `exec` macro

The macro instruction `exec` executes some object method. The syntax is:

;begin fasm
exec PTR_OBJ, TYPE:METHOD, [ARG]
;end

The macros has various count of arguments, depending on the arguments the 
method accepts. 

`TYPE:METHOD` must be valid combination of defined object type and method 
name, separated by colon ":".

### Check object type
[#istype] `istype` macro

The user can check whether the object belongs to some type by using "istype" 
macro instruction:

;begin fasm
        istype OBJECT, TYPE
;end

This macro returns ZF flag set if the object belongs to the type or ZF cleared 
if not. It will not change any registers.

For example, see following code:

;begin fasm
        create eax, TCat        ; create object instance.

        istype eax, TCat
        je     .yes_cat         ; ZF=1  It is a TCat...

        int3

.yes_cat:
        istype eax, TAnimal
        je     .yes_animal      ; ZF=1  ...also, it is TAnimal...

        int3

.yes_animal:
        istype eax, TDog
        je     .yes_dog         ; ZF=0  ...but is it NOT TDog.

        int3                    ; will stop here

.yes_dog:
;end

## Polymorphism

Polymorphism is one of the main properties of the OOP. It is the ability of 
the object to execute different code on the same method call, depending on its 
type.

   [!2:_images/poly.png][Fig.2 Polymorphism]

In the context of our library, as long as the types inherit all the methods of 
its parents and can redefine it, it means, that in the above example, `TCat` 
and `TDog` both have method `.Jump`, inherited from `TAnimal`. (In this sense, 
they are both of type `TAnimal`), but the implementation of `TCat.Jump` and 
`TDog.Jump` differs.

This way, we can use the same code to process both types.

;begin fasm
        create  eax, TCat
        create  ebx, TDog

        exec    eax, TAnimal:Jump, 100 
        exec    ebx, TAnimal:Jump, 100 
;end

You can see, that the same code will call in the first case `TCat.Jump` and in 
the second case `TDog.Jump` methods.

