JAX4TH.WORDS Please refer to non-guarantee, non-warranty disclaimer in JAX4TH.DOC. Contents: 1) List of dpANS-2 words appearing in JAX4TH. 2) List and definitions of JAX4TH implementation words. ------------------------------------------------------------------------------- | Apologies for any inaccuracies or incompleteness! Among other things slated | | for incremental improvement each JAX4TH revision is the documentation! | ------------------------------------------------------------------------------- 1) Here are the words from X3J14 dpANS-2 which appear in JAX4TH with at least one of their (possibly multiple) stack diagrams. Consult X3J14 dpANS-2 for the definition and complete stack diagram(s) for each word. Words appear roughly in the order in which they appear in the BASIS. ANS/ASC X3/X3J14 111 N. Sepulveda Blvd. Suite 300 Manhattan Beach CA 90266 USA CORE Word Set ( ( "ccc<)>" --) ! ( x a-addr --) #> ( xd -- c-addr u) #S ( ud1 -- ud2) #TIB ( -- a-addr) ' ( "name" -- xt) * ( n1|u1 n2|u2 -- n3|u3) */ ( n1 n2 n3 -- n4) */MOD ( n1 n2 n3 -- n4 n5) + ( n1|u1 n2|u2 --- n3|u3) +! ( n|u a-addr --) +LOOP ( n --) ( R: sys --) , ( x --) - ( n1|u1 n2|u2 --- n3|u3) . ( n --) ." ( "ccc<">" --) ( compiling) ( --) ( execution) / ( n1 n2 -- n3) /MOD ( n1 n2 -- n3 n4) 0< ( n -- flag) 0= ( n|u -- flag) 1+ ( n1|u1 -- n2|u2) 1- ( n1|u1 -- n2|u2) 2! ( x1 x2 a-addr --) 2* ( n1 -- n2) 2/ ( n1 -- n2) 2@ ( a-addr -- x1 x2) 2DROP ( x1 x2 --) 2DUP ( x1 x2 -- x1 x2 x1 x2) 2OVER ( x1 x2 x3 x4 -- x1 x2 x3 x4 x1 x2) 2SWAP ( x1 x2 x3 x4 --- x3 x4 x1 x2) : compilation ( "name" -- colon-sys) ; compilation ( colon-sys --) < ( n1 n2 --- flag) <# ( --) = ( x1 x2 -- flag) > ( n1 n2 --- flag) >BODY ( xt -- a-addr) >IN ( -- a-addr) >R ( x --) ( R: -- x) >NUMBER ( ud1 c-addr1 u1 -- ud2 c-addr2 u2) ?DUP ( x -- x x) OR ( 0 - 0) @ ( a-addr -- x) ABORT (i*x --) ( R: j*x --) ABORT" Compilation: ( "ccc<">" --) ABS ( n1 -- +n2) ACCEPT ( c-addr +n -- +n2) ALIGN ( --) ALIGN-DICT ( --) ALIGNED ( addr -- a-addr) ALLOT ( n --) AND ( x1 x2 -- x3) BASE ( -- a-addr) BEGIN Compilation: ( -- dest) BL ( -- char) BLK ( -- a-addr) C! ( char c-addr --) C, ( char --) C@ ( c-addr -- char) CELL+ ( addr1 -- addr2) CELLS ( n1 -- n2) CHAR ("ccc< >" -- char) CHAR+ ( addr1 -- addr2) CHARS ( n1 -- n2) CONSTANT ( x "name" --) COUNT ( c-addr1 -- c-addr2 u) CR ( --) CREATE" ( --) CREATE ( "" --) DECIMAL ( --) DEPTH ( -- +n) DO Compilation: ( -- dodest) DOES> Compilation: ( colon-sys1 -- colon-sys2) Execution: ( -- a-addr) ( R: sys --) name Execution: ( -- a-addr) (R: -- sys2) DROP ( x --) DUP ( x -- x x) ELSE Compilation: ( orig1 -- orig2) EMIT ( x --) ENVIRONMENT? ( c-addr u -- value true) or EVALUATE ( i*x c-addr u -- j*x) EXECUTE ( i*x xt -- j*x) EXIT ( --) ( R: sys --) FILL ( c-addr u char ---) FIND ( c-addr -- [[c-addr 0]|[xt 1]|[xt -1]]) FM/MOD ( d1 n1 -- n2 n3) HERE ( -- addr) HOLD ( char -- ) I ( -- n|u) ( R: sys -- sys) IF Compiling: ( -- orig) IMMEDIATE ( --) INVERT ( mask1 -- mask2) KEY ( -- char) LEAVE ( --) ( R: sys --) LITERAL Compilation: ( x --) LOOP Compilation: ( dodest --) M* ( n1 n2 -- d) MAX ( n1 n2 -- n3) MIN ( n1 n2 -- n3) MOD ( n1 n2 -- n3) MOVE ( addr1 addr2 u ---) NEGATE ( n1 -- n2) OR ( mask1 mask2 -- mask3) OVER ( x1 x2 --- x1 x2 x1) POSTPONE Compilation: ( "name" --) QUIT ( --) ( R: i*x --) R@ ( -- x) ( R: x -- x) R> ( -- x) ( R: x --) RECURSE ( --) REPEAT Compilation: ( orig dest --) ROT ( x1 x2 x3 --- x2 x3 x1) S" Compilation: ( "ccc<">" --) Execution ( -- c-addr u) Intepretation ( "ccc<">" -- c-addr u) S>D ( n -- d) SHIFT ( x1 n -- x2) SIGN ( n --) SM/REM ( d1 n1 -- n2 n3) SPACE ( --) SPACES ( n --) STATE ( -- a-addr) SWAP ( x1 x2 --- x2 x1) THEN Compilation: ( orig --) 'TIB ( -- a-adr) TIB ( -- c-addr) TYPE ( c-addr u --) U. ( u --) U< ( u1 u2 -- flag) UM* ( u1 u2 --- ud) UM/MOD ( ud u1 -- u2 u3) UNLOOP ( --) ( R: sys --) UNTIL Compilation: ( dest --) VARIABLE ( "name" --) WHILE Compilation: ( dest -- orig dest) WORD ( char "ccc" -- c-addr) XOR ( x1 x2 -- x3) [ ( --) ['] Compilation: ( "name" --) [CHAR] Compilation: ("ccc< >" --) ] ( --) CORE Extension Word Set .( ( "ccc<)>" --) .R ( n1 n2 --) 0< ( n|u -- flag) 0> ( n|u -- flag) 2>R ( x1 x2 --) ( R: -- x1 x2) 2R> ( -- x1 x2) ( R: x1 x2 -- ) 2R@ ( -- x1 x2) ( R: x1 x2 -- x1 x2) ?DO Compilation ( -- dodest) :NONAME ( -- xt sys1) <> ( x1 x2 -- flag) AGAIN Compilation: ( dest --) C" Compilation: ( "ccc" --) CASE Compilation: ( -- case-sys) COMPILE, ( xt --) CONVERT ( ud1 c-addr1 -- ud2 c-addr2 --) ENDCASE Compilation: ( case-sys1 case-sys2 of-sys --) ENDOF Compilation: ( case-sys1 of-sys -- case-sys2) ERASE ( addr u --) EXPECT ( c-addr +n --) FALSE ( -- false) HEX ( ---) J ( -- n|u) ( R: sys -- sys) OF Compilation: ( case-sys1 -- case-sys2 of-sys) TO Usage: TO name UNMARK ( a-addr --) MARKER ( "name"--) NIP ( x1 x2 --- x2) PAD ( -- c-addr) (PARSE) ( char "ccc" -- c-addr u) PARSE ( char "ccc" -- c-addr u) PICK ; ( x(u) .. x(1) x (0) u -- x(u) .. x(1) x(0) x(u)) QUERY ( --) REFILL ( -- flag) RESTORE-INPUT ( x1 .. xn n -- flag) ROLL ( x(u) x(u-1) .. x(0)u -- x(u-1) .. x(0) x(u)) SAVE-INPUT ( -- x1 .. xn n) SPAN ( -- a-addr) TRUE ( -- true) TUCK ( x1 x2 --- x2 x1 x2) U.R ( u n -- ) U> ( u1 u2 -- flag) UNUSED ( -- u) MAKEVAL ( --) VALUE ( "name" --) WITHIN ( n1|u1 n2|u2 n3|u3 -- flag) BLOCK Word Set BLOCK ( u -- a-addr) BUFFER ( u -- a-addr) FLUSH ( --) SAVE-BUFFER ( u a --) SAVE-BUFFERS ( --) UPDATE ( --) BLOCK Extensions Word Set EMPTY-BUFFERS ( --) LIST ( u --) LOAD ( i*x u -- j*x) SCR ( -- a-addr THRU ( u1 u2 --) DOUBLE Word Set 2CONSTANT Compilation: ( x1 x2 "name" --) 2LITERAL ( -- x1 x2) 2VARIABLE Compilation: ( "name" --) D+ ( d1|ud11 d2|ud2 --- d3|ud3) D- ( d1|ud11 d2|ud2 --- d3|ud3) D. ( d --) D.R ( d n --) D0< ( d -- flag) D0= ( d|ud -- flag) D2* ( d1 -- d2) D2/ ( d1 -- d2) D< ( d1 d2 -- flag) D= ( xd1 xd2 -- flag) D>S ( d -- n) DABS ( d1 -- +d2) DMAX ( d1 d2 -- d3) DMIN ( d1 d2 -- d3) DNEGATE ( d1 -- d2) M*/ ( d1 n1 +n2 -- d2) M+ ( d1|ud11 n1|u1 --- d2|ud2) DOUBLE Extensions Word Set 2ROT ( x1 x2 x3 x4 x5 x6 -- x3 x4 x5 x6 x1 x2) D! ( d a-addr --) D@ ( a-addr -- d) DU< ( ud1 ud2 -- flag) ERROR Handling Word Set CATCH ( i*x xt -- j*x 0) no THROW received THROW ( k*x 0 -- k*x) not thrown FACILITY Extensions Word Set AT-XY ( u1 u2 --) EKEY ( -- u) EKEY? ( -- flag) EMIT? ( -- flag) DATESTAMP ( -- reg-d0) TIME? ( -- seconds minutes hours) YEAR? ( -- days year-1976) MONTH? ( days year-1976 -- day month year) TIME&DATE ( -- +n1 +n2 +n3 +n4 +n5 +n6) KEY? ( -- flag) MS ( u --) \ u < 1,310,720 PAGE ( --) FILE Access Word Set \ ( "ccc" --) BLOCK-FID ( -- a-addr) CLOSE-FILE ( fileid -- ior) NEWFILE ( -- x1) CREATE-FILE ( c-addr u x1 -- x2 ior) DELETE-FILE ( c-addr u -- ior) FILE-POSITION ( fileid -- ud ior) FILE-SIZE (fileid -- ud ior) INCLUDE-FILE (i*x fileid -- j*x) INCLUDED (i*x c-addr u -- j*x) OPEN-FILE ( c-addr u x1 -- x2 ior) R/O ( -- x) R/W ( -- x) READ-FILE ( c-addr u1 fileid -- u2 ior) READ-LINE ( c-addr u1 fileid -- u2 flag ior) REPOSITION-FILE ( ud fileid -- ior) RESIZE-FILE ( ud fileid -- ior) SOURCE-FILE ( -- a-addr) W/O ( -- x) WRITE-FILE ( c-addr u1 fileid -- ior) WRITE-LINE ( c-addr u1 fileid -- ior) MEMORY Word Set MEM-TYPE ( -- a-addr) ALLOCATE ( u -- a-addr ior) FREE ( a-addr -- ior) RESIZE ( a-addr1 u -- a-addr2 ior) MEMORY Extensions Word Set AVAILABLE ( -- u) SEARCH Order Word Set DEFINITIONS ( --) FORTH-WORDLIST ( -- wid) GET-CURRENT ( -- wid) GET-ORDER ( -- wid1 ... widn n) SET-CURRENT ( wid --) SET-ORDER ( wid1 ... widn n --) SEARCH-WORDLIST ( c-addr u wid -- 0) if not found WORDLIST ( -- wid) SEARCH Order Extensions Word Set ALSO ( --) FORTH ( --) ONLY ( --) ORDER ( --) PREVIOUS ( --) STRING Word Set -TRAILING ( c-addr u1 -- c-addr u2) /STRING ( c-addr1 u1 n --- c-addr2 u2) BLANK ( c-addr u ---) CMOVE> ( c-addr1 c-addr2 u --) CMOVE ( c-addr1 c-addr2 u --) COMPARE ( c-addr1 u1 c-addr2 u2 -- n) SEARCH ( c-addr1 u1 c-addr2 u2 -- c-addr3 u3 flag) STRING Extensions Word Set LEX ( c-addr1 u1 c-addr2 u2 -- c-addr3 u3 c-addr1 u4 char true | c-addr1 u1 false) * * * * * * * * * * 2) Here are the definitions of most of the findable words appearing in JAX4TH which are not dpANS words, but rather are implementation-specific. Any or all of these words may disappear or have their definitions changed in future revisions of JAX4TH. The use of most of these words is highly discouraged! Their correct use frequently depends on understanding of system internals, understanding not provided with the current level of documentation of this experimental system. This list is supplied for information only, and is in no particular order. SAVE-IMAGE ( c-addr ct -- 0|ior) Save the code and data portions of the local image as a reloadable JAX4TH image akin to the supplied DEFIMAGE.JX4 with the syntax: SAVE-IMAGE MY-IMAGE.JX4 Such an image can be reloaded subsequently by invoking its name on the Amiga Shell command line, as in: 1> JAX4TH MY-IMAGE.JX4 at which time JAX4TH will load the named image. At load time of such an image, if the contents of the variable AUTOSTART are non- NULL, those contents will be treated as an execution token and executed prior to JAX4TH displaying its logo and quitting to the interpreter. Use of SAVE-IMAGE requires that the default image DEFIMAGE.JX4 be present on the JX4: device. SAVE-IMAGE returns a zero (0) for success. If SAVE-IMAGE encounters difficulties, it will report them as follows: Error Code Meaning ---------- ------- 1 couldn't open named destination imagefile 2 couldn't open JX4:DEFIMAGE.JX4 3 couldn't read DEFIMAGE.JX4 4 couldn't read DEFIMAGE.JX4 5 couldn't write code image 6 couldn't read DEFIMAGE.JX4 7 couldn't read DEFIMAGE.JX4 8 couldn't write data image 9 couldn't read DEFIMAGE.JX4 10 couldn't write end-of-image AUTOSTART ( -- a-addr) Variable, normally contains $00000000. If this variable is non-NULL in a loaded image, JAX4TH will treat the contents as an execution token and attempt to execute same before displaying the JAX4TH logo and quitting to the interpreter. JAX4TH currently performs no validity check on the contents of AUTOSTART so AUTOSTART had better either contain a valid execution token in a saved image or had been left NULL. DOS ( -- addr) Variable, holds initialized library pointer for Amiga Exec library. DO NOT WRITE TO THIS VARIABLE EXEC ( -- addr) Variable, holds library pointer for Amiga DOS library. DO NOT WRITE TO THIS VARIABLE. ARGARRAY ( -- addr) Array to hold arguments to a CALL , instantiated by >DREG and >AREG . CALL ( offset lib-ptr-var-addr -- ret) Amiga library routine caller. Calls the Amiga library routine whose offset is <> in the library whose pointer is contained at <>, returning <>. At the time of the CALL registers are loaded from ARGARRAY as loaded via >AREG and >DREG . >AREG ( x n --) Prepares to store x in the nth address register in the next CALL . >DREG ( x n --) Prepares to store x in the nth data register in the next CALL . STDOUT ( -- addr) Variable, contains the output handle of the current instance of JAX4TH. STDIN ( -- addr) Variable, contains the input handle of the current instance of JAX4TH. IMPLEMENTOR ( --) Make the IMPLEMENTOR-WORDLIST first in the search order, overwriting previous first-in-search-order entry. IMPLEMENTOR-WORDLIST ( -- wid) The WORDLIST of non-standard words which the implementor (me! hi mom!) left findable in the JAX4TH kernel for one revision. None of the words in the IMPLEMENTOR-WORDLIST in one revision of JAX4TH are guaranteed to be present in any futher revisions, or if present, to have the same definition. PERFORM ( a-addr --) Fetch from a-addr and EXECUTE. UNNEST ( ---) Pop Instruction Pointer from Return Stack and continue Forth execution. .NAME ( namtok --) Print the name of the word whose name token is on the stack. SMUDGE ( --) Hide the latest definition from dictionary searches. UNSMUDGE ( --) Reveal the latest definition to dictionary searches. VOCABULARY ( "ccc" --) Create a WORDLIST and associate a name with it such that when the name is invoked, the new WORDLIST will become first in the dictionary search order, overwriting the previous first-in-search- order WORDLIST. -ROT ( w1 w2 w3 --- w3 w1 w2) Negative rotation of top three stack items. (DUP>R) ( w1 -- w1) ( R: -- w1) Execution engine to DUP top-of-stack to Return Stack. (R>DROP) ( --) ( R: w --) Execution engine to DROP top of Return Stack DUP>R ( w1 -- w1) ( R: -- w1) Correct way to invoke (DUP>R). Aborts if interpreting. R>DROP ( --) ( R: w --) Correct way to invoke (R>DROP). Aborts if interpreting. SP0 ( -- adr) Variable, contains address of original Data Stack pointer used by this instance of JAX4Th. SP@ ( -- w1) Returns current Data Stack pointer value. SP! ( a-addr --) Stores a-addr to SP. You are nuts if you try to use this. Please don't crash your Amiga on my account! RP0 ( -- adr) Variable, contains address of original Return Stack pointer used by this instance of JAX4Th. RP@ ( -- w1) Returns current Return Stack pointer value. RP! ( w1 -- ) Stores a-addr to RP. You are nuts if you try to use this. Please don't crash your Amiga on my account! UNDERDUP ( n1 n2 -- n1 n1 n2) Duplicate second-on-stack as shown in stack diagram. ?ENOUGH ( i*x n -- i*x -or- --) A' la Laxen & Perry, aborts if i < n. ?STACK ( i*x -- i*x -or- --) A' la Laxen & Perry, aborts on stack underflow. Stack overflow not yet checked. NOOP ( --) Does nothing. Marvellously, this word has been omitted from dpANS. LMOVE ( a-addr1 a-addr2 ct ---) Move a number of chars divisible by four (4) from a-addr1 to a-addr2. As CMOVE. LMOVE> ( a-addr1 a-addr2 ct --) Move a number of chars divisible by four (4) from a-addr1 to a-addr2. As CMOVE>. WMOVE ( a-addr1 a-addr2 ct --) Move a number of chars divisible by two (2) from a-addr1 to a-addr2. As CMOVE. WMOVE> ( a-addr1 a-addr2 ct --) Move a number of chars divisible by four (2) from a-addr1 to a-addr2. As CMOVE>. PLACE ( c-addr1 u c-addr2 --) Install c-addr1 u as a counted string at c-addr2. W@ ( a-addr --- 16b) As @ for 16-bit quantities at word-aligned addresses. W, ( 16b --) As , for 16-bit quantities at word-aligned addresses. W! ( 16b a-addr ---) As ! for 16-bit quantities at word-aligned addresses. 2, ( x1 x2 ---) As , for double-entries ( two stack entries ). ON ( a-addr --) Store TRUE to a-addr. OFF ( a-addr --) Store FALSE to a-addr. 0>= ( n1 -- flag) Tests for positive or zero. 0<= ( n1 -- flag) Tests for negative or zero. BETWEEN ( n1 n2 n3 -- flag) TRUE if ((n1>=n2)&(n1<=n3)). HLD ( -- a-addr) Holds address of current position in the formatted number output buffer. 2+ ( n1 -- n2) BASIS12 Add two (2) to n1. 2- ( n1 -- n2) BASIS12 Subtract two (2) from n1. MU/MOD ( ud u -- u.rem ud.quot ) Unsigned divide UD by U and return double quotient and single modulus. UNDER+ ( n1 n2 n3 -- n1+n3 n2) Add top-of-stack to third-on-stack. ?DNEGATE ( ud flag -- ud|-ud) Treat UD as signed and negate if flag is TRUE. TABS ( t1 -- _t1_) Return abs value of a triple number. CAPS ( -- a-addr) Variable, TRUE if all input is converted to uppercase. *NOTE* this feature in particular will change in future revisions! Truly-case-insensitive searching will be a switchable option. UPC ( char1 -- char2) Convert char1 to uppercase. UPPER ( c-addr u --) Convert alphabetical chars in the string specified by c-addr u to uppercase. ?UPPERCASE ( c-addr --) If CAPS is ON, convert all alphabetical characters in the counted string residing at c-addr to uppercase. SKIP ( b-addr1 u1 char --- b-addr2 u2) SKIP all leading delimiters char. SCAN ( addr ct char --- addr ct) SCAN for first instance of delimiter char. KERN>ABS ( resident-kernel-token --- abs-addr) Convert a kernel token to a CPU address. CODE>ABS ( local-code-token --- abs-addr) Convert a local code token to a CPU address. DATA>ABS ( dat-addr --- abs-addr) Convert a data address to a CPU address. ABS>KERN ( abs-addr --- resident-kernel-token) Convert a CPU address to a kernel token. ABS>CODE ( abs-addr --- local-code-addr) Convert a CPU address to a local code address. ABS>DATA ( abs-addr --- data-addr) Convert a CPU address to a data address. L>DATA ( link -- data-seg-relative-addr) Convert a link token to a data address. CELL ( -- n) The size in address units of one cell. BOUNDS ( addr u -- outerlim innerlim) Convert an address and a count to loop bounds. DP! ( a-addr --- ) Set the dictionary pointer. DP@ ( --- a-addr) Fetch the dictionary pointer. CONTEXT ( -- addr) Address containing token for first wordlist in search order. WIDTH ( -- a-addr) Variable containing max name header size, max == 31. HASH ( $addr -- thread#) Find the thread number for a counted string. #VOCS ( -- n) Constant, max number of vocs in search order L>NAME ( link-tok -- name-tok) Convert link token to name token. L ( linktok -- exetok) Convert a link field token to an execution token. CHECK-STATE ( --) Aborts if STATE @ yields FALSE. EMITBUF ( -- addr) A buffer which holds char(s) to be EMITted. DOSWRITE ( fh rel-addr ct -- ret) Assembly primitive to write to AmigaDOS file handle. LAST ( -- a-addr) Variable, holds token referring to last addition to dictionary. B/BUF ( -- n) Constant, number of chars in a BLOCK. OPEN-FILE" ( "ccc<"> -- fh ior) Opens file whose name is in input stream: OPEN-FILE" ram:foo.bar" 'WORD ( -- a-addr) Address of the word buffer used by WORD. INTERPRET ( --) Interpret a line or BLOCK of current input stream. ?MISSING ( t|f --) Aborts with query when dictionary entry not found and input cannot be converted to a number. STATUS ( --) End-of-input-line processor, a' la Laxen & Perry C/L ( -- n) Constant, number of chars per line of a LIST display. L/SCR ( -- n) Constant, number of lines in a LIST display. DEBUG ( --) A no-op, in effect, in this revision of JAX4TH. COLD ( --) Cold boot. WARM ( --) Warm start. INSTANCES ( -- +n) Display the number instances currently running off of one resident JAX4TH kernel. MAKECREATE ( --) MAKENEST ( --) MAKECONST ( --) MAKEDOES ( --) MAKEDDOES ( --) DOESZ ( a-addr --) MAKE2CONST ( --) All these create various execution engines. Don't use these words. Really! MAKE-TOKEN ( local-code-addr --- local-token) Turn an address in the local code segment into an execution token. DIGIT ( char n -- n true | char false ) Convert char to binary digit in current number base. UD*S ( ud1 n -- ud2) Multiply unsigned double by a single. ?LEAVE ( flag --) ( R: sys --) ( --) Exit a loop if flag is TRUE ," ( "ccc<">" --) Compile counted string with no execution engine at HERE. BYE ( --) Clean up and exit this instance of JAX4TH.