dox/urforth.txt

   1 proper documentation will follow... maybe.
   2 but please, read this document if you want to use UrForth.
   3 UrForth is not a standard Forth system (it is a mixture of ANS, FIG,
   4 and my own creations), and this document contains valuable bits of
   5 knowledge about some non-standard UrForth features.
   6
   7 one of the non-standard UrForth features is locals support. it is
   8 done like this:
   9   : myword  ( a b -- c )
  10     args: a b
  11     locals: loc1 loc2
  12
  13     :a TO :loc1
  14     :b TO :loc2
  15     :loc1 :loc2 +
  16   ;
  17 here, "args:" will declare local variables, and automatically fill them
  18 with arguments from the data stack. "locals:" declare "free" locals.
  19 there can be more than one "locals:" section, but all such sections should
  20 come before anything else. to use local, you must prepend its name with a
  21 colon. the usual "TO" word is used to set local values.
  22
  23 "DOES>" works only on CREATEd words.
  24
  25 some global variables are state-local. also, each state has its own TIB,
  26 independent of other states.
  27
  28 state-local vars are:
  29 BASE
  30 ( -- base-addr )
  31 current number base.
  32
  33 TIB
  34 ( -- addr )
  35 current TIB.
  36
  37 >IN
  38 ( -- ofs )
  39 offset in current TIB.
  40
  41 (STD-TIB-ADDR)
  42 ( -- )
  43 default TIB address. WARNING! if this user var contains a handle, that
  44 handle will be freed on destroying the task. if you want to replace the
  45 default TIB, make sure that you will free the old handle (if it is a handle).
  46
  47 (USER-VAR-USED)
  48 ( -- uvar-used-addr )
  49 address of the variable contains first free user area address.
  50
  51 (USER-VAR-ADDR)
  52 ( -- uvar-begin-addr )
  53 start address of the user area.
  54
  55 (USER-VAR-SIZE)
  56 ( -- uvar-size )
  57 maximum user area size in bytes.
  58
  59
  60
  61 DEBUG:DUMP-STACK
  62 ( -- )
  63 dump data stack
  64
  65 DEBUG:BACKTRACE
  66 ( -- )
  67 show current backtrace (slow!)
  68
  69 DEBUG:DECOMPILE name
  70 ( -- )
  71 decompile given forth word.
  72
  73 SP0!
  74 ( -- )
  75 clear data stack.
  76
  77 RP0!
  78 ( -- )
  79 clear return stack.
  80
  81 PAD
  82 ( -- pad )
  83 return PAD address. this is area that can be used for storing
  84 temporary values. you can assume to have at least 4096 bytes there.
  85 WARNING! some words may use PAD for their own needs. this is mostly
  86          words which need to create some temporary strings.
  87
  88
  89 note that address for memory operations may be a handle too. with handles,
  90 low bits are used as offset, so you can directly address some bytes in handle
  91 data area. currently, low 12 bits are reserved for offset, so you can address
  92 4096 bytes inside a handle. but don't hardcode it, use "FORTH:(MAX-HANDLE-OFS)"
  93 constant to get the maximum allowed offset (because it may change in the future).
  94
  95 also, UrForth is 32-bit system, and stores all numbers as little-endian. this
  96 will not change, so you can write your code without checking cell size, or
  97 byte order.
  98
  99
 100 C@
 101 ( addr -- value8 )
 102 load 8-bit value.
 103
 104 W@
 105 ( addr -- value16 )
 106 load 16-bit value.
 107
 108 @
 109 ( addr -- value32 )
 110 load 32-bit value.
 111
 112 C!
 113 ( val8 addr -- )
 114 store 8-bit value.
 115
 116 W!
 117 ( val16 addr -- )
 118 store 16-bit value.
 119
 120 !
 121 ( val32 addr -- )
 122 store 32-bit value.
 123
 124 C,
 125 ( val8 -- )
 126 compile 8-bit value.
 127
 128 W,
 129 ( val16 -- )
 130 compile 16-bit value.
 131
 132 ,
 133 ( val -- )
 134 compile 32-bit value.
 135
 136
 137 (LIT)
 138 ( -- n )
 139 read 4 bytes immediately following this word, and push them
 140 to the data stack. adjust IP to skip those bytes.
 141
 142 (LITCFA)
 143 ( -- n )
 144 read 4 bytes immediately following this word, and push them
 145 to the data stack. adjust IP to skip those bytes. this is
 146 the same as "(LIT)", but used to store CFAs of words. using
 147 different words for different data types helps the debugger
 148 and the decompiler.
 149
 150 (LITVOCID)
 151 ( -- n )
 152 the same as "(LIT)", but for vocids.
 153
 154 (STRLIT8)
 155 ( -- addr count )
 156 inline byte-counted string literal. note that the string
 157 always have a trailing zero byte (which is not counted),
 158 and always padded so it ends on a 4-byte boundary.
 159
 160 (BRANCH) ( -- )
 161 read next 4 bytes, and set IP to that address.
 162
 163 (TBRANCH)
 164 ( flag -- )
 165 skip next 4 bytes if `flag` is 0, otherwise perform "(BRANCH)".
 166
 167 (0BRANCH)
 168 ( flag -- )
 169 skip next 4 bytes if `flag` is not 0, otherwise perform "(BRANCH)".
 170
 171
 172 EXECUTE
 173 ( cfa )
 174 pop word CFA address, and execute it.
 175
 176 EXECUTE-TAIL
 177 ( cfa )
 178 pop word CFA address, and execute it. returning from the executed
 179 word will return to the upper word. i.e. this performs a tail call.
 180
 181
 182 (EXIT)
 183 internal compiler word, placed at the end of colon definition.
 184 pops a number from return stack, and sets IP to that number.
 185
 186 (L-ENTER)
 187 this word is used to implement local variables and arguments.
 188 it doesn't matter how it works, you should not used it anyway.
 189 read the source code, if you're curious.
 190
 191 (L-LEAVE)
 192 this word is used to implement local variables and arguments.
 193 it doesn't matter how it works, you should not used it anyway.
 194 read the source code, if you're curious.
 195
 196 (LOCAL@)
 197 ( idx -- value )
 198 read local variable with the given index. indices are 1-based.
 199
 200 (LOCAL!)
 201 ( value idx -- )
 202 write local variable with the given index. indices are 1-based.
 203
 204 DUP
 205 ( n -- n n )
 206 duplicates a number on the data stack.
 207
 208 ?DUP
 209 ( n -- n n ) | ( 0 -- 0 )
 210 duplicates a number on the data stack, but only if that number is not 0.
 211
 212 2DUP
 213 ( n0 n1 -- n0 n1 n0 n1 )
 214
 215 DROP
 216 ( n -- )
 217
 218 2DROP
 219 ( n0 n1 -- )
 220
 221 SWAP
 222 ( n0 n1 -- n1 n0 )
 223
 224 2SWAP
 225 ( n0 n1 -- n1 n0 )
 226
 227 OVER
 228 ( n0 n1 -- n0 n1 n0 )
 229
 230 2OVER
 231 ( n0 n1 -- n0 n1 n0 )
 232
 233 ROT
 234 ( n0 n1 n2 -- n1 n2 n0 )
 235
 236 NROT
 237 ( n0 n1 n2 -- n2 n0 n1 )
 238
 239 NIP
 240 ( a b -- b )
 241
 242 TUCK
 243 ( a b -- b a b )
 244
 245 RDUP
 246 ( n -- n n )
 247 the same as "DUP", but for the return stack.
 248
 249 RDROP
 250 ( n -- )
 251 the same as "DROP", but for the return stack.
 252
 253 RSWAP
 254 ( n0 n1 -- n1 n0 )
 255 the same as "SWAP", but for the return stack.
 256
 257 ROVER
 258 ( n0 n1 -- n0 n1 n0 )
 259 the same as "OVER", but for the return stack.
 260
 261 RROT
 262 ( n0 n1 n2 -- n1 n2 n0 )
 263 the same as "ROT", but for the return stack.
 264
 265 RNROT
 266 ( n0 n1 n2 -- n2 n0 n1 )
 267 the same as "NROT", but for the return stack.
 268
 269 >R
 270 ( n -- | n )
 271 move number from the data stack to the return stack.
 272
 273 R>
 274 ( | n -- n )
 275 move number from the return stack to the data stack.
 276
 277 R@
 278 ( | n -- n | n )
 279 copy number from the return stack to the data stack.
 280
 281 PICK
 282 ( idx -- n )
 283 copy n-th element at the data stack. "0 PICK" is the same as "DUP".
 284
 285 RPICK
 286 ( idx -- n )
 287 the same as "PICK", but for the return stack.
 288
 289 ROLL
 290 ( idx -- n )
 291 move n-th element at the data stack to the top. "1 ROLL" is the same as "SWAP".
 292
 293 RROLL
 294 ( idx -- n )
 295 the same as "ROLL", but for the return stack.
 296
 297 REFILL
 298 ( -- eofflag )
 299 read next input line. can cross include boundaries. pushes 0 if
 300 there are no more input lines. TIB contents is undefined in this case.
 301
 302 REFILL-NOCROSS
 303 ( -- eofflag )
 304 read next input line. cannot cross include boundaries. pushes 0 if
 305 there are no more input lines. TIB contents is undefined in this case.
 306
 307 (TIB-IN)
 308 ( -- addr )
 309 get address of the current TIB position.
 310 WARNING! do not try to emulate "TIB-GETCH" and such with this word!
 311          TIB usually ends with 0 byte, and if you will advance beyond
 312          that 0, Bad Things will happen.
 313
 314 TIB-PEEKCH
 315 ( -- char )
 316 push current TIB char, do not advance >IN.
 317
 318 TIB-PEEKCH-OFS
 319 ( ofs -- char )
 320 peek TIB char with the given offset. "0 TIB-PEEKCH-OFS" is the same as "TIB-PEEKCH".
 321
 322 TIB-GETCH
 323 ( -- char )
 324 push current TIB char, advance >IN. it is safe to call this even
 325 when you reached the end of TIB. in this case, returned char code
 326 will be 0. i.e. "0" means "end of TIB".
 327
 328 TIB-SKIPCH
 329 ( -- )
 330 skip current TIB char. it is safe to call this even when you reached
 331 the end of TIB.
 332
 333
 334 (PARSE)
 335 ( delim skip-leading-delim? -- addr count TRUE / FALSE )
 336 does base TIB parsing; never copies anything.
 337 as our reader is line-based, returns FALSE on EOL.
 338 EOL is detected after skipping leading delimiters.
 339 passing -1 as delimiter skips the whole line, and always returns FALSE.
 340 finishing delimiter is always skipped.
 341
 342 PARSE-SKIP-BLANKS
 343 ( -- )
 344 skip all chars with codes <=32.
 345
 346 (PARSE-SKIP-COMMENTS)
 347 ( allow-multiline? -- )
 348 skip all blanks and comments. if multiline skip is not allowed, reaching
 349 end of TIB while still waiting for the comment terminator is error.
 350 single-line comments are ok, though.
 351
 352 PARSE-SKIP-LINE
 353 ( -- )
 354 advance >IN to the end of TIB.
 355
 356 PARSE-NAME
 357 ( -- addr count )
 358 parse with leading blanks skipping. doesn't copy anything.
 359 return empty string on EOL.
 360
 361 PARSE
 362 ( delim -- addr count TRUE / FALSE )
 363 parse without skipping delimiters; never copies anything.
 364 as our reader is line-based, returns FALSE on EOL.
 365 passing 0 as delimiter skips the whole line, and always returns FALSE.
 366 finishing delimiter is always skipped.
 367
 368 EMIT
 369 ( n -- )
 370 print char.
 371
 372 XEMIT
 373 ( n -- )
 374 "safe" char printer. all non-printable chars (including newline and such)
 375 will be printed as "?".
 376
 377 LASTCR?
 378 ( -- bool )
 379 was last printed char a newline?
 380
 381 LASTCR!
 382 ( bool -- )
 383 force-set the flag for "LASTCR?" word.
 384
 385 CR
 386 ( -- )
 387 print newline.
 388
 389 SPACE
 390 ( -- )
 391 print space.
 392
 393 SPACES
 394 ( n -- )
 395 print `n` spaces. if `n` is negative, prints nothing.
 396
 397 ENDCR
 398 ( -- )
 399 prints newline if the last printed char was not a newline.
 400
 401 TYPE
 402 ( addr count -- )
 403 print the string. negative count is ok, in this case the word prints nothing.
 404
 405 XTYPE
 406 ( addr count -- )
 407 the same as "TYPE", but uses "XEMIT".
 408
 409 FLUSH-EMIT
 410 ( -- )
 411 output can be buffered. it usually flushed when newline is printed, but
 412 you can flush it manually using this word.
 413
 414 +
 415 ( a b -- a+b )
 416
 417 -
 418 ( a b -- a-b )
 419
 420 *
 421 ( a b -- a*b )
 422
 423 U*
 424 ( a b -- a*b )
 425
 426 /
 427 ( a b -- a/b )
 428
 429 U/
 430 ( a b -- a/b )
 431
 432 MOD
 433 ( a b -- a%b )
 434
 435 UMOD
 436 ( a b -- a%b )
 437
 438 /MOD
 439 ( a b -- a/b, a%b )
 440 note that the results are swaped, contrary to ANS idiocity.
 441 i don't fuckin' know why ANS morons decided to make the stack
 442 effect that contradicts the word name. "/MOD" clearly indicates
 443 that quotient comes first.
 444
 445 U/MOD
 446 ( a b -- a/b, a%b )
 447 note that the results are swaped, contrary to ANS idiocity.
 448 i don't fuckin' know why ANS morons decided to make the stack
 449 effect that contradicts the word name. "/MOD" clearly indicates
 450 that quotient comes first.
 451
 452 */
 453 ( a b c -- a*b/c )
 454 this uses 64-bit intermediate value.
 455
 456 U*/
 457 ( a b c -- a*b/c )
 458 this uses 64-bit intermediate value.
 459
 460 */MOD
 461 ( a b c -- a*b/c a*b%c )
 462 this uses 64-bit intermediate value.
 463 note that the results are swaped, contrary to ANS idiocity.
 464 i don't fuckin' know why ANS morons decided to make the stack
 465 effect that contradicts the word name. "/MOD" clearly indicates
 466 that quotient comes first.
 467
 468 U*/
 469 ( a b c -- a*b/c )
 470 this uses 64-bit intermediate value.
 471
 472 M*
 473 ( a b -- lo(a*b) hi(a*b) )
 474 this leaves 64-bit result.
 475
 476 UM*
 477 ( a b -- lo(a*b) hi(a*b) )
 478 this leaves 64-bit result.
 479
 480 M/MOD
 481 ( alo ahi b -- a/b a%b )
 482 note that the results are swaped, contrary to ANS idiocity.
 483 i don't fuckin' know why ANS morons decided to make the stack
 484 effect that contradicts the word name. "/MOD" clearly indicates
 485 that quotient comes first.
 486
 487 UM/MOD
 488 ( alo ahi b -- a/b a%b )
 489 note that the results are swaped, contrary to ANS idiocity.
 490 i don't fuckin' know why ANS morons decided to make the stack
 491 effect that contradicts the word name. "/MOD" clearly indicates
 492 that quotient comes first.
 493
 494 <
 495 ( a b -- a<b )
 496
 497 U<
 498 ( a b -- a<b )
 499
 500 >
 501 ( a b -- a>b )
 502
 503 U>
 504 ( a b -- a>b )
 505
 506 <=
 507 ( a b -- a<=b )
 508
 509 U<=
 510 ( a b -- a<=b )
 511
 512 >=
 513 ( a b -- a>=b )
 514
 515 U>=
 516 ( a b -- a>=b )
 517
 518 =
 519 ( a b -- a=b )
 520
 521 <>
 522 ( a b -- a<>b )
 523
 524 NOT
 525 ( a -- !a )
 526
 527 LAND
 528 ( a b -- a&&b )
 529 logical "and".
 530
 531 LOR
 532 ( a b -- a||b )
 533 logical "or".
 534
 535 AND
 536 ( a b -- a&b )
 537 bitwise "and".
 538
 539 OR
 540 ( a b -- a|b )
 541 bitwise "or".
 542
 543 XOR
 544 ( a b -- a^b )
 545 bitwise "xor".
 546
 547 BITNOT
 548 ( a -- ~a )
 549
 550 2U*
 551 ( u -- u*2 )
 552
 553 2U/
 554 ( u -- u*2 )
 555
 556 4U*
 557 ( u -- u*4 )
 558
 559 4U/
 560 ( u -- u*4 )
 561
 562 ASH
 563 ( n count -- )
 564 arithmetic shift; positive `n` shifts to the left.
 565
 566 LSH
 567 ( n count -- )
 568 logical shift; positive `n` shifts to the left.
 569
 570 COMPILER:(UNESCAPE)
 571 ( addr count -- addr new-count )
 572 process string escapes. modifies string in-place. the resulting string is
 573 never bigger than the source one. negative counts are allowed.
 574
 575 (BASED-NUMBER)
 576 ( addr count allowsign? base -- num TRUE / FALSE )
 577 tries to convert the given string to the number, using the given
 578 default base. if "allowsign?" is non-zero, properly process leading
 579 number sign. this words understands numbers in non-default bases too
 580 (like "0x29a", for example).
 581
 582
 583 [
 584 switch to interpretation mode.
 585
 586 ]
 587 switch to compilation mode.
 588
 589 (CREATE-WORD-HEADER)
 590 ( addr count word-flags -- )
 591 create word header in the dictionary, link word to the current vocabulary.
 592 doesn't create CFA.
 593
 594 (CREATE-NAMELESS-WORD-HEADER)
 595 ( word-flags -- )
 596 create nameless word header in the dictionary, link word to the current vocabulary.
 597 doesn't create CFA.
 598
 599 FIND-WORD
 600 ( addr count -- cfa TRUE / FALSE)
 601 general word finder. checks wordlist stack, performs colon resolution.
 602
 603 FIND-WORD-IN-VOC
 604 ( addr count vocid allowhidden -- cfa TRUE / FALSE)
 605 find word in the given wordlist. does no name resolution, and
 606 doesn't look in parent wordlists.
 607
 608 FIND-WORD-IN-VOC-AND-PARENTS
 609 ( addr count vocid allowhidden -- cfa TRUE / FALSE)
 610 find word in the given wordlist. does no name resolution, but searches
 611 parent wordlists if "vocid" is nested.
 612
 613 COMPILER:?EXEC
 614 check if we are in interpretation mode, and throws an error if we aren't.
 615
 616 COMPILER:?COMP
 617 check if we are in compilation mode, and throws an error if we aren't.
 618
 619 "
 620 string literal.
 621
 622 (VSP@)
 623 ( -- vsp )
 624 this word is used internally to work with wordlist stack.
 625
 626 (VSP!)
 627 ( vsp -- )
 628 this word is used internally to work with wordlist stack.
 629
 630 (VSP-AT@)
 631 ( idx -- value )
 632 this word is used internally to work with wordlist stack.
 633
 634 (VSP-AT!)
 635 ( value idx -- )
 636 this word is used internally to work with wordlist stack.
 637
 638 CFA->PFA
 639 ( cfa -- pfa )
 640
 641 PFA->CFA
 642 ( pfa -- cfa )
 643
 644 CFA->NFA
 645 ( cfa -- nfa )
 646
 647 NFA->CFA
 648 ( nfa -- cfa )
 649
 650 CFA->LFA
 651 ( cfa -- lfa )
 652
 653 LFA->CFA
 654 ( lfa -- cfa )
 655
 656 LFA->PFA
 657 ( lfa -- pfa )
 658
 659 LFA->BFA
 660 ( lfa -- bfa )
 661
 662 LFA->SFA
 663 ( lfa -- sfa )
 664
 665 LFA->NFA
 666 ( lfa -- nfa )
 667
 668 NFA->LFA
 669 ( nfa -- lfa )
 670
 671 CFA->WEND
 672 ( cfa -- wend-addr )
 673 convert CFA to word end address.
 674
 675 DEBUG:IP->NFA
 676 ( ip -- nfa / 0 )
 677 convert instruction pointer to NFA. return 0 if cannot.
 678
 679 DEBUG:IP->FILE/LINE
 680 ( ip -- addr count line TRUE / FALSE )
 681 name is at PAD; it is safe to use PAD, because each task has its own temp image.
 682
 683 STRING:=
 684 ( a0 c0 a1 c1 -- bool )
 685
 686 STRING:=CI
 687 ( a0 c0 a1 c1 -- bool )
 688 case-insensitive compare (only for ASCII).
 689
 690 STRING:HASH
 691 ( addr count -- hash )
 692
 693 STRING:HASH-CI
 694 ( addr count -- hash )
 695 case-insensitive hash (only for ASCII).
 696
 697 ($DEFINE)
 698 ( addr count -- )
 699 add new conditional define. case-insensitive (for ASCII).
 700
 701 ($UNDEF)
 702 ( addr count -- )
 703 remove conditional define. case-insensitive (for ASCII).
 704
 705 ($DEFINED?)
 706 ( addr count -- bool )
 707 check if we have a conditional define. case-insensitive (for ASCII).
 708
 709 ERROR
 710 ( addr count -- )
 711 print error message and abort.
 712
 713 ?ERROR
 714 ( errflag addr count -- )
 715 if "errflag" is not zero, print error message and abort.
 716
 717 ?NOT-ERROR
 718 ( errflag addr count -- )
 719 if "errflag" is zero, print error message and abort.
 720
 721 (INCLUDE-DEPTH)
 722 ( -- depth )
 723 return number of items in the include stack.
 724
 725 (INCLUDE-FILE-ID)
 726 ( isp -- id )
 727 isp 0 is current, then 1, etc.
 728 each include file has unique non-zero id.
 729
 730 (INCLUDE-FILE-LINE)
 731 ( isp -- line )
 732
 733 (INCLUDE-FILE-NAME)
 734 ( isp -- addr count )
 735 current file name; at PAD.
 736
 737 (INCLUDE)
 738 ( addr count soft? system? -- )
 739 push current file to the include stack, open a new one. used internally.
 740
 741 $INCLUDE "str"
 742 immediate word.
 743
 744 $INCLUDE-ONCE "str"
 745 includes file only once; unreliable on shitdoze, i believe.
 746 immediate word.
 747
 748 HANDLE:NEW
 749 ( typeid -- hx )
 750 allocate a new handle with the given typeid. typeid is just a number
 751 without any special meaning. any number except "-1" is allowed.
 752 new handle size is 0.
 753
 754 HANDLE:FREE
 755 ( hx -- )
 756 deallocate a handle, free all allocated handle memory.
 757
 758 HANDLE:TYPEID@
 759 ( hx -- typeid )
 760
 761 HANDLE:TYPEID!
 762 ( typeid hx -- )
 763
 764 HANDLE:SIZE@
 765 ( hx -- size )
 766
 767 HANDLE:SIZE!
 768 ( size hx -- )
 769 resize memory allocated for handle data.
 770
 771 HANDLE:USED@
 772 ( hx -- used )
 773 "used" is just a number, which means nothing for most code.
 774 it is used to implement dynamic arrays.
 775
 776 HANDLE:USED!
 777 ( size hx -- )
 778
 779 HANDLE:C@
 780 ( idx hx -- value )
 781
 782 HANDLE:W@
 783 ( idx hx -- value )
 784
 785 HANDLE:@
 786 ( idx hx -- value )
 787
 788 HANDLE:C!
 789 ( value idx hx -- value )
 790
 791 HANDLE:W!
 792 ( value idx hx -- )
 793
 794 HANDLE:!
 795 ( value idx hx -- )
 796
 797 HANDLE:LOAD-FILE
 798 ( addr count -- stx )
 799 load file with the given name into newly allocated handle.
 800 aborts if there is no such file.
 801
 802 A>
 803 ( -- rega )
 804 get address register contents.
 805
 806 >A
 807 ( rega -- )
 808 set address register contents.
 809
 810 A-SWAP
 811 ( rega -- olda )
 812 swap TOS and the address register.
 813
 814 +1>A
 815 ( -- )
 816 increment the address register.
 817
 818 A>R
 819 ( -- | rega )
 820 copy the address register to the return stack.
 821
 822 R>A
 823 ( | rega -- )
 824 restore the address register from the return stack.
 825
 826 C@A
 827 ( -- byte )
 828
 829 W@A
 830 ( -- word )
 831
 832 @A
 833 ( -- value )
 834
 835 C!A
 836 ( byte -- )
 837
 838 W!A
 839 ( word -- )
 840
 841 !A
 842 ( value -- )
 843
 844 C@A+
 845 ( idx -- byte )
 846 safe way to access both dictionary memory, and handle memory.
 847 "idx" is used as offset from address register contents.
 848
 849 W@A+
 850 ( idx -- word )
 851 safe way to access both dictionary memory, and handle memory.
 852 "idx" is used as offset from address register contents.
 853
 854 @A+
 855 ( idx -- value )
 856 safe way to access both dictionary memory, and handle memory.
 857 "idx" is used as offset from address register contents.
 858
 859 C!A+
 860 ( byte idx -- )
 861 safe way to access both dictionary memory, and handle memory.
 862 "idx" is used as offset from address register contents.
 863
 864 W!A+
 865 ( word idx -- )
 866 safe way to access both dictionary memory, and handle memory.
 867 "idx" is used as offset from address register contents.
 868
 869 @A+
 870 ( value idx -- )
 871 safe way to access both dictionary memory, and handle memory.
 872 "idx" is used as offset from address register contents.
 873
 874 DEBUG:(DECOMPILE-CFA)
 875 ( cfa -- )
 876
 877 GET-MSECS
 878 ( -- u32 )
 879
 880 DEFER (UFO-INTERPRET-FINISHED)
 881 ( -- )
 882 this is called by INTERPRET when it is out of input stream. internally,
 883 it simply sets a flag to tell the VM that it should stop.
 884
 885
 886 HERE
 887 ( -- dp )
 888 push current dictionary pointer to the data stack.
 889 NOTE: there are actually two DPs -- normal, and temporary. "(DP-TEMP)" is
 890 the temp one, and if it is 0, "(DP)" is used. UrForth has 1MB temp area
 891 (that's where PAD is too), it had different addresses, and vocabularies
 892 created in that area are not linked to the main voclink list. this is used,
 893 for example, in locals engine, to store names of locals. so if you're using
 894 locals in your word, do not use temp area while compiling that word.
 895
 896 LATEST-LFA
 897 ( -- lfa )
 898 push LFA of the latest defined word in the current vocabulary. note that
 899 "smudge" bit doesn't matter here, it is always the last word you created
 900 header for. this includes "nonamed" words (which have empty string as a name).
 901
 902 NOOP
 903 ( -- )
 904 does nothing. at all.
 905
 906 COMPILER:(TRACE-COLON) DEFER
 907 ( -- )
 908 this defered word is called in colon, after creating word header and CFA.
 909 you can compile your own debug code into the new word.
 910
 911 COMPILER:(TRACE-SEMI)
 912 ( -- )
 913 this is called by semicolon, right before compiling "(EXIT)" and such.
 914 you can compile your own debug code into the new word.
 915
 916 COMPILER:(TRACE-DOES)
 917 ( -- )
 918 this is called by "DOES>".
 919 you can compile your own debug code into the new word.
 920
 921 COMPILER:(CTLID-COLON)
 922 ( -- ctlid-colon )
 923 semicolon expects this on the data stack.
 924
 925 ' <name>
 926 ( -- cfa )
 927 find word, push its CFA to the data stack. note that the tick
 928 is NOT immediate. use "[']" if you need to compile next word CFA.
 929
 930 :
 931 start new word definition.
 932
 933 ;
 934 end new word definition.
 935
 936 ALIAS oldword newword
 937 ( -- )
 938 "newword" will do exactly the same as "oldword". word attributes
 939 will be copied too (hidden, immediate, etc.).
 940
 941 LATEST-CFA
 942 ( -- cfa )
 943
 944 LATEST-PFA
 945 ( -- pfa )
 946
 947 LATEST-NFA
 948 ( -- nfa )
 949
 950 LATEST-SFA
 951 ( -- sfa )
 952
 953 ~AND
 954 ( a b -- a&~b )
 955
 956 SWAP!
 957 ( addr value -- )
 958
 959 OR!
 960 ( value addr -- )
 961
 962 ~AND!
 963 ( value addr -- )
 964
 965 XOR!
 966 ( value addr -- )
 967
 968 IMMEDIATE
 969 mark last defined word as immediate (or remove immediate mark if it is already set).
 970
 971 (HIDDEN)
 972 mark last defined word as hidden. DO NOT USE. this is obsolete feature,
 973 and it will be removed. it is here for compatibility with my other Forth system.
 974
 975 (PUBLIC)
 976 the opposite of "(HIDDEN)".
 977
 978 -FIND-REQUIRED
 979 alias for the tick.
 980
 981 PARSE-SKIP-COMMENTS
 982 ( -- )
 983 skip all comments and blanks, multiline mode.
 984
 985 PARSE-SKIP-LINE-COMMENTS
 986 skip all comments and blanks, single line mode.
 987
 988 (SET-DEF-WORD-FLAGS)
 989 ( flg -- )
 990 add (OR) default flag for new words.
 991 word flags are:
 992   (WFLAG-IMMEDIATE)
 993   (WFLAG-SMUDGE)
 994   (WFLAG-NORETURN)
 995   (WFLAG-HIDDEN)
 996   (WFLAG-CBLOCK)
 997   (WFLAG-VOCAB)
 998   (WFLAG-SCOLON)
 999   (WFLAG-PROTECTED)
1000
1001 (RESET-DEF-WORD-FLAGS)
1002 ( flg -- )
1003 remove (~AND) default flag for new words.
1004
1005 <PUBLIC-WORDS>
1006 ( -- )
1007 all following words will be public.
1008
1009 <HIDDEN-WORDS>
1010 ( -- )
1011 all following words will be hidden.
1012
1013 <PROTECTED-WORDS>
1014 ( -- )
1015 all following words will be protected. you cannot redefine
1016 protected words.
1017
1018 <UNPROTECTED-WORDS>
1019 ( -- )
1020 all following words will not be protected.
1021
1022 ONLY
1023 ( -- )
1024 clear the wordlist stack.
1025
1026 ALSO
1027 ( -- )
1028 push context vocabulary onto the wordlist stack.
1029
1030 PREVIOUS
1031 ( -- )
1032 pop vocabulary from the wordlist stack, and make in context.
1033
1034 DEFINITIONS
1035 ( -- )
1036 make context vocabulary also current. "current" is the vocabulary
1037 that will receive new word definitions. "context" is the vocabulary
1038 that will be used to search words.
1039
1040 1+
1041 ( a -- a+1 )
1042
1043 2+
1044 ( a -- a+2 )
1045
1046 4+
1047 ( a -- a+2 )
1048
1049 1-
1050 ( a -- a-1 )
1051
1052 2-
1053 ( a -- a-2 )
1054
1055 4-
1056 ( a -- a-2 )
1057
1058 0=
1059 ( n -- n==0 )
1060
1061 0<>
1062 ( n -- n<>0 )
1063
1064 0<
1065 ( n -- n==0 )
1066
1067 0<=
1068 ( n -- n==0 )
1069
1070 0>
1071 ( n -- n<>0 )
1072
1073 0>=
1074 ( n -- n<>0 )
1075
1076 NOTNOT
1077 ( a -- !!a )
1078
1079 ABS
1080 ( a -- |a| )
1081
1082 SIGN?
1083 ( n -- -1|0|1 )
1084
1085 NEGATE
1086 ( n -- -n )
1087
1088 LSHIFT
1089 ( n count -- n )
1090
1091 RSHIFT
1092 ( n count -- n )
1093
1094 ARSHIFT
1095 ( n count -- n )
1096
1097 SHL
1098 ( n count -- n )
1099
1100 SHR
1101 ( n count -- n )
1102
1103 SAL
1104 ( n count -- n )
1105
1106 SAR
1107 ( n count -- n )
1108
1109 LO-WORD
1110 ( a -- a&0xffff )
1111
1112 HI-WORD
1113 ( a -- [a>>16]&0xffff )
1114
1115 LO-BYTE
1116 ( a -- a&0xff )
1117
1118 HI-BYTE
1119 ( a -- [a>>8]&0xff )
1120
1121 0!
1122 ( addr -- )
1123
1124 1!
1125 ( addr -- )
1126
1127 +!
1128 ( n addr -- )
1129
1130 -!
1131 ( n addr -- )
1132
1133 1+!
1134 ( addr -- )
1135
1136 1-!
1137 ( addr -- )
1138
1139 BCOUNT
1140 ( addr -- addr+1 count )
1141
1142 COUNT
1143 ( addr -- addr+4 count )
1144
1145 HEX
1146 ( -- )
1147
1148 DECIMAL
1149 ( -- )
1150
1151 OCTAL
1152 ( -- )
1153
1154 BINARY
1155 ( -- )
1156
1157 WITHIN
1158 ( value a b -- value>=a&&value<b )
1159
1160 UWITHIN
1161 ( value a b -- value>=a&&value<b )
1162
1163 BOUNDS?
1164 ( value a b -- value>=a&&value<=b )
1165 numbers are unsigned.
1166
1167 (HANDLE-ADDR?)
1168 ( addr -- )
1169 check if the given addres is actually a handle.
1170
1171 COMPILER:SET-SMUDGE
1172 ( -- )
1173 set "smudge" bit for the latest word.
1174
1175 COMPILER:RESET-SMUDGE
1176 ( -- )
1177 reset "smudge" bit for the latest word.
1178
1179 COMPILER:SET-WARG
1180 ( warg -- )
1181 set argument type for the latest word. each word has "argument type" field,
1182 which inditates word argument type in the compiled code. arguments are:
1183   (WARG-NONE)
1184   (WARG-BRANCH)
1185   (WARG-LIT)
1186   (WARG-C4STRZ)
1187   (WARG-CFA)
1188   (WARG-CBLOCK)
1189   (WARG-VOCID)
1190   (WARG-C1STRZ)
1191
1192 (WARG-MASK)
1193 ( -- mask )
1194 this mask can be used to get only argument type bits from the first NFA cell.
1195
1196 COMPILER:(GET-NEW-WORD-FLAGS)
1197 ( -- flags )
1198 get sanitized new word flags. currently, only "hidden" and "protected" flags
1199 are retained, all other flags will be reset.
1200
1201 COMPILER:(CREATE-HEADER)
1202 ( addr count -- )
1203 create new named word header with the default flags. additionally, sets
1204 "smudge" flag on the new word.
1205
1206 COMPILER:(CREATE-NAMELESS)
1207 ( -- cfa )
1208 create new nameless word header with the default flags. additionally, sets
1209 "smudge" and "hidden" flags on the new word.
1210 return CFA address of the new word. CFA contents is not filled yet.
1211
1212 COMPILER:(MK-CONST-VAR)
1213 ( value cfaidx -- )
1214 don't bother using this.
1215
1216 COMPILER:FORTH-WORD?
1217 ( cfa -- bool )
1218 check if the given word is normal Forth word (i.e. defined with the colon).
1219
1220 COMPILE
1221 ( cfa -- )
1222 compiles CFA to be executed.
1223
1224 use the following words to compile branch destinations. this way your code
1225 will be independent of branch instruction operand format.
1226
1227 ;; usage:
1228 ;;  compile (0branch)
1229 ;;  (mark>)
1230 ;;  ...
1231 ;;  (resolve>)
1232 ;;
1233 ;;  (<mark)
1234 ;;  ...
1235 ;;  compile (branch)
1236 ;;  (<resolve)
1237
1238 COMPILER:(BRANCH-ADDR!)
1239 ( destaddr addr -- )
1240 write "branch to destaddr" address to addr.
1241
1242 COMPILER:(BRANCH-ADDR@)
1243 ( addr -- dest )  @ ;
1244 read branch address.
1245
1246
1247 COMPILER:(<J-MARK)
1248 ( -- addr )
1249 return addr suitable for "(<J-RESOLVE)".
1250
1251 COMPILER:(<J-CHAIN)
1252 ( addr -- addr )
1253 use after "(<J-MARK)" to reserve jump and append it to jump chain.
1254
1255 COMPILER:(<J-RESOLVE)
1256 ( addr -- )
1257 patch "forward jump" address to HERE. "addr" is the result of "(<J-MARK)".
1258
1259 COMPILER:(MARK-J>)
1260 reserve room for branch address, return addr suitable for "(RESOLVE-J>)".
1261
1262 COMPILER:(CHAIN-J>)
1263 use after "(MARK-J>)" to reserve jump and append it to jump chain.
1264
1265 COMPILER:(RESOLVE-J>)
1266 ( addr -- )
1267 compile "forward jump" (possibly chain) from address to HERE. addr is the
1268 result of "(MARK-J>)". this resolves the whole "jump chain".
1269
1270
1271 COMPILER:?PAIRS
1272 ( a b -- )
1273 throw error if a <> b.
1274
1275 ?2PAIRS
1276 ( a b c -- )
1277 throw error if a <> b and a <> c.
1278
1279 LITERAL
1280 ( C:n -- )
1281 ( E:n -- n )
1282 compile number from the data stack as literal. NOT IMMEDIATE.
1283
1284 IMM-LITERAL
1285 ( C:n -- )
1286 ( E:n -- n )
1287 immediate version of "LITERAL".
1288
1289
1290 CFALITERAL
1291 ( C:cfa -- )
1292 ( E:cfa -- cfa )
1293
1294 IMM-CFALITERAL
1295 ( C:cfa -- )
1296 ( E:cfa -- cfa )
1297
1298 [COMPILE] <wordname>
1299 force the next word to be compiled as normal word, even if it is an immediate one.
1300
1301 [']
1302 compile next word CFA as CFA literal.
1303
1304 COMPILER:(COMPILE-CFA-LITERAL)
1305 ( cfa -- )
1306 compile cfa literal to be compiled. ;-)
1307
1308 COMPILER:END-COMPILE-FORTH-WORD
1309 ( -- )
1310 push colon ctlid and call ";".
1311
1312
1313 COMPILE <wordname>
1314 compile next word to the currently defining word.
1315
1316 [CHAR] <char>
1317 ( -- ch )
1318 push/compile first char of the next word as char code.
1319 note that words with more than one char will cause an error.
1320
1321 RECURSE
1322 recursively call the currently defining word. this is required
1323 due to currently defining word being invisible yet (because it
1324 is not finished).
1325
1326 RECURSE-TAIL
1327 tail-call recursion.
1328
1329 CONSTANT <name>
1330 ( value -- )
1331 create new constant.
1332
1333 VARIABLE <name>
1334 ( value -- )
1335 create new variable.
1336
1337 (CREATE)
1338 ( addr count -- )
1339 this is what "CREATE" is using to create a new word.
1340
1341 CREATE <name>
1342 ( -- )
1343 create new word. when executed, this new word will push its PFA.
1344 note that new word is not smudged.
1345
1346 CREATE;
1347 ( -- )
1348 finish CREATEd word. this is required to correctly set SFA.
1349 note that "DOES>" automatically takes care of SFA, so you don't have
1350 to call this if you're using "DOES>".
1351
1352 (DOES>)
1353 ( doer-addr -- )
1354 patch CREATEd word. put doer address to its CFA, VM will do the rest.
1355 this is used internally by the compiler.
1356
1357 (SET-DOER)
1358 ( doer-pfa cfa -- )
1359 makes CFA word to execute "doer-pfa" as doer.
1360 this is used internally by the compiler. do not try to understand this.
1361
1362 DOES>
1363 ( -- )  ( pfa )
1364 the usual Forth "CREATE" -- "DOES>" support.
1365
1366 4 CONSTANT CELL
1367 ANS idiocity.
1368
1369 ALIAS 4U* CELLS  ( n -- n*cells )
1370 ANS idiocity.
1371
1372 ALIAS 4+  CELL+  ( n -- n+cell )
1373 ANS idiocity.
1374
1375 ALIAS 4-  CELL-  ( n -- n-cell )
1376 ANS idiocity.
1377
1378 +CELLS
1379 ( a n -- a+n*cells )
1380 ANS idiocity.
1381
1382 -CELLS
1383 ( a n -- a+n*cells )
1384 ANS idiocity.
1385
1386 .( text)
1387 immediately print the text.
1388
1389 ." text"
1390 compile text printer.
1391
1392 N-ALLOT
1393 ( n -- stard-addr )
1394 allocate n *bytes* in the current DP, return the address of
1395 the first allocated byte.
1396
1397 ALLOT
1398 ( n -- )
1399 allocate n *bytes* in the current DP.
1400
1401
1402 STRLITERAL
1403 ( C:addr count -- )
1404 ( E: -- addr count )
1405
1406
1407 COMPILER:(NEW-WORDLIST)
1408 ( parentvocid need-hashtable? -- vocid )
1409 create new empty wordlist.
1410
1411 COMPILER:(CREATE-NAMED-VOCAB)
1412 ( vocid addr count -- )
1413 create vocabulary word.
1414
1415 COMPILER:(CREATE-VOCAB) <vocname>
1416 ( vocid -- )
1417 create vocabulary word.
1418
1419 COMPILER:(IS-VOC-WORD?)
1420 ( cfa -- bool )
1421 check if the given CFA defined as a vocabulary header.
1422
1423 COMPILER:(WORD->VOCID)
1424 ( cfa -- vocid )
1425 get vocid from the vocabulary word. doesn't check arguments.
1426
1427 COMPILER:(VOCID-PARENT@)
1428 ( vocid -- vocid )
1429 get vocid parent vocabulary. return 0 if there is no parent.
1430 doesn't check arguments.
1431
1432 COMPILER:(VOCID-PARENT!)
1433 ( parent-vocid vocid -- )
1434 set vocid parent vocabulary. doesn't check arguments.
1435
1436 COMPILER:(VOCID-TYPEID@)
1437 ( vocid -- typeid )
1438 internal helper for STRUCT support.
1439
1440 COMPILER:(VOCID-TYPEID!)
1441 internal helper for STRUCT support.
1442
1443 (VOCABULARY-EX)
1444 ( addr count parent need-hashtbl? -- )
1445 useful low-level words to create vocabs with already parsed names.
1446
1447 (VOCABULARY)
1448 ( addr count -- )
1449
1450 (SIMPLE-VOCABULARY)
1451 ( addr count -- )
1452 creates vocabulary without a hash table.
1453
1454 (NESTED-VOCABULARY)
1455 ( addr count -- )
1456
1457 (SIMPLE-NESTED-VOCABULARY)
1458 ( addr count -- )
1459
1460 VOCABULARY <vocname>
1461
1462 SIMPLE-VOCABULARY <vocname>
1463
1464 NESTED-VOCABULARY <vocname>
1465
1466 SIMPLE-NESTED-VOCABULARY <vocname>
1467
1468 VOCID: <vocname>
1469 ( -- vocid )
1470 return vocid for the given vocabulary. this word is immediate.
1471
1472 VOC-LATEST
1473 ( vocid -- latest )
1474 return latest word LFA for the given vocid.
1475
1476 ALSO-DEFS: <vocname>
1477 ( -- )
1478 this does "ALSO <vocname> DEFINITIONS"
1479
1480 PREV-DEFS
1481 ( -- )
1482 this does "PREVIOUS DEFINITIONS".
1483
1484 VOCAB-IF-NONE <vocname>
1485 create vocabulary if we don't have such word yet.
1486
1487 NESTED-VOCAB-IF-NONE <vocname>
1488 create nested vocabulary if we don't have such word yet.
1489
1490 -TO  ( n -- )  \ name
1491 decrement value by n.
1492
1493 +TO  ( n -- )  \ name
1494 increment value by n.
1495
1496 -1-TO  ( -- )  \ name
1497 decrement value by 1.
1498
1499 +1-TO  ( -- )  \ name
1500 increment value by 1.
1501
1502 0-TO  ( -- )  \ name
1503 write 0 to value.
1504
1505 ... FORTH:(TO-EXTENDER) ...
1506 ( addr count FALSE -- addr count FALSE / TRUE )
1507 "TO" can be extended to support things it doesn't know about yet.
1508 after parsing a name, "(TO-EXTENDER)" will be called (this is
1509 scattered colon word). note that due to how scattered colon works,
1510 you'd better DON'T use "EXIT", but pass a flag if you need to stop
1511 further processing. also, do not forget to check the flag at the
1512 start of your extender, because some other extender may already
1513 did its work before yours.
1514
1515 ... FORTH:(EXIT-EXTENDER) ...
1516 ( -- )
1517 this scattered colon word allows you to extend "EXIT". "EXIT" is
1518 the immediate word that compiles word leaving instructions. you
1519 can compile your cleanup code before the standard cleanup.
1520
1521 ... FORTH:(INTERPRET-CHECK-WORD) ...
1522 ( addr count FALSE -- addr count FALSE / TRUE )
1523 this is called by INTERPRET before the standard word processing.
1524
1525 ... FORTH:(INTERPRET-WORD-NOT-FOUND) ...
1526 ( addr count FALSE -- addr count FALSE / TRUE )
1527 this is called by INTERPRET when word resolution failed.
1528
1529
1530 UrForth supports cooperative multitasking. it is also used to implement
1531 interactive debugger. tasks are called "execution states", or simply
1532 "states".
1533
1534 MTASK:NEW-STATE
1535 ( cfa -- stid )
1536 create new state, return state id.
1537
1538 MTASK:FREE-STATE
1539 ( stid -- )
1540 free state. state id should be valid, and should not be an active state.
1541
1542 MTASK:STATE-NAME@
1543 ( stid -- addr count )
1544 copy state name to PAD.
1545
1546 MTASK:STATE-NAME!
1547 ( addr count stid -- )
1548 set new state name. maximum name length is 127 chars. state name
1549 should not include char with code 0.
1550
1551 MTASK:STATE-FIRST
1552 ( -- stid )
1553 get first state in the list of all created states. this is used to
1554 iterate over all states.
1555 WARNING! do not mutate state list while iterating! result will be UB.
1556
1557 MTASK:STATE-NEXT
1558 ( stid -- stid / 0 )
1559 get next state id. used to iterate over all states.
1560 WARNING! do not mutate state list while iterating! result will be UB.
1561
1562 MTASK:YIELD-TO
1563 ( ... argc stid -- )
1564 yield to another state. move argc numbers from the current state data
1565 stack to the new state data stack. push args to the new state data
1566 stack, and then push current state id. i.e. new state data stack will
1567 look like this:
1568   ( ... argc old-stid )
1569 it is ok to swith to the currently active state (it is a no-op).
1570
1571 MTASK:SET-SELF-AS-DEBUGGER
1572 ( -- )
1573 register current task as system debugger. you can yeild from the debugger
1574 after this.
1575
1576 DEBUG:(BP)
1577 ( -- )
1578 breakpoint. debugger task receives debugge stid on the data stack,
1579 and `-1` as yield argument count. i.e. debugger stack will be:
1580   ( -1 old-stid )
1581
1582 MTASK:DEBUGGER-RESUME
1583 ( stid -- )
1584 resume debugee execution.
1585
1586 MTASK:DEBUGGER-SINGLE-STEP
1587 ( stid -- )
1588 execute one debuggee instruction, and return to debugger.
1589 this is basically "YIELD", but to use in the debugger
1590 (and it doesn't pass any arguments). debugger stack will be:
1591   ( -2 old-stid )
1592
1593 MTASK:STATE-IP@
1594 ( stid -- ip )
1595 get state instruction pointer.
1596
1597 MTASK:STATE-IP!
1598 ( ip stid -- )
1599 set state instruction pointer.
1600
1601 MTASK:STATE-A>
1602 ( stid -- regA )
1603 get address register contents.
1604
1605 MTASK:STATE->A
1606 ( rega stid -- )
1607 set address register contents.
1608
1609 MTASK:STATE-USER@
1610 ( addr stid -- valie )
1611 get other state user area cell.
1612
1613 MTASK:STATE-USER!
1614 ( value addr stid -- )
1615 set other state user area cell.
1616
1617 MTASK:STATE-RPOPCFA@
1618 ( -- flag )
1619 VM has special mode when it gets next CFA from the return stack
1620 instead of the address pointed by IP. this is used to implement
1621 "EXECUTE", for example. use this word to retrieve that flag.
1622
1623 MTASK:STATE-RPOPCFA!
1624 ( flag -- )
1625 VM has special mode when it gets next CFA from the return stack
1626 instead of the address pointed by IP. this is used to implement
1627 "EXECUTE", for example. use this word to set that flag.
1628
1629 MTASK:ACTIVE-STATE
1630 ( -- stid )
1631 return state id of the currently executing state.
1632
1633 MTASK:YIELDED-FROM
1634 ( -- stid / 0 )
1635 return state which called "MTASK:YIELD-TO" last.
1636
1637 MTASK:STATE-SP@
1638 ( stid -- depth )
1639 get the data stack depth for the given state.
1640
1641 MTASK:STATE-RP@
1642 ( stid -- depth )
1643 get the return stack depth for the given state.
1644
1645 MTASK:STATE-LP@
1646 ( stid -- lp )
1647 get local stack ptr.
1648
1649 MTASK:STATE-LBP@
1650 ( stid -- lbp )
1651 get local stack base ptr.
1652
1653 MTASK:STATE-SP!
1654 ( depth stid -- )
1655 set the data stack depth for the given state.
1656
1657 MTASK:STATE-RP!
1658 ( stid -- depth )
1659 set the return stack depth for the given state.
1660
1661 MTASK:STATE-LP!
1662 ( lp stid -- )
1663 set local stack ptr.
1664
1665 MTASK:STATE-LBP!
1666 ( lbp stid -- )
1667 set local stack base ptr.
1668
1669 MTASK:STATE-DS@
1670 ( idx stid -- value )
1671 read the data stack of the given state. note that the index is bound-checked.
1672
1673 MTASK:STATE-RS@
1674 ( idx stid -- value )
1675 read the return stack of the given state. note that the index is bound-checked.
1676
1677 MTASK:STATE-LS@
1678 ( idx stid -- value )
1679 read the locals stack of the given state. note that the index is bound-checked.
1680
1681 MTASK:STATE-DS!
1682 ( value idx stid -- )
1683 write the data stack of the given state. note that the index is bound-checked.
1684 i.e. if you want to push some value, increase stack depth first.
1685
1686 MTASK:STATE-RS!
1687 ( value idx stid -- )
1688 write the return stack of the given state. note that the index is bound-checked.
1689 i.e. if you want to push some value, increase stack depth first.
1690
1691 MTASK:STATE-LS!
1692 ( value idx stid -- )
1693 write the locals stack of the given state. note that the index is bound-checked.
1694 i.e. if you want to push some value, increase stack depth first.
1695
1696
1697 there are some words to work with TTY (only GNU/Linux).
1698
1699 TTY:TTY?
1700 ( -- bool )
1701 check if input and output are valid TTY(s).
1702
1703 TTY:RAW?
1704 ( -- bool )
1705 check if current TTY mode is raw.
1706
1707 TTY:SIZE
1708 ( -- width height )
1709 get TTY size. for non-TTYs retur default 80x24.
1710
1711 TTY:SET-RAW
1712 ( -- success-bool )
1713 switch TTY to raw mode.
1714
1715 TTY:SET-COOKED
1716 ( -- success-bool )
1717 switch TTY to cooked mode.
1718
1719 TTY:RAW-EMIT
1720 ( n -- )
1721 type char without any filtering or safety nets.
1722
1723 TTY:RAW-TYPE
1724 ( addr count -- )
1725 type string without any filtering or safety nets.
1726
1727 TTY:RAW-FLUSH
1728 ( -- )
1729 the output of the two words above is buffered. this words flushes
1730 the buffer. buffering is done because raw TTY is mostly used to
1731 build user interfaces, and sending accumulated terminal commands
1732 in one big chunk looks much better (most terminal emulators will
1733 process the whole chunk before refreshing their windows).
1734
1735 TTY:RAW-READCH
1736 ( -- ch / -1 )
1737 -1 returned on error, or on EOF.
1738 read one char (without any interpretation) if TTY is in raw mode.
1739 note that 0 is a valid char (it is used to send Ctrl+Space in some
1740 terminal emulators). also note that there is no way to tell if we
1741 hit a EOF, or some error occured. in practice, it doesn't matter,
1742 because in both cases it means that TTY is unusable anymore.
1743
1744 TTY:RAW-READY?
1745 ( -- bool )
1746 check if raw TTY has some data to read.