DPANSA6.HTM (49447B)
1 <HTML><HEAD> 2 <TITLE>DPANS94</TITLE> 3 <link disabled rel="stylesheet" href="mpexc6.css"> 4 <style>@import url(mpexc6.css);</style> 5 </head> 6 7 <BODY> 8 <table width=100%> 9 <tr> 10 <td align=left> 11 <a href=dpansa5.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpansa7.htm><img src=right.gif 14 width=26 height=26 align=ALIGN border=0></a> 15 </td> 16 <td align=right> 17 <a href=dpans.htm#toc><img src=up.gif 18 width=26 height=26 align=ALIGN border=0></a> 19 <a name=A.6>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H2>A.6 Glossary</H2> 27 28 In this and following sections we present rationales for the handling of 29 specific words: why we included them, why we placed them in certain word 30 sets, or why we specified their names or meaning as we did. 31 32 <P> 33 34 Words in this section are organized by word set, retaining their index 35 numbers for easy cross-referencing to the glossary. 36 37 <P> 38 39 Historically, many Forth systems have been written in Forth. Many of 40 the words in Forth originally had as their primary purpose support of 41 the Forth system itself. For example, WORD and FIND are often used as 42 the principle instruments of the Forth text interpreter, and CREATE in 43 many systems is the primitive for building dictionary entries. In 44 defining words such as these in a standard way, we have endeavored not 45 to do so in such a way as to preclude their use by implementors. One of 46 the features of Forth that has endeared it to its users is that the same 47 tools that are used to implement the system are available to the 48 application programmer - a result of this approach is the compactness 49 and efficiency that characterizes most Forth implementations. 50 51 <P> 52 53 <hr> 54 <a name=A.6.1> 55 <H3>A.6.1 Core words</H3> 56 </a> 57 58 59 60 <hr> 61 <a name=A.6.1.0070>A.6.1.0070 '</A> 62 <P> 63 </a> 64 65 Typical use: <code>... ' name .</code> 66 <P> 67 68 Many Forth systems use a state-smart tick. Many do not. ANS Forth follows 69 the usage of Forth-83. 70 71 <P> 72 <code> 73 See: 74 <a href=dpansa3.htm#A.3.4.3.2>A.3.4.3.2</a> Interpretation semantics, 75 <a href=dpansa6.htm#A.6.1.1550>A.6.1.1550 FIND</a> 76 </code> 77 <P> 78 79 <hr> 80 <a name=A.6.1.0080>A.6.1.0080 (</A> 81 <P> 82 83 Typical use: <code>... ( ccc) ...</code> 84 <P> 85 86 <hr> 87 <a name=A.6.1.0140>A.6.1.0140 +LOOP</A> 88 <P> 89 90 Typical use: <code>: X ... limit first DO ... step +LOOP ;</code> 91 <P> 92 93 <hr> 94 <a name=A.6.1.0150>A.6.1.0150 ,</A> 95 <P> 96 97 The use of , (comma) for compiling execution tokens is not portable. 98 <P> 99 <code> 100 See: 101 <a href=dpans6.htm#6.2.0945>6.2.0945 COMPILE,</a> 102 </code> 103 <P> 104 105 <hr> 106 <a name=A.6.1.0190>A.6.1.0190 ."</A> 107 <P> 108 109 Typical use: <code>: X ... ." ccc" ... ;</code> 110 <P> 111 112 An implementation may define interpretation semantics for ." if desired. 113 In one plausible implementation, interpreting ." would display the 114 delimited message. In another plausible implementation, interpreting ." 115 would compile code to display the message later. In still another 116 plausible implementation, interpreting ." would be treated as an 117 exception. Given this variation a Standard Program may not use ." while 118 interpreting. Similarly, a Standard Program may not compile POSTPONE ." 119 inside a new word, and then use that word while interpreting. 120 121 <P> 122 123 <hr> 124 <a name=A.6.1.0320>A.6.1.0320 2*</A> 125 <P> 126 127 Historically, 2* has been implemented on two's-complement machines as a 128 logical left-shift instruction. Multiplication by two is an efficient 129 side-effect on these machines. However, shifting implies a knowledge of 130 the significance and position of bits in a cell. While the name implies 131 multiplication, most implementors have used a hardware left shift to 132 implement 2*. 133 134 <P> 135 136 <hr> 137 <a name=A.6.1.0330>A.6.1.0330 2/</A> 138 <P> 139 140 This word has the same common usage and misnaming implications as 2*. 141 It is often implemented on two's-complement machines with a hardware 142 right shift that propagates the sign bit. 143 144 <P> 145 146 <hr> 147 <a name=A.6.1.0350>A.6.1.0350 2@</A> 148 <P> 149 150 With 2@ the storage order is specified by the Standard. 151 152 <P> 153 154 <hr> 155 <a name=A.6.1.0450>A.6.1.0450 :</A> 156 <P> 157 158 Typical use: <code>: name ... ;</code> 159 160 <P> 161 162 In Forth-83, this word was specified to alter the search order. This 163 specification is explicitly removed in this Standard. We believe that 164 in most cases this has no effect; however, systems that allow many 165 search orders found the Forth-83 behavior of colon very undesirable. 166 167 <P> 168 169 Note that colon does not itself invoke the compiler. Colon sets 170 compilation state so that later words in the parse area are compiled. 171 172 <P> 173 174 <hr> 175 <a name=A.6.1.0460>A.6.1.0460 ;</A> 176 <P> 177 178 179 Typical use: <code>: name ... ;</code> 180 181 <P> 182 183 One function performed by both ; and ;CODE is to allow the current 184 definition to be found in the dictionary. If the current definition was 185 created by :NONAME the current definition has no definition name and 186 thus cannot be found in the dictionary. If :NONAME is implemented the 187 Forth compiler must maintain enough information about the current 188 definition to allow ; and ;CODE to determine whether or not any action 189 must be taken to allow it to be found. 190 191 <P> 192 193 <hr> 194 <a name=A.6.1.0550>A.6.1.0550 >BODY</A> 195 <P> 196 197 a-addr is the address that HERE would have returned had it been executed 198 immediately after the execution of the CREATE that defined xt. 199 200 <P> 201 202 <hr> 203 <a name=A.6.1.0680>A.6.1.0680 ABORT"</A> 204 <P> 205 206 Typical use: <code>: X ... test ABORT" ccc" ... ;</code> 207 208 <P> 209 210 <hr> 211 <a name=A.6.1.0695>A.6.1.0695 ACCEPT</A> 212 <P> 213 214 Previous standards specified that collection of the input string 215 terminates when either a <B>return</B> is received or when +n1 216 characters have been received. Terminating when +n1 characters have 217 been received is difficult, expensive, or impossible to implement in 218 some system environments. Consequently, a number of existing 219 implementations do not comply with this requirement. Since line-editing 220 and collection functions are often implemented by system components 221 beyond the control of the Forth implementation, this Standard imposes no 222 such requirement. A Standard Program may only assume that it can 223 receive an input string with ACCEPT or 224 <a href=dpans6.htm#6.2.1390>EXPECT</a>. 225 The detailed sequence of 226 user actions necessary to prepare and transmit that line are beyond the 227 scope of this Standard. 228 229 <P> 230 231 Specification of a non-zero, positive integer count (+n1) for ACCEPT 232 allows some implementors to continue their practice of using a zero or 233 negative value as a flag to trigger special behavior. Insofar as such 234 behavior is outside the Standard, Standard Programs cannot depend upon 235 it, but the Technical Committee doesn't wish to preclude it 236 unnecessarily. Since actual values are almost always small integers, no 237 functionality is impaired by this restriction. 238 239 <P> 240 241 ACCEPT and EXPECT perform similar functions. ACCEPT is recommended for 242 new programs, and future use of EXPECT is discouraged. 243 244 <P> 245 246 It is recommended that all non-graphic characters be reserved for 247 editing or control functions and not be stored in the input string. 248 249 <P> 250 251 Commonly, when the user is preparing an input string to be transmitted 252 to a program, the system allows the user to edit that string and correct 253 mistakes before transmitting the final version of the string. The 254 editing function is supplied sometimes by the Forth system itself, and 255 sometimes by external system software or hardware. Thus, control 256 characters and functions may not be available on all systems. In the 257 usual case, the end of the editing process and final transmission of the 258 string is signified by the user pressing a <B>Return</B> or <B>Enter</B> 259 key. 260 261 <P> 262 263 As in previous standards, EXPECT returns the input string immediately 264 after the requested number of characters are entered, as well as when a 265 line terminator is received. The <B>automatic termination after 266 specified count of characters have been entered</B> behavior is widely 267 considered undesirable because the user <B>loses control</B> of the 268 input editing process at a potentially unknown time (the user does not 269 necessarily know how many characters were requested from EXPECT). Thus 270 EXPECT and SPAN have been made obsolescent and exist in the Standard 271 only as a concession to existing implementations. If EXPECT exists in a 272 Standard System it must have the <B>automatic termination</B> behavior. 273 274 <P> 275 276 ACCEPT does not have the <B>automatic termination</B> behavior of 277 EXPECT. However, because external system hardware and software may 278 perform the ACCEPT function, when a line terminator is received the 279 action of the cursor, and therefore the display, is 280 implementation-defined. It is recommended that the cursor remain 281 immediately following the entered text after a line terminator is 282 received. 283 284 <P> 285 286 <hr> 287 <a name=A.6.1.0705>A.6.1.0705 ALIGN</A> 288 <P> 289 290 In this Standard we have attempted to provide transportability across 291 various CPU architectures. One of the frequent causes of 292 transportability problems is the requirement of cell-aligned addresses 293 on some CPUs. On these systems, ALIGN and ALIGNED may be required to 294 build and traverse data structures built with C,. Implementors may 295 define these words as no-ops on systems for which they aren't 296 functional. 297 298 <P> 299 300 <hr> 301 <a name=A.6.1.0706>A.6.1.0706 ALIGNED</A> 302 <P> 303 <code> 304 See: 305 <a href=dpansa6.htm#A.6.1.0705>A.6.1.0705 ALIGN</a> 306 </code> 307 <P> 308 309 <hr> 310 <a name=A.6.1.0760>A.6.1.0760 BEGIN</A> 311 <P> 312 313 Typical use: 314 <pre> 315 : X ... BEGIN ... test UNTIL ; 316 </pre> 317 318 or 319 <P> 320 321 322 <PRE> 323 : X ... BEGIN ... test WHILE ... REPEAT ; 324 </PRE> 325 <P> 326 327 <hr> 328 <a name=A.6.1.0770>A.6.1.0770 BL</A> 329 <P> 330 331 Because space is used throughout Forth as the standard delimiter, this 332 word is the only way a program has to find and use the system value of 333 <B>space</B>. The value of a space character can not be obtained with 334 CHAR, for instance. 335 336 <P> 337 338 <hr> 339 <a name=A.6.1.0880>A.6.1.0880 CELL+</A> 340 <P> 341 342 As with ALIGN and ALIGNED, the words CELL and CELL+ were added to aid in 343 transportability across systems with different cell sizes. They are 344 intended to be used in manipulating indexes and addresses in integral 345 numbers of cell-widths. 346 347 <P> 348 349 Example: 350 351 <PRE> 352 2VARIABLE DATA 353 354 0 100 DATA 2! 355 DATA @ . 100 356 357 DATA CELL+ @ . 0 358 </PRE> 359 360 <P> 361 362 <hr> 363 <a name=A.6.1.0890>A.6.1.0890 CELLS</A> 364 <P> 365 <code> 366 See: 367 <a href=dpansa6.htm#A.6.1.0880>A.6.1.0880 CELL+</a> 368 </code> 369 <P> 370 371 Example: <code>CREATE NUMBERS 100 CELLS ALLOT</code> 372 <P> 373 374 (Allots space in the array NUMBERS for 100 cells of data.) 375 376 <P> 377 378 <hr> 379 <a name=A.6.1.0895>A.6.1.0895 CHAR</A> 380 <P> 381 382 Typical use: <code>... CHAR A CONSTANT "A" ...</code> 383 384 <P> 385 386 <hr> 387 <a name=A.6.1.0950>A.6.1.0950 CONSTANT</A> 388 <P> 389 390 Typical use: <code>... DECIMAL 10 CONSTANT TEN ...</code> 391 392 <P> 393 394 <hr> 395 <a name=A.6.1.1000>A.6.1.1000 CREATE</A> 396 <P> 397 398 The data-field address of a word defined by CREATE is given by the 399 data-space pointer immediately following the execution of CREATE 400 401 <P> 402 403 Reservation of data field space is typically done with ALLOT. 404 405 <P> 406 407 Typical use: <code>... CREATE SOMETHING ...</code> 408 409 <P> 410 411 <hr> 412 <a name=A.6.1.1240>A.6.1.1240 DO</A> 413 <P> 414 415 Typical use: 416 <P> 417 418 419 <PRE> 420 : X ... limit first DO ... LOOP ; 421 </PRE> 422 <P> 423 424 or 425 <P> 426 427 428 <PRE> 429 : X ... limit first DO ... step +LOOP ; 430 </PRE> 431 <P> 432 433 <hr> 434 <a name=A.6.1.1250>A.6.1.1250 DOES></A> 435 <P> 436 437 Typical use: <code>: X ... DOES> ... ;</code> 438 439 <P> 440 441 Following DOES>, a Standard Program may not make any assumptions 442 regarding the ability to find either the name of the definition 443 containing the DOES> or any previous definition whose name may be 444 concealed by it. DOES> effectively ends one definition and begins 445 another as far as local variables and control-flow structures are 446 concerned. The compilation behavior makes it clear that the user is not 447 entitled to place DOES> inside any control-flow structures. 448 449 <P> 450 451 <hr> 452 <a name=A.6.1.1310>A.6.1.1310 ELSE</A> 453 <P> 454 455 Typical use: <code>: X ... test IF ... ELSE ... THEN ;</code> 456 457 <P> 458 459 <hr> 460 <a name=A.6.1.1345>A.6.1.1345 ENVIRONMENT?</A> 461 <P> 462 463 In a Standard System that contains only the Core word set, effective use 464 of ENVIRONMENT? requires either its use within a definition, or the use 465 of user-supplied auxiliary definitions. The Core word set lacks both a 466 direct method for collecting a string in interpretation state 467 ( 468 <a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> 469 S" is in an optional word set) and also a means to test the 470 returned flag in interpretation state (e.g. the optional 471 <a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF]). 472 473 <P> 474 475 The combination of 476 <a href=dpans6.htm#6.1.1345>6.1.1345</a> ENVIRONMENT?, 477 <a href=dpans11.htm#11.6.1.2165>11.6.1.2165</a> S", 478 <a href=dpans15.htm#15.6.2.2532>15.6.2.2532</a> [IF], 479 <a href=dpans15.htm#15.6.2.2531>15.6.2.2531</a> [ELSE], and 480 <a href=dpans15.htm#15.6.2.2533>15.6.2.2533</a> [THEN] constitutes an 481 effective suite of words for conditional compilation that works in 482 interpretation state. 483 484 <P> 485 486 <hr> 487 <a name=A.6.1.1360>A.6.1.1360 EVALUATE</A> 488 <P> 489 490 The Technical Committee is aware that this function is commonly spelled 491 EVAL. However, there exist implementations that could suffer by 492 defining the word as is done here. We also find EVALUATE to be more 493 readable and explicit. There was some sentiment for calling this 494 INTERPRET, but that too would have undesirable effects on existing code. 495 The longer spelling was not deemed significant since this is not a word 496 that should be used frequently in source code. 497 498 <P> 499 500 <hr> 501 <a name=A.6.1.1380>A.6.1.1380 EXIT</A> 502 <P> 503 504 Typical use: <code>: X ... test IF ... EXIT THEN ... ;</code> 505 506 <P> 507 508 <hr> 509 <a name=A.6.1.1550>A.6.1.1550 FIND</A> 510 <P> 511 512 One of the more difficult issues which the Committee took on was the 513 problem of divorcing the specification of implementation mechanisms from 514 the specification of the Forth language. Three basic implementation 515 approaches can be quickly enumerated: 516 517 <P> 518 519 1) Threaded code mechanisms. These are the traditional approaches to 520 implementing Forth, but other techniques may be used. 521 522 <P> 523 524 2) Subroutine threading with <B>macro-expansion</B> (code copying). 525 Short routines, like the code for DUP, are copied into a definition 526 rather than compiling a JSR reference. 527 528 <P> 529 530 3) Native coding with optimization. This may include stack optimization 531 (replacing such phrases as 532 <code>SWAP ROT +</code> with one or two machine 533 instructions, for example), parallelization (the trend in the newer RISC 534 chips is to have several functional subunits which can execute in 535 parallel), and so on. 536 537 <P> 538 539 The initial requirement (inherited from Forth-83) that compilation 540 addresses be compiled into the dictionary disallowed type 2 and type 3 541 implementations. 542 543 <P> 544 545 Type 3 mechanisms and optimizations of type 2 implementations were 546 hampered by the explicit specification of immediacy or non-immediacy of 547 all standard words. POSTPONE allowed de-specification of immediacy or 548 non-immediacy for all but a few Forth words whose behavior must be 549 STATE-independent. 550 551 <P> 552 553 One type 3 implementation, Charles Moore's cmForth, has both compiling 554 and interpreting versions of many Forth words. At the present, this 555 appears to be a common approach for type 3 implementations. The 556 Committee felt that this implementation approach must be allowed. 557 Consequently, it is possible that words without interpretation semantics 558 can be found only during compilation, and other words may exist in two 559 versions: a compiling version and an interpreting version. Hence the 560 values returned by FIND may depend on STATE, and ' and ['] may be unable 561 to find words without interpretation semantics. 562 563 <P> 564 565 <hr> 566 <a name=A.6.1.1561>A.6.1.1561 FM/MOD</A> 567 <P> 568 569 By introducing the requirement for <B>floored</B> division, Forth-83 570 produced much controversy and concern on the part of those who preferred 571 the more common practice followed in other languages of implementing 572 division according to the behavior of the host CPU, which is most often 573 symmetric (rounded toward zero). In attempting to find a compromise 574 position, this Standard provides primitives for both common varieties, 575 floored and symmetric 576 (<a href=dpans6.htm#6.1.2214>see</a> SM/REM). FM/MOD is the floored version. 577 578 <P> 579 580 The Technical Committee considered providing two complete sets of 581 explicitly named division operators, and declined to do so on the 582 grounds that this would unduly enlarge and complicate the Standard. 583 Instead, implementors may define the normal division words in terms of 584 either FM/MOD or SM/REM providing they document their choice. People 585 wishing to have explicitly named sets of operators are encouraged to do 586 so. FM/MOD may be used, for example, to define: 587 588 <P> 589 590 591 <PRE> 592 : /_MOD ( n1 n2 -- n3 n4) >R S>D R> FM/MOD ; 593 594 : /_ ( n1 n2 -- n3) /_MOD SWAP DROP ; 595 596 : _MOD ( n1 n2 -- n3) /_MOD DROP ; 597 598 : */_MOD ( n1 n2 n3 -- n4 n5) >R M* R> FM/MOD ; 599 600 : */_ ( n1 n2 n3 -- n4 ) */_MOD SWAP DROP ; 601 </PRE> 602 603 <P> 604 605 <hr> 606 <a name=A.6.1.1700>A.6.1.1700 IF</A> 607 <P> 608 609 Typical use: 610 <P> 611 612 613 <PRE> 614 : X ... test IF ... THEN ... ; 615 </PRE> 616 <P> 617 618 or 619 <P> 620 621 622 <PRE> 623 : X ... test IF ... ELSE ... THEN ... ; 624 </PRE> 625 <P> 626 627 <hr> 628 <a name=A.6.1.1710>A.6.1.1710 IMMEDIATE</A> 629 <P> 630 631 Typical use: <code>: X ... ; IMMEDIATE</code> 632 633 <P> 634 635 <hr> 636 <a name=A.6.1.1720>A.6.1.1720 INVERT</A> 637 <P> 638 639 The word NOT was originally provided in Forth as a flag operator to make 640 control structures readable. Under its intended usage the following two 641 definitions would produce identical results: 642 643 <P> 644 645 646 <PRE> 647 : ONE ( flag -- ) 648 IF ." true" ELSE ." false" THEN ; 649 650 : TWO ( flag -- ) 651 NOT IF ." false" ELSE ." true" THEN ; 652 </PRE> 653 654 <P> 655 656 This was common usage prior to the Forth-83 Standard which redefined NOT 657 as a cell-wide one's-complement operation, functionally equivalent to 658 the phrase 659 <code>-1 XOR</code>. At the same time, the data type manipulated by this 660 word was changed from a flag to a cell-wide collection of bits and the 661 standard value for true was changed from <B>1</B> (rightmost bit only 662 set) to <B>-1</B> (all bits set). As these definitions of TRUE and NOT 663 were incompatible with their previous definitions, many Forth users 664 continue to rely on the old definitions. Hence both versions are in 665 common use. 666 667 <P> 668 669 Therefore, usage of NOT cannot be standardized at this time. The two 670 traditional meanings of NOT - that of negating the sense of a flag and 671 that of doing a one's complement operation - are made available by 0= 672 and INVERT, respectively. 673 674 <P> 675 676 <hr> 677 <a name=A.6.1.1730>A.6.1.1730 J</A> 678 <P> 679 680 J may only be used with a nested DO...LOOP, DO...+LOOP, ?DO...LOOP, or 681 ?DO...+LOOP, for example, in the form: 682 683 684 <PRE> 685 : X ... DO ... DO ... J ... LOOP ... +LOOP ... ; 686 </PRE> 687 <P> 688 689 <hr> 690 <a name=A.6.1.1760>A.6.1.1760 LEAVE</A> 691 <P> 692 693 Note that LEAVE immediately exits the loop. No words following LEAVE 694 within the loop will be executed. Typical use: 695 696 697 <PRE> 698 : X ... DO ... IF ... LEAVE THEN ... LOOP ... ; 699 </PRE> 700 <P> 701 702 <hr> 703 <a name=A.6.1.1780>A.6.1.1780 LITERAL</A> 704 <P> 705 706 Typical use: <code>: X ... [ x ] LITERAL ... ;</code> 707 708 <P> 709 710 <hr> 711 <a name=A.6.1.1800>A.6.1.1800 LOOP</A> 712 <P> 713 714 Typical use: 715 <P> 716 717 718 <PRE> 719 : X ... limit first DO ... LOOP ... ; 720 </PRE> 721 <P> 722 723 or 724 <P> 725 726 727 <PRE> 728 : X ... limit first ?DO ... LOOP ... ; 729 </PRE> 730 <P> 731 732 <hr> 733 <a name=A.6.1.1810>A.6.1.1810 M*</A> 734 <P> 735 736 This word is a useful early step in calculation, going to extra 737 precision conveniently. It has been in use since the Forth systems of 738 the early 1970's. 739 740 <P> 741 742 <hr> 743 <a name=A.6.1.1900>A.6.1.1900 MOVE</A> 744 <P> 745 746 CMOVE and CMOVE> are the primary move operators in Forth-83. They 747 specify a behavior for moving that implies propagation if the move is 748 suitably invoked. In some hardware, this specific behavior cannot be 749 achieved using the best move instruction. Further, CMOVE and CMOVE> 750 move characters; ANS Forth needs a move instruction capable of dealing 751 with address units. Thus MOVE has been defined and added to the Core 752 word set, and CMOVE and CMOVE> have been moved to the String word set. 753 754 <P> 755 756 <hr> 757 <a name=A.6.1.2033>A.6.1.2033 POSTPONE</A> 758 <P> 759 760 Typical use: 761 762 <P> 763 764 765 <PRE> 766 : ENDIF POSTPONE THEN ; IMMEDIATE 767 768 : X ... IF ... ENDIF ... ; 769 </PRE> 770 771 <P> 772 773 POSTPONE replaces most of the functionality of 774 COMPILE and 775 <a href=dpans6.htm#6.2.2530>[COMPILE]</a>. 776 COMPILE and [COMPILE] are used for the same purpose: postpone the 777 compilation behavior of the next word in the parse area. COMPILE was 778 designed to be applied to non-immediate words and [COMPILE] to immediate 779 words. This burdens the programmer with needing to know which words in 780 a system are immediate. Consequently, Forth standards have had to 781 specify the immediacy or non-immediacy of all words covered by the 782 Standard. This unnecessarily constrains implementors. 783 784 <P> 785 786 A second problem with COMPILE is that some programmers have come to 787 expect and exploit a particular implementation, namely: 788 789 790 <PRE> 791 : COMPILE R> DUP @ , CELL+ >R ; 792 </PRE> 793 794 <P> 795 796 This implementation will not work on native code Forth systems. In a 797 native code Forth using inline code expansion and peephole optimization, 798 the size of the object code produced varies; this information is 799 difficult to communicate to a <B>dumb</B> COMPILE. A <B>smart</B> 800 (i.e., immediate) COMPILE would not have this problem, but this was 801 forbidden in previous standards. 802 803 <P> 804 805 For these reasons, COMPILE has not been included in the Standard and 806 [COMPILE] has been moved in favor of POSTPONE. Additional discussion 807 can be found in Hayes, J.R., <B>Postpone</B>, Proceedings of the 1989 808 Rochester Forth Conference. 809 810 <P> 811 812 <hr> 813 <a name=A.6.1.2120>A.6.1.2120 RECURSE</A> 814 <P> 815 816 Typical use: <code>: X ... RECURSE ... ;</code> 817 818 <P> 819 820 This is Forth's recursion operator; in some implementations it is called 821 MYSELF. The usual example is the coding of the factorial function. 822 823 <PRE> 824 : FACTORIAL ( +n1 -- +n2) 825 DUP 2 < IF DROP 1 EXIT THEN 826 DUP 1- RECURSE * 827 ; 828 </PRE> 829 830 <P> 831 832 n2 = n1(n1-1)(n1-2)...(2)(1), the product of n1 with all positive 833 integers less than itself (as a special case, zero factorial equals 834 one). While beloved of computer scientists, recursion makes unusually 835 heavy use of both stacks and should therefore be used with caution. See 836 alternate definition in 837 <a href=dpansa6.htm#A.6.1.2140>A.6.1.2140</a> REPEAT. 838 839 <P> 840 841 <hr> 842 <a name=A.6.1.2140>A.6.1.2140 REPEAT</A> 843 <P> 844 845 Typical use: 846 <P> 847 848 849 850 <PRE> 851 : FACTORIAL ( +n1 -- +n2) 852 DUP 2 < IF DROP 1 EXIT THEN 853 DUP 854 BEGIN DUP 2 > WHILE 855 1- SWAP OVER * SWAP 856 REPEAT DROP 857 ; 858 </PRE> 859 860 <P> 861 862 <hr> 863 <a name=A.6.1.2165>A.6.1.2165 S"</A> 864 <P> 865 866 Typical use: <code>: X ... S" ccc" ... ;</code> 867 868 <P> 869 870 This word is found in many systems under the name " (quote). However, 871 current practice is almost evenly divided on the use of ", with many 872 systems using the execution semantics given here, while others return 873 the address of a counted string. We attempt here to satisfy both camps 874 by providing two words, S" and the Core Extension word C" so that users 875 may have whichever behavior they expect with a simple renaming 876 operation. 877 878 <P> 879 880 <hr> 881 <a name=A.6.1.2214>A.6.1.2214 SM/REM</A> 882 <P> 883 884 See the previous discussion of division under FM/MOD. SM/REM is the 885 symmetric-division primitive, which allows programs to define the 886 following symmetric-division operators: 887 888 <P> 889 890 891 <PRE> 892 : /-REM ( n1 n2 -- n3 n4 ) >R S>D R> SM/REM ; 893 894 : /- ( n1 n2 -- n3 ) /-REM SWAP DROP ; 895 896 : -REM ( n1 n2 -- n3 ) /-REM DROP ; 897 898 : */-REM ( n1 n2 n3 -- n4 n5 ) >R M* R> SM/REM ; 899 900 : */- ( n1 n2 n3 -- n4 ) */-REM SWAP DROP ; 901 </PRE> 902 903 <P> 904 905 <hr> 906 <a name=A.6.1.2216>A.6.1.2216 SOURCE</A> 907 <P> 908 909 SOURCE simplifies the process of directly accessing the input buffer by 910 hiding the differences between its location for different input sources. 911 This also gives implementors more flexibility in their implementation of 912 buffering mechanisms for different input sources. The committee moved 913 away from an input buffer specification consisting of a collection of 914 individual variables, declaring TIB and #TIB obsolescent. 915 916 <P> 917 918 SOURCE in this form exists in F83, POLYFORTH, LMI's Forths and others. 919 In conventional systems it is equivalent to the phrase 920 921 922 <PRE> 923 BLK @ IF BLK @ BLOCK 1024 ELSE TIB #TIB @ THEN 924 </PRE> 925 926 <P> 927 928 <hr> 929 <a name=A.6.1.2250>A.6.1.2250 STATE</A> 930 <P> 931 932 Although EVALUATE, LOAD, INCLUDE-FILE, and INCLUDED are not listed as 933 words which alter STATE, the text interpreted by any one of these words 934 could include one or more words which explicitly alter STATE. EVALUATE, 935 LOAD, INCLUDE-FILE, and INCLUDED do not in themselves alter STATE. 936 937 <P> 938 939 STATE does not nest with text interpreter nesting. For example, the 940 code sequence: 941 942 943 <PRE> 944 : FOO S" ]" EVALUATE ; FOO 945 </PRE> 946 947 <P> 948 949 will leave the system in compilation state. Similarly, after LOADing a 950 block containing ], the system will be in compilation state. 951 952 <P> 953 954 Note that ] does not affect the parse area and that the only effect that 955 : has on the parse area is to parse a word. This entitles a program to 956 use these words to set the state with known side-effects on the parse 957 area. For example: 958 959 <P> 960 961 962 <PRE> 963 : NOP : POSTPONE ; IMMEDIATE ; 964 965 NOP ALIGN NOP ALIGNED 966 </PRE> 967 968 <P> 969 970 Some non-ANS Forth compliant systems have ] invoke a compiler loop in 971 addition to setting STATE. Such a system would inappropriately attempt 972 to compile the second use of NOP. 973 974 <P> 975 976 Also note that nothing in the Standard prevents a program from finding 977 the execution tokens of ] or [ and using these to affect STATE. These 978 facts suggest that implementations of ] will do nothing but set STATE 979 and a single interpreter/compiler loop will monitor STATE. 980 981 982 <P> 983 984 <hr> 985 <a name=A.6.1.2270>A.6.1.2270 THEN</A> 986 <P> 987 988 Typical use: 989 <P> 990 991 992 <PRE> 993 : X ... test IF ... THEN ... ; 994 </PRE> 995 <P> 996 997 or 998 <P> 999 1000 1001 <PRE> 1002 : X ... test IF ... ELSE ... THEN ... ; 1003 </PRE> 1004 <P> 1005 1006 <hr> 1007 <a name=A.6.1.2380>A.6.1.2380 UNLOOP</A> 1008 <P> 1009 1010 1011 Typical use: 1012 1013 <PRE> 1014 : X ... 1015 1016 limit first DO 1017 1018 ... test IF ... UNLOOP EXIT THEN ... 1019 1020 LOOP 1021 ... 1022 ; 1023 </PRE> 1024 1025 <P> 1026 1027 UNLOOP allows the use of EXIT within the context of DO ... LOOP and 1028 related do-loop constructs. UNLOOP as a function has been called UNDO. 1029 UNLOOP is more indicative of the action: nothing gets undone -- we 1030 simply stop doing it. 1031 1032 <P> 1033 1034 <hr> 1035 <a name=A.6.1.2390>A.6.1.2390 UNTIL</A> 1036 <P> 1037 1038 Typical use: <code>: X ... BEGIN ... test UNTIL ... ;</code> 1039 1040 <P> 1041 1042 <hr> 1043 <a name=A.6.1.2410>A.6.1.2410 VARIABLE</A> 1044 <P> 1045 1046 1047 Typical use: <code>... VARIABLE XYZ ...</code> 1048 1049 <P> 1050 1051 <hr> 1052 <a name=A.6.1.2430>A.6.1.2430 WHILE</A> 1053 <P> 1054 1055 1056 Typical use: <code>: X ... BEGIN ... test WHILE ... REPEAT ... ;</code> 1057 1058 <P> 1059 1060 <hr> 1061 <a name=A.6.1.2450>A.6.1.2450 WORD</A> 1062 <P> 1063 1064 Typical use: <code>char WORD ccc<char></code> 1065 1066 <P> 1067 1068 <hr> 1069 <a name=A.6.1.2500>A.6.1.2500 [</A> 1070 <P> 1071 1072 Typical use: <code>: X ... [ 4321 ] LITERAL ... ;</code> 1073 1074 <P> 1075 1076 <hr> 1077 <a name=A.6.1.2510>A.6.1.2510 [']</A> 1078 <P> 1079 1080 Typical use: <code>: X ... ['] name ... ;</code> 1081 1082 <P> 1083 <code> 1084 See: 1085 <a href=dpansa6.htm#A.6.1.1550>A.6.1.1550 FIND</a> 1086 </code> 1087 <P> 1088 1089 <hr> 1090 <a name=A.6.1.2520>A.6.1.2520 [CHAR]</A> 1091 <P> 1092 1093 Typical use: <code>: X ... [CHAR] ccc ... ;</code> 1094 1095 <P> 1096 1097 <hr> 1098 <a name=A.6.1.2540>A.6.1.2540 ]</A> 1099 <P> 1100 1101 Typical use: <code>: X ... [ 1234 ] LITERAL ... ;</code> 1102 1103 <P> 1104 1105 1106 <hr> 1107 <a name=A.6.2> 1108 <H3>A.6.2 Core extension words</H3> 1109 </a> 1110 1111 The words in this collection fall into several categories: 1112 <P> 1113 1114 <UL> 1115 <LI>Words that are in common use but are deemed less essential than Core 1116 words (e.g., 1117 <a href=dpans6.htm#6.2.0260>0<></a>); 1118 <LI>Words that are in common use but can be trivially defined from Core 1119 words (e.g., 1120 <a href=dpans6.htm#6.2.1485>FALSE</a>); 1121 <LI>Words that are primarily useful in narrowly defined types of 1122 applications or are in less frequent use (e.g., 1123 <a href=dpans6.htm#6.2.2008>PARSE</a>); 1124 <LI>Words that are being deprecated in favor of new words introduced to 1125 solve specific problems (e.g., 1126 <a href=dpans6.htm#6.2.0970>CONVERT</a>). 1127 </UL> 1128 <P> 1129 1130 Because of the varied justifications for inclusion of these words, the 1131 Technical Committee does not encourage implementors to offer the 1132 complete collection, but to select those words deemed most valuable to 1133 their clientele. 1134 1135 <P> 1136 1137 <hr> 1138 <a name=A.6.2.0060>A.6.2.0060 #TIB</A> 1139 <P> 1140 1141 The function of #TIB has been superseded by 1142 <a href=dpans6.htm#6.1.2216>SOURCE</a>. 1143 1144 <P> 1145 1146 <hr> 1147 <a name=A.6.2.0200>A.6.2.0200 .(</A> 1148 <P> 1149 1150 Typical use: <code>.( ccc)</code> 1151 1152 <P> 1153 1154 <hr> 1155 <a name=A.6.2.0210>A.6.2.0210 .R</A> 1156 <P> 1157 1158 In .R, <B>R</B> is short for RIGHT. 1159 1160 <P> 1161 1162 <hr> 1163 <a name=A.6.2.0340>A.6.2.0340 2>R</A> 1164 <P> 1165 1166 Historically, 2>R has been used to implement 1167 <a href=dpans6.htm#6.1.1240>DO</a>. Hence the order of 1168 parameters on the return stack. 1169 1170 <P> 1171 1172 The primary advantage of 2>R is that it puts the top stack entry on the 1173 top of the return stack. For instance, a double-cell number may be 1174 transferred to the return stack and still have the most significant cell 1175 accessible on the top of the return stack. 1176 1177 <P> 1178 1179 <hr> 1180 <a name=A.6.2.0410>A.6.2.0410 2R></A> 1181 <P> 1182 1183 Note that 2R> is not equivalent to 1184 <a href=dpans6.htm#6.1.2060>R></a> R>. Instead, it mirrors the 1185 action of 1186 <a href=dpans6.htm#6.2.0340>2>R</a> 1187 (see <a href=dpansa6.htm#A.6.2.0340>A.6.2.0340</A>). 1188 1189 <P> 1190 1191 <hr> 1192 <a name=A.6.2.0455>A.6.2.0455 :NONAME</A> 1193 <P> 1194 1195 :NONAME allows a user to create an execution token with the semantics of 1196 a colon definition without an associated name. Previously, only 1197 <a href=dpans6.htm#6.1.0450>:</a> 1198 (colon) could create an execution token with these semantics. Thus, 1199 Forth code could only be compiled using the syntax of :, that is: 1200 1201 1202 <PRE> 1203 : NAME ... ; 1204 </PRE> 1205 1206 <P> 1207 1208 :NONAME removes this constraint and places the Forth compiler in the 1209 hands of the programmer. 1210 1211 <P> 1212 1213 :NONAME can be used to create application-specific programming 1214 languages. One technique is to mix Forth code fragments with 1215 application-specific constructs. The application-specific constructs 1216 use :NONAME to compile the Forth code and store the corresponding 1217 execution tokens in data structures. 1218 1219 <P> 1220 1221 The functionality of :NONAME can be built on any Forth system. For 1222 years, expert Forth programmers have exploited intimate knowledge of 1223 their systems to generate unnamed code fragments. Now, this function 1224 has been named and can be used in a portable program. 1225 1226 <P> 1227 1228 For example, :NONAME can be used to build a table of code fragments 1229 where indexing into the table allows executing a particular fragment. 1230 The declaration syntax of the table is: 1231 1232 <P> 1233 1234 1235 <PRE> 1236 :NONAME .. code for command 0 .. ; 0 CMD ! 1237 1238 :NONAME .. code for command 1 .. ; 1 CMD ! 1239 ... 1240 1241 :NONAME .. code for command 99 .. ; 99 CMD ! 1242 1243 ... 5 CMD @ EXECUTE ... 1244 1245 </PRE> 1246 <P> 1247 1248 The definitions of the table building words are: 1249 1250 <PRE> 1251 CREATE CMD-TABLE \ table for command execution tokens 1252 100 CELLS ALLOT 1253 1254 : CMD ( n -- a-addr ) \ nth element address in table 1255 CELLS CMD-TABLE + ; 1256 </PRE> 1257 1258 <P> 1259 1260 As a further example, a defining word can be created to allow 1261 performance monitoring. In the example below, the number of times a 1262 word is executed is counted. : must first be renamed to allow the 1263 definition of the new ;. 1264 1265 <P> 1266 1267 1268 <PRE> 1269 : DOCOLON ( -- ) \ Modify CREATEd word to execute like a colon def 1270 DOES> ( i*x a-addr -- j*x ) 1271 1 OVER +! \ count executions 1272 CELL+ @ EXECUTE \ execute :NONAME definition 1273 ; 1274 1275 : OLD: : ; \ just an alias 1276 1277 OLD: : ( "name" -- a-addr xt colon-sys ) 1278 \ begins an execution-counting colon definition 1279 CREATE HERE 0 , \ storage for execution counter 1280 0 , \ storage for execution token 1281 DOCOLON \ set run time for CREATEd word 1282 :NONAME \ begin unnamed colon definition 1283 ; 1284 </PRE> 1285 <P> 1286 1287 ( Note the placement of DOES>: DOES> must modify the CREATEd word and not 1288 the :NONAME definition, so DOES> must execute before :NONAME.) 1289 1290 <PRE> 1291 OLD: ; ( a-addr xt colon-sys -- ) 1292 \ ends an execution-counting colon definition ) 1293 POSTPONE ; \ complete compilation of colon def 1294 SWAP CELL+ ! \ save execution token 1295 ; IMMEDIATE 1296 </PRE> 1297 1298 <P> 1299 1300 The new : and ; are used just like the standard ones to define words: 1301 <P> 1302 1303 1304 <PRE> 1305 ... : xxx ... ; ... xxx ... 1306 </PRE> 1307 1308 Now however, these words may be <B>ticked</B> to retrieve the count (and 1309 execution token): 1310 1311 1312 <PRE> 1313 ... ' xxx >BODY ? ... 1314 </PRE> 1315 1316 <P> 1317 1318 <hr> 1319 <a name=A.6.2.0620>A.6.2.0620 ?DO</A> 1320 <P> 1321 1322 Typical use: 1323 1324 <code>: FACTORIAL ( +n1 -- +n2 ) 1 SWAP 1+ ?DO I * LOOP ;</code> 1325 1326 <P> 1327 1328 This word was added in response to many requests for a resolution of the 1329 difficulty introduced by Forth-83's DO, which on a 16-bit system will 1330 loop 65,535 times if given equal arguments. As this Standard also 1331 encourages 32-bit systems, this behavior can be intolerable. The 1332 Technical Committee considered applying these semantics to 1333 <a href=dpans6.htm#6.1.1240>DO</a>, but 1334 declined on the grounds that it might break existing code. 1335 1336 <P> 1337 1338 <hr> 1339 <a name=A.6.2.0700>A.6.2.0700 AGAIN</A> 1340 <P> 1341 1342 Typical use: <code>: X ... BEGIN ... AGAIN ... ;</code> 1343 1344 <P> 1345 1346 Unless word-sequence has a way to terminate, this is an endless loop. 1347 1348 <P> 1349 1350 <hr> 1351 <a name=A.6.2.0855>A.6.2.0855 C"</A> 1352 <P> 1353 1354 Typical use: <code>: X ... C" ccc" ... ;</code> 1355 1356 <P> 1357 1358 It is easy to convert counted strings to pointer/length but hard to do 1359 the opposite. C" is the only new word that uses the <B>address of 1360 counted string</B> stack representation. It is provided as an aid to 1361 porting existing programs to ANS Forth systems. It is relatively 1362 difficult to implement C" in terms of other standard words, considering 1363 its <B>compile string into the current definition</B> semantics. 1364 1365 <P> 1366 1367 Users of C" are encouraged to migrate their application code toward the 1368 consistent use of the preferred <B>c-addr u</B> stack representation 1369 with the alternate word 1370 <a href=dpans6.htm#6.1.2165>S"</a>. This may be accomplished by converting 1371 application words with counted string input arguments to use the 1372 preferred <B>c-addr u</B> representation, thus eliminating the need for 1373 C" . 1374 1375 <P> 1376 <code> 1377 See: 1378 <a href=dpansa3.htm#A.3.1.3.4>A.3.1.3.4</a> Counted strings 1379 </code> 1380 <P> 1381 1382 <hr> 1383 <a name=A.6.2.0873>A.6.2.0873 CASE</A> 1384 <P> 1385 1386 Typical use: 1387 1388 <PRE> 1389 : X ... 1390 CASE 1391 test1 OF ... ENDOF 1392 testn OF ... ENDOF 1393 ... ( default ) 1394 ENDCASE ... 1395 ; 1396 </PRE> 1397 1398 <P> 1399 1400 <hr> 1401 <a name=A.6.2.0945>A.6.2.0945 COMPILE,</A> 1402 <P> 1403 1404 COMPILE, is the compilation equivalent of 1405 <a href=dpans6.htm#6.1.1370>EXECUTE</a>. In many cases, it is 1406 possible to compile a word by using 1407 <a href=dpans6.htm#6.1.2033>POSTPONE</a> without resorting to the 1408 use of COMPILE,. However, the use of POSTPONE requires that the name of 1409 the word must be known at compile time, whereas COMPILE, allows the word 1410 to be located at any time. It is sometime possible to use 1411 <a href=dpans6.htm#6.1.1360>EVALUATE</a> to 1412 compile a word whose name is not known until run time. This has two 1413 possible problems: 1414 1415 <UL> 1416 <LI>EVALUATE is slower than COMPILE, because a dictionary search is 1417 required. 1418 <LI>The current search order affects the outcome of EVALUATE. 1419 </UL> 1420 <P> 1421 1422 In traditional threaded-code implementations, compilation is performed 1423 by 1424 <a href=dpans6.htm#6.1.0150>,</a> (comma). 1425 This usage is not portable; it doesn't work for 1426 subroutine-threaded, native code, or relocatable implementations. Use 1427 of COMPILE, is portable. 1428 1429 <P> 1430 1431 In most systems it is possible to implement COMPILE, so it will generate 1432 code that is optimized to the same extent as code that is generated by 1433 the normal compilation process. However, in some implementations there 1434 are two different <B>tokens</B> corresponding to a particular definition 1435 name: the normal <B>execution token</B> that is used while interpreting 1436 or with EXECUTE, and another <B>compilation token</B> that is used while 1437 compiling. It is not always possible to obtain the compilation token 1438 from the execution token. In these implementations, COMPILE, might not 1439 generate code that is as efficient as normally compiled code. 1440 1441 <P> 1442 1443 <hr> 1444 <a name=A.6.2.0970>A.6.2.0970 CONVERT</A> 1445 <P> 1446 1447 CONVERT may be defined as follows: 1448 1449 1450 <PRE> 1451 : CONVERT CHAR+ 65535 >NUMBER DROP ; 1452 </PRE> 1453 1454 <P> 1455 1456 <hr> 1457 <a name=A.6.2.1342>A.6.2.1342 ENDCASE</A> 1458 <P> 1459 1460 Typical use: 1461 1462 <PRE> 1463 : X ... 1464 CASE 1465 test1 OF ... ENDOF 1466 testn OF ... ENDOF 1467 ... ( default ) 1468 ENDCASE ... 1469 ; 1470 </PRE> 1471 1472 <P> 1473 1474 <hr> 1475 <a name=A.6.2.1343>A.6.2.1343 ENDOF</A> 1476 <P> 1477 1478 Typical use: 1479 1480 <PRE> 1481 : X ... 1482 CASE 1483 test1 OF ... ENDOF 1484 testn OF ... ENDOF 1485 ... ( default ) 1486 ENDCASE ... 1487 ; 1488 </PRE> 1489 1490 <P> 1491 1492 <hr> 1493 <a name=A.6.2.1390>A.6.2.1390 EXPECT</A> 1494 <P> 1495 1496 Specification of positive integer counts (+n) for EXPECT allows some 1497 implementors to continue their practice of using a zero or negative 1498 value as a flag to trigger special behavior. Insofar as such behavior 1499 is outside the Standard, Standard Programs cannot depend upon it, but 1500 the Technical Committee doesn't wish to preclude it unnecessarily. 1501 Since actual values are almost always small integers, no functionality 1502 is impaired by this restriction. 1503 1504 <P> 1505 1506 <hr> 1507 <a name=A.6.2.1850>A.6.2.1850 MARKER</A> 1508 <P> 1509 1510 As dictionary implementations have gotten more elaborate and in some 1511 cases have used multiple address spaces, 1512 <a href=dpans15.htm#15.6.2.1580>FORGET</a> has become prohibitively 1513 difficult or impossible to implement on many Forth systems. MARKER 1514 greatly eases the problem by making it possible for the system to 1515 remember <B>landmark information</B> in advance that specifically marks 1516 the spots where the dictionary may at some future time have to be 1517 rearranged. 1518 1519 <P> 1520 1521 <hr> 1522 <a name=A.6.2.1950>A.6.2.1950 OF</a> 1523 <P> 1524 1525 Typical use: 1526 1527 <PRE> 1528 : X ... 1529 CASE 1530 test1 OF ... ENDOF 1531 testn OF ... ENDOF 1532 ... ( default ) 1533 ENDCASE ... 1534 ; 1535 </PRE> 1536 1537 <P> 1538 1539 <hr> 1540 <a name=A.6.2.2000>A.6.2.2000 PAD</A> 1541 <P> 1542 1543 PAD has been available as scratch storage for strings since the earliest 1544 Forth implementations. It was brought to our attention that many 1545 programmers are reluctant to use PAD, fearing incompatibilities with 1546 system uses. PAD is specifically intended as a programmer convenience, 1547 however, which is why we documented the fact that no standard words use 1548 it. 1549 1550 <P> 1551 1552 <hr> 1553 <a name=A.6.2.2008>A.6.2.2008 PARSE</A> 1554 <P> 1555 1556 Typical use: <code>char PARSE ccc<char></code> 1557 1558 <P> 1559 1560 The traditional Forth word for parsing is 1561 <a href=dpans6.htm#6.1.2450>WORD</a>. PARSE solves the 1562 following problems with WORD: 1563 1564 <P> 1565 1566 a) WORD always skips leading delimiters. This behavior is appropriate 1567 for use by the text interpreter, which looks for sequences of non-blank 1568 characters, but is inappropriate for use by words like ( , .( , and ." . 1569 Consider the following (flawed) definition of .( : 1570 1571 1572 <PRE> 1573 : .( [CHAR] ) WORD COUNT TYPE ; IMMEDIATE 1574 </PRE> 1575 1576 <P> 1577 1578 This works fine when used in a line like: 1579 1580 1581 <PRE> 1582 .( HELLO) 5 . 1583 </PRE> 1584 1585 <P> 1586 1587 but consider what happens if the user enters an empty string: 1588 1589 1590 <PRE> 1591 .( ) 5 . 1592 </PRE> 1593 1594 <P> 1595 1596 The definition of .( shown above would treat the ) as a leading 1597 delimiter, skip it, and continue consuming characters until it located 1598 another ) that followed a non-) character, or until the parse area was 1599 empty. In the example shown, the 5 . would be treated as part of the 1600 string to be printed. 1601 1602 <P> 1603 1604 With PARSE, we could write a correct definition of .( : 1605 1606 1607 <PRE> 1608 : .( [CHAR] ) PARSE TYPE ; IMMEDIATE 1609 </PRE> 1610 1611 <P> 1612 1613 This definition avoids the <B>empty string</B> anomaly. 1614 1615 <P> 1616 1617 b) WORD returns its result as a counted string. This has four bad 1618 effects: 1619 1620 <P> 1621 1622 1) The characters accepted by WORD must be copied from the input buffer 1623 into a temporary buffer, in order to make room for the count character that 1624 must be at the beginning of the counted string. The copy step is inefficient, 1625 compared to PARSE, which leaves the string in the input buffer and doesn't 1626 need to copy it anywhere. 1627 1628 <P> 1629 1630 2) WORD must be careful not to store too many characters into the 1631 temporary buffer, thus overwriting something beyond the end of the buffer. 1632 This adds to the overhead of the copy step. (WORD may have to scan a lot of 1633 characters before finding the trailing delimiter.) 1634 1635 <P> 1636 1637 3) The count character limits the length of the string returned by WORD 1638 to 255 characters (longer strings can easily be stored in blocks!). This 1639 limitation does not exist for PARSE. 1640 1641 <P> 1642 1643 4) The temporary buffer is typically overwritten by the next use of WORD. 1644 This introduces a temporal dependency; the value returned by WORD is only 1645 valid for a limited duration. PARSE has a temporal dependency, too, related 1646 to the lifetime of the input buffer, but that is less severe in most cases 1647 than WORD's temporal dependency. 1648 1649 <P> 1650 1651 The behavior of WORD with respect to skipping leading delimiters is 1652 useful for parsing blank-delimited names. Many system implementations 1653 include an additional word for this purpose, similar to PARSE with 1654 respect to the <B>c-addr u</B> return value, but without an explicit 1655 delimiter argument (the delimiter set is implicitly <B>white space</B>), 1656 and which does skip leading delimiters. A common description for this 1657 word is: 1658 1659 1660 <PRE> 1661 PARSE-WORD ( <spaces>name -- c-addr u ) 1662 </PRE> 1663 1664 <P> 1665 1666 Skip leading spaces and parse name delimited by a space. c-addr is the 1667 address within the input buffer and u is the length of the selected string. 1668 If the parse area is empty, the resulting string has a zero length. 1669 1670 <P> 1671 1672 If both PARSE and PARSE-WORD are present, the need for WORD is largely 1673 eliminated. 1674 1675 <P> 1676 1677 <hr> 1678 <a name=A.6.2.2030>A.6.2.2030 PICK</A> 1679 <P> 1680 1681 0 PICK is equivalent to 1682 <a href=dpans6.htm#6.1.1290>DUP</a> and 1 PICK is equivalent to 1683 <a href=dpans6.htm#6.1.1990>OVER</a>. 1684 1685 <P> 1686 1687 <hr> 1688 <a name=A.6.2.2040>A.6.2.2040 QUERY</A> 1689 <P> 1690 1691 The function of QUERY may be performed with 1692 <a href=dpans6.htm#6.1.0695>ACCEPT</a> and 1693 <a href=dpans6.htm#6.1.1360>EVALUATE</a>. 1694 1695 <P> 1696 1697 <hr> 1698 <a name=A.6.2.2125>A.6.2.2125 REFILL</A> 1699 <P> 1700 1701 This word is a useful generalization of 1702 <a href=dpans6.htm#6.2.2040>QUERY</a>. Re-defining QUERY to 1703 meet this specification would have broken existing code. REFILL is 1704 designed to behave reasonably for all possible input sources. If the 1705 input source is coming from the user, as with QUERY, REFILL could still 1706 return a false value if, for instance, a communication channel closes so 1707 that the system knows that no more input will be available. 1708 1709 <P> 1710 1711 <hr> 1712 <a name=A.6.2.2150>A.6.2.2150 ROLL</A> 1713 <P> 1714 1715 2 ROLL is equivalent to 1716 <a href=dpans6.htm#6.1.2160>ROT</a>, 1717 1 ROLL is equivalent to 1718 <a href=dpans6.htm#6.1.2260>SWAP</a> and 0 ROLL is 1719 a null operation. 1720 1721 <P> 1722 1723 <hr> 1724 <a name=A.6.2.2182>A.6.2.2182 SAVE-INPUT</A> 1725 <P> 1726 1727 SAVE-INPUT and 1728 <a href=dpans6.htm#6.2.2148>RESTORE-INPUT</a> 1729 allow the same degree of input source 1730 repositioning within a text file as is available with 1731 <a href=dpans7.htm#7.6.1.0800>BLOCK</a> input. 1732 SAVE-INPUT and RESTORE-INPUT <B>hide the details</B> of the operations 1733 necessary to accomplish this repositioning, and are used the same way 1734 with all input sources. This makes it easier for programs to reposition 1735 the input source, because they do not have to inspect several variables 1736 and take different action depending on the values of those variables. 1737 1738 <P> 1739 1740 SAVE-INPUT and RESTORE-INPUT are intended for repositioning within a 1741 single input source; for example, the following scenario is NOT allowed 1742 for a Standard Program: 1743 1744 <PRE> 1745 : XX 1746 SAVE-INPUT CREATE 1747 S" RESTORE-INPUT" EVALUATE 1748 ABORT" couldn't restore input" 1749 ; 1750 </PRE> 1751 1752 <P> 1753 1754 This is incorrect because, at the time RESTORE-INPUT is executed, the 1755 input source is the string via 1756 <a href=dpans6.htm#6.1.1360>EVALUATE</a>, which is not the same input 1757 source that was in effect when SAVE-INPUT was executed. 1758 1759 <P> 1760 1761 The following code is allowed: 1762 1763 1764 <PRE> 1765 : XX 1766 SAVE-INPUT CREATE 1767 S" .( Hello)" EVALUATE 1768 RESTORE-INPUT ABORT" couldn't restore input" 1769 ; 1770 </PRE> 1771 1772 <P> 1773 1774 After EVALUATE returns, the input source specification is restored to 1775 its previous state, thus SAVE-INPUT and RESTORE-INPUT are called with 1776 the same input source in effect. 1777 1778 <P> 1779 1780 In the above examples, the EVALUATE phrase could have been replaced by a 1781 phrase involving 1782 <a href=dpans11.htm#11.6.1.1717>INCLUDE-FILE</a> 1783 and the same rules would apply. 1784 1785 <P> 1786 1787 The Standard does not specify what happens if a program violates the 1788 above rules. A Standard System might check for the violation and return 1789 an exception indication from RESTORE-INPUT, or it might fail in an 1790 unpredictable way. 1791 1792 <P> 1793 1794 The return value from RESTORE-INPUT is primarily intended to report the 1795 case where the program attempts to restore the position of an input 1796 source whose position cannot be restored. The keyboard might be such an 1797 input source. 1798 1799 <P> 1800 1801 Nesting of SAVE-INPUT and RESTORE-INPUT is allowed. For example, the 1802 following situation works as expected: 1803 1804 <PRE> 1805 : XX 1806 SAVE-INPUT 1807 S" f1" INCLUDED \ The file "f1" includes: 1808 \ ... SAVE-INPUT ... RESTORE-INPUT ... 1809 \ End of file "f1" 1810 RESTORE-INPUT ABORT" couldn't restore input" 1811 ; 1812 </PRE> 1813 1814 <P> 1815 1816 In principle, RESTORE-INPUT could be implemented to <B>always fail</B>, e.g.: 1817 1818 <PRE> 1819 : RESTORE-INPUT ( x1 ... xn n -- flag ) 1820 0 ?DO DROP LOOP TRUE 1821 ; 1822 </PRE> 1823 1824 <P> 1825 1826 Such an implementation would not be useful in most cases. It would be 1827 preferable for a system to leave SAVE-INPUT and RESTORE-INPUT undefined, 1828 rather than to create a useless implementation. In the absence of the 1829 words, the application programmer could choose whether or not to create 1830 <B>dummy</B> implementations or to work-around the problem in some other 1831 way. 1832 1833 <P> 1834 1835 Examples of how an implementation might use the return values from 1836 SAVE-INPUT to accomplish the save/restore function: 1837 1838 <P> 1839 1840 1841 <PRE> 1842 Input Source possible stack values 1843 ------------ --------------------- 1844 block >IN @ BLK @ 2 1845 EVALUATE >IN @ 1 1846 keyboard >IN @ 1 1847 text file >IN @ lo-pos hi-pos 3 1848 </PRE> 1849 1850 <P> 1851 1852 These are examples only; a Standard Program may not assume any particular 1853 meaning for the individual stack items returned by SAVE-INPUT. 1854 1855 <P> 1856 1857 <hr> 1858 <a name=A.6.2.2290>A.6.2.2290 TIB</A> 1859 <P> 1860 1861 The function of TIB has been superseded by 1862 <a href=dpans6.htm#6.1.2216>SOURCE</a>. 1863 1864 <P> 1865 1866 <hr> 1867 <a name=A.6.2.2295>A.6.2.2295 TO</A> 1868 <P> 1869 1870 Historically, some implementations of TO have not explicitly parsed. 1871 Instead, they set a mode flag that is tested by the subsequent execution 1872 of name. ANS Forth explicitly requires that TO must parse, so that TO's 1873 effect will be predictable when it is used at the end of the parse area. 1874 1875 <P> 1876 1877 Typical use: <code>x TO name</code> 1878 1879 <P> 1880 1881 <hr> 1882 <a name=A.6.2.2298>A.6.2.2298 TRUE</A> 1883 <P> 1884 1885 TRUE is equivalent to the phrase <code>0 0=</code>. 1886 1887 <P> 1888 1889 <hr> 1890 <a name=A.6.2.2405>A.6.2.2405 VALUE</A> 1891 <P> 1892 1893 Typical use: 1894 1895 <PRE> 1896 0 VALUE DATA 1897 1898 : EXCHANGE ( n1 -- n2 ) DATA SWAP TO DATA ; 1899 </PRE> 1900 1901 <P> 1902 1903 EXCHANGE leaves n1 in DATA and returns the prior value n2. 1904 1905 <P> 1906 1907 <hr> 1908 <a name=A.6.2.2440>A.6.2.2440 WITHIN</A> 1909 <P> 1910 1911 We describe WITHIN without mentioning circular number spaces (an 1912 undefined term) or providing the code. Here is a number line with the 1913 overflow point (o) at the far right and the underflow point (u) at the 1914 far left: 1915 1916 <PRE> 1917 u--------------------------------------------------------------o 1918 </PRE> 1919 1920 <P> 1921 1922 There are two cases to consider: either the n2|u2..n3|u3 range straddles 1923 the overflow/underflow points or it does not. Lets examine the 1924 non-straddle case first: 1925 1926 <PRE> 1927 u-------------------[.....................)------------------------o 1928 </PRE> 1929 1930 <P> 1931 1932 The [ denotes n2|u2, the ) denotes n3|u3, and the dots and [ are numbers 1933 WITHIN the range. n3|u3 is greater than n2|u2, so the following tests 1934 will determine if n1|u1 is WITHIN n2|u2 and n3|u3: 1935 1936 <p> 1937 <pre> 1938 n2|u2 < n1|u1 and n1|u1 < n3|u3. 1939 </pre> 1940 <P> 1941 1942 In the case where the comparison range straddles the overflow/underflow 1943 points: 1944 <P> 1945 1946 u...............)-----------------------------[........................o 1947 1948 <p> 1949 1950 n3|u3 is less than n2|u2 and the following tests will determine if n1|u1 is 1951 WITHIN n2|u2 and n3|u3: 1952 1953 <P> 1954 <pre> 1955 n2|u2 > n1|u1 and n1|u1 > n3|u3. 1956 </pre> 1957 <P> 1958 1959 1960 WITHIN must work for both signed and unsigned arguments. One obvious 1961 implementation does not work: 1962 1963 <PRE> 1964 : WITHIN ( test low high -- flag ) 1965 >R OVER < 0= ( test flag1 ) 1966 SWAP R> < ( flag1 flag2 ) 1967 AND 1968 ; 1969 </PRE> 1970 1971 <P> 1972 1973 Assume two's-complement arithmetic on a 16-bit machine, and consider the 1974 following test: 1975 1976 1977 <PRE> 1978 33000 32000 34000 WITHIN 1979 </PRE> 1980 1981 <P> 1982 1983 The above implementation returns false for that test, even though the 1984 unsigned number 33000 is clearly within the range {{32000 .. 34000}}. 1985 1986 <P> 1987 1988 The problem is that, in the incorrect implementation, the signed 1989 comparison 1990 < gives the wrong answer when 32000 is compared to 33000, 1991 because when those numbers are treated as signed numbers, 33000 is 1992 treated as negative 32536, while 32000 remains positive. 1993 1994 <P> 1995 1996 Replacing < with 1997 <a href=dpans6.htm#6.1.2340>U<</a> 1998 in the above implementation makes it work with 1999 unsigned numbers, but causes problems with certain signed number ranges; 2000 in particular, the test: 2001 2002 2003 <PRE> 2004 1 -5 5 WITHIN 2005 </PRE> 2006 2007 <P> 2008 2009 would give an incorrect answer. 2010 2011 <P> 2012 2013 For two's-complement machines that ignore arithmetic overflow (most 2014 machines), the following implementation works in all cases: 2015 2016 <PRE> 2017 : WITHIN ( test low high -- flag ) OVER - >R - R> U< ; 2018 2019 </PRE> 2020 <P> 2021 2022 <hr> 2023 <a name=A.6.2.2530>A.6.2.2530 [COMPILE]</A> 2024 <P> 2025 2026 Typical use: <code>: name2 ... [COMPILE] name1 ... ; IMMEDIATE</code> 2027 2028 <P> 2029 2030 <hr> 2031 <a name=A.6.2.2535>A.6.2.2535 \</A> 2032 <P> 2033 2034 Typical use: <code>5 CONSTANT THAT \ THIS IS A COMMENT ABOUT THAT</code> 2035 2036 <P> 2037 2038 <hr> 2039 <a href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 2040 <BR> 2041 <a href=dpansa7.htm><IMG src="right.gif" ></A> 2042 Next Section 2043 <P> 2044 </BODY> 2045 </HTML>