From d2e032a559ec29726a839c3ce557519c4f99a765 Mon Sep 17 00:00:00 2001 From: mgcaret Date: Tue, 21 Jan 2020 23:39:06 -0800 Subject: [PATCH] more doc stuff; generated markdown contains flags info --- asm/forth-dictionary.s | 12 ++- docs/forth_dictionary.md | 191 +++++++++++++++++++++++++++++++++++---- utils/index.rb | 2 +- utils/index2md.rb | 23 +++-- 4 files changed, 197 insertions(+), 31 deletions(-) diff --git a/asm/forth-dictionary.s b/asm/forth-dictionary.s index 7e87d87..469c50c 100644 --- a/asm/forth-dictionary.s +++ b/asm/forth-dictionary.s @@ -635,7 +635,8 @@ noabort: .dword TWODROP EXIT eword -; H: Compilation/Interpretation: ( [text<">] -- ) Execution: ( f -- ) +; H: Compilation/Interpretation: ( [text<">] -- ) +; H: Execution: ( f -- ) ; H: If f is true, display text and execute -2 THROW. dwordq ABORTQ,"ABORT'",F_IMMED ENTER @@ -3704,7 +3705,7 @@ dword UDOTR,"U.R" EXIT eword -; ( u1 -- ) output u1 with no trailing space +; H: ( u1 -- ) output u1 with no trailing space dword UDOTZ,"U.0" ENTER .dword ZERO @@ -4308,7 +4309,8 @@ eword ; this does *not* save and restore the FCode evaluator state, that's what byte-load is ; for. This just gets things going, and unless SET-TOKEN is called, sticks with the ROM ; FCode tables. -; H: ( addr xt -- ) evaluate FCode at addr with fetch function xt, do not save state +; H: ( addr xt -- ) evaluate FCode at addr with fetch function xt, do not save FCode +; H: evaluator state dword dBYTE_EXEC,"$BYTE-EXEC" jsr _2parm ENTER @@ -5793,7 +5795,7 @@ dovalue: ldy #.loword(_pushvalue) NEXT eword -; H: ( n1 n2 str len ) create a definition that pushes the first two cells of the body +; H: ( n1 n2 str len -- ) create a definition that pushes the first two cells of the body ; H: initially n1 and n2 dword dTWOVALUE,"$2VALUE" jsr _4parm ; avoid dictionary corruption from stack underflow @@ -5906,7 +5908,7 @@ hword _TO,"_TO" eword ; H: ( n "name"<> -- ) change the first cell of the body of xt to n. Can be used on -; most words created with CREATE, DEFER, VALUE, etc. even VARIABLE +; H: most words created with CREATE, DEFER, VALUE, etc. even VARIABLE dword TO,"TO",F_IMMED ENTER .dword PARSEFIND diff --git a/docs/forth_dictionary.md b/docs/forth_dictionary.md index 32d5354..fb42e7b 100644 --- a/docs/forth_dictionary.md +++ b/docs/forth_dictionary.md @@ -1,6 +1,6 @@ # Forth Dictionary -Updated: 2020-01-16 09:50:15 -0800 +Updated: 2020-01-21 23:37:36 -0800 ## ! @@ -8,6 +8,8 @@ _( n c-addr -- )_ write cell n to c-addr ## " +- Immediate. + _( "text"<"> -- c-addr u )_ parse string, including hex interpolation ## \# @@ -36,12 +38,13 @@ _( ud -- 0 )_ perform # until quotient is zero ## $2VALUE -_( n1 n2 str len )_ create a definition that pushes the first two cells of the body +_( n1 n2 str len -- )_ create a definition that pushes the first two cells of the body initially n1 and n2 ## $BYTE-EXEC -_( addr xt -- )_ evaluate FCode at addr with fetch function xt, do not save state +_( addr xt -- )_ evaluate FCode at addr with fetch function xt, do not save FCode +evaluator state ## $CREATE @@ -53,7 +56,7 @@ _( -- addr )_ addr = address of the CPU direct page ## $EMPTY-WL -_( -- wid )_ create a new empty wordlist _(danger!)_ +_( -- wid )_ create a new empty wordlist (danger!) ## $ENV?-WL @@ -69,6 +72,8 @@ _( xt -- )_ forget word referenced by xt and subsequent words ## $HEX( +- Immediate. + _( "text" -- c-addr u )_ parse hex, return in allocated string ## $MEMTOP @@ -101,7 +106,7 @@ by an existing buffer, free it. ## $VALUE -_( n str len )_ create a definition that pushes the first cell of the body, initially n +( n str len ) create a definition that pushes the first cell of the body, initially n ## ' @@ -109,6 +114,8 @@ _( old-name<> -- xt )_ parse old-name in input stream, return xt of word ## ( +- Immediate. + _( "text" -- )_ parse and discard text until a right paren or end of input ## (.) @@ -153,6 +160,9 @@ _( n c-addr -- )_ add n to value at c-addr ## +LOOP +- Immediate. +- Compile-only. + Compilation: _( C: do-sys -- )_ Execution: _( u|n -- )_ add u|n to loop index and continue loop if within bounds @@ -183,10 +193,14 @@ _( n -- )_ output n ## ." +- Immediate. + _( "text"<"> -- )_ output parsed text ## .( +- Immediate. + _( "text" -- )_ parse text until a right paren or end of input, output text ## .D @@ -389,15 +403,24 @@ compiling state. The temporary definition is executed immediately after ; ## ; +- Immediate. +- Compile-only. + _( colon-sys -- )_ consume colon-sys and enter interpretation state, ending the current definition. If the definition was temporary, execute it. ## ;CODE +- Immediate. +- Compile-only. + _( -- )_ end compiler mode, begin machine code section of definition ## ;] +- Immediate. +- Compile-only. + _( C: quot-sys -- )_ _( R: -- xt )_ End a quotation. During executon, leave xt of the quotation on the stack. @@ -479,7 +502,10 @@ _( a-addr -- )_ output signed contents of cell at a-addr ## ?DO -Compilation: _( -- )_ ( R: -- do-sys ) +- Immediate. +- In interpretation state, starts temporary definition. + +Compilation: _( -- )_ _( R: -- do-sys )_ Execution: _( limit start -- )_ begin DO loop, skip if limit=start @@ -489,6 +515,8 @@ _( n -- n )_ if n = 0, else _( n1 -- n1 n2 )_ n2 = n1 ## ?LEAVE +- Compile-only. + _( f -- )_ exit loop if f is nonzero ## @ @@ -505,7 +533,11 @@ _( -- )_ Execute -1 THROW. ## ABORT" -Compilation/Interpretation: _( [text<">] -- )_ Execution: _( f -- )_ +- Immediate. + +Compilation/Interpretation: _( [text<">] -- )_ + +Execution: _( f -- )_ If f is true, display text and execute -2 THROW. ## ABS @@ -523,11 +555,17 @@ freeing the originals. ## AGAIN +- Immediate. +- Compile-only. + _( C: dest -- )_ _( R: -- )_ resolve dest, jump to BEGIN ## AHEAD -_( C: orig )_ _( E: -- )_ jump ahead as resolved by e.g. THEN +- Immediate. +- In interpretation state, starts temporary definition. + +_( C: orig ) ( E: -- )_ jump ahead as resolved by e.g. THEN ## ALIAS @@ -535,7 +573,7 @@ _( "name1"<> "name2"<> -- )_ create name1, name1 is a synonym for name2 ## ALIGN -_( u -- u )_ align u _(no-op in this implementation)_ +_( u -- u )_ align u (no-op in this implementation) ## ALIGNED @@ -559,11 +597,13 @@ _( n1 n2 -- n3 )_ n3 = n1 & n2 ## ASCII +- Immediate. + _( "word"<> -- char )_ perform either CHAR or [CHAR] per the current compile state ## AT-XY -_( u1 u2 -- )_ place cursor at col u1 row u2 _(uses ANSI escape sequence)_ +_( u1 u2 -- )_ place cursor at col u1 row u2 (uses ANSI escape sequence) ## BASE @@ -571,6 +611,9 @@ _( -- a-addr )_ System BASE variable. ## BEGIN +- Immediate. +- In interpretation state, starts temporary definition. + _( C: -- dest )_ _( E: -- )_ start a BEGIN loop ## BEHAVIOR @@ -663,6 +706,9 @@ _( -- )_ ## CASE +- Immediate. +- In interpretation state, starts temporary definition. + Compilation: _( R: -- case-sys )_ start a CASE...ENDCASE structure Execution: _( -- )_ @@ -721,10 +767,15 @@ _( addr1 u1 addr2 u2 -- n1 )_ compare two strings ## COMPILE +- Immediate. +- Compile-only. + _( -- )_ Compile code to compile the immediately following word. Better to use POSTPONE. ## COMPILE, +- Immediate. + _( xt -- )_ compile xt into the dictionary ## CONSTANT @@ -737,7 +788,9 @@ _( -- wid )_ Return first wordlist in search order. ## CONTROL -_( "name"<> )_ parse name, place low 5 bits of first char on stack, if compiling stat +- Immediate. + +( "name"<> ) parse name, place low 5 bits of first char on stack, if compiling stat compile it as a literal ## COUNT @@ -762,6 +815,8 @@ _( "name"<> -- )_ create a definition, when executed pushes the body address ## D# +- Immediate. + _( "#"<> -- n | -- )_ parse following number as decimal, compile as literal if compiling ## D+ @@ -818,12 +873,18 @@ _( d -- d' )_ negate d ## DO -Compilation: _( -- )_ ( R: -- do-sys ) +- Immediate. +- In interpretation state, starts temporary definition. + +Compilation: _( -- )_ _( R: -- do-sys )_ Execution: _( limit start -- )_ begin DO loop ## DOES> +- Immediate. +- Compile-only. + _( -- )_ alter execution semantics of most recently-created definition to perform the following execution semantics. @@ -841,6 +902,9 @@ _( n1 -- n1 n2 )_ n2 = n1 ## ELSE +- Immediate. +- Compile-only. + _( C: if-sys -- else-sys )_ _( E: -- )_ ELSE clause of IF ... ELSE ... THEN ## EMIT @@ -849,17 +913,26 @@ _( char -- )_ Output char. ## END-CODE +- Immediate. +- Compile-only. + _( code-sys -- )_ synonym for C; ## ENDCASE +- Immediate. +- Compile-only. + Compilation: _( case-sys -- )_ conclude a CASE...ENDCASE structure Execution: _( | n -- )_ continue execution, dropping n if no OF matched ## ENDOF -Compilation; ( case-sys of-sys -- case-sys ) conclude an OF...ENDOF structure +- Immediate. +- Compile-only. + +Compilation; _( case-sys of-sys -- case-sys )_ conclude an OF...ENDOF structure Execution: Continue execution at ENDCASE of case-sys @@ -889,6 +962,8 @@ _( xt -- )_ execute xt, regardless of its flags ## EXIT +- Compile-only. + ## EXIT? _( -- f )_ If #LINE >= 20, prompt user to continue and return false if they want to. @@ -957,6 +1032,8 @@ _( fcode# -- xt f )_ get fcode#'s xt and immediacy ## H# +- Immediate. + _( "#"<> -- n | -- )_ parse following number as hex, compile as literal if compiling ## HERE @@ -973,11 +1050,16 @@ _( c -- )_ place c in pictured numeric output ## I +- Compile-only. + _( -- n )_ copy inner loop index to stack ## IF -_( C: if-sys )_ _( E: n -- )_ begin IF ... ELSE ... ENDIF +- Immediate. +- In interpretation state, starts temporary definition. + +_( C: if-sys ) ( E: n -- )_ begin IF ... ELSE ... ENDIF ## IMMEDIATE @@ -989,6 +1071,8 @@ _( x -- x' )_ invert the bits in x ## J +- Compile-only. + _( -- n )_ copy second-inner loop index to stack ## KEY @@ -1043,6 +1127,8 @@ _( char -- char' )_ lower case convert char ## LEAVE +- Compile-only. + _( -- )_ exit loop ## LEFT-PARSE-STRING @@ -1056,10 +1142,15 @@ _( -- )_ ## LITERAL +- Immediate. + _( n -- )_ compile numeric literal n into dictionary, leave n on stack at execution ## LOOP +- Immediate. +- Compile-only. + Compilation: _( C: do-sys -- )_ Execution: _( -- )_ add 1 to loop index and continue loop if within bounds @@ -1146,6 +1237,8 @@ _( R: x1 ... xn -- )_ _( n -- x1 ... xn n )_ ## O# +- Immediate. + _( "#"<> -- n | --)_ parse following number as octal, compile as literal if compiling ## OCTAL @@ -1154,6 +1247,9 @@ _( -- )_ store 8 to BASE ## OF +- Immediate. +- Compile-only. + Compilation: _( case-sys -- case-sys of-sys )_ begin an OF...ENDOF structure Execution: _( x1 x2 -- | x1 )_ execute OF clause if x1 = x2, leave x1 on stack if not @@ -1192,7 +1288,7 @@ _( -- a-addr )_ return address of PAD ## PAGE -_( -- )_ clear screen & home cursor _(uses ANSI escape sequence)_ +_( -- )_ clear screen & home cursor (uses ANSI escape sequence) ## PARSE @@ -1216,6 +1312,8 @@ _( x1 ... xn u -- x1 ... xn x(n-u)_ ) ## POSTPONE +- Immediate. + _( "name"<> -- )_ ## PREVIOUS @@ -1240,10 +1338,14 @@ _( R: n -- n )_ _( -- n )_ ## RB! +- Immediate. + _( byte addr -- )_ perform FCode-equivalent RB!: store byte ## RB@ +- Immediate. + _( addr -- byte )_ perform FCode-equivalent RB@: fetch byte ## RDROP @@ -1252,10 +1354,16 @@ _( R: n -- )_ ## RECURSE +- Immediate. +- Compile-only. + _( -- )_ compile the execution semantics of the most recently-created definition ## RECURSIVE +- Immediate. +- Compile-only. + _( -- )_ make the current definition findable during compilation ## REFILL @@ -1264,6 +1372,9 @@ _( -- f )_ refill input buffer, f = true if that worked, false if not ## REPEAT +- Immediate. +- Compile-only. + _( C: orig dest -- )_ _(R: -- )_ resolve orig and dest, repeat BEGIN loop ## RESET-ALL @@ -1274,10 +1385,14 @@ _( -- )_ Reset the system. ## RL! +- Immediate. + _( cell addr -- )_ perform FCode-equivalent RL!, store cell ## RL@ +- Immediate. + _( addr -- cell )_ perform FCode-equivalent RL@: fetch cell ## ROLL @@ -1294,14 +1409,20 @@ _( n1 n2 -- n3 )_ n3 = n1 >> n2 ## RW! +- Immediate. + _( word addr -- )_ perform FCode-equivalent RW!: store word ## RW@ +- Immediate. + _( addr -- word )_ perform FCode-equivalent RW@: fetch word ## S" +- Immediate. + _( "text"<"> -- c-addr u )_ ## S. @@ -1356,6 +1477,9 @@ _( n -- s )_ s = -1 if n is negative, 0 if 0, 1 if positive ## SLITERAL +- Immediate. +- Compile-only. + C: _( c-addr1 u -- )_ R: _( -- c-addr 2 u )_ compile string literal into current def ## SM/REM @@ -1368,7 +1492,7 @@ _( -- c-addr u )_ return address and length of input source buffer ## SOURCE-ID -_( -- n )_ return current input source id _(0 = console, -1 = string, >0 = file)_ +_( -- n )_ return current input source id (0 = console, -1 = string, >0 = file) ## SPACE @@ -1398,6 +1522,9 @@ _( n1 n2 -- n2 n1 )_ ## THEN +- Immediate. +- Compile-only. + _( C: if-sys|else-sys -- )_ _( E: -- )_ ## THROW @@ -1406,7 +1533,10 @@ _( n -- )_ Throw exception n if n <> 0. ## TO +- Immediate. + _( n "name"<> -- )_ change the first cell of the body of xt to n. Can be used on +most words created with CREATE, DEFER, VALUE, etc. even VARIABLE ## TRUE @@ -1442,6 +1572,8 @@ _( u -- )_ output u ## U.0 +_( u1 -- )_ output u1 with no trailing space + ## U.R _( u1 u2 -- )_ output u1 in a field of u2 chars @@ -1500,10 +1632,15 @@ _( c-addr -- n )_ fetch word from c-addr ## UNLOOP +- Compile-only. + _( -- )_ _( R: loop-sys -- )_ remove loop parameters from stack ## UNTIL +- Immediate. +- Compile-only. + _( C: dest -- )_ _( R: x -- )_ UNTIL clause of BEGIN...UNTIL loop ## UNUSED @@ -1563,6 +1700,9 @@ _( u -- u1 .. u2 )_ u1 .. u2 = bytes of word u. ## WHILE +- Immediate. +- Compile-only. + _( C: dest -- orig dest )_ _( E: x -- )_ WHILE clause of BEGIN...WHILE...REPEAT loop ## WITHIN @@ -1604,29 +1744,46 @@ _( n1 n2 -- n3 )_ n3 = n1 ^ n2 ## [ +- Immediate. +- Compile-only. + _( -- )_ Enter interpretation state. ## ['] +- Immediate. + _( [old-name<>] -- xt )_ immediately parse old-name in input stream, return xt of word ## [: +- Immediate. +- Compile-only. + _( C: -- quot-sys )_ _( R: -- )_ Start a quotation. ## [CHAR] +- Immediate. +- Compile-only. + _( "word"<> -- char )_ immediately perform CHAR and compile literal ## [COMPILE] +- Immediate. + _( "name"<> -- )_ Compile name now. Better to use POSTPONE. ## \ -_( "..." -- )_ discard the rest of the input buffer _(line during EVALUATE)_ +- Immediate. + +_( "..." -- )_ discard the rest of the input buffer (line during EVALUATE) ## ] +- Immediate. + _( -- )_ Enter compilation state. diff --git a/utils/index.rb b/utils/index.rb index 8ee7d40..47e69b4 100755 --- a/utils/index.rb +++ b/utils/index.rb @@ -41,7 +41,7 @@ input.lines.each do |line| output[name] ||= {} output[name].merge!({"help" => help}) unless help.empty? if flags - fl = flags.split('|') + fl = flags.split(/[|\+]/) output[name].merge!({"flags" => fl}) unless fl.empty? end output[name].merge!({"tests" => coverage[name.downcase]}) if coverage[name.downcase] diff --git a/utils/index2md.rb b/utils/index2md.rb index 10b7c21..6ecdfab 100755 --- a/utils/index2md.rb +++ b/utils/index2md.rb @@ -37,16 +37,23 @@ index.keys.sort.each do |word| cword.gsub!(/^([<>])/) { "\\#{$1}" } puts "## #{cword}" puts + if word_info['flags'] + puts "- Immediate." if word_info['flags'].include?('F_IMMED') + if word_info['flags'].include?('F_CONLY') + if word_info['flags'].include?('F_TEMPD') + puts "- In interpretation state, starts temporary definition." + else + puts "- Compile-only." + end + end + puts + end if word_info['help'] word_info['help'].each_with_index do |line, i| - if line.start_with?('(') - line.gsub!(/[(](.+?)[)]/, '_(\1)_') # emphasize stack effects - else - if line =~ /^\s*\S+:/ - # space for separating interpretation/compilation/etc. - puts if i > 0 - end - line.gsub!(/:\s+[(](.+?)[)]/, ': _(\1)_') # emphasize stack effects + line.gsub!(/[(](.+?--.+?)[)]/, '_(\1)_') # emphasize stack effects + if line =~ /^\s*\S+:/ + # space for separating interpretation/compilation/etc. + puts if i > 0 end puts line end