*** Progress on CORE wordset: on AND  (skipped ahead some places)

                                Forth Summary
                                -------------

The ANS Forth spec is nearly impossible to read, especially if you don't
know Forth too well yet, even if you invented Forth.  While there are some
oversights in ANS Forth (I'll get to that at the end), the main problem is
the way the standard is written -- long-winded, jargon-filled and
disorganized.

This "cheat sheet" leans toward tersity.  A one-line explanation is usually
all you need; for the trickier words like CREATE and DOES> you can refer to
a tutorial.


Data type abbreviations for stack comments: (a # - n)
(These are mostly from Leo Brodie's "Summary of Forth Style Conventions"
found at ftp://ftp.forth.org/pub/Literature/forth_style.txt
A few are from ANS, and I made up a few more)
	x	Any type
	xd	Double-cell value, any type
	u	Unsigned integer
	ud	Unsigned double-cell integer
	n	Signed integer
	+n	Non-negative signed integer
	d	Signed double integer
	+d	Positive double integer
	?	Boolean flag
	=t	  True
	=f	  False
	a	Address
	aa	Aligned Address
	cfa	Code Field Address
	pfa	Parameter Field Address
	'	(prefix) "Address of"
	'	(suffix) "changed/transformed" (as in Algebra notation)
	xt	eXecution Token (typically a word's CFA)
	c	Character (7-bit ASCII)
	c8	Character (8-bit extended ASCII)
	cu	Unicode character (16-bit)
	b	Byte (8-bit, or whatever the machine's byte size is)
	lo hi	Bounds (as used for WITHIN)
	fr to	Range "from..to", as in "fr to THRU"
	to fr		Backwards, as in "to fr DO ... LOOP"
	s d	Source & Destination
	#	count
	o	offset (typically in bytes)
	i	index (i.e., to a record in a table)
	m	mask
	cstr	Counted string (1st byte = count)
	a #	New-style string
	var	Variable (used by itself in a stack comment)

	*	0 or more cells (used by itself: the entire stack)
	*a #	"*a" stands for a number "#" of addresses

Parameters can be given names, like this:
	nTOP	A number called TOP

Input-stream parameters: (pulled from the input buffer, not the stack)
	"c"	Single character, blank delimited
	"name"	Several characters, blank delimited
	textX	Several characters, delimited by 'X'


Conventions/format:
origin	WORD (stack effects)  Short description

"origin" is a 6-letter abbreviation saying where it's from:
	------	Not sure, various sources, or I made it up..
	retro	Retro/Forth OS
	aztec	Aztec Forth
	pygmy	Pygmy Forth
	cm	CMforth
	color	Color Forth
	f83	FIG Forth '83 (still a major standard)
	f79	FIG Forth '79
	core	ANS "core" wordset
	coreX	ANS "core-ext" (I won't mention the other "-ext" wordsets)
	block	ANS "block" wordset
	file	ANS "file" wordset (Some major inconsistencies here)
	fclty	ANS "facility" wordset (A good start, but too minimal)
	malloc	ANS "memory-allocation" wordset
	order	ANS "search-order" wordset (lacks something big: VOCABULARIES)
	tools	ANS "programming-tools" wordset (half-assed)
	str	ANS "string" wordset (not too useful.. rather incomplete)
	float	ANS "floating-point" wordset
	dbl	ANS "double-number" wordset
	exc	ANS "exception" wordset
	local	ANS "locals" wordset (not too popular)


Obsolete words in ANS Forth:
coreX	CONVERT (ud1 cstring - ud2 a)  (superceded by >NUMBER)
coreX	EXPECT (a +n -)  Input a string (superceded by ACCEPT)
coreX	SPAN (var)  Length of last string returned by EXPECT
coreX	QUERY (-)  "TIB #max EXPECT" etc. (superceded by ACCEPT & EVALUATE)
coreX	TIB (var)  Address of input buffer (superceded by SOURCE)
coreX	#TIB (var)  Length of input buffer (superceded by SOURCE)
tools	FORGET ("name" -)  (Doesn't work with fancy dictionary structures)

CORE words:
core	ABORT		empty stacks & exit to interpreter
core	ABORT ("message"-) (X -) If X isn't 0, show message and ABORT

  Compilation, etc:
core	CREATE ("name" -)  Creates a new word. 
		Typically followed by , or C, to add data.
core	DOES> (- x)  Compiles code for the new word, up to ;
		x = location of data added after CREATE
core	: ("name") ... ;
core	' ("name" - xt)
core	EXECUTE (xt -)
core	>BODY (xt - PFA)  Get Parameter (data) Field Addr of a CREATEd word

  Memory:
core	! @ +! , C, HERE ALLOT ALIGN ALIGNED
core	2! 2@ 2,  Double-cell versions..


  Stack:
core(X)	DROP DUP ?DUP OVER SWAP NIP TUCK PICK ROT -ROT ROLL
dbl	2DROP 2DUP 2OVER 2SWAP 2NIP 2TUCK
dblX	2ROT
core	>R (PUSH)
core	R> (POP)

  Loops:
core	to from DO ... LOOP
core	to from DO ... step +LOOP

  Math:
core	+ - * / (n n - n)  The usual
core	/MOD (nTOP nBOTTOM - nQUOT nREM)
core	*/  (a b c - n)  Scaling: a * b / c (doesn't lose precision)
core	*/MOD
core	1+ 1- (n - n)  Increment/decrement
core	2* 2/ (n - n)  Multiply/divide by 2 (left/right shift by 1)
core	ABS (n - u)  Absolute value

  Conditionals:
core	0< 0> 0= 0<>
core	< = >

  Display/Input, and strings & numbers..
core	. (n -)  Prints a number, followed by a space
core	U. (u -)  unsigned
core	.R (n # -)  Right-justified & space-padded to # wide
core	U.R (u # -)  unsigned
core	BASE (var)
core	." (text" -)  Usage: ." string"
	S" (text" - a #)
	C" (text" - cstr)
core	TYPE (a # -)  Print a string
core	ACCEPT (a # - #')  Input a string (#=max length; #'=actual)
core	>NUMBER (ud a # - ud' a' #')  Parse a number from a string
gforth	SNUMBER? ( a # - n 1 | 0)  ...A more pragmatic version
core	>IN (var)  Parser position within input buffer
core	WORD (C textC - cstr)  Parse a word from input buffer
coreX	PARSE (C textC - a #)  "

  Custom number formatting:
core	<# # #S #>

  Comments:
core	( comment )
core	\ comment


FACILITY wordset:
fclty	AT-XY (x y -)  Move cursor to x,y coordinate
fclty	KEY? (- ?)  TRUE if a key is available
fclty	PAGE (-)  Clear screen / form feed

FACILITY-EXT wordset:
fcltyX	EKEY (- cr)  Get a "raw" key event
fcltyX	EKEY>CHAR (cr -- c =f | c =t)  TRY to convert to a char
fcltyX	EKEY? (- ?)  TRUE if a key is available for EKEY
fcltyX	EMIT? (- ?)  TRUE if terminal is ready for output (not blocked)
fcltyX	MS (# -)  Wait for at least # milliseconds
fcltyX	TIME&DATE (- sec min hr day mon yr)

FILE wordset:
   fam = file access method (binary/text, read/write/append, etc.)
   fid = fileid (file handle)
   ior = I/O result: 0 if ok; error codes vary (they *should* be documented)
   a # = filename
file	BIN (fam - fam')  Use binary mode, not linemode
file	CLOSE-FILE (fid - ior)
file	CREATE-FILE (a # fam - fid ior)
file	DELETE-FILE (a # - ior)
file	FILE-POSITION (fid - ud ior)  ud = current file position
file	FILE-SIZE (fid - ud ior)   ud = file size, in chars
file	INCLUDE-FILE (* fid - *)  intrepret from file
file	INCLUDED (* a # - *)  shortcut; Usage: S" FILENAME" INCLUDED
file	OPEN-FILE (a # fam - fid ior)
file	R/O (- fam)
file	R/W (- fam)
file	READ-FILE (A # fid - #' ior) Read # chars to A
		#' = chars actually read (0 = EOF)
file	READ-LINE (A # fid - #' ? ior)
		Read a line of text (at most # chars); store at A
		EOF if ?=f; #' = chars actually read
		** FLAW: no way to tell if EOL was reached or not!
		** The ANS method (# #' =) is ambiguous.. dumb asses!
file	REPOSITION-FILE (ud fid - ior)  Seek to position ud
file	RESIZE-FILE ( ud fid - ior)
file	WRITE-FILE (a # fid - ior) Write string 'a #' to file
file	WRITE-LINE (a # fid - ior) Write string followed by EOL char(s)

FILE-EXT wordset:
fileX	FILE-STATUS (a # - x ior)  If filename 'a #' exists,
		ior is 0 and x is implementation-defined (attributes, etc.)
fileX	FLUSH-FILE (fid - ior)  Write out to disk
fileX	REFILL (- ?)  {tk}
fileX	RENAME-FILE (a1 #1  a2 #2 - ior) 1=original, 2=new name

BLOCK wordset:
block	BLK (var)  Block # being interpreted, or 0 if none
block	BLOCK (i - a)  Get address of block i (load if necessary)
block	BUFFER (i - a)                        (don't load)
block	FLUSH (-)  SAVE-BUFFERS, then unassign all buffers
block	LOAD (* i - *)  Interpret from block i
block	SAVE-BUFFERS (-)  Save all UPDATEd blocks & mark as unmodified
block	UPDATE (-)  Mark current block buffer as modified

BLOCK-EXT wordset:
blockX	EMPTY-BUFFERS (-)  Unassign all buffers, without saving
blockX	LIST (i -)  Display block i on screen
blockX	SCR (var)  Last block # LISTed
blockX	THRU (* fr to - *)  LOAD blocks FR through TO

MEMORY-ALLOCATION wordset:
malloc	ALLOCATE (# - aa ior)  Allocate # bytes
malloc	FREE (aa - ior)
malloc	RESIZE (aa # - aa' ior) Note: original region may be moved

PROGRAMMING-TOOLS wordset:
tools	.S (-)  Stack trace
tools	? (aa -)  Display value at a-addr
tools	DUMP (a # -)  Dump memory
tools	SEE ("name" -)  Decompile/Disassemble a word
tools	WORDS (-)

PROGRAMMING-TOOLS-EXT wordset:
toolsX	AHEAD
toolsX	ASSEMBLER
toolsX	BYE
toolsX	CODE
toolsX	;CODE
toolsX	CS-PICK
toolsX	CS-ROLL
toolsX	EDITOR
toolsX	FORGET
toolsX	STATE
toolsX	[IF] [ELSE] [THEN]	Interpreted, immediate version..

SEARCH-ORDER wordset:
   wid = Wordlist ID
order	DEFINITIONS (-)  compile to first wordlist in search order
order	FORTH-WORDLIST (- wid)	Get standard FORTH wordlist
order	GET-CURRENT (- wid)	Get current wordlist
order	SET-CURRENT (wid -)	Compile to WID
order	GET-ORDER (- wid# ... wid1 #)  Get entire search-order
order	SET-ORDER (wid# ... wid1 # -)
order	WORDLIST (- wid)	Create an empty wordlist
order	ALSO (-)	Duplicate the first wordlist in the search order
order	FORTH (-)	Replace first wordlist with FORTH-WORDLIST
order	ONLY (-)	Set the minimum search order (which includes
			FORTH-WORDLIST and SET-ORDER)
order	ORDER (-)	Display the search-order
order	PREVIOUS (-)	Drop the first wordlist

order	FIND (cstr - cstr 0 | xt 1 | xt -1)  Search full search-order
order	SEARCH-WORDLIST (a # wid - 0 | xt 1 | xt -1)  Search one list

------	VOCABULARY ("name" -)  Create a new vocabulary (wordlist)
	That's the normal, non-ANS way to do things, and the way it's still
	done.  You still use most of the other ANS words, except WORDLIST.
	This way is easier, and it stores vocabulary names, not just wid's.

STRING wordset:
str	-TRAILING (a # - a #')  Trim trailing spaces
str	/STRING (a # #N - a' #')  Remainder of string after Nth char
str	BLANK (a # -)  Fill A with U spaces
str	CMOVE (s d # -)  Copy # bytes from S to D
str	CMOVE> (s d # -)  Same thing, starting with the highest address
str	COMPARE (a1 #1  a2 #2 - n)  n=0 if equal, -1 if 1<2, 1 if 2>1
str	SEARCH (a1 #1  a2 #2 - a3 #3 f)  Search a1 for a2. a3=where found
str	SLITERAL (a # -) (- a' #)  Copy to a "safe" location & compile...
