--- freem/doc/freem.texi 2025/05/05 05:16:34 1.44 +++ freem/doc/freem.texi 2025/05/05 14:10:34 1.50 @@ -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,21 +2044,22 @@ Identical to @ref{$TRANSLATE()}, except * VIEW:: Modify FreeM internal parameters. * WRITE:: Write output to current input/output device. * XECUTE:: Interpret string as M code. -* ZBREAK:: Unknown. +* ZASSERT:: Raise error when a conditional expression evaluates @emph{false}. +* ZBREAK:: Enable/disable ZBREAK mode. * ZCONST:: Define a constant that cannot be altered after initial definition. -* ZGO:: Unknown. -* ZHALT:: Unknown. +* ZGOTO:: @code{GOTO} with @code{BREAK} control. +* ZHALT:: Exit FreeM job with return value. * ZINSERT:: Insert code into routine buffer. -* ZJOB:: Invokes a job, ignoring any timeouts. +* ZJOB:: Invoke job, ignoring any timeouts. * ZLOAD:: Load routine into routine buffer. * ZMAP:: Map a global name to a non-default namespace. * ZNEW:: Unknown. * ZPRINT:: Print contents of routine buffer. -* ZQUIT:: Quits multiple stack levels at once. +* ZQUIT:: Quit multiple stack levels at once. * ZREMOVE:: Remove code from routine buffer. * ZSAVE:: Save routine buffer to disk. * ZTHROW:: Programmatically raise an error condition. -* ZTRAP:: Unknown. +* ZTRAP:: Raise a FreeM error. * ZUNMAP:: Remove a mapping of a global to a non-default namespace. * ZWATCH:: Enable or disable watchpoints, or set or clear watchpoints on specified globals, locals, or structured system variables. * ZWITH:: Set prefix for future variable references. @@ -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 @@ -3362,6 +3365,14 @@ VIEW 133:@emph{tvexpr} @cindex commands, non-standard @emph{FreeM Extension} +Sets or clears the @code{ZBREAK} flag@footnote{NOTE: FreeM team needs to investigate how @code{zbreakon} and @code{zbflag} affect program execution.}, based on the result of evaluating @emph{tvexpr}. + +@emph{Syntax} + +@example +ZBREAK @emph{tvexpr} +@end example + @node ZCONST @section ZCONST @cindex ZCONST @@ -3379,14 +3390,30 @@ Constants must only be locals, and globa @code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}} @end example -@node ZGO -@section ZGO -@cindex ZGO -@cindex commands, ZGO +@node ZGOTO +@section ZGOTO +@cindex ZGOTO +@cindex commands, ZGOTO @cindex commands, implementation-specific @cindex commands, non-standard @emph{FreeM Extension} +In its argumented form, enables @code{BREAK} mode and branches unconditionally to @emph{entryref}. + +@emph{Syntax} + +@example +ZGOTO @emph{entryref} +@end example + +In its argumented form, resumes execution after a @code{BREAK}. + +@emph{Syntax} + +@example +ZGOTO +@end example + @node ZHALT @section ZHALT @cindex ZHALT @@ -3395,6 +3422,22 @@ Constants must only be locals, and globa @cindex commands, non-standard @emph{FreeM Extension} +In its single-argumented form, @code{ZHALT} command is used to exit the FreeM process with a specific return value @emph{intexpr}. + +@emph{Syntax} + +@example +ZHALT @emph{intexpr} +@end example + +In its argumentless form, @code{ZHALT} is synonymous with @code{HALT}. + +@emph{Syntax} + +@example +ZHALT +@end example + @node ZINSERT @section ZINSERT @cindex ZINSERT @@ -3536,6 +3579,8 @@ Raises an error condition as long as the @cindex commands, non-standard @emph{FreeM Extension} +Synonymous with @ref{ZTHROW}. + @node ZUNMAP @section ZUNMAP @cindex ZUNMAP @@ -4944,7 +4989,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 +5053,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 +5072,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 +5095,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 +5118,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 +5129,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 +5726,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}.