misc wordset
Prev Chapter 3. Wordset Reference Next

misc wordset

description

-- miscellaneous useful words, mostly stemming from fig-forth

Copyright (C) Tektronix, Inc. 1998 - 2001. All rights reserved.

description: Compatiblity with former standards, miscellaneous useful words. 

FORTH

ok ( .. )();
as:"ok";

ordinary primitive ok

an executable word (no special usage info)

or wrapper call around p4_ok

FORTH

COLD ( -- )();
p4:"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 ;
 
FORTH

LIT ( .. )();
as:"lit";

ordinary primitive LIT

an executable word (no special usage info)

or wrapper call around p4_literal_execution

FORTH

.LINE ( line# block# -- )();
p4:"dot-line";

FORTH

OUT ( .. )();
as:"out";

threadstate variable OUT

out (no special usage info)

FORTH

DP ( .. )();
as:"dp";

threadstate variable DP

dp (no special usage info)

FORTH

HLD ( .. )();
as:"hld";

threadstate variable HLD

hld (no special usage info)

FORTH

R0 ( .. )();
as:"r-zero";

threadstate variable R0

r0 (no special usage info)

FORTH

S0 ( .. )();
as:"s-zero";

threadstate variable S0

s0 (no special usage info)

FORTH

UD.R ( 2val r -- )();
p4:"u-d-dot-r";

FORTH

UD. ( 2val -- )();
p4:"u-d-dot";

see also UD.R 

FORTH

ID. ( nfa -- )();
p4:"id-dot";

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 

FORTH

.NAME ( .. )();
as:"dot-name";

forthword synonym .NAME

is doing the same as ID.

this word is provided only for compatibility with common forth usage in programs. Thegiven synonym should be preferred however.

FORTH
-ROLL ( xn ... x2 x1 n -- x1 xn ... x2 )(); 
 ;

the inverse of ROLL 

FORTH

RANDOM ( n1 -- n2 )();
p4:"random";

returns random number with 0 <= n2 < n1) 

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

SRAND ( n -- )();
p4:"srand";

FORTH
(UNDER+) ( n1 n2 -- n1+n2 n2 )(); 
 ;

quicker than 

 : (UNDER+) TUCK + SWAP ; or : (UNDER+) DUP UNDER+ ;
 
FORTH
UNDER+ ( n1 x n2 -- n1+n2 x )TF(); 
 ;

quicker than 

 : UNDER+  ROT + SWAP ;
 
FORTH

+TO ( val [name] -- )();
p4:"plus-to";

add the val to the named VALUE or LOCALS| value 

FORTH
BUILD-ARRAY ( n1 n2 ... nX X --- n )(); 
 ;

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

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

see BUILD-ARRAY 

FORTH

.STATUS ( -- )();
p4:"dot-status";

display internal variables 

 : .STATUS .VERSION .CVERSION .MEMORY .SEARCHPATHS .DICTVARS .REGSUSED ;
 
FORTH
SHOW-STATUS ( .. )(); 
 ;

forthword synonym SHOW-STATUS

is doing the same as .STATUS

this word is provided only for compatibility with common forth usage in programs. Thegiven synonym should be preferred however.

FORTH
UPPER-CASE? ( .. )(); 
 ;

- loader type P4_DVaL UPPER-CASE?

wordl_flag (no special usage info)

FORTH

LOWER-CASE ( .. )();
as:"lower-minus-case";

threadstate variable LOWER-CASE

wordl_flag (no special usage info)

FORTH
LOWER-CASE-FN? ( .. )(); 
 ;

- loader type P4_DVaL LOWER-CASE-FN?

lower_case_fn (no special usage info)

FORTH
LOWER-CASE-FN ( .. )(); 
 ;

threadstate variable LOWER-CASE-FN

lower_case_fn (no special usage info)

FORTH
REDEFINED-MSG? ( .. )(); 
 ;

- loader type P4_DVaL REDEFINED-MSG?

redefined_msg (no special usage info)

FORTH
REDEFINED-MSG ( .. )(); 
 ;

threadstate variable REDEFINED-MSG

redefined_msg (no special usage info)

FORTH
QUOTED-PARSE? ( .. )(); 
 ;

- loader type P4_DVaL QUOTED-PARSE?

quoted_parse (no special usage info)

FORTH

SOURCE-LINE ( -- n )();
p4:"source-line";

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

FORTH
SOURCE-NAME ( -- str-ptr str-len )(); 
 ;

if SOURCE is from INCLUDE then the result is the filename, otherwise a generic name for the SOURCE-ID is given. 

FORTH

TH'POCKET ( n -- addr u )();
p4:"th-pocket";

returns the specified pocket as a S" string reference 

FORTH

POCKET-PAD ( -- addr )();
p4:"pocket-pad";

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
   ;
 


FORTH
/CELL
 ( .. )();
as:"slash-cell";
( sizeof (p4cell) )  constant /CELL
an ordinary constant (no special usage info)


FORTH
WSIZE
 ( .. )();
as:"wsize";
forthword synonym WSIZE 
is doing the same as /CELL
this word is provided only for compatibility with common forth usage in programs. Thegiven synonym should be preferred however.


FORTH
W@
 ( addr -- w-val )();
p4:"w-fetch";
       fetch a 2byte-val from address



FORTH
W!
 ( w-val addr -- )();
p4:"w-store";
       store a 2byte-val at addressed 2byte-value



FORTH
W+!
 ( w-val addr -- )();
p4:"w-plus-store";
       add a 2byte-val to addressed 2byte-value



FORTH
WL-HASH
 ( c-addr n1 -- n2 )();
p4:"wl-hash";
       calc hash-code for selection of thread
       in a threaded-vocabulary



FORTH
TOPMOST
 ( wid -- a-addr )();
p4:"topmost";
       that last valid word in the specified vocabulary



FORTH
LS.WORDS
 ( -- )();
p4:"ls-words";
       see WORDS



FORTH
LS.PRIMITIVES
 ( -- )();
p4:"ls-primitives";
       see WORDS



FORTH
LS.COLON-DEFS
 ( -- )();
p4:"ls-cdefs";
       see WORDS



FORTH
LS.DOES-DEFS
 ( -- )();
p4:"ls-ddefs";
       see WORDS



FORTH
LS.CONSTANTS
 ( -- )();
p4:"ls-constants";
       see WORDS



FORTH
LS.VARIABLES
 ( -- )();
p4:"ls-variables";
       see WORDS



FORTH
LS.VOCABULARIES
 ( -- )(); 
 ;
       see WORDS



FORTH
LS.MARKERS
 ( -- )();
p4:"ls-markers";
       see WORDS



FORTH
TAB
 ( n -- )();
p4:"tab";
       jump to next column divisible by n 



FORTH
BACKSPACE
 ( -- )();
p4:"backspace";
       reverse of SPACE



FORTH
?STOP
 ( -- flag )();
p4:"Q-stop";
       check for 'q' pressed
       - see ?CR



FORTH
START?CR
 ( -- )();
p4:"start-Q-cr";
       initialized for more-like effect
       - see ?CR



FORTH
?CR
 ( -- flag )();
p4:"Q-cr";
       like CR , stop 25 lines past START?CR



FORTH
CLOSE-ALL-FILES
 ( -- )(); 
 ;


FORTH
.MEMORY
 ( -- )();
p4:"dot-memory";


FORTH
*EMIT*
 ( .. )();
as:"star-emit-star";
threadstate variable *EMIT*
emit (no special usage info)


FORTH
*EXPECT*
 ( .. )();
as:"star-expect-star";
threadstate variable *EXPECT*
expect (no special usage info)


FORTH
*KEY*
 ( .. )();
as:"star-key-star";
threadstate variable *KEY*
key (no special usage info)


FORTH
*TYPE*
 ( .. )();
as:"star-type-star";
threadstate variable *TYPE*
type (no special usage info)


FORTH
(EMIT)
 ( .. )();
as:"paren-emit";
ordinary primitive (EMIT) 
an executable word  (no special usage info)
 or wrapper call around p4_paren_emit


FORTH
(EXPECT)
 ( .. )();
as:"paren-expect";
ordinary primitive (EXPECT) 
an executable word  (no special usage info)
 or wrapper call around p4_paren_expect


FORTH
(KEY)
 ( .. )();
as:"paren-key";
ordinary primitive (KEY) 
an executable word  (no special usage info)
 or wrapper call around p4_paren_key


FORTH
(TYPE)
 ( .. )();
as:"paren-type";
ordinary primitive (TYPE) 
an executable word  (no special usage info)
 or wrapper call around p4_paren_type


FORTH
STANDARD-I/O
 ( -- )();
p4:"standard-io";
       initialize *TYPE* , *EMIT* , *EXPECT* and *KEY*
       to point directly to the screen I/O routines, <br> 
       namely (TYPE) , (EMIT) , (EXPECT) , (KEY) 



FORTH
HELP
 ( name -- )();
p4:"help";
       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.



FORTH
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.



FORTH
APPLICATION
 ( .. )();
as:"application";
threadstate variable APPLICATION
application (no special usage info)


FORTH
ARGC
 ( -- n )();
p4:"argc";


FORTH
ARGV
 ( n -- addr u )();
p4:"argv";


FORTH
EXITCODE
 ( .. )();
as:"exitcode";
threadstate variable EXITCODE
exitcode (no special usage info)


FORTH
STDIN
 ( .. )();
as:"stdin";
- loader type P4_DVaL STDIN
stdIn (no special usage info)


FORTH
STDOUT
 ( .. )();
as:"stdout";
- loader type P4_DVaL STDOUT
stdOut (no special usage info)


FORTH
STDERR
 ( .. )();
as:"stderr";
- loader type P4_DVaL STDERR
stdErr (no special usage info)


FORTH
EXPAND-FN
 ( addr1 u1 addr2 -- addr2 cnt2 )(); 
 ;


FORTH
LOAD"
 ( [filename<">] -- ? )obsolete (); 
 ;
       load the specified file - this word can be compiled into a word-definition
       obsolete! use OPEN-BLOCKFILE name LOAD



FORTH
SYSTEM
 ( addr u -- ret-val )();
p4:"system";
       run a shell command  (note: embedded systems have no shell)



FORTH
SYSTEM"
 ( [commandline<">] -- ret-val )obsolete(); 
 ;
       run a shell command (note:embedded systems have no shell)
       obsolete! use S" string" SYSTEM



FORTH
RAISE
 ( n -- )();
p4:"raise";
       send a SIGNAL to self



FORTH
SIGNAL
 ( xt1 n -- xt2 )();
p4:"signal";
       install signal handler
       - return old signal handler



FORTH
CREATE:
 ( 'name' -- )();
p4:"create-var";
       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, ;
 


FORTH
BUFFER:
 ( size 'name' -- )(); 
 ;
       this creates a name with the VARIABLE runtime and ALLOTs memory

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


FORTH
R'@
 ( R: a b -- a R: a b )(); 
 ;
       fetch the next-under value from the returnstack.
       used to interpret the returnstack to hold two LOCALS| values.
       ( R@ / 2R@ / R>DROP / R"@)



FORTH
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



FORTH
R"@
 ( R: a b c -- a R: a b c )(); 
 ;
       fetch the second-under value from the returnstack.
       used to interpret the returnstack to hold three LOCALS| values.
       see R"! for inverse operation ( R'@ R@ / 2R@ / R>DROP )



FORTH
R"!
 ( x R: a b c -- R: x b c )(); 
 ;
       store the value into the second-under value in the returnstack.
       used to interpret the returnstack to hold three LOCALS| values.
       see R"@ for inverse operation



FORTH
R!
 ( x R: a -- R: x )();
p4:"r-store";
       store the value as the topmost value in the returnstack.
       see R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R!)



FORTH
2R!
 ( x y R: a b -- R: x y )(); 
 ;
       store the value as the topmost value in the returnstack.
       see 2R@ for inverse operation ( R'@ / R"@ / 2R@ / 2R!)



FORTH
DUP>R
 ( val -- val )();
p4:"dup-to-r";
       shortcut, see R>DROP
       <br> note again that the following will fail:

 : DUP>R DUP >R ;
 


FORTH
R>DROP
 ( -- )();
p4:"r-from-drop";
       shortcut (e.g. in CSI-Forth)
       <br> 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 ;
 


FORTH
2R>2DROP
 ( -- )();
p4:"two-r-from-drop";
       this is two times R>DROP but a bit quicker.
       it is however really quick compared to the sequence 2R> and 2DROP



FORTH
CLEARSTACK
 ( -- )();
p4:"clearstack";
       reset the parameter stack to be empty

 : CLEARSTACK  S0 SP! ;
 


EXTENSIONS
+UNDER
 ( .. )();
as:"plus-under";
ordinary primitive +UNDER 
an executable word  (no special usage info)
 or wrapper call around p4_plus_under


EXTENSIONS
EXECUTES
 ( n [word] -- )();
p4:"executes";
       stores the execution token of following word into
       the callback pointer for the specified function-key 



ENVIRONMENT
RAND_MAX
 ( .. )();
as:"rand-max";
( RAND_MAX )  constant RAND_MAX
an ordinary constant (no special usage info)
Prev Up Next
memory wordset Home module wordset