various documentation updates and small fixes

examples/readme.txt

@@ -23,8 +23,8 @@ life.frt: Conveys game of life. Its very memory intensive, the example
    code works on an Atmega16, but a bigger one would allow larger
    worlds.
 
-string-rec.frt: converts a " delimited string into a printable,
-   compilable and postponable text object. It replaces the s" command.
+rec-*.frt: Collection of various recognizers. They enable new native
+   data types and modify the behaviour of the interpreter.
 
 sierpinski.frt: simple fractal generator. Illustrates the use of
    the amforth-shell to include library files.
@@ -35,3 +35,6 @@ co.frt: co routines aka subroutines for nonpreemtive multitasking.
 many.frt: Repeat the input line until a key is hit. Use it with care
    since it can cause a lot of trouble. Since the input line is re-parsed
    every time, it is much slower than a compiled word.
+
+stack.frt: Generic stack operations. Implements a independent stack, 
+   see ../tests/stack-test.frt for a Hayes test suite.

examples/rec-char.frt

@@ -1,12 +1,11 @@
-\ check for the 'c' syntax for single
-\ characters.
-: rec:char ( addr len -- n r:num | r:fail )
+\ check for the 'c' syntax for single characters.
+: rec-char ( addr len -- n rectype-num | rectype-null )
   3 = if \ a three character string
     dup c@ [char] ' = if \ starts with a '
       dup 2 + c@ [char] ' = if \ and ends with a '
-        1+ c@ r:num exit
+        1+ c@ rectype-num exit
       then
     then
   then
-  drop r:fail
+  drop rectype-null
 ;

examples/rec-double-paren.frt

@@ -69,5 +69,3 @@ set-current
 \ T{ S" ))"   rec-comment rot drop -> 1 rectype-xt }T
 \
 \ ------------------------------------------
-\ with nesting the [IF] [ELSE] [THEN] can be
-\ implemented likewise.

examples/rec-name.frt

@@ -14,5 +14,5 @@ rectype: rectype-nt
     if rectype-nt else rectype-null then
 ;
 
-\ replace rec:word with rec:name
+\ replace rec-word with rec-name
 \ everthing else should work as before

examples/string-rec.frt → examples/rec-string.frt

@@ -19,7 +19,7 @@
 :noname postpone sliteral ;
 :noname -48 throw ; rectype: rectype-string
 
-: rec:string ( addr len -- addr' len' rectype-string | rectype-null )
+: rec-string ( addr len -- addr' len' rectype-string | rectype-null )
   over c@ [char] " <> if 2drop rectype-null exit then
   negate 1+ >in +! drop \ reset parse area to SOURCE
   [char] " parse  \ get trailing delimiter

tests/stack-test.frt

@@ -0,0 +1,58 @@
+s" tester.fs" INCLUDED 
+s" Stack.4th" INCLUDED
+
+\ ------------- Test Cases ------------
+
+4 STACK constant test
+
+: s1 1 0 ; \ 0 means continue with map-stack
+: s2 2 0 ;
+: s3 3 0 ;
+: s4 4 -1 ; \ -1 means premature exit from map-stack
+
+\ set and get methods
+T{ -1 test ' SET-STACK CATCH -> -1 test -4 }T
+T{ 0 test SET-STACK -> }T
+T{ test GET-STACK -> 0 }T
+
+T{ ' s1 1 test SET-STACK -> }T
+T{ test GET-STACK -> ' s1 1 }T
+
+T{ ' s2 ' s1 2 test SET-STACK -> }T
+T{ test GET-STACK -> ' s2 ' s1 2 }T
+
+T{ ' s1 ' s2 ' s3 3 test SET-STACK -> }T
+T{ test GET-STACK -> ' s1 ' s2 ' s3 3 }T
+
+\ testing map-stack
+\ the whole stack is used for execute
+T{ ' EXECUTE test MAP-STACK -> 3 2 1 0 }T
+
+T{ ' s1 ' s2 ' s4 3 test SET-STACK -> }T
+\ only the 1st element is executed
+T{ ' EXECUTE test MAP-STACK -> 4 -1 }T
+
+\ append and prepend methods
+T{ ' s1 1 test SET-STACK -> }T
+T{ ' s2 test >STACK -> }T
+T{ test GET-STACK -> ' s1 ' s2 2 }T
+T{ test STACK> -> ' s2 }T
+T{ test GET-STACK -> ' s1 1 }T
+
+T{ ' s1 1 test SET-STACK -> }T
+T{ ' s2 test >BACK -> }T
+T{ test GET-STACK -> ' s2 ' s1 2 }T
+T{ test BACK> -> ' s2 }T
+T{ test GET-STACK -> ' s1 1 }T
+
+\ depth
+T{ 2 1 0 3 test SET-STACK -> }T
+T{ test DEPTH-STACK -> 3 }T 
+
+\ pick
+T{ 2 1 0 3 test SET-STACK -> }T
+T{ 0 test PICK-STACK -> 0 }T 
+T{ 1 test PICK-STACK -> 1 }T 
+
+T{ -1 test ' PICK-STACK CATCH -> -1 test -9 }T
+T{ 5 test ' PICK-STACK CATCH -> 5 test -9 }T