goForth in 10 minutes

goForth_intro.txt

TIILE:          gForth Overiew
ORIG DATE:      20170930
LAST REV DATE:  20170930
AUTHOR:         mj <modusjonens@gmail.com>

==========================================================
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
==========================================================


Basic Stack Ops:
===============

1 2 3 4 	\\ pushes 1,2,3,4 on the stack

.s		\\ print top of stack (peek) 
		\\   *AND* <height> of stack

.		\\ pop and print

==========================================================
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
==========================================================


Binary Math Ops:
===============

+ - * / mod 	\\ operate on top two stack items

2 2 + . 	\\ Adds 2 + 2 and pops/prints result 4

100 11 + 6 *	\\ push 100, 11. add 100, 11, push
		\\ on stack. push 6 on top of stack,
		\\ pop 2, multiply them, push result
		\\ on top of stack

==========================================================
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
==========================================================

Fancy Stack Ops:
===============

ASH?: 
    [T|F] :: (Operation) Affects Stack Height?
    
    if T: 
	[-|+] :: (-) shrinks stack (+) grows stack	

NAME	| ASH?	| NOTES
+--------------------------------------------------------+
drop	| T(-)	| pop + remove the top of stack
+--------------------------------------------------------+
swap	| F	| switch top two stack items 
	|	|
	|	| Example:
	|	| -------
	|	|   1 25 100  ok
	|	|   swap  ok
	|	|   .s <3> 1 100 25  ok
+--------------------------------------------------------+
dup	| F	| copy top-most item and push copy
	|	| back on top of stack
+--------------------------------------------------------+
over	| T(+)	| cp s[-2] and push on top of stack
	|	|		
	|	| Example:
	|	| -------
	|	|   .s <2> 1 100  ok
	|	|   over .s
	|	|   .s <3> 1 100 1  ok
+--------------------------------------------------------+
rot	| F	| shift stack members down
	|	| bottom-most element ends up on top
	|	|
	|	| Example:
	|	| -------
	|	|   1 100 25  ok
	|	|   rot
	|	|   .s <3> 100 25 1  ok	
+--------------------------------------------------------+
nip	| T(-)	| pop s[-2]
        |       |
        |       | nip == swap drop
+--------------------------------------------------------+
tuck	| T(+)	| tuck == swap over
	|	| 	
	|	| 
	|	| Examples:
	|	| --------
	|	|   1 2  ok
	|	|   tuck  ok
        |       |   .s <3> 2 1 2  ok
        |       | 
        |       |   1 7 13  ok
        |       |   tuck  ok
        |       |   .s <4> 1 13 7 13  ok
+--------------------------------------------------------+

2-Variants:
  (Read '?' as zero or more)

NAME	| ASH?	| NOTES
+--------------------------------------------------------+
2drop	| T(-)	| 2drop == drop drop
        |       |
        |       | Example:
        |       | --------
        |       |   1 3 5  ok
        |       |   2drop  ok
        |       |   .s <1> 1  ok
+--------------------------------------------------------+
2swap   | F     | A B C D -> C D A B
        |       |
        |       | ? A B C D -> ? C D A B
        |       |
        |       | Example:
        |       | --------
        |       |   1 2 3 4  ok
        |       |   2swap  ok
        |       |   .s <4> 3 4 1 2  ok               
+--------------------------------------------------------+
2dup    | T(+)  | A B -> A B A B 
        |       |
        |       | ? A B -> ? A B A B 
        |       |
        |       | Examples:
        |       | --------
        |       |   1 3 4  ok
        |       |   2dup  ok
        |       |   .s <5> 1 3 4 3 4  ok
+--------------------------------------------------------+
2over   | T(+)  | ? A B C D -> ? A B C D A B
        |       |
        |       | Example:
        |       | --------
        |       |       
        |       |   1 2 3 4  ok
        |       |   2over  ok
        |       |   .s <6> 1 2 3 4 1 2  ok
+--------------------------------------------------------+
2rot    | F     | Stack height >= 6
        |       |
        |       | # TODO -- provide examples
+--------------------------------------------------------+
2nip    | T(-)  | Stack height >= 4
        |       |
        |       | A B C D -> C D
        |       |
        |       | Examples:
        |       | --------
        |       |   1 2 3 4  ok
        |       |   2nip  ok
        |       |   .s <2> 3 4  ok
+--------------------------------------------------------+
2tuck   | T(+)  | Stack height >=4
        |       |
        |       | A B C D -> C D A B C D
        |       |
        |       | Examples:
        |       | --------
        |       |   1 2 3 4  ok
        |       |   2tuck  ok
        |       |   .s <6> 3 4 1 2 3 4  ok
        |       |
        |       |   1 2 3 4 5 6  ok
        |       |   2tuck  ok
        |       |   .s <8> 1 2 5 6 3 4 5 6  ok
+--------------------------------------------------------+

==========================================================
$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$$
==========================================================


Functions/Procedures:
====================

Define a function:
       
    : <function word> ( Desc as comment ) [ body words ] ;

    Example:
    -------
    : getsix ( multiply 2 3 ) * . ;  ok
    1 2 3  ok
    getsix 6  ok

Chain together functions by invoking words within the 
context of your defined functions.