Commit c82c9a52 authored by John P. Willis's avatar John P. Willis
Browse files

Expand documentation

parent b2bc00c6
Pipeline #691 failed with stage
in 1 minute and 23 seconds
......@@ -713,3 +713,8 @@ VERSION 0.45.3
VERSION 0.46.0
Make BERKELEYDB global handler a compile-time option
********************************************************************************
VERSION 0.47.0
Expand documentation
......@@ -37,7 +37,7 @@
#
#
AC_INIT([freem],[0.46.0],[jpw@coherent-logic.com])
AC_INIT([freem],[0.47.0],[jpw@coherent-logic.com])
AC_CONFIG_HEADERS([src/config.h])
AC_CONFIG_MACRO_DIRS([m4])
......
......@@ -4,7 +4,7 @@
@settitle The FreeM Manual
@copying
This manual is for FreeM, (version 0.46.0), which is a free and open-source implementation of the M programming language and database system.
This manual is for FreeM, (version 0.47.0), which is a free and open-source implementation of the M programming language and database system.
Copyright @copyright{} 2014-2021 Coherent Logic Development LLC
......@@ -18,7 +18,7 @@ Permission is granted to copy, distribute and/or modify this document under the
@title The FreeM Manual
@subtitle @sc{The Official Manual of FreeM}
@subtitle Version 0.46.0
@subtitle Version 0.47.0
@c@vskip 10pt
@c@center @image{freem-logo-sm,,,,.png}
@author John P. Willis
......@@ -280,7 +280,7 @@ $ chmod +x @emph{myscript.m}
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
Coherent Logic Development FreeM version 0.46.0 (x86_64-pc-linux-gnu)
Coherent Logic Development FreeM version 0.47.0 (x86_64-pc-linux-gnu)
Copyright (C) 2014, 2020, 2021 Coherent Logic Development LLC
......@@ -1183,6 +1183,8 @@ Replaces all instances of @code{arg2} with @code{arg3} in string @code{arg1}.
@cindex !
@cindex commands, !
@cindex commands, external
@cindex commands, non-standard
@emph{FreeM Extension}
Invokes a shell to run @emph{<external-command>} from within FreeM. This temporarily disables @command{SIGALRM} handling in FreeM, which may interrupt the use of event-driven M programming commands including @command{ESTART} and @command{ESTOP}.
......@@ -1196,6 +1198,8 @@ If the @command{>} character is supplied immediately preceding @emph{<external-c
@cindex !!
@cindex commands, !!
@cindex commands, external
@cindex commands, non-standard
@emph{FreeM Extension}
Launches a subshell within the FreeM direct mode, allowing the user to run operating system commands.
......@@ -1244,6 +1248,8 @@ In its exclusive form, @code{ABLOCK} increments the block counters for all event
@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}).
......@@ -1366,6 +1372,8 @@ In its argumentless form, @code{BREAK} suspends execution of running code, provi
@code{BREAK@emph{:postcondition} @emph{breakflag}}
@end example
@emph{FreeM Extension}
In its single-argument form, @code{BREAK} sets @emph{Ctrl-C} handling and error handling characteristics, provided the optional @emph{postcondition} is @emph{true} or omitted.
The following table enumerates the possible values of @emph{breakflag}
......@@ -1403,6 +1411,8 @@ In its single-argument form, @code{CLOSE} closes the I/O device associated with
@section CONST
@cindex CONST
@cindex commands, CONST
@cindex commands, non-standard
@emph{FreeM Extension}
Defines a local @emph{constant}, or variable that cannot be altered after its initial definition, provided the optional @emph{postcondition} is @emph{true} or omitted.
......@@ -1418,38 +1428,223 @@ Constants must only be locals, and globals are not supported.
@cindex DO
@cindex commands, DO
In its inclusive form, transfers program control to one or more specified subroutines, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Line levels of entryrefs specified in the argument list must be one, or error @code{M14} is raised.
@emph{Syntax}
@example
DO[@emph{:postcondition}] @emph{entryref}[@emph{:postcondition}[,...]]
@end example
In its argumentless form, transfers control to the following block of code where the line level is one greater than the level at which @code{DO} was encountered, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
DO[@emph{:postcondition}]
@end example
@section ELSE
@cindex ELSE
@cindex commands, ELSE
Executes the remainder of the line of code on which @code{ELSE} is encountered only if @code{$TEST} evaluates to @emph{false}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
ELSE[@emph{:postcondition}]
@end example
@cartouche
@quotation
@emph{Non-Standard Behavior}
FreeM allows a @emph{postcondition} on @code{ELSE}. While explicitly forbidden in the @emph{standard}--and for good reason--it was decided that FreeM should allow postconditions everywhere, both for the sake of foolish consistency (the likes of which Emerson warned against), and for the benefit of entrants to a hypothetical future obfuscated M contest, and those with a Machiavellian predisposition to wicked perversions and undue cleverness.
Using postconditions on @code{ELSE} should be strictly avoided in production code, as they have no practical use, and may contribute to technical debt, hardening of the arteries, hobgoblins, a small mind, a surfeit of logic, climate change, Daily WTF rants, or meltdown of global financial markets.
@end quotation
@end cartouche
@section FOR
@cindex FOR
@cindex commands, FOR
In its argumentless form, repeatedly executes the remainder of the line on which @code{FOR} was encountered until a @code{QUIT}, @code{GOTO}, or end-of-line is encountered, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
FOR[@emph{:postcondition}]
@end example
@cartouche
@quotation
@emph{Non-Standard Behavior}
FreeM allows a @emph{postcondition} on @code{FOR}. Much like postconditions on @code{ELSE} and @code{IF}, this is explicitly forbidden in the @emph{standard}. Although there is an argument to be made that this feature of FreeM might be confusing, in the author's opinion, this use of postconditions is a much cleaner and more precise construct than using @code{IF} followed by @code{FOR}.
If you wish to ensure portability of your FreeM code to other, more rigid M implementations, this use of postconditions should quite obviously be avoided. However, you earn FreeM coolness points for using this feature, which have no value and may not be redeemed for anything at all.
@end quotation
@end cartouche
In its sentinel form, repeatedly executes the remainder of the line and sets a sentinel variable on each iteration, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
On the first iteration of the loop, @emph{glvn} will be set to @emph{initalizer-expression}. On each subsequent iteration, @emph{glvn} will be incremented by @emph{increment-expression}, and the loop will terminate when @emph{glvn} meets or exceeds the value of @emph{max-expression}.
@emph{Syntax}
@example
FOR[@emph{:postcondition}] @emph{glvn}=@emph{initializer-expression}:@emph{increment-expression}:@emph{max-expression}
@end example
@emph{Example}
@example
USER> FOR I=1:1:10 WRITE I,!
1
2
3
4
5
6
7
8
9
10
USER> FOR I=2:2:10 WRITE I,!
2
4
6
8
10
@end example
In its explicit parameter form, a variable is set to each of a series of explicit values, once per iteration, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. The loop terminates when no more values are available.
@emph{Syntax}
@example
FOR[@emph{:postcondition}] @emph{glvn}=@emph{expr1}[,..@emph{exprN}]
@end example
@emph{Example}
@example
USER> FOR I=60,"FOO",-3,"George",1450,$HOROLOG WRITE I,!
60
FOO
-3
George
1450
66106,52388
@end example
@section GOTO
@cindex GOTO
@cindex commands, GOTO
Transfers program execution to another line of code, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Attempting to @code{GOTO} a different line level or a different block when the line level of @code{GOTO} is greater than one will raise error @code{M45}.
@emph{Syntax}
@example
GOTO[@emph{:postcondition}] @emph{entryref}
@end example
@section HALT
@cindex HALT
@cindex commands, HALT
Halts program execution and frees resources allocated during execution, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
HALT[@emph{:postcondition}]
@end example
@section HANG
@cindex HANG
@cindex commands, HANG
Temporarily suspends the program for @emph{expr} seconds, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Values of @emph{expr} that are zero or less than zero are ignored.
@emph{Syntax}
@example
HANG[@emph{:postcondition}] @emph{expr}
@end example
@cartouche
@quotation
@emph{Non-Standard Behavior}
FreeM supports sub-second values for @emph{expr}.
@end quotation
@end cartouche
@section IF
@cindex IF
@cindex commands, IF
In its argumented form, allows the remainder of the line of code following @code{IF} to execute only if all @emph{tvexpr}s evaluate to @emph{true}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
IF[@emph{:postcondition}] @emph{tvexpr}[,...@emph{tvexpr}]
@end example
In its argumentless form, allows the remainder of the line of code following @code{IF} to execute only if @code{$TEST} evaluates to @emph{1}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
IF[@emph{:postcondition}]
@end example
@section JOB
@cindex JOB
@cindex commands, JOB
Executes @emph{entryref} in a separate process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
JOB[@emph{:postcondition}] @emph{entryref}[:@emph{job-parameters}[:@emph{timeout}]]
@end example
If @emph{timeout} is supplied, FreeM will set @code{$TEST} to @emph{1} if the child process completes within @emph{timeout} seconds.
@section KILL
@cindex KILL
@cindex commands, KILL
In its inclusive form, @code{KILL} deletes the specified @emph{glvn}s and their descendant subscripts, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
KILL[@emph{:postcondition}] @emph{glvn}[,...@emph{glvn}]
@end example
In its exclusive form, @code{KILL} deletes all local variables @emph{except} for those specified by @emph{lvn}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
KILL[@emph{:postcondition}] (@emph{lvn}[,...@emph{lvn}])
@end example
In its argumentless form, @code{KILL} deletes all local variables, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
KILL[@emph{:postcondition}]
@end example
@section KSUBSCRIPTS
@cindex KSUBSCRIPTS
@cindex commands, KSUBSCRIPTS
......@@ -1501,7 +1696,7 @@ In the above @emph{inclusive} form, @code{KVALUE} will kill the data values at e
@cartouche
@quotation
@emph{Note}
The below @emph{argumentless} and @emph{exclusive} forms of @code{KVALUE} are not implemented in FreeM, as of version 0.46.0, 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.47.0, but are planned for a future release.
@end quotation
@end cartouche
......@@ -1517,11 +1712,45 @@ KVALUE@emph{:postcondition} (@emph{var1},...)
In the above @emph{exclusive} form, @code{KVALUE} will kill the data values of all local variables, @emph{with the exception of} those named in the list, provided that the optional @emph{postcondition} is @emph{true} or omitted, while leaving their descendant subscripts intact.
@section LOCK
@cindex LOCK
@cindex commands, LOCK
Acquires or releases ownership of names.
In its argumentless form, @code{LOCK} releases ownership of all names previously locked by the current process, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted.
@emph{Syntax}
@example
LOCK[@emph{:postcondition}]
@end example
In its incremental form, increments or decrements the lock counter for each specified @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. Ownership of each @emph{name} is considered to be the current process as long as the lock counter for @emph{name} is greater than zero. If @emph{timeout} is specified, FreeM will wait no more than @emph{timeout} seconds in attempting to acquire ownership of @emph{name}.
If @code{LOCK} succeeds within @emph{timeout}, @code{$TEST} is set to @emph{1}. Otherwise, @code{$TEST} is set to @emph{0}.
@emph{Syntax}
@example
LOCK[@emph{:postcondition}] {+|-}@emph{name}[:@emph{timeout}][,...{+|-}@emph{name}[:@emph{timeout}]]
@end example
@emph{Example}
This example will increment the lock counter for @code{^JPW} and decrement the lock counter for @code{^MJR}.
@example
LOCK +^JPW,-^MJR
@end example
In its non-incremental form, @code{LOCK} releases all @code{LOCK}s held by the current process, and then attempts to acquire a lock on each @emph{name}, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. If @emph{timeout} is supplied, FreeM will attempt to lock @emph{name} for no more than @emph{timeout} seconds.
If @code{LOCK} succeeds within @emph{timeout}, @code{$TEST} is set to @emph{1}. Otherwise, @code{$TEST} is set to @emph{0}.
@emph{Syntax}
@example
LOCK[@emph{:postcondition}] @emph{name}[:@emph{timeout}][,...@emph{name}[:@emph{timeout}]]
@end example
@section MERGE
@cindex MERGE
@cindex commands, MERGE
......@@ -1540,6 +1769,24 @@ The above example will merge the @code{^$JOB} SSV into the @code{A} local. Note
@cindex NEW
@cindex commands, NEW
In all forms of @code{NEW}, @emph{name} must be a local variable name or @code{NEW}-able structured or intrinsic system variable.
In its inclusive form, @code{NEW} saves each specified @emph{name} on the process stack and removes it, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current code block ends, the previous values are restored.
@emph{Syntax}
@example
NEW[@emph{:postcondition}] @emph{name}[,...@emph{name}]
@end example
In its exclusive form, @code{NEW} saves all local variables @emph{except} those named (each @emph{name}) and removes them, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current code block ends, the previous values are restored.
@emph{Syntax}
@example
NEW[@emph{:postcondition}] (@emph{name}[,...@emph{name}])
@end example
In its argumentless form, @code{NEW} saves all local variables and removes them, provided the optional @emph{postcondition} evaluates to @emph{true} or is omitted. When the current code block ends, the previous values are restored.
@section OPEN
@cindex OPEN
@cindex commands, OPEN
......@@ -1631,9 +1878,15 @@ If you do not specify the address family and connection type, they will default
@cindex TCOMMIT
@cindex commands, TCOMMIT
@section THEN
@cindex THEN
@cindex commands, THEN
@section THROW
@cindex THROW
@cindex commands, THROW
@cindex commands, non-standard
@emph{FreeM Extension}
Raises an error condition as long as the optional @emph{postcondition} is @emph{true} or omitted.
......@@ -1713,6 +1966,8 @@ For network sockets, @emph{io-channel} must be in the range 100-255.
@cindex commands, WATCH
@cindex commands, debugging
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
Sets a watchpoint on a global, local, or SSV node.
......@@ -1770,6 +2025,8 @@ USER> WATCH ?^JPW(1)
@section WITH
@cindex WITH
@cindex commands, WITH
@cindex commands, non-standard
@emph{FreeM Extension}
Sets a prefix to be applied to all subsequent local variable or constant references.
......@@ -1802,57 +2059,79 @@ In the above argumentless form, clears the @code{$WITH} prefix, provided the opt
@cindex ZALLOCATE
@cindex commands, ZALLOCATE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZBREAK
@cindex ZBREAK
@cindex commands, ZBREAK
@cindex commands, debugging
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZDEALLOCATE
@cindex ZDEALLOCATE
@cindex commands, ZDEALLOCATE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZGO
@cindex ZGO
@cindex commands, ZGO
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZHALT
@cindex ZHALT
@cindex commands, ZHALT
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZINSERT
@cindex ZINSERT
@cindex commands, ZINSERT
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZJOB
@cindex ZJOB
@cindex commands, ZJOB
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZLOAD
@cindex ZLOAD
@cindex commands, ZLOAD
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZNEW
@cindex ZNEW
@cindex commands, ZNEW
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZPRINT
@cindex ZPRINT
@cindex commands, ZPRINT
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZQUIT
@cindex ZQUIT
@cindex commands, ZQUIT
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
In its single-argument form, quits from @emph{levels} levels of the stack, provided the optional @emph{postcondition} is @emph{true} or omitted.
......@@ -1868,22 +2147,30 @@ In its argumentless form, quits from @code{$STACK} levels of the stack, provided
@cindex ZREMOVE
@cindex commands, ZREMOVE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZSAVE
@cindex ZSAVE
@cindex commands, ZSAVE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZTRAP
@cindex ZTRAP
@cindex commands, ZTRAP
@cindex commands, debugging
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
@section ZWRITE
@cindex ZWRITE
@cindex commands, ZWRITE
@cindex commands, implementation-specific
@cindex commands, non-standard
@emph{FreeM Extension}
Writes the names and values of M variables to @code{$IO}.
......@@ -2595,8 +2882,10 @@ To open a client socket and connect to it, you will need to call the @code{OPEN}
@node Extended Global References
@chapter Extended Global References
@cindex global references, extended
@cindex extended global references
@section Standard Global References
@section Standard Extended Global References
@cindex extended global references, standard
FreeM supports extended global references, allowing the user to access globals in namespaces other than the current default namespace and the @code{SYSTEM} namespace, without switching to the other namespace.
......@@ -2606,7 +2895,16 @@ For example, if you are in the @code{USER} namespace, the following code will pr
WRITE ^|"VISTA"|VA(200,0),!
@end example
@cartouche
@quotation
@emph{Non-Standard Behavior}
In FreeM, extended references must be specified as a @code{strlit}. Extended references derived from the result of an @code{expr} are not yet supported.
@end quotation
@end cartouche
@section File Path Extended Global References
@cindex extended global references, file path
If a namespace is configured to use the @code{BUILTIN} global handler, FreeM supports accessing a global database file by way of its filesystem path.
......@@ -3272,7 +3570,57 @@ Raised when an attempt is made to use a naked reference before the naked indicat
@cindex configuration, system
@section Installing FreeM
@cindex installation, FreeM
@cindex installation
@section Build Configuration
@cindex build configuration
When configuring FreeM with the supplied @code{configure} script, there are some FreeM-specific options that may be used to compile in optional features, or exclude default ones:
@table @asis
@item @code{--enable-mwapigtk} (EXPERIMENTAL)
Enables experimental support for the M Windowing API using the GTK3 libraries. Requires that you have GTK 3 libraries, their headers, and their dependencies installed on your system.
Please consult your operating system's documentation for the correct commands to install the required libraries.
@emph{Example}
@example
$ ./configure --enable-mwapigtk
$ make
$ sudo make install
@end example
@item @code{--enable-berkeleydb} (EXPERIMENTAL)
Enables experimental support for using the BerkeleyDB database as a global handler for FreeM global namespaces. Requires that you have the @code{libdb} library, headers, and dependencies installed on your system.
Please consult your operating system's documentation for the correct commands to install the required libraries.
@emph{Example}
@example
$ ./configure --enable-berkeleydb
$ make
$ sudo make install
@end example
@item @code{--without-readline}
Builds FreeM without GNU @code{readline} support, even if @code{readline} is installed on your system.
Please note that building FreeM without GNU @code{readline} will also exclude REPL functionality and all direct-mode utility commands, i.e. @code{events}, @code{tdump}, @code{shmstat}, and @code{shmpages}.
@emph{Example}
@example
$ ./configure --without-readline
$ make
$ sudo make install
@end example
@end table
@node Accessing FreeM from C Programs
@chapter Accessing FreeM from C Programs
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment