DPANS13.HTM (14521B)
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=dpans12.htm><img src=left.gif 12 width=26 height=26 align=ALIGN border=0></a> 13 <a href=dpans14.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=13.>Table of Contents</a> 20 </td> 21 </tr> 22 </table> 23 <p> 24 <hr size=4> 25 26 <H1>13. The optional Locals word set</H1> 27 28 29 <hr> 30 <A name=13.1> 31 <H2>13.1 Introduction</H2> 32 </a> 33 34 <p> 35 <code> 36 See: 37 <A href=dpansa13.htm>Annex A.13</a> The Locals Word Set 38 </code> 39 <P> 40 41 <hr> 42 <A name=13.2> 43 <H2>13.2 Additional terms and notation</H2> 44 </a> 45 46 None. 47 <P> 48 49 <hr> 50 <A name=13.3> 51 <H2>13.3 Additional usage requirements</H2> 52 </a> 53 54 <p> 55 <code> 56 See: 57 <A href=dpansa13.htm#A.13.3>A.13.3</a> Additional usage requirements 58 </code> 59 <P> 60 61 <hr> 62 <A name=13.3.1> 63 <H3>13.3.1 Locals</H3> 64 </a> 65 66 A local is a data object whose execution semantics shall return its 67 value, whose scope shall be limited to the definition in which it is 68 declared, and whose use in a definition shall not preclude reentrancy or 69 recursion. 70 71 <P> 72 73 <hr> 74 <A name=13.3.2> 75 <H3>13.3.2 Environmental queries</H3> 76 </a> 77 78 Append table 13.1 to table 3.5. 79 <P> 80 81 <code> 82 See: 83 <A href=dpans3.htm#3.2.6>3.2.6</a> Environmental queries 84 </code> 85 86 <P> 87 88 Table 13.1 - Environmental query strings 89 <P> 90 91 92 93 <PRE> 94 String Value data type Constant? Meaning 95 ------ --------------- --------- ------- 96 #LOCALS n yes maximum number of local variables in a definition 97 LOCALS flag no locals word set present 98 LOCALS-EXT flag no locals extensions word set present 99 </PRE> 100 101 102 <P> 103 104 <hr> 105 <A name=13.3.3> 106 <H3>13.3.3 Processing locals</H3> 107 </a> 108 109 To support the locals word set, a system shall provide a mechanism to 110 receive the messages defined by 111 <a href=dpans13.htm#13.6.1.0086>(LOCAL)</a> 112 and respond as described here. 113 114 <P> 115 116 During the compilation of a definition after : 117 (<a href=dpans6.htm#6.1.0450>colon</a>), 118 <a href=dpans6.htm#6.2.0455>:NONAME</a>, or 119 <a href=dpans6.htm#6.1.1250>DOES></a>, 120 a program may begin sending local identifier messages to the 121 system. The process shall begin when the first message is sent. The 122 process shall end when the <B>last local</B> message is sent. The 123 system shall keep track of the names, order, and number of identifiers 124 contained in the complete sequence. 125 126 <P> 127 128 <hr> 129 <A name=13.3.3.1> 130 <H4>13.3.3.1 Compilation semantics</H4> 131 </a> 132 133 The system, upon receipt of a sequence of local-identifier messages, 134 shall take the following actions at compile time: 135 136 <P> 137 138 a) Create temporary dictionary entries for each of the identifiers 139 passed to 140 <a href=dpans13.htm#13.6.1.0086>(LOCAL)</a>, 141 such that each identifier will behave as a local. 142 These temporary dictionary entries shall vanish at the end of the 143 definition, denoted by ; 144 (<a href=dpans6.htm#6.1.0460>semicolon</a>), 145 <a href=dpans15.htm#15.6.2.0470>;CODE</a>, or 146 <a href=dpans6.htm#6.1.1250>DOES></a>. The system need 147 not maintain these identifiers in the same way it does other dictionary 148 entries as long as they can be found by normal dictionary searching 149 processes. Furthermore, if the Search-Order word set is present, local 150 identifiers shall always be searched before any of the word lists in any 151 definable search order, and none of the Search-Order words shall change 152 the locals' privileged position in the search order. Local identifiers 153 may reside in mass storage. 154 155 <P> 156 157 b) For each identifier passed to (LOCAL), the system shall generate an 158 appropriate code sequence that does the following at execution time: 159 160 <P> 161 162 <OL> 163 <LI>Allocate a storage resource adequate to contain the value of a local. 164 The storage shall be allocated in a way that does not preclude 165 re-entrancy or recursion in the definition using the local. 166 <LI>Initialize the value using the top item on the data stack. If more 167 than one local is declared, the top item on the stack shall be moved 168 into the first local identified, the next item shall be moved into the 169 second, and so on. 170 </ol> 171 172 The storage resource may be the return stack or may be implemented in 173 other ways, such as in registers. The storage resource shall not be 174 the data stack. Use of locals shall not restrict use of the data 175 stack before or after the point of declaration. 176 <p> 177 178 c) Arrange that any of the legitimate methods of terminating execution 179 of a definition, specifically ; (semicolon), ;CODE, DOES> or 180 <a href=dpans6.htm#6.1.1380>EXIT</a>, will 181 release the storage resource allocated for the locals, if any, declared 182 in that definition. 183 <a href=dpans6.htm#6.1.0670>ABORT</a> 184 shall release all local storage resources, 185 and 186 <a href=dpans9.htm#9.6.1.0875>CATCH</a> / 187 <a href=dpans9.htm#9.6.1.2275>THROW</a> 188 (if implemented) shall release such resources for all 189 definitions whose execution is being terminated. 190 191 <P> 192 193 d) Separate sets of locals may be declared in defining words before 194 DOES> for use by the defining word, and after DOES> for use by the word 195 defined. 196 197 <P> 198 199 A system implementing the Locals word set shall support the declaration 200 of at least eight locals in a definition. 201 202 <P> 203 204 <hr> 205 <A name=13.3.3.2> 206 <H4>13.3.3.2 Syntax restrictions</H4> 207 </a> 208 209 Immediate words in a program may use 210 <a href=dpans13.htm#13.6.1.0086>(LOCAL)</a> to implement syntaxes for 211 local declarations with the following restrictions: 212 213 <P> 214 215 a) A program shall not compile any executable code into the current 216 definition between the time (LOCAL) is executed to identify the first 217 local for that definition and the time of sending the single required 218 <B>last local</B> message; 219 220 <P> 221 222 b) The position in program source at which the sequence of (LOCAL) 223 messages is sent, referred to here as the point at which locals are 224 declared, shall not lie within the scope of any control structure; 225 226 <P> 227 228 c) Locals shall not be declared until values previously placed on the 229 return stack within the definition have been removed; 230 231 <P> 232 233 d) After a definition's locals have been declared, a program may place 234 data on the return stack. However, if this is done, locals shall not be 235 accessed until those values have been removed from the return stack; 236 237 <P> 238 239 e) Words that return execution tokens, such as ' 240 (<a href=dpans6.htm#6.1.0070>tick</a>), 241 <a href=dpans6.htm#6.1.2510>[']</a>, or 242 <a href=dpans6.htm#6.1.1550>FIND</a>, 243 shall not be used with local names; 244 245 <P> 246 247 f) A program that declares more than eight locals in a single definition 248 has an environmental dependency; 249 250 <P> 251 252 g) Locals may be accessed or updated within control structures, 253 including do-loops; 254 255 <P> 256 257 h) Local names shall not be referenced by 258 <a href=dpans6.htm#6.1.2033>POSTPONE</a> and 259 <a href=dpans6.htm#6.2.2530>[COMPILE]</a>. 260 <P> 261 262 <code> 263 See: 264 <A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter 265 </code> 266 267 <P> 268 269 <hr> 270 <A name=13.4> 271 <H2>13.4 Additional documentation requirements</H2> 272 </a> 273 274 275 <hr> 276 <A name=13.4.1> 277 <H3>13.4.1 System documentation</H3> 278 </a> 279 280 281 <hr> 282 <A name=13.4.1.1> 283 <H4>13.4.1.1 Implementation-defined options</H4> 284 </a> 285 286 <UL> 287 <LI>maximum number of locals in a definition 288 (<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals, 289 <a href=dpans13.htm#13.6.2.1795>13.6.2.1795</a> LOCALS|). 290 </UL> 291 292 <P> 293 294 <hr> 295 <A name=13.4.1.2> 296 <H4>13.4.1.2 Ambiguous conditions</H4> 297 </a> 298 299 <UL> 300 <LI>executing a named local while in interpretation state 301 (<a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a> 302 (LOCAL)); 303 <LI>name not defined by 304 <a href=dpans6.htm#6.2.2405>VALUE</a> or 305 LOCAL 306 (<a href=dpans13.htm#13.6.1.2295>13.6.1.2295</a> TO). 307 </ul> 308 309 <hr> 310 <A name=13.4.1.3> 311 <h4>13.4.1.3 Other system documentation</h4> 312 </a> 313 <ul> 314 <LI>no additional requirements. 315 </UL> 316 <P> 317 318 <hr> 319 <A name=13.4.2> 320 <H3>13.4.2 Program documentation</H3> 321 </a> 322 323 324 <hr> 325 <A name=13.4.2.1> 326 <H4>13.4.2.1 Environmental dependencies</H4> 327 </a> 328 329 <UL> 330 <LI>declaring more than eight locals in a single definition 331 (<a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals). 332 </UL> 333 334 <P> 335 336 <hr> 337 <A name=13.4.2.2> 338 <H4>13.4.2.2 Other program documentation</H4> 339 </a> 340 341 <UL> 342 <LI>no additional requirements. 343 </UL> 344 345 <P> 346 347 <hr> 348 <A name=13.5> 349 <H2>13.5 Compliance and labeling</H2> 350 </a> 351 352 353 <hr> 354 <A name=13.5.1> 355 <H3>13.5.1 ANS Forth systems</H3> 356 </a> 357 358 The phrase <B>Providing the Locals word set</B> shall be appended to the 359 label of any Standard System that provides all of the Locals word set. 360 361 <P> 362 363 The phrase <B>Providing name(s) from the Locals Extensions word set</B> 364 shall be appended to the label of any Standard System that provides 365 portions of the Locals Extensions word set. 366 367 <P> 368 369 The phrase <B>Providing the Locals Extensions word set</B> shall be 370 appended to the label of any Standard System that provides all of the 371 Locals and Locals Extensions word sets. 372 373 <P> 374 375 <hr> 376 <A name=13.5.2> 377 <H3>13.5.2 ANS Forth programs</H3> 378 </a> 379 380 The phrase <B>Requiring the Locals word set</B> shall be appended to the 381 label of Standard Programs that require the system to provide the Locals 382 word set. 383 384 <P> 385 386 The phrase <B>Requiring name(s) from the Locals Extensions word set</B> 387 shall be appended to the label of Standard Programs that require the 388 system to provide portions of the Locals Extensions word set. 389 390 <P> 391 392 The phrase <B>Requiring the Locals Extensions word set</B> shall be 393 appended to the label of Standard Programs that require the system to 394 provide all of the Locals and Locals Extensions word sets. 395 396 <P> 397 398 <hr> 399 <A name=13.6> 400 <H2>13.6 Glossary</H2> 401 </a> 402 403 404 <hr> 405 <A name=13.6.1> 406 <H3>13.6.1 Locals words</H3> 407 </a> 408 409 410 <hr> 411 <A name=13.6.1.0086> 412 <code> 413 13.6.1.0086 <b>(LOCAL)</b> 414 </code> 415 </a> 416 <BR> 417 <B>paren-local-paren</B> LOCAL 418 <p> 419 <pre> 420 Interpretation: Interpretation semantics for this word are undefined. 421 </pre> 422 <P> 423 <pre> 424 Execution: ( c-addr u -- ) 425 </pre> 426 <P> 427 428 When executed during compilation, (LOCAL) passes a message to the system 429 that has one of two meanings. If u is non-zero, the message identifies 430 a new local whose definition name is given by the string of characters 431 identified by c-addr u. If u is zero, the message is <B>last local</B> 432 and c-addr has no significance. 433 434 <P> 435 436 The result of executing (LOCAL) during compilation of a definition is to 437 create a set of named local identifiers, each of which is a definition 438 name, that only have execution semantics within the scope of that 439 definition's source. 440 441 <PRE> 442 <i>local</i> Execution: ( -- x ) 443 </PRE> 444 <P> 445 446 Push the local's value, x, onto the stack. The local's value is 447 initialized as described in 448 <a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals and may be changed 449 by preceding the local's name with 450 <a href=dpans13.htm#13.6.1.2295>TO</a>. An ambiguous condition exists 451 when local is executed while in interpretation state. 452 <p> 453 454 <b>Note:</b> This word does not have special compilation semantics in 455 the 456 usual sense because it provides access to a system capability for use 457 by other user-defined words that do have them. However, the locals 458 facility as a whole and the sequence of messages passed defines 459 specific usage rules with semantic implications that are described in 460 detail in section 461 <a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals. 462 463 <P> 464 465 <b>Note:</b> This word is not intended for direct use in a definition to 466 declare that definition's locals. It is instead used by system or 467 user compiling words. These compiling words in turn define their own 468 syntax, and may be used directly in definitions to declare locals. In 469 this context, the syntax for (LOCAL) is defined in terms of a sequence 470 of compile-time messages and is described in detail in section 471 <a href=dpans13.htm#13.3.3>13.3.3</a> Processing locals. 472 473 <P> 474 475 <b>Note:</b> The Locals word set modifies the syntax and semantics of 476 <a href=dpans6.htm#6.2.2295>6.2.2295</a> TO 477 as defined in the Core Extensions word set. 478 479 <P> 480 481 <code> 482 See: 483 <A href=dpans3.htm#3.4>3.4</a> The Forth text interpreter 484 </code> 485 486 <P> 487 488 <hr> 489 <A name=13.6.1.2295> 490 <code> 491 13.6.1.2295 <b>TO</b> 492 </code> 493 </a> 494 <BR> 495 LOCAL 496 <BR> 497 <P> 498 499 Extend the semantics of 500 <a href=dpans6.htm#6.2.2295>6.2.2295</a> TO to be: 501 <P> 502 503 504 <PRE> 505 Interpretation: ( x <B>"<spaces>name"</B> -- ) 506 </PRE> 507 <P> 508 509 Skip leading spaces and parse name delimited by a space. Store x in 510 name. An ambiguous condition exists if name was not defined by 511 <a href=dpans6.htm#6.2.2405>VALUE</a>. 512 513 514 <PRE> 515 Compilation: ( <B>"<spaces>name"</B> -- ) 516 </PRE> 517 <P> 518 519 Skip leading spaces and parse name delimited by a space. Append the 520 run-time semantics given below to the current definition. An ambiguous 521 condition exists if name was not defined by either VALUE or 522 <a href=dpans13.htm#13.6.1.0086>(LOCAL)</a>. 523 524 525 <PRE> 526 Run-time: ( x -- ) 527 </PRE> 528 <P> 529 530 Store x in name. 531 532 <P> 533 534 <b>Note:</b> An ambiguous condition exists if either 535 <a href=dpans6.htm#6.1.2033>POSTPONE</a> or 536 <a href=dpans6.htm#6.2.2530>[COMPILE]</a> 537 is applied to TO. 538 539 540 <P> 541 542 <code> 543 See: 544 <A href=dpans3.htm#3.4.1>3.4.1</a> Parsing, 545 <a href=dpansa13.htm#A.13.6.1.2295>A.13.6.1.2295 TO</a> 546 </code> 547 548 <P> 549 550 <hr> 551 <A name=13.6.2> 552 <H3>13.6.2 Locals extension words</H3> 553 </a> 554 555 556 <hr> 557 <A name=13.6.2.1795> 558 <code> 559 13.6.2.1795 <b>LOCALS|</b> 560 </code> 561 </a> 562 <BR> 563 <B>locals-bar</B> LOCAL EXT 564 <p> 565 <pre> 566 Interpretation: Interpretation semantics for this word are undefined. 567 </pre> 568 <P> 569 <pre> 570 Compilation: ( <B>"<spaces>name1"</B> <B>"<spaces>name2"</B> ... <B>"<spaces>namen"</B> <B>|</B> -- ) 571 </pre> 572 <P> 573 574 Create up to eight local identifiers by repeatedly skipping leading 575 spaces, parsing name, and executing 576 <a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a> (LOCAL). The list of 577 locals to be defined is terminated by |. Append the run-time semantics 578 given below to the current definition. 579 580 <PRE> 581 Run-time: ( xn ... x2 x1 -- ) 582 </PRE> 583 <P> 584 585 Initialize up to eight local identifiers as described in 586 <a href=dpans13.htm#13.6.1.0086>13.6.1.0086</a> (LOCAL), 587 each of which takes as its initial value the top stack item, 588 removing it from the stack. Identifier name1 is initialized with x1, 589 identifier name2 with x2, etc. When invoked, each local will return its 590 value. The value of a local may be changed using 591 <a href=dpans13.htm#13.6.1.2295>13.6.1.2295</a> TO. 592 593 <p> 594 <code> 595 See: 596 <A href=dpansa13.htm#A.13.6.2.1795>A.13.6.2.1795 LOCALS|</a> 597 </code> 598 <P> 599 600 601 <hr> 602 <A href=dpans.htm#toc><IMG src="up.gif" ></A> Table of Contents 603 <BR> 604 <A href=dpans14.htm><IMG src="right.gif" ></A> 605 Next Section 606 <P> 607 </BODY> 608 </HTML>