freem/doc/freem.texi - diff

Return to freem.texi CVS log

Up to [Coherent Logic Development] / freem / doc

Diff for /freem/doc/freem.texi between versions 1.47 and 1.57

version 1.47, 2025/05/05 12:55:17	version 1.57, 2025/05/17 17:00:05
Line 4	Line 4
@settitle The FreeM Manual	@settitle The FreeM Manual

@copying	@copying
This manual is for FreeM, (version 0.64.0-rc1), which is a free software implementation of the M programming language.	This manual is for FreeM, (version 0.65.1-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.	Print-optimized versions of this book are typeset in @emph{Computer Modern} by the author using the @emph{GNU Texinfo} tools.

Line 19 Permission is granted to copy, distribut	Line 19 Permission is granted to copy, distribut

@title The FreeM Manual	@title The FreeM Manual
@subtitle @sc{The Official Manual of FreeM}	@subtitle @sc{The Official Manual of FreeM}
@subtitle Version 0.64.0-rc1	@subtitle Version 0.65.1-rc0
@c@vskip 10pt	@c@vskip 10pt
@c@center @image{freem-logo-sm,,,,.png}	@c@center @image{freem-logo-sm,,,,.png}
@author Serena Willis	@author Serena Willis
Line 100 This is the official manual for the Free	Line 100 This is the official manual for the Free
* Accessing FreeM from C Programs:: How to use the mlib interface.	* Accessing FreeM from C Programs:: How to use the mlib interface.

* FreeM Administrator:: The fmadm system manager tool.	* 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.	* FreeM VIEW Commands and Functions:: Getting and setting info about FreeM internals.
* Implementation Limits:: FreeM limitations.	* Implementation Limits:: FreeM limitations.
* US-ASCII Character Set:: The US-ASCII character set.	* US-ASCII Character Set:: The US-ASCII character set.
Line 149 Current contributors denoted with a @emp	Line 148 Current contributors denoted with a @emp
@cindex contributors, Gerum, Winfried	@cindex contributors, Gerum, Winfried
@cindex contributors, Kreis, Greg	@cindex contributors, Kreis, Greg
@cindex contributors, Landis, Larry	@cindex contributors, Landis, Larry
	@cindex contributors, McGlothlen, Ken
@cindex contributors, Milligan, Lloyd	@cindex contributors, Milligan, Lloyd
@cindex contributors, Morris, Steve	@cindex contributors, Morris, Steve
@cindex contributors, Murray, John	@cindex contributors, Murray, John
Line 190 Larry Landis (Coordination, Code, Docume	Line 190 Larry Landis (Coordination, Code, Docume
Rick Marshall (Testing, MDC Conformance) @emph{+}	Rick Marshall (Testing, MDC Conformance) @emph{+}

@item	@item
	Ken McGlothlen (Apple Silicon build/test environment, proofreading of documentation) @emph{+}

	@item
Lloyd Milligan (Code, Testing, Documentation)	Lloyd Milligan (Code, Testing, Documentation)

@item	@item
Line 441 Attempting to start a FreeM interpreter	Line 444 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{<entryref>}} or @option{--routine=@emph{<entryref>}}:	The FreeM direct-mode environment is the mode entered when FreeM is invoked without the use of @option{-r @emph{<entryref>}} or @option{--routine=@emph{<entryref>}}:

@example	@example
Coherent Logic Development FreeM version 0.64.0-rc1 (x86_64-pc-linux-gnu)	Coherent Logic Development FreeM version 0.65.1-rc0 (x86_64-pc-linux-gnu)
Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC	Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC


Line 1115 See @emph{https://wiki.osdev.org/Target_	Line 1118 See @emph{https://wiki.osdev.org/Target_
* $ZLSD():: Compute Levenshtein distance between two arguments.	* $ZLSD():: Compute Levenshtein distance between two arguments.
* $ZM():: Unknown.	* $ZM():: Unknown.
* $ZNAME():: Unknown.	* $ZNAME():: Unknown.
* $ZNEXT():: Unknown.	* $ZNEXT():: Return glvn of next numeric subscript following given glvn.
* $ZORDER():: Unknown.	* $ZORDER():: Unknown.
* $ZPIECE():: Unknown.	* $ZPIECE():: Unknown.
* $ZPREVIOUS():: Unknown.	* $ZPREVIOUS():: Unknown.
Line 1313 The optional second argument indicates t	Line 1316 The optional second argument indicates t
@cindex intrinsic functions, $NEXT	@cindex intrinsic functions, $NEXT

Deprecated. Use @code{$ORDER} instead.	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()	@node $ORDER()
@section $ORDER	@section $ORDER
Line 1713 Returns the Levenshtein distance between	Line 1738 Returns the Levenshtein distance between
@cindex intrinsic functions, $ZM	@cindex intrinsic functions, $ZM
@cindex intrinsic functions, implementation-specific	@cindex intrinsic functions, implementation-specific

	Purpose unknown.

@node $ZNAME()	@node $ZNAME()
@section $ZNAME	@section $ZNAME
@cindex $ZNAME	@cindex $ZNAME
Line 1721 Returns the Levenshtein distance between	Line 1748 Returns the Levenshtein distance between

Purpose unknown.	Purpose unknown.

	This function relies on the value of @code{$VIEW(71)} being @code{0} (this is not the default).

@node $ZNEXT()	@node $ZNEXT()
@section $ZNEXT	@section $ZNEXT
@cindex $ZNEXT	@cindex $ZNEXT
@cindex intrinsic functions, $ZNEXT	@cindex intrinsic functions, $ZNEXT
@cindex intrinsic functions, implementation-specific	@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()	@node $ZORDER()
@section $ZORDER	@section $ZORDER
Line 2045 Identical to @ref{$TRANSLATE()}, except	Line 2097 Identical to @ref{$TRANSLATE()}, except
* WRITE:: Write output to current input/output device.	* WRITE:: Write output to current input/output device.
* XECUTE:: Interpret string as M code.	* XECUTE:: Interpret string as M code.
* ZASSERT:: Raise error when a conditional expression evaluates @emph{false}.	* ZASSERT:: Raise error when a conditional expression evaluates @emph{false}.
* ZBREAK:: Unknown.	* ZBREAK:: Enable/disable ZBREAK mode.
* ZCONST:: Define a constant that cannot be altered after initial definition.	* ZCONST:: Define a constant that cannot be altered after initial definition.
* ZGO:: Unknown.	* ZGOTO:: @code{GOTO} with @code{BREAK} control.
* ZHALT:: Unknown.	* ZHALT:: Exit FreeM job with return value.
* ZINSERT:: Insert code into routine buffer.	* 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.	* ZLOAD:: Load routine into routine buffer.
* ZMAP:: Map a global name to a non-default namespace.	* ZMAP:: Map a global name to a non-default namespace.
* ZNEW:: Unknown.	* ZNEW:: Unknown.
* ZPRINT:: Print contents of routine buffer.	* 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.	* ZREMOVE:: Remove code from routine buffer.
* ZSAVE:: Save routine buffer to disk.	* ZSAVE:: Save routine buffer to disk.
* ZTHROW:: Programmatically raise an error condition.	* 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.	* 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.	* 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.	* ZWITH:: Set prefix for future variable references.
Line 2600 In the above @emph{inclusive} form, @cod	Line 2652 In the above @emph{inclusive} form, @cod
@cartouche	@cartouche
@quotation	@quotation
@emph{Note}	@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.1-rc0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2635 In the above @emph{inclusive} form, @cod	Line 2687 In the above @emph{inclusive} form, @cod
@cartouche	@cartouche
@quotation	@quotation
@emph{Note}	@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.1-rc0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 3365 DEFAULT.USER> ZASSERT:DEBUG 1=0	Line 3417 DEFAULT.USER> ZASSERT:DEBUG 1=0
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@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	@node ZCONST
@section ZCONST	@section ZCONST
@cindex ZCONST	@cindex ZCONST
Line 3382 Constants must only be locals, and globa	Line 3442 Constants must only be locals, and globa
@code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}}	@code{ZCONST@emph{:postcondition} @emph{mref1}=@emph{initial-value1},...,@emph{mrefN}=@emph{initial-valueN}}
@end example	@end example

@node ZGO	@node ZGOTO
@section ZGO	@section ZGOTO
@cindex ZGO	@cindex ZGOTO
@cindex commands, ZGO	@cindex commands, ZGOTO
@cindex commands, implementation-specific	@cindex commands, implementation-specific
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@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	@node ZHALT
@section ZHALT	@section ZHALT
@cindex ZHALT	@cindex ZHALT
Line 3398 Constants must only be locals, and globa	Line 3474 Constants must only be locals, and globa
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@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	@node ZINSERT
@section ZINSERT	@section ZINSERT
@cindex ZINSERT	@cindex ZINSERT
Line 3539 Raises an error condition as long as the	Line 3631 Raises an error condition as long as the
@cindex commands, non-standard	@cindex commands, non-standard
@emph{FreeM Extension}	@emph{FreeM Extension}

	Synonymous with @ref{ZTHROW}.

@node ZUNMAP	@node ZUNMAP
@section ZUNMAP	@section ZUNMAP
@cindex ZUNMAP	@cindex ZUNMAP
Line 5882 Raised when an attempt is made to use a	Line 5976 Raised when an attempt is made to use a
FreeM allows the following installation methods:	FreeM allows the following installation methods:
@table @asis	@table @asis
@item Binary Repository	@item Binary Repository
On recent versions the Ubuntu and Debian distributions of GNU/Linux, we provide package repositories from which FreeM may easily be installed. See the @emph{FreeM Wiki} for more information, and @emph{https://packages.coherent-logic.com} for instructions.	For recent versions of the Ubuntu and Debian distributions of GNU/Linux, we provide package repositories from which FreeM may easily be installed. See the @emph{FreeM Wiki} for more information, and @emph{https://packages.coherent-logic.com} for instructions.

If available, this is the simplest method of installing FreeM.	If available, this is the simplest method of installing FreeM.
@item Binary Packages	@item Binary Packages
We provide binary packages of FreeM for @emph{dpkg} and @emph{rpm}-based distributions of GNU/Linux, and @emph{pkgadd} packages for Solaris 8-10. If you cannot use repositories, this is the easiest option.	We provide binary packages of FreeM for @emph{dpkg} and @emph{rpm}-based distributions of GNU/Linux, and @emph{pkgadd} packages for Solaris 8-10. If you cannot use repositories, this is the easiest option.

See @emph{https://freem.coherent-logic.com/binaries.cfm} for downloads and instructions.	See @emph{https://freem.coherent-logic.com/binaries.cfm} for downloads and instructions.
@item Source Archive	@item Source Tarball
If you prefer installing from source, we recommend that you download the latest @emph{.tar.gz} file from @emph{https://freem.coherent-logic.com/downloads.cfm}, and follow these steps:	If you prefer installing from source, we recommend that you download the latest @emph{.tar.gz} file from @emph{https://freem.coherent-logic.com/downloads.cfm}, and follow these steps:

@example	@example
Line 5942 $ make	Line 6036 $ make
$ sudo make install	$ sudo make install
@end example	@end example

	@item @code{--enable-newglobals} (EXPERIMENTAL)
	Enables a new and modernized global handler. This global handler has a number of known bugs, and thus should be used with caution.

	Note that global files created in the default global handler are incompatible with the new global handler, and vice-versa. You will need to back up and remove all globals in your environments when switching global handlers.


	@emph{Example}

	@example
	$ ./configure --enable-newglobals
	$ make
	$ sudo make install
	@end example

@end table	@end table

@subsection Initial Configuration	@subsection Initial Configuration
Line 6400 int main(int argc, char argv, char e	Line 6508 int main(int argc, char argv, char e
@cindex fmadm	@cindex fmadm

The @code{fmadm} utility is the preferred method of managing a FreeM installation, and will eventually replace all of the existing utilities.	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.	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, until all of the legacy utilities have been replaced.	This appendix will document each @code{fmadm} facility as it is implemented.

The @code{fmadm} utility's functions all follow the below, consistent syntax:	The @code{fmadm} utility's functions all follow the below, consistent syntax:

Line 6495 Supported actions are @code{list} and @c	Line 6603 Supported actions are @code{list} and @c
@end table	@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{</path/to/global/file>}
@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{</path/to/global/file>}
@end example

@node FreeM VIEW Commands and Functions	@node FreeM VIEW Commands and Functions
@appendix FreeM VIEW Commands and Functions	@appendix FreeM VIEW Commands and Functions

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>

Removed from v.1.47
changed lines
	Added in v.1.57