--- freem/doc/freem.texi 2025/05/05 05:16:34 1.44 +++ freem/doc/freem.texi 2025/05/05 12:55:17 1.47 @@ -271,12 +271,14 @@ Refers to an M intrinsic special variabl Indicates a @emph{list} of the following item, e.g., @emph{L gvn} means @emph{list of global variable names}. @item @emph{lvn} Refers to the name of an M local variable. +@item @emph{postcondition} +A @emph{tvexpr} immediately following a command verb affecting that command's execution. @item @emph{strlit} Refers to an M string literal. @item @emph{ssvn} Refers to the name of an M structured system variable. @item @emph{tvexpr} -Refers to a truth-valued expression. +Refers to a truth-valued expression, i.e., an expression interpreted as a truth value. @end table @node A Note on Standards @@ -2011,7 +2013,6 @@ Identical to @ref{$TRANSLATE()}, except * !:: Run an external program or command. * !!:: Launch a subshell from FreeM direct mode. * ABLOCK:: Increment the block counter for one or more event classes. -* ASSERT:: Raise error when a conditional expression evaluates @emph{false}. * ASTART:: Enable asynchronous event handling for one or more event classes. * ASTOP:: Disable asynchronous event handling for one or more event classes. * AUNBLOCK:: Decrement the block counter for one or more event classes. @@ -2043,6 +2044,7 @@ Identical to @ref{$TRANSLATE()}, except * VIEW:: Modify FreeM internal parameters. * WRITE:: Write output to current input/output device. * XECUTE:: Interpret string as M code. +* ZASSERT:: Raise error when a conditional expression evaluates @emph{false}. * ZBREAK:: Unknown. * ZCONST:: Define a constant that cannot be altered after initial definition. * ZGO:: Unknown. @@ -2182,41 +2184,6 @@ In its inclusive form, @code{ABLOCK} inc In its exclusive form, @code{ABLOCK} increments the block counters for all event classes @emph{except for} those named in the list, provided the optional @emph{postcondition} is either @emph{true} or omitted. -@node ASSERT -@section ASSERT -@cindex ASSERT -@cindex commands, ASSERT -@cindex commands, debugging -@cindex commands, implementation-specific -@cindex commands, non-standard -@emph{FreeM Extension} - -Triggers error @code{ASSERT} if the supplied truth-valued expression @emph{tvexpr} is @emph{false} (@emph{1} is @emph{true}, and @emph{0} is @emph{false}), and that the optional @emph{postcondition} evaluates to @emph{true} or is omitted. - -The @code{ASSERT} error is catchable whether using standard-style, FreeM-style, or DSM 2.0-style error processing. - -@emph{Syntax} - -@example - ASSERT@emph{:postcondition} @emph{} -@end example - -@emph{Example} - -@example -DEFAULT.USER> SET DEBUG=1 - - -DEFAULT.USER> ASSERT:DEBUG 1=1 - - -DEFAULT.USER> ASSERT:DEBUG 1=0 - - ->> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0] ->> ASSERT:DEBUG 1=0 - ^ -@end example @node ASTART @section ASTART @@ -3353,6 +3320,42 @@ VIEW 133:@emph{tvexpr} @cindex XECUTE @cindex commands, XECUTE +@node ZASSERT +@section ZASSERT +@cindex ZASSERT +@cindex commands, ZASSERT +@cindex commands, debugging +@cindex commands, implementation-specific +@cindex commands, non-standard +@emph{FreeM Extension} + +Triggers error @code{ZASSERT} if the supplied truth-valued expression @emph{tvexpr} is @emph{false} (@emph{1} is @emph{true}, and @emph{0} is @emph{false}), and that the optional @emph{postcondition} evaluates to @emph{true} or is omitted. + +The @code{ZASSERT} error is catchable whether using standard-style, FreeM-style, or DSM 2.0-style error processing. + +@emph{Syntax} + +@example + ZASSERT@emph{:postcondition} @emph{} +@end example + +@emph{Example} + +@example +DEFAULT.USER> SET DEBUG=1 + + +DEFAULT.USER> ZASSERT:DEBUG 1=1 + + +DEFAULT.USER> ZASSERT:DEBUG 1=0 + + +>> Error ZASSERT: programmer assertion failed in SYSTEM::^%SYSINIT [$STACK = 0] +>> ZASSERT:DEBUG 1=0 + ^ +@end example + @node ZBREAK @section ZBREAK @cindex ZBREAK @@ -4944,7 +4947,15 @@ If you use other M implementations, you @cindex object-oriented programming @cindex programming, object-oriented +@menu +* Classes:: The organizing concept of object-oriented programming. +* Inheritance:: Making one class derive from another. +* Methods:: Attach code to classes. +* Public and Private Variables:: Determining accessibility. +* Instantiating Objects:: Creating instances of classes. +@end menu +@node Classes @section Classes @subsection Class Overview @@ -5000,6 +5011,7 @@ DESTROY(THIS) ; Q @end example +@node Inheritance @section Inheritance Every class you create will automatically inherit the methods and functionality of the @code{OBJECT} class, supplied with FreeM. @@ -5018,6 +5030,7 @@ You can achieve runtime polymorphism by 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 @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). @@ -5040,6 +5053,7 @@ DEFAULT.USER> W MYOBJ.MYMETHOD() 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. @@ -5062,6 +5076,7 @@ Either of the following commands will cr Attempting to access private fields from outside of the class will raise error condition @code{ZOBJFLDACCV}. +@node Instantiating Objects @section Instantiating Objects To instantiate an object (i.e., create an object from a certain class), you will use the @code{NEW} command as follows: @@ -5072,7 +5087,7 @@ NEW MYSTR=$#^%STRING("myString") This will create a local variable called MYSTR of type STRING, and initialize it with the value myString. -@section Determining Object Class +@subsection Determining Object Class To determine the class of any FreeM local variable, you will use the @code{$$TYPE()} method: @@ -5669,7 +5684,7 @@ Raised when you attempt to use multiple Raised when attempts are made to set @code{$ECODE} to an invalid error code value. Obsolete and replaced by standard error code @code{M101}. @item @code{ZASSERT} - @emph{programmer assertion failed} -Raised when an @code{ASSERT} expression's result is not true. +Raised when an @code{ZASSERT} expression's result is not true. @item @code{ZUSERERR} - @emph{user-defined error} Raised when program code calls @code{THROW} with an error code argument for which the first character is @code{U}, or when @code{$ECODE} is set to an error code for which the first character is @code{U}.