6502
/
of816
mirror of https://github.com/mgcaret/of816.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

more doc stuff; generated markdown contains flags info

This commit is contained in:
mgcaret 2020-01-21 23:39:06 -08:00
parent 79a32db4e2
commit d2e032a559
4 changed files with 197 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
asm/forth-dictionary.s
View File

@ -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

191
docs/forth_dictionary.md
View File

@ -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"<rparen> -- 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"<rparen> -- )_ 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"<rparen> -- )_ 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 @@ _( -- <cr> )_
## 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 @@ _( -- <lf> )_
## 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.
## \
_( "..."<end> -- )_ discard the rest of the input buffer _(line during EVALUATE)_
- Immediate.
_( "..."<end> -- )_ discard the rest of the input buffer (line during EVALUATE)
## ]
- Immediate.
_( -- )_ Enter compilation state.

2
utils/index.rb
View File

@ -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]

23
utils/index2md.rb
View File

@ -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