--- freem/doc/freem.texi 2025/04/18 19:43:18 1.28 +++ freem/doc/freem.texi 2025/04/18 22:02:33 1.29 @@ -4405,11 +4405,15 @@ An @code{INTEGER} is an interpretation o @cindex data types, REAL @cindex types, REAL +A @code{REAL} is a numeric interpretation of data including a fractional part. + @node STRING @section STRING @cindex data types, STRING @cindex types, STRING +A @code{STRING} is any data in FreeM. + @node Custom Types (Classes) @section Custom Types (Classes) @cindex data types, custom @@ -4482,30 +4486,126 @@ See @ref{Classes}. @cindex programming, object-oriented @menu -* Classes:: The basis of object-oriented programming. +* Classes:: The basis of object-oriented programming. +* Inheritance:: Basing one class upon another. +* Methods:: Attaching code to a class. +* Public and Private Variables:: Managing class member access. @end menu @node Classes @section Classes -@menu -* Inheritance:: Basing one class upon another. -* Methods:: Attaching code to a class. -* Public Variables:: Variables visible outside of a class. -* Private Variables:: Variables only visible within a class. -@end menu +A @emph{class} is the primary organizing concept of FreeM support for object-oriented programming, and in FreeM, is simply an M routine with a few special properties: + +@example +MYCLASS(THIS,INIT):OBJECT ; Constructor for MYCLASS, inherits OBJECT + ; two private variables + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q + ; +DESTROY(THIS) ; This is the destructor + Q +@end example + +The above example demonstrates general class syntax. + +@node Constructors +@subsection Constructors + +A @emph{constructor} is an M entry point that is called when a new instance of a class is created. + +A constructor must be the first entry point in a class routine, its tag must match the class/routine name, and it must take two arguments, @code{THIS} and @code{INIT}. + +@code{THIS} represents the instance of the object being accessed, and @code{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: + +@example +%FRACTION(THIS,INIT):OBJECT ; + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q +@end example + +@emph{Syntax} +@example +@emph{}(THIS,INIT)[:@emph{}] +@end example + +In the above example, @emph{} represents the name of a class from which this class should inherit. In this case, the @code{FRACTION} class inherits from the @code{OBJECT} class. Note that this is not strictly necessary in this case, as all classes in FreeM automatically inherit from @code{OBJECT}. + +@node Destructors +@subsection Destructors +A @code{destructor} is called when you @code{KILL} an instance variable. Its tag must be @code{DESTROY}, and it must take one argument (@code{THIS}). + +The destructor should be used to clean up any resources used by class methods. + +A destructor looks like this: + +@example +DESTROY(THIS) ; + ; free any resources that should be freed at the end of the object's lifetime + Q +@end example @node Inheritance -@subsection Inheritance +@section Inheritance + +Every class you create will automatically inherit the methods and functionality of the @code{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 @code{OBJECT} class. + +Inheritance is achieved by specifying the name of the superclass in the constructor: + +@example +CLASS(THIS,INIT):SUPERCLASS +@end example + +@node Runtime Polymorphism +@subsection Runtime Polymorphism + +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 @emph{formallist} of the superclass method would specify. @node Methods -@subsection Methods +@section Methods +Class methods are defined as tags with @emph{formallist}s in a class routine, and per the typical FreeM object pattern, must take at least one argument, being @code{THIS} (representing a reference to the object instance being accessed). + +The following class (@code{MYCLASS}) has a constructor, a destructor, and a method called @code{MYMETHOD}: -@node Public Variables -@subsection Public Variables +@example +%MYCLASS(THIS,INIT) ; + Q THIS +DESTROY(THIS) ; + Q +MYMETHOD(THIS) ; + Q "VALUE" +@end example + +@node Public and Private Variables +@section Public and Private Variables + +FreeM supports private fields with the @code{:PRIVATE} specifier in the @code{SET} command, enforcing classical object-oriented data encapsulation. The code{:PUBLIC} specifier is provided for completeness, and is the default. + +The below constructor for a @code{FRACTION} class defines two private fields: + +@example +%FRACTION(THIS,INIT):OBJECT ; + S THIS("NUMERATOR"):PRIVATE=$P(INIT,"/",1) + S THIS("DENOMINATOR"):PRIVATE=$P(INIT,"/",2) + Q +@end example + +Either of the following commands will create a public field: + +@example + S THIS("VARNAM")="Initial Value" + S THIS("VARNAM"):PUBLIC="Initial Value" +@end example -@node Private Variables -@subsection Private Variables +Attempting to access private fields from outside of the class will raise error condition @code{ZOBJFLDACCV}. @node Libraries @chapter Libraries