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.46 and 1.54

version 1.46, 2025/05/05 12:51:46	version 1.54, 2025/05/07 19:03:06
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.64.0), 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.64.0
@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 271 Refers to an M intrinsic special variabl	Line 270 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}.	Indicates a @emph{list} of the following item, e.g., @emph{L gvn} means @emph{list of global variable names}.
@item @emph{lvn}	@item @emph{lvn}
Refers to the name of an M local variable.	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}	@item @emph{strlit}
Refers to an M string literal.	Refers to an M string literal.
@item @emph{ssvn}	@item @emph{ssvn}
Refers to the name of an M structured system variable.	Refers to the name of an M structured system variable.
@item @emph{tvexpr}	@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	@end table

@node A Note on Standards	@node A Note on Standards
Line 439 Attempting to start a FreeM interpreter	Line 440 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.64.0 (x86_64-pc-linux-gnu)
Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC	Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC


Line 1113 See @emph{https://wiki.osdev.org/Target_	Line 1114 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 1311 The optional second argument indicates t	Line 1312 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 1711 Returns the Levenshtein distance between	Line 1734 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 1719 Returns the Levenshtein distance between	Line 1744 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 2043 Identical to @ref{$TRANSLATE()}, except	Line 2093 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 2598 In the above @emph{inclusive} form, @cod	Line 2648 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.64.0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 2633 In the above @emph{inclusive} form, @cod	Line 2683 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.64.0, but are planned for a future release.
@end quotation	@end quotation
@end cartouche	@end cartouche

Line 3363 DEFAULT.USER> ZASSERT:DEBUG 1=0	Line 3413 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 3380 Constants must only be locals, and globa	Line 3438 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 3396 Constants must only be locals, and globa	Line 3470 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 3537 Raises an error condition as long as the	Line 3627 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 6398 int main(int argc, char argv, char e	Line 6490 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 6493 Supported actions are @code{list} and @c	Line 6585 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.46
changed lines
	Added in v.1.54