misc

"Misc.Compatibility words"

misc
Compatiblity with former standards, miscellaneous useful words.

Tektronix CTE

%version: bln_mpt1!5.31 %

GNU LGPL

FORTH

* just print OK, also fine for copy-and-paste in terminal

FORTH ok

no special info, see general notes

misc ordinary primitive

more fig-forth

* COLD ( -- )

cold abort - reinitialize everything and go to QUIT routine
... this routine is implemented as a warm-boot in pfe.

 : WARM FENCE @ (FORGET) INCLUDE-FILE ?DUP IF COUNT INCLUDED THEN QUIT ;

misc ordinary primitive

FORTH LIT

no special info, see general notes

misc ordinary primitive

* .LINE ( line# block# -- )

misc ordinary primitive

* basic system variables ( OUT DP HLD R0 S0 )

* OUT                 ( -- addr )

  Promiscuous variable.
 VARIABLE OUT

misc threadstate variable

FORTH DP

no special info, see general notes

misc threadstate variable

FORTH HLD

no special info, see general notes

misc threadstate variable

FORTH R0

no special info, see general notes

misc threadstate variable

FORTH S0

no special info, see general notes

misc threadstate variable

words without pedigree

* UD.R ( 2val r -- )

misc ordinary primitive

* UD. ( 2val -- )

see also UD.R

misc ordinary primitive

* ID. ( nfa -- )

print the name-field pointed to by the nfa-argument.
a synonym for .NAME - but this word is more portable due its
heritage from fig-forth.

in fig-forth the name-field is effectivly a bstring with some flags,
so the nfa's count has to be masked out, e.g.

 : .NAME COUNT 32 AND TYPE ;

in other pfe configurations, the name might not contain the flags it
it just a counted string - and there may be even more possibility.

 : .NAME COUNT TYPE ;

you should more and more convert your code to use the sequence
NAME>STRING TYPE

misc ordinary primitive

* .NAME ( nfa -- )

use ID. or better NAME>STRING TYPE

misc forthword synonym

* -ROLL ( xn ... x2 x1 n -- x1 xn ... x2 )

the inverse of ROLL

misc ordinary primitive

* RANDOM ( n1 -- n2 )

returns random number with 0 <= n2 < n1)

 : RANDOM ?DUP IF _random SWAP MOD ELSE _random THEN ;

misc ordinary primitive

* SRAND ( n -- )

misc ordinary primitive

* UNDER+ ( n1 n2 -- n1+n2 n2 )

quicker than

 : UNDER+ TUCK + SWAP ;

misc ordinary primitive

more local variables

* +TO ( val [name] -- )

add the val to the named VALUE or LOCALS| value

misc compiling primitive

data structures

* BUILD-ARRAY ( n1 n2 ... nX X --- n )

writes X, n1, ... nX into the dictionary -
returns product n1 * n2 * ... * nX

misc ordinary primitive

* ACCESS-ARRAY ( i1 i2 ... iX addr1 --- addr2 n )

see BUILD-ARRAY

misc ordinary primitive

* .STATUS ( -- )

display internal variables

 : .STATUS .VERSION .CVERSION .MEMORY .SEARCHPATHS .DICTVARS .REGSUSED ;

misc ordinary primitive

FORTH SHOW-STATUS

no special info, see general notes

misc forthword synonym

Call to enable lower-case symbols as input, supersedes plain Vars

FORTH LOWER-CASE@

no special info, see general notes

misc loader code P4_DVaL

* LOWER-CASE! ( val -- )

Call to enable lower-case symbols as input, supersedes the plain
variable LOWER-CASE

 : LOWER-CASE! LOWER-CASE ! ;
 : LOWER-CASE! TO LOWER-CASE@ ;

misc threadstate valueSET

FORTH LOWER-CASE

no special info, see general notes

misc threadstate variable

FORTH LOWER-CASE-FN@

no special info, see general notes

misc loader code P4_DVaL

* LOWER-CASE-FN! ( val -- )

Call to enable lower-case symbols as input, supersedes the plain
variable LOWER-CASE-FN

 : LOWER-CASE-FN!    LOWER-CASE-FN ! ;
 : LOWER-CASE-FN! TO LOWER-CASE-FN@ ;

misc threadstate valueSET

FORTH LOWER-CASE-FN

no special info, see general notes

misc threadstate variable

* Call to enable warnings if creating symbols being in the ORDER

FORTH REDEFINED-MSG@

no special info, see general notes

misc loader code P4_DVaL

* REDEFINED-MSG! ( val -- )

Call to enable warnings if creating symbols being in the ORDER
- supersedes the plain variable REDEFINED-MSG

 : REDEFINED-MSG!    REDEFINED-MSG ! ;
 : REDEFINED-MSG! TO REDEFINED-MSG@ ;

misc threadstate valueSET

FORTH REDEFINED-MSG

no special info, see general notes

misc threadstate variable

* Call to enable quoted-parse extension in PARSE WORDs

FORTH QUOTED-PARSE*

no special info, see general notes

misc threadstate variable

FORTH QUOTED-PARSE@

no special info, see general notes

misc loader code P4_DVaL

FORTH QUOTED-PARSE!

no special info, see general notes

misc threadstate valueSET

* SOURCE-LINE ( -- n )

if SOURCE is from EVALUATE (or QUERY ) then
the result is 0 else the line-numbers start from 1

misc ordinary primitive

* TH'POCKET ( n -- addr u )

returns the specified pocket as a S" string reference

misc ordinary primitive

* POCKET-PAD ( -- addr )

Returns the next pocket.
A pocket has usually the size of a maxstring, see ENVIRONMENT /STRING
(but can be configured to be different, mostly when MAXPATH > /STRING )
Note that a pocket is a temporary and forth internal functions do
sometimes call POCKET-PAD too, especially when building filenames
and getting a literal (but temporary) string from the keyboard.
Functions are not expected to hold references to this transient
area any longer than building a name and calling another word with it.

Usage of a pocket pad is a good way to make local temporary buffers
superfluous that are only used to construct a temporary string that
usually gets swallowed by another function.

 depracated code:
   create temp-buffer 255 allot
   : make-temp ( str buf ) 
          temp-buffer place  " .tmp" count temp-buffer append 
          temp-buffer count make-file ;
 replace with this:
   : make-temp ( str buf )
        pocket-pad >r    
        r place  " .tmp" count r append
        r> count make-file
   ;

misc ordinary primitive

P4_OCoN ("/CELL", sizeof (p4cell)), FORTH WSIZE

no special info, see general notes

misc forthword synonym

* W@ ( addr -- w-val )

fetch a 2byte-val from address

misc ordinary primitive

* W! ( w-val addr -- )

store a 2byte-val at addressed 2byte-value

misc ordinary primitive

* W+! ( w-val addr -- )

add a 2byte-val to addressed 2byte-value

misc ordinary primitive

* WL-HASH ( c-addr n1 -- n2 )

calc hash-code for selection of thread
in a threaded-vocabulary

misc ordinary primitive

* TOPMOST ( wid -- a-addr )

that last valid word in the specified vocabulary

misc ordinary primitive

* the variable accessed with LATEST

* LS.WORDS ( -- )

see WORDS

misc ordinary primitive

* LS.PRIMITIVES ( -- )

see WORDS

misc ordinary primitive

* LS.COLON-DEFS ( -- )

see WORDS

misc ordinary primitive

* LS.DOES-DEFS ( -- )

see WORDS

misc ordinary primitive

* LS.CONSTANTS ( -- )

see WORDS

misc ordinary primitive

* LS.VARIABLES ( -- )

see WORDS

misc ordinary primitive

* LS.VOCABULARIES ( -- )

see WORDS

misc ordinary primitive

* LS.MARKERS ( -- )

see WORDS

misc ordinary primitive

* TAB ( n -- )

jump to next column divisible by n

misc ordinary primitive

* BACKSPACE ( -- )

reverse of SPACE

misc ordinary primitive

* ?STOP ( -- flag )

check for 'q' pressed
- see ?CR

misc ordinary primitive

* START?CR ( -- )

initialized for more-like effect
- see ?CR

misc ordinary primitive

* ?CR ( -- flag )

like CR , stop 25 lines past START?CR

misc ordinary primitive

* CLOSE-ALL-FILES ( -- )

misc ordinary primitive

* .MEMORY ( -- )

misc ordinary primitive

* vectorized i/o variables, see STANDARD-I/O

FORTH *EMIT*

no special info, see general notes

misc threadstate variable

FORTH *EXPECT*

no special info, see general notes

misc threadstate variable

FORTH *KEY*

no special info, see general notes

misc threadstate variable

FORTH *TYPE*

no special info, see general notes

misc threadstate variable

* (EMIT) ( val -- )

like EMIT and always to screen
- the routine to be put into *EMIT*

misc ordinary primitive

* (EXPECT) ( . -- . )

like EXPECT and always from screen
- the routine to be put into *EXPECT*

misc ordinary primitive

* (KEY) ( -- ... )

like KEY and always from screen
- the routine to be put into *KEY*

misc ordinary primitive

* (TYPE) ( val -- )

like TYPE and always to screen
- the routine to be put into *TYPE*

misc ordinary primitive

* STANDARD-I/O ( -- )

initialize *TYPE* , *EMIT* , *EXPECT* and *KEY*
to point directly to the screen I/O routines,

namely (TYPE) , (EMIT) , (EXPECT) , (KEY)

misc ordinary primitive

show online help:

* HELP ( name -- )

will load the help module in the background and hand over the
parsed name to (HELP) to be resolved. If no (HELP) word
can be loaded, nothing will happen.

misc ordinary primitive

* EDIT-BLOCKFILE ( name -- )

will load the edit module in the background and look for a word
called EDIT-BLOCK that could be used to edit the blockfile.
If no EDIT-BLOCKFILE word can be loaded, nothing will happen.
Otherwise, OPEN-BLOCKFILE is called followed by 0 EDIT-BLOCK
to start editing the file at the first block.

misc ordinary primitive

* the application to be called, options like ARGC ARGV

FORTH APPLICATION

no special info, see general notes

misc threadstate variable

* task system hooks

* ARGC ( -- n )

misc ordinary primitive

* ARGV ( n -- addr u )

misc ordinary primitive

FORTH EXITCODE

no special info, see general notes

misc threadstate variable

* ( -- fid ) - the standard file-handles of the task

FORTH STDIN

no special info, see general notes

misc loader code P4_DVaL

FORTH STDOUT

no special info, see general notes

misc loader code P4_DVaL

FORTH STDERR

no special info, see general notes

misc loader code P4_DVaL

* EXPAND-FN ( addr1 u1 addr2 -- addr2 cnt2 )

misc ordinary primitive

FORTH LOAD"

no special info, see general notes

misc compiling primitive

#ifndef NO_SYSTEM

* SYSTEM ( addr u -- ret-val )

run a shell command (note: embedded systems have no shell)

misc ordinary primitive

FORTH SYSTEM"

no special info, see general notes

misc compiling primitive

#endif  NO_SYSTEM

* RAISE ( n -- )

send a SIGNAL to self

misc ordinary primitive

* SIGNAL ( xt1 n -- xt2 )

install signal handler
- return old signal handler

misc ordinary primitive

almost usable everywhere

* CREATE: ( 'name' -- )

this creates a name with the VARIABLE runtime.
Note that this is the FIG-implemenation of CREATE whereas in
ANS-Forth mode we have a CREATE identical to FIG-style <BUILDS

 : CREATE: BL WORD $HEADER DOVAR A, ;

misc ordinary primitive

* BUFFER: ( size 'name' -- )

this creates a name with the VARIABLE runtime and ALLOTs memory

 : BUFFER: BL WORD $HEADER DOVAR A, ALLOT ;

misc ordinary primitive

quite useful, esp. for non-locals code

* R'@ ( -- x )( R: x y -- x y )

The second element on the return stack.

 : R'@   S" 2R@ DROP " EVALUATE ; IMMEDIATE

misc ordinary primitive

* R'! ( x R: a b -- R: x b )

store the value into the next-under value in the returnstack.
used to interpret the returnstack to hold two LOCALS| values.
see R'@ for inverse operation

misc ordinary primitive

FORTH R"@

no special info, see general notes

misc ordinary primitive

FORTH R"!

no special info, see general notes

misc ordinary primitive

* R! ( x R: a -- R: x )

store the value as the topmost value in the returnstack.
see R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R! )

misc ordinary primitive

* 2R! ( x y R: a b -- R: x y )

store the value as the topmost value in the returnstack.
see R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R! )

misc ordinary primitive

* DUP>R ( val -- val )

shortcut, see R>DROP

note again that the following will fail:

 : DUP>R DUP >R ;

misc ordinary primitive

* R>DROP ( -- )

shortcut (e.g. in CSI-Forth)

note that the access to R is configuration dependent - only in
a traditional fig-forth each NEST will be one cell wide - in case that
there are no LOCALS| of course. And remember, the word above reads
like the sequence R> and DROP but that is not quite true.

 : R>DROP R> DROP ; ( is bad - correct might be )  : R>DROP R> R> DROP >R ;

misc ordinary primitive

* 2R>2DROP ( -- )

this is two times R>DROP but a bit quicker.
it is however really quick compared to the sequence 2R> and 2DROP

misc ordinary primitive

* CLEARSTACK ( -- )

reset the parameter stack to be empty

 : CLEARSTACK  S0 SP! ;

misc ordinary primitive

smart

* EXECUTES ( n [word] -- )

stores the execution token of following word into
the callback pointer for the specified function-key

misc ordinary primitive

ENVIRONMENT ENVIRONMENT RAND_MAX

no special info, see general notes

misc ordinary constant