Object-Oriented Programming in FreeM

This article's contents should eventually be integrated into the FreeM Manual as part of the official, bundled documentation.

This article documents one or more features currently implemented only in the development branch, and as such, may not apply to any current, official release.

Classes

In FreeM, a class is defined by a routine. For instance, the STRING class (built into FreeM) is contained in the %STRING routine.

Constructors

A constructor must be the first entry point in a class definition, and the label name must match the routine name, and it must take two arguments, THIS and INIT. THIS represents the instance of the object being accessed, and INIT represents an initializer that can be used to assign an initial value to the object when instantiating the class.

A constructor looks like this:

%FRACTION(THIS,INIT):OBJECT ;
   S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1)
   S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2)
   Q

The general syntax of a constructor is <routine-name>(THIS,INIT)[:<superclass>], where superclass represents the name of a class from which this class should inherit. In the above example, the FRACTION class inherits from the OBJECT class. Note that this is not strictly necessary in this case, as all classes automatically inherit from OBJECT.

Destructors

A destructor is called when you KILL an instance variable. It must be named DESTROY, and must take one argument (THIS). The destructor should be used to clean up any resources used by class methods.

A destructor looks like this:

DESTROY(THIS) ;
  ; free any resources that should be freed at the end of the object's lifetime
  Q

Inheritance Rules

Every class you create will automatically inherit the methods and functionality of the OBJECT class, supplied with FreeM.

When attempting to call a method, FreeM will first search the class routine for a matching entry point, and then follow the inheritance chain upwards until a matching entry point is found. If the final class in the chain does not have a matching entry point, FreeM will try to find a matching entry point in the OBJECT class.

Instantiating Classes

To instantiate a class (i.e., create an object from a certain class), you will use the NEW command as follows:

NEW MYSTR=$#^%STRING("myString")

This will create a local variable called MYSTR of type STRING, and initialize it with the value myString.

Defining Class Methods

Class methods are defined as labels with formallists in a class routine, and per the typical FreeM object pattern, must take at least one argument, being THIS (representing a reference to the object instance being accessed).

The following class (MYCLASS) has a constructor, a destructor, and a method called $$MYMETHOD:

%MYCLASS(THIS,INIT) ;
  Q THIS
DESTROY(THIS) ;
  Q
MYMETHOD(THIS) ;
  Q "VALUE"

Runtime Polymorphism with Method Overriding

You can achieve runtime polymorphism by subclassing, and defining methods in the subclass that match the names of existing methods in the superclass. Following FreeM inheritance rules, the overridden method in the subclass will be called, and the method in the superclass will not.

Note that the overridden method in the subclass can take a different set or number of arguments than the formallist of the superclass would specify.

Calling Class Methods

The dot operator is used to invoke class methods:

USER> N MYOBJ=$#^%MYCLASS("")
USER> W MYOBJ.MYMETHOD()
VALUE

Determining an Object's Class at Run-Time

To determine the class of any FreeM local variable, you will use the $$TYPE() method:

USER> W MYSTR.$$TYPE()
^%STRING

The $$TYPE() method is a member of the OBJECT class.

Default Class

M local variables not explicitly instantiated as objects will always appear to be objects of the ^%STRING class, which is supplied with the FreeM distribution.

Retrieving an Object's Value

To retrieve the value of a FreeM object, either dereference the object via the usual M mechanisms, or use the $$VALUE() method:

USER> W MYSTR
myString
USER> W MYSTR.$$VALUE()
myString
USER>

For simple classes, the value of an object retrieved with either method should be the same. However, for more complex classes that override the OBJECT class's $$VALUE() method, they may be different.

Retrieve Numeric Representation of Object

To retrieve a numeric representation of a FreeM object, use the $$TONUMBER() method. Note that this may not retrieve anything if the object has no meaningful numeric representation.

Public and Private Class Fields

FreeM supports private fields with the :PRIVATE specifier in the SET command, enforcing classical object-oriented data encapsulation. The :PUBLIC specifier is provided for completeness, and is the default.

The below constructor for a FRACTION class defines two private fields:

%FRACTION(THIS,INIT):OBJECT ;
   S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1)
   S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2)
   Q

Either of the following commands will create a public field:

  S THIS("VARNAM")="Initial Value"
  S THIS("VARNAM"):PUBLIC="Initial Value"

Attempting to access private fields from outside of the class will raise error condition ZOBJFLDACCV.