--- freem/doc/freem.texi 2025/05/05 04:46:35 1.42 +++ freem/doc/freem.texi 2025/05/05 14:10:34 1.50 @@ -4,8 +4,7 @@ @settitle The FreeM Manual @copying -This manual is for FreeM, (version 0.64.0-rc1), which is a free software@footnote{FreeM subscribes to the software licensing philosophy described in @emph{Free Software, Free Society: -Selected Essays of Richard M. Stallman}.} implementation of the M programming language. +This manual is for FreeM, (version 0.64.0-rc1), which is a free software implementation of the M programming language. Print-optimized versions of this book are typeset in @emph{Computer Modern} by the author using the @emph{GNU Texinfo} tools. @@ -272,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 @@ -2012,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. @@ -2044,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. @@ -2183,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 @@ -3354,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 @@ -3363,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 @@ -3380,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 @@ -3396,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 @@ -3537,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 @@ -4590,7 +4634,7 @@ SET MYSTRING="This is a ""string literal @cindex types, custom @cindex classes -See @ref{Classes}. +See @ref{Object-Oriented Programming}. @node Globals @chapter Globals @@ -4946,19 +4990,15 @@ If you use other M implementations, you @cindex programming, object-oriented @menu -* 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. -* Instantiating Objects:: Creating instances of classes. -* Determining Object Class:: Getting object information at runtime. +* 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 - - -@node Class Overview @subsection Class Overview 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: @@ -4976,7 +5016,6 @@ DESTROY(THIS) ; This is the destructor 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. @@ -5001,7 +5040,6 @@ A constructor looks like this: 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}). @@ -5028,7 +5066,6 @@ Inheritance is achieved by specifying th 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. @@ -5058,7 +5095,7 @@ DEFAULT.USER> W MYOBJ.MYMETHOD() VALUE @end example -@node Public and Private Variables +@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. @@ -5092,8 +5129,7 @@ NEW MYSTR=$#^%STRING("myString") This will create a local variable called MYSTR of type STRING, and initialize it with the value myString. -@node Determining Object Class -@section Determining Object Class +@subsection Determining Object Class To determine the class of any FreeM local variable, you will use the @code{$$TYPE()} method: @@ -5690,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}.