--- freem/doc/freem.texi 2025/05/05 04:46:35 1.42 +++ freem/doc/freem.texi 2025/05/08 12:52:53 1.55 @@ -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.65.0-rc0), 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. @@ -20,7 +19,7 @@ Permission is granted to copy, distribut @title The FreeM Manual @subtitle @sc{The Official Manual of FreeM} -@subtitle Version 0.64.0-rc1 +@subtitle Version 0.65.0-rc0 @c@vskip 10pt @c@center @image{freem-logo-sm,,,,.png} @author Serena Willis @@ -101,7 +100,6 @@ This is the official manual for the Free * Accessing FreeM from C Programs:: How to use the mlib interface. * FreeM Administrator:: The fmadm system manager tool. -* FreeM Legacy Utilities:: FreeM legacy system manager utilities. * FreeM VIEW Commands and Functions:: Getting and setting info about FreeM internals. * Implementation Limits:: FreeM limitations. * US-ASCII Character Set:: The US-ASCII character set. @@ -272,12 +270,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 @@ -440,7 +440,7 @@ Attempting to start a FreeM interpreter The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{}} or @option{--routine=@emph{}}: @example -Coherent Logic Development FreeM version 0.64.0-rc1 (x86_64-pc-linux-gnu) +Coherent Logic Development FreeM version 0.65.0-rc0 (x86_64-pc-linux-gnu) Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC @@ -1114,7 +1114,7 @@ See @emph{https://wiki.osdev.org/Target_ * $ZLSD():: Compute Levenshtein distance between two arguments. * $ZM():: Unknown. * $ZNAME():: Unknown. -* $ZNEXT():: Unknown. +* $ZNEXT():: Return glvn of next numeric subscript following given glvn. * $ZORDER():: Unknown. * $ZPIECE():: Unknown. * $ZPREVIOUS():: Unknown. @@ -1312,6 +1312,28 @@ The optional second argument indicates t @cindex intrinsic functions, $NEXT Deprecated. Use @code{$ORDER} instead. +Returns the next numeric subscript of the specified glvn. + +@emph{Syntax} + +@example +$NEXT(@emph{glvn}) +@end example + +@emph{Example} + +Assume the following array: + +@example +^foo(1)="" +^foo(2)="" +@end example + +And the following code: + +@example + W $ZNEXT(^foo(1)) ; => 2 +@end example @node $ORDER() @section $ORDER @@ -1712,6 +1734,8 @@ Returns the Levenshtein distance between @cindex intrinsic functions, $ZM @cindex intrinsic functions, implementation-specific +Purpose unknown. + @node $ZNAME() @section $ZNAME @cindex $ZNAME @@ -1720,13 +1744,38 @@ Returns the Levenshtein distance between Purpose unknown. +This function relies on the value of @code{$VIEW(71)} being @code{0} (this is not the default). + @node $ZNEXT() @section $ZNEXT @cindex $ZNEXT @cindex intrinsic functions, $ZNEXT @cindex intrinsic functions, implementation-specific -Purpose unknown. +Returns a fully-formed variable reference of the next numeric subscript of the specified glvn. + +@emph{Syntax} + +@example +$ZNEXT(@emph{glvn}) +@end example + +@emph{Example} + +Assume the following array: + +@example +^foo(1)="" +^foo(2)="" +@end example + +And the following code: + +@example + W $ZNEXT(^foo(1)) ; => ^foo(2) +@end example + +This function relies on the value of @code{$VIEW(71)} being @code{1} (this is the default). @node $ZORDER() @section $ZORDER @@ -2012,7 +2061,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 +2092,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 +2232,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 @@ -2634,7 +2648,7 @@ In the above @emph{inclusive} form, @cod @cartouche @quotation @emph{Note} -The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release. +The below @emph{argumentless} and @emph{exclusive} forms of @code{KSUBSCRIPTS} are not implemented in FreeM, as of version 0.65.0-rc0, but are planned for a future release. @end quotation @end cartouche @@ -2669,7 +2683,7 @@ In the above @emph{inclusive} form, @cod @cartouche @quotation @emph{Note} -The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.64.0-rc1, but are planned for a future release. +The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.65.0-rc0, but are planned for a future release. @end quotation @end cartouche @@ -3354,6 +3368,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 +3413,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 +3438,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 +3470,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 +3627,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 +4682,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 +5038,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 +5064,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 +5088,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 +5114,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 +5143,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 +5177,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 +5774,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}. @@ -6406,8 +6490,8 @@ int main(int argc, char **argv, char **e @cindex fmadm The @code{fmadm} utility is the preferred method of managing a FreeM installation, and will eventually replace all of the existing utilities. -Unlike the existing, legacy utilities, @code{fmadm} presents a consistent, simple interface for all FreeM management tasks, and is namespace-aware. -This appendix will document each @code{fmadm} facility as it is implemented, until all of the legacy utilities have been replaced. +In support of FreeM operators, @code{fmadm} presents a consistent, simple interface for all FreeM management tasks, and is namespace-aware. +This appendix will document each @code{fmadm} facility as it is implemented. The @code{fmadm} utility's functions all follow the below, consistent syntax: @@ -6501,43 +6585,6 @@ Supported actions are @code{list} and @c @end table -@node FreeM Legacy Utilities -@appendix FreeM Legacy Utilities -@cindex utilities, legacy - -@section Global Compactor (gcompact) -@cindex utilities, legacy, gcompact - -Compacts the specified global in place. - -@emph{Syntax} - -@example -gcompact @emph{/path/to/global/file} -@end example - -@section Block Examiner (gfix) -@cindex utilities, gfix - -The @emph{gfix} interactive utility program permits navigation of the B-tree structure of the specified global a block at a time. - -@emph{Syntax} - -@example -gfix @emph{} -@end example - -@section Global Repair Tool (grestore) -@cindex utilities, legacy, grestore - -This utility will fix problems with the specified global. - -@emph{Syntax} - -@example -grestore @emph{} -@end example - @node FreeM VIEW Commands and Functions @appendix FreeM VIEW Commands and Functions