Powered by ViewCVS 1.0-dev
| 1 : | anton | 1.1 | \input texinfo @c -*-texinfo-*- |
| 2 : | @comment The source is gforth.ds, from which gforth.texi is generated | ||
| 3 : | @comment %**start of header (This is for running Texinfo on a region.) | ||
| 4 : | @setfilename gforth-info | ||
| 5 : | @settitle GNU Forth Manual | ||
| 6 : | @setchapternewpage odd | ||
| 7 : | @comment %**end of header (This is for running Texinfo on a region.) | ||
| 8 : | |||
| 9 : | @ifinfo | ||
| 10 : | This file documents GNU Forth 0.0 | ||
| 11 : | |||
| 12 : | Copyright @copyright{} 1994 GNU Forth Development Group | ||
| 13 : | |||
| 14 : | Permission is granted to make and distribute verbatim copies of | ||
| 15 : | this manual provided the copyright notice and this permission notice | ||
| 16 : | are preserved on all copies. | ||
| 17 : | |||
| 18 : | @ignore | ||
| 19 : | Permission is granted to process this file through TeX and print the | ||
| 20 : | results, provided the printed document carries a copying permission | ||
| 21 : | notice identical to this one except for the removal of this paragraph | ||
| 22 : | (this paragraph not being relevant to the printed manual). | ||
| 23 : | |||
| 24 : | @end ignore | ||
| 25 : | Permission is granted to copy and distribute modified versions of this | ||
| 26 : | manual under the conditions for verbatim copying, provided also that the | ||
| 27 : | sections entitled "Distribution" and "General Public License" are | ||
| 28 : | included exactly as in the original, and provided that the entire | ||
| 29 : | resulting derived work is distributed under the terms of a permission | ||
| 30 : | notice identical to this one. | ||
| 31 : | |||
| 32 : | Permission is granted to copy and distribute translations of this manual | ||
| 33 : | into another language, under the above conditions for modified versions, | ||
| 34 : | except that the sections entitled "Distribution" and "General Public | ||
| 35 : | License" may be included in a translation approved by the author instead | ||
| 36 : | of in the original English. | ||
| 37 : | @end ifinfo | ||
| 38 : | |||
| 39 : | @titlepage | ||
| 40 : | @sp 10 | ||
| 41 : | @center @titlefont{GNU Forth Manual} | ||
| 42 : | @sp 2 | ||
| 43 : | @center for version 0.0 | ||
| 44 : | @sp 2 | ||
| 45 : | @center Anton Ertl | ||
| 46 : | |||
| 47 : | @comment The following two commands start the copyright page. | ||
| 48 : | @page | ||
| 49 : | @vskip 0pt plus 1filll | ||
| 50 : | Copyright @copyright{} 1994 GNU Forth Development Group | ||
| 51 : | |||
| 52 : | @comment !! Published by ... or You can get a copy of this manual ... | ||
| 53 : | |||
| 54 : | Permission is granted to make and distribute verbatim copies of | ||
| 55 : | this manual provided the copyright notice and this permission notice | ||
| 56 : | are preserved on all copies. | ||
| 57 : | |||
| 58 : | Permission is granted to copy and distribute modified versions of this | ||
| 59 : | manual under the conditions for verbatim copying, provided also that the | ||
| 60 : | sections entitled "Distribution" and "General Public License" are | ||
| 61 : | included exactly as in the original, and provided that the entire | ||
| 62 : | resulting derived work is distributed under the terms of a permission | ||
| 63 : | notice identical to this one. | ||
| 64 : | |||
| 65 : | Permission is granted to copy and distribute translations of this manual | ||
| 66 : | into another language, under the above conditions for modified versions, | ||
| 67 : | except that the sections entitled "Distribution" and "General Public | ||
| 68 : | License" may be included in a translation approved by the author instead | ||
| 69 : | of in the original English. | ||
| 70 : | @end titlepage | ||
| 71 : | |||
| 72 : | |||
| 73 : | @node Top, License, (dir), (dir) | ||
| 74 : | @ifinfo | ||
| 75 : | GNU Forth is a free implementation of ANS Forth available on many | ||
| 76 : | personal machines. This manual corresponds to version 0.0. | ||
| 77 : | @end ifinfo | ||
| 78 : | |||
| 79 : | @menu | ||
| 80 : | * License:: | ||
| 81 : | * Goals:: About the GNU Forth Project | ||
| 82 : | * Other Books:: Things you might want to read | ||
| 83 : | * Invocation:: Starting GNU Forth | ||
| 84 : | * Words:: Forth words available in GNU Forth | ||
| 85 : | * ANS conformance:: Implementation-defined options etc. | ||
| 86 : | * Model:: The abstract machine of GNU Forth | ||
| 87 : | * Emacs and GForth:: The GForth Mode | ||
| 88 : | * Internals:: Implementation details | ||
| 89 : | * Bugs:: How to report them | ||
| 90 : | * Pedigree:: Ancestors of GNU Forth | ||
| 91 : | * Word Index:: An item for each Forth word | ||
| 92 : | * Node Index:: An item for each node | ||
| 93 : | @end menu | ||
| 94 : | |||
| 95 : | @node License, Goals, Top, Top | ||
| 96 : | @unnumbered License | ||
| 97 : | !! Insert GPL here | ||
| 98 : | |||
| 99 : | @iftex | ||
| 100 : | @unnumbered Preface | ||
| 101 : | This manual documents GNU Forth. The reader is expected to know | ||
| 102 : | Forth. This manual is primarily a reference manual. @xref{Other Books} | ||
| 103 : | for introductory material. | ||
| 104 : | @end iftex | ||
| 105 : | |||
| 106 : | @node Goals, Other Books, License, Top | ||
| 107 : | @comment node-name, next, previous, up | ||
| 108 : | @chapter Goals of GNU Forth | ||
| 109 : | @cindex Goals | ||
| 110 : | The goal of the GNU Forth Project is to develop a standard model for | ||
| 111 : | ANSI Forth. This can be split into several subgoals: | ||
| 112 : | |||
| 113 : | @itemize @bullet | ||
| 114 : | @item | ||
| 115 : | GNU Forth should conform to the ANSI Forth standard. | ||
| 116 : | @item | ||
| 117 : | It should be a model, i.e. it should define all the | ||
| 118 : | implementation-dependent things. | ||
| 119 : | @item | ||
| 120 : | It should become standard, i.e. widely accepted and used. This goal | ||
| 121 : | is the most difficult one. | ||
| 122 : | @end itemize | ||
| 123 : | |||
| 124 : | To achieve these goals GNU Forth should be | ||
| 125 : | @itemize @bullet | ||
| 126 : | @item | ||
| 127 : | Similar to previous models (fig-Forth, F83) | ||
| 128 : | @item | ||
| 129 : | Powerful. It should provide for all the things that are considered | ||
| 130 : | necessary today and even some that are not yet considered necessary. | ||
| 131 : | @item | ||
| 132 : | Efficient. It should not get the reputation of being exceptionally | ||
| 133 : | slow. | ||
| 134 : | @item | ||
| 135 : | Free. | ||
| 136 : | @item | ||
| 137 : | Available on many machines/easy to port. | ||
| 138 : | @end itemize | ||
| 139 : | |||
| 140 : | Have we achieved these goals? GNU Forth conforms to the ANS Forth | ||
| 141 : | standard; it may be considered a model, but we have not yet documented | ||
| 142 : | which parts of the model are stable and which parts we are likely to | ||
| 143 : | change; it certainly has not yet become a de facto standard. It has some | ||
| 144 : | similarities and some differences to previous models; It has some | ||
| 145 : | powerful features, but not yet everything that we envisioned; on RISCs | ||
| 146 : | it is as fast as interpreters programmed in assembly, on | ||
| 147 : | register-starved machines it is not so fast, but still faster than any | ||
| 148 : | other C-based interpretive implementation; it is free and available on | ||
| 149 : | many machines. | ||
| 150 : | |||
| 151 : | @node Other Books, Invocation, Goals, Top | ||
| 152 : | @chapter Other books on ANS Forth | ||
| 153 : | |||
| 154 : | As the standard is relatively new, there are not many books out yet. It | ||
| 155 : | is not recommended to learn Forth by using GNU Forth and a book that is | ||
| 156 : | not written for ANS Forth, as you will not know your mistakes from the | ||
| 157 : | deviations of the book. | ||
| 158 : | |||
| 159 : | There is, of course, the standard, the definite reference if you want to | ||
| 160 : | write ANS Forth programs. It will be available in printed form from | ||
| 161 : | Global Engineering Documents !! somtime in spring or summer 1994. If you | ||
| 162 : | are lucky, you can still get dpANS6 (the draft that was approved as | ||
| 163 : | standard) by aftp from ftp.uu.net:/vendor/minerva/x3j14. | ||
| 164 : | |||
| 165 : | @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an | ||
| 166 : | introductory book based on a draft version of the standard. It does not | ||
| 167 : | cover the whole standard. It also contains interesting background | ||
| 168 : | information (Jack Woehr was in the ANS Forth Technical Committe). It is | ||
| 169 : | not appropriate for complete newbies, but programmers experienced in | ||
| 170 : | other languages should find it ok. | ||
| 171 : | |||
| 172 : | @node Invocation, Words, Other Books, Top | ||
| 173 : | @chapter Invocation | ||
| 174 : | |||
| 175 : | You will usually just say @code{gforth}. In many other cases the default | ||
| 176 : | GNU Forth image will be invoked like this: | ||
| 177 : | |||
| 178 : | @example | ||
| 179 : | gforth [files] [-e forth-code] | ||
| 180 : | @end example | ||
| 181 : | |||
| 182 : | executing the contents of the files and the Forth code in the order they | ||
| 183 : | are given. | ||
| 184 : | |||
| 185 : | In general, the command line looks like this: | ||
| 186 : | |||
| 187 : | @example | ||
| 188 : | gforth [initialization options] [image-specific options] | ||
| 189 : | @end example | ||
| 190 : | |||
| 191 : | The initialization options must come before the rest of the command | ||
| 192 : | line. They are: | ||
| 193 : | |||
| 194 : | @table @code | ||
| 195 : | @item --image-file @var{file} | ||
| 196 : | Loads the Forth image @var{file} instead of the default | ||
| 197 : | @file{gforth.fi}. | ||
| 198 : | |||
| 199 : | @item --path @var{path} | ||
| 200 : | Uses @var{path} for searching the image file and Forth source code | ||
| 201 : | files instead of the default in the environment variable | ||
| 202 : | @code{GFORTHPATH} or the path specified at installation time (typically | ||
| 203 : | @file{/usr/local/lib/gforth:.}). A path is given as a @code{:}-separated | ||
| 204 : | list. | ||
| 205 : | |||
| 206 : | @item --dictionary-size @var{size} | ||
| 207 : | @item -m @var{size} | ||
| 208 : | Allocate @var{size} space for the Forth dictionary space instead of | ||
| 209 : | using the default specified in the image (typically 256K). The | ||
| 210 : | @var{size} specification consists of an integer and a unit (e.g., | ||
| 211 : | @code{4M}). The unit can be one of @code{b} (bytes), @code{e} (element | ||
| 212 : | size, in this case Cells), @code{k} (kilobytes), and @code{M} | ||
| 213 : | (Megabytes). If no unit is specified, @code{e} is used. | ||
| 214 : | |||
| 215 : | @item --data-stack-size @var{size} | ||
| 216 : | @item -d @var{size} | ||
| 217 : | Allocate @var{size} space for the data stack instead of using the | ||
| 218 : | default specified in the image (typically 16K). | ||
| 219 : | |||
| 220 : | @item --return-stack-size @var{size} | ||
| 221 : | @item -r @var{size} | ||
| 222 : | Allocate @var{size} space for the return stack instead of using the | ||
| 223 : | default specified in the image (typically 16K). | ||
| 224 : | |||
| 225 : | @item --fp-stack-size @var{size} | ||
| 226 : | @item -f @var{size} | ||
| 227 : | Allocate @var{size} space for the floating point stack instead of | ||
| 228 : | using the default specified in the image (typically 16K). In this case | ||
| 229 : | the unit specifier @code{e} refers to floating point numbers. | ||
| 230 : | |||
| 231 : | @item --locals-stack-size @var{size} | ||
| 232 : | @item -l @var{size} | ||
| 233 : | Allocate @var{size} space for the locals stack instead of using the | ||
| 234 : | default specified in the image (typically 16K). | ||
| 235 : | |||
| 236 : | @end table | ||
| 237 : | |||
| 238 : | As explained above, the image-specific command-line arguments for the | ||
| 239 : | default image @file{gforth.fi} consist of a sequence of filenames and | ||
| 240 : | @code{-e @var{forth-code}} options that are interpreted in the seqence | ||
| 241 : | in which they are given. The @code{-e @var{forth-code}} or | ||
| 242 : | @code{--evaluate @var{forth-code}} option evaluates the forth | ||
| 243 : | code. This option takes only one argument; if you want to evaluate more | ||
| 244 : | Forth words, you have to quote them or use several @code{-e}s. To exit | ||
| 245 : | after processing the command line (instead of entering interactive mode) | ||
| 246 : | append @code{-e bye} to the command line. | ||
| 247 : | |||
| 248 : | Not yet implemented: | ||
| 249 : | On startup the system first executes the system initialization file | ||
| 250 : | (unless the option @code{--no-init-file} is given; note that the system | ||
| 251 : | resulting from using this option may not be ANS Forth conformant). Then | ||
| 252 : | the user initialization file @file{.gforth.fs} is executed, unless the | ||
| 253 : | option @code{--no-rc} is given; this file is first searched in @file{.}, | ||
| 254 : | then in @file{~}, then in the normal path (see above). | ||
| 255 : | |||
| 256 : | @node Words, , Invocation, Top | ||
| 257 : | @chapter Forth Words | ||
| 258 : | |||
| 259 : | @menu | ||
| 260 : | * Notation:: | ||
| 261 : | * Arithmetic:: | ||
| 262 : | * Stack Manipulation:: | ||
| 263 : | * Memory access:: | ||
| 264 : | * Control Structures:: | ||
| 265 : | * Local Variables:: | ||
| 266 : | * Defining Words:: | ||
| 267 : | * Vocabularies:: | ||
| 268 : | * Files:: | ||
| 269 : | * Blocks:: | ||
| 270 : | * Other I/O:: | ||
| 271 : | * Programming Tools:: | ||
| 272 : | @end menu | ||
| 273 : | |||
| 274 : | @node Notation, Arithmetic, Words, Words | ||
| 275 : | @section Notation | ||
| 276 : | |||
| 277 : | The Forth words are described in this section in the glossary notation | ||
| 278 : | that has become a de-facto standard for Forth texts, i.e. | ||
| 279 : | |||
| 280 : | @quotation | ||
| 281 : | @var{word} @var{Stack effect} @var{wordset} @var{pronunciation} | ||
| 282 : | @var{Description} | ||
| 283 : | @end quotation | ||
| 284 : | |||
| 285 : | @table @var | ||
| 286 : | @item word | ||
| 287 : | The name of the word. BTW, GNU Forth is case insensitive, so you can | ||
| 288 : | type the words in in lower case. | ||
| 289 : | |||
| 290 : | @item Stack effect | ||
| 291 : | The stack effect is written in the notation @code{@var{before} -- | ||
| 292 : | @var{after}}, where @var{before} and @var{after} describe the top of | ||
| 293 : | stack entries before and after the execution of the word. The rest of | ||
| 294 : | the stack is not touched by the word. The top of stack is rightmost, | ||
| 295 : | i.e., a stack sequence is written as it is typed in. Note that GNU Forth | ||
| 296 : | uses a separate floating point stack, but a unified stack | ||
| 297 : | notation. Also, return stack effects are not shown in @var{stack | ||
| 298 : | effect}, but in @var{Description}. The name of a stack item describes | ||
| 299 : | the type and/or the function of the item. See below for a discussion of | ||
| 300 : | the types. | ||
| 301 : | |||
| 302 : | @item pronunciation | ||
| 303 : | How the word is pronounced | ||
| 304 : | |||
| 305 : | @item wordset | ||
| 306 : | The ANS Forth standard is divided into several wordsets. A standard | ||
| 307 : | system need not support all of them. So, the fewer wordsets your program | ||
| 308 : | uses the more portable it will be in theory. However, we suspect that | ||
| 309 : | most ANS Forth systems on personal machines will feature all | ||
| 310 : | wordsets. Words that are not defined in the ANS standard have | ||
| 311 : | @code{gforth} as wordset. | ||
| 312 : | |||
| 313 : | @item Description | ||
| 314 : | A description of the behaviour of the word. | ||
| 315 : | @end table | ||
| 316 : | |||
| 317 : | The name of a stack item corresponds in the following way with its type: | ||
| 318 : | |||
| 319 : | @table @code | ||
| 320 : | @item name starts with | ||
| 321 : | Type | ||
| 322 : | @item f | ||
| 323 : | Bool, i.e. @code{false} or @code{true}. | ||
| 324 : | @item c | ||
| 325 : | Char | ||
| 326 : | @item w | ||
| 327 : | Cell, can contain an integer or an address | ||
| 328 : | @item n | ||
| 329 : | signed integer | ||
| 330 : | @item u | ||
| 331 : | unsigned integer | ||
| 332 : | @item d | ||
| 333 : | double sized signed integer | ||
| 334 : | @item ud | ||
| 335 : | double sized unsigned integer | ||
| 336 : | @item r | ||
| 337 : | Float | ||
| 338 : | @item a_ | ||
| 339 : | Cell-aligned address | ||
| 340 : | @item c_ | ||
| 341 : | Char-aligned address (note that a Char is two bytes in Windows NT) | ||
| 342 : | @item f_ | ||
| 343 : | Float-aligned address | ||
| 344 : | @item df_ | ||
| 345 : | Address aligned for IEEE double precision float | ||
| 346 : | @item sf_ | ||
| 347 : | Address aligned for IEEE single precision float | ||
| 348 : | @item xt | ||
| 349 : | Execution token, same size as Cell | ||
| 350 : | @item wid | ||
| 351 : | Wordlist ID, same size as Cell | ||
| 352 : | @item f83name | ||
| 353 : | Pointer to a name structure | ||
| 354 : | @end table | ||
| 355 : | |||
| 356 : | @node Arithmetic, , Notation, Words | ||
| 357 : | @section Arithmetic | ||
| 358 : | Forth arithmetic is not checked, i.e., you will not hear about integer | ||
| 359 : | overflow on addition or multiplication, you may hear about division by | ||
| 360 : | zero if you are lucky. The operator is written after the operands, but | ||
| 361 : | the operands are still in the original order. I.e., the infix @code{2-1} | ||
| 362 : | corresponds to @code{2 1 -}. Forth offers a variety of division | ||
| 363 : | operators. If you perform division with potentially negative operands, | ||
| 364 : | you do not want to use @code{/} or @code{/mod} with its undefined | ||
| 365 : | behaviour, but rather @code{fm/mod} or @code{sm/mod} (probably the | ||
| 366 : | former). | ||
| 367 : | |||
| 368 : | @subsection Single precision | ||
| 369 : | doc-+ | ||
| 370 : | doc-- | ||
| 371 : | doc-* | ||
| 372 : | doc-/ | ||
| 373 : | doc-mod | ||
| 374 : | doc-/mod | ||
| 375 : | doc-negate | ||
| 376 : | doc-abs | ||
| 377 : | doc-min | ||
| 378 : | doc-max | ||
| 379 : | |||
| 380 : | @subsection Bitwise operations | ||
| 381 : | doc-and | ||
| 382 : | doc-or | ||
| 383 : | doc-xor | ||
| 384 : | doc-invert | ||
| 385 : | doc-2* | ||
| 386 : | doc-2/ | ||
| 387 : | |||
| 388 : | @subsection Mixed precision | ||
| 389 : | doc-m+ | ||
| 390 : | doc-*/ | ||
| 391 : | doc-*/mod | ||
| 392 : | doc-m* | ||
| 393 : | doc-um* | ||
| 394 : | doc-m*/ | ||
| 395 : | doc-um/mod | ||
| 396 : | doc-fm/mod | ||
| 397 : | doc-sm/rem | ||
| 398 : | |||
| 399 : | @subsection Double precision | ||
| 400 : | doc-d+ | ||
| 401 : | doc-d- | ||
| 402 : | doc-dnegate | ||
| 403 : | doc-dabs | ||
| 404 : | doc-dmin | ||
| 405 : | doc-dmax | ||
| 406 : | |||
| 407 : | @node Stack Manipulation,,, | ||
| 408 : | @section Stack Manipulation | ||
| 409 : | |||
| 410 : | gforth has a data stack (aka parameter stack) for characters, cells, | ||
| 411 : | addresses, and double cells, a floating point stack for floating point | ||
| 412 : | numbers, a return stack for storing the return addresses of colon | ||
| 413 : | definitions and other data, and a locals stack for storing local | ||
| 414 : | variables. Note that while every sane Forth has a separate floating | ||
| 415 : | point stack, this is not strictly required; an ANS Forth system could | ||
| 416 : | theoretically keep floating point numbers on the data stack. As an | ||
| 417 : | additional difficulty, you don't know how many cells a floating point | ||
| 418 : | number takes. It is reportedly possible to write words in a way that | ||
| 419 : | they work also for a unified stack model, but we do not recommend trying | ||
| 420 : | it. Also, a Forth system is allowed to keep the local variables on the | ||
| 421 : | return stack. This is reasonable, as local variables usually eliminate | ||
| 422 : | the need to use the return stack explicitly. So, if you want to produce | ||
| 423 : | a standard complying program and if you are using local variables in a | ||
| 424 : | word, forget about return stack manipulations in that word (see the | ||
| 425 : | standard document for the exact rules). | ||
| 426 : | |||
| 427 : | @subsection Data stack | ||
| 428 : | doc-drop | ||
| 429 : | doc-nip | ||
| 430 : | doc-dup | ||
| 431 : | doc-over | ||
| 432 : | doc-tuck | ||
| 433 : | doc-swap | ||
| 434 : | doc-rot | ||
| 435 : | doc--rot | ||
| 436 : | doc-?dup | ||
| 437 : | doc-pick | ||
| 438 : | doc-roll | ||
| 439 : | doc-2drop | ||
| 440 : | doc-2nip | ||
| 441 : | doc-2dup | ||
| 442 : | doc-2over | ||
| 443 : | doc-2tuck | ||
| 444 : | doc-2swap | ||
| 445 : | doc-2rot | ||
| 446 : | |||
| 447 : | @subsection Floating point stack | ||
| 448 : | doc-fdrop | ||
| 449 : | doc-fnip | ||
| 450 : | doc-fdup | ||
| 451 : | doc-fover | ||
| 452 : | doc-ftuck | ||
| 453 : | doc-fswap | ||
| 454 : | doc-frot | ||
| 455 : | |||
| 456 : | @subsection Return stack | ||
| 457 : | doc->r | ||
| 458 : | doc-r> | ||
| 459 : | doc-r@ | ||
| 460 : | doc-rdrop | ||
| 461 : | doc-2>r | ||
| 462 : | doc-2r> | ||
| 463 : | doc-2r@ | ||
| 464 : | doc-2rdrop | ||
| 465 : | |||
| 466 : | @subsection Locals stack | ||
| 467 : | |||
| 468 : | @subsection Stack pointer manipulation | ||
| 469 : | doc-sp@ | ||
| 470 : | doc-sp! | ||
| 471 : | doc-fp@ | ||
| 472 : | doc-fp! | ||
| 473 : | doc-rp@ | ||
| 474 : | doc-rp! | ||
| 475 : | doc-lp@ | ||
| 476 : | doc-lp! | ||
| 477 : | |||
| 478 : | @node Memory access | ||
| 479 : | @section Memory access | ||
| 480 : | |||
| 481 : | @subsection Stack-Memory transfers | ||
| 482 : | |||
| 483 : | doc-@ | ||
| 484 : | doc-! | ||
| 485 : | doc-+! | ||
| 486 : | doc-c@ | ||
| 487 : | doc-c! | ||
| 488 : | doc-2@ | ||
| 489 : | doc-2! | ||
| 490 : | doc-f@ | ||
| 491 : | doc-f! | ||
| 492 : | doc-sf@ | ||
| 493 : | doc-sf! | ||
| 494 : | doc-df@ | ||
| 495 : | doc-df! | ||
| 496 : | |||
| 497 : | @subsection Address arithmetic | ||
| 498 : | |||
| 499 : | ANS Forth does not specify the sizes of the data types. Instead, it | ||
| 500 : | offers a number of words for computing sizes and doing address | ||
| 501 : | arithmetic. Basically, address arithmetic is performed in terms of | ||
| 502 : | address units (aus); on most systems the address unit is one byte. Note | ||
| 503 : | that a character may have more than one au, so @code{chars} is no noop | ||
| 504 : | (on systems where it is a noop, it compiles to nothing). | ||
| 505 : | |||
| 506 : | ANS Forth also defines words for aligning addresses for specific | ||
| 507 : | addresses. Many computers require that accesses to specific data types | ||
| 508 : | must only occur at specific addresses; e.g., that cells may only be | ||
| 509 : | accessed at addresses divisible by 4. Even if a machine allows unaligned | ||
| 510 : | accesses, it can usually perform aligned accesses faster. | ||
| 511 : | |||
| 512 : | For the performance-concious: alignment operations are usually only | ||
| 513 : | necessary during the definition of a data structure, not during the | ||
| 514 : | (more frequent) accesses to it. | ||
| 515 : | |||
| 516 : | ANS Forth defines no words for character-aligning addresses. This is not | ||
| 517 : | an oversight, but reflects the fact that addresses that are not | ||
| 518 : | char-aligned have no use in the standard and therefore will not be | ||
| 519 : | created. | ||
| 520 : | |||
| 521 : | The standard guarantees that addresses returned by @code{CREATE}d words | ||
| 522 : | are cell-aligned; in addition, gforth guarantees that these addresses | ||
| 523 : | are aligned for all purposes. | ||
| 524 : | |||
| 525 : | doc-chars | ||
| 526 : | doc-char+ | ||
| 527 : | doc-cells | ||
| 528 : | doc-cell+ | ||
| 529 : | doc-align | ||
| 530 : | doc-aligned | ||
| 531 : | doc-floats | ||
| 532 : | doc-float+ | ||
| 533 : | doc-falign | ||
| 534 : | doc-faligned | ||
| 535 : | doc-sfloats | ||
| 536 : | doc-sfloat+ | ||
| 537 : | doc-sfalign | ||
| 538 : | doc-sfaligned | ||
| 539 : | doc-dfloats | ||
| 540 : | doc-dfloat+ | ||
| 541 : | doc-dfalign | ||
| 542 : | doc-dfaligned | ||
| 543 : | doc-address-unit-bits | ||
| 544 : | |||
| 545 : | @subsection Memory block access | ||
| 546 : | |||
| 547 : | doc-move | ||
| 548 : | doc-erase | ||
| 549 : | |||
| 550 : | While the previous words work on address units, the rest works on | ||
| 551 : | characters. | ||
| 552 : | |||
| 553 : | doc-cmove | ||
| 554 : | doc-cmove> | ||
| 555 : | doc-fill | ||
| 556 : | doc-blank | ||
| 557 : | |||
| 558 : | @node Control Structures | ||
| 559 : | @section Control Structures | ||
| 560 : | |||
| 561 : | Control structures in Forth cannot be used in interpret state, only in | ||
| 562 : | compile state, i.e., in a colon definition. We do not like this | ||
| 563 : | limitation, but have not seen a satisfying way around it yet, although | ||
| 564 : | many schemes have been proposed. | ||
| 565 : | |||
| 566 : | @subsection Selection | ||
| 567 : | |||
| 568 : | @example | ||
| 569 : | @var{flag} | ||
| 570 : | IF | ||
| 571 : | @var{code} | ||
| 572 : | ENDIF | ||
| 573 : | @end example | ||
| 574 : | or | ||
| 575 : | @example | ||
| 576 : | @var{flag} | ||
| 577 : | IF | ||
| 578 : | @var{code1} | ||
| 579 : | ELSE | ||
| 580 : | @var{code2} | ||
| 581 : | ENDIF | ||
| 582 : | @end example | ||
| 583 : | |||
| 584 : | You can use @code{THEN} instead of {ENDIF}. Indeed, @code{THEN} is | ||
| 585 : | standard, and @code{ENDIF} is not, although it is quite popular. We | ||
| 586 : | recommend using @code{ENDIF}, because it is less confusing for people | ||
| 587 : | who also know other languages (and is not prone to reinforcing negative | ||
| 588 : | prejudices against Forth in these people). Adding @code{ENDIF} to a | ||
| 589 : | system that only supplies @code{THEN} is simple: | ||
| 590 : | @example | ||
| 591 : | : endif POSTPONE then ; immediate | ||
| 592 : | @end example | ||
| 593 : | |||
| 594 : | [According to @cite{Webster's New Encyclopedic Dictionary}, @dfn{then | ||
| 595 : | (adv.)} has the following meanings: | ||
| 596 : | @quotation | ||
| 597 : | ... 2b: following next after in order ... 3d: as a necessary consequence | ||
| 598 : | (if you were there, then you saw them). | ||
| 599 : | @end quotation | ||
| 600 : | Forth's @code{THEN} has the meaning 2b, whereas @code{THEN} in Pascal | ||
| 601 : | and many other programming languages has the meaning 3d.] | ||
| 602 : | |||
| 603 : | We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you | ||
| 604 : | can avoid using @code{?dup}. | ||
| 605 : | |||
| 606 : | @example | ||
| 607 : | @var{n} | ||
| 608 : | CASE | ||
| 609 : | @var{n1} OF @var{code1} ENDOF | ||
| 610 : | @var{n2} OF @var{code2} ENDOF | ||
| 611 : | @dots | ||
| 612 : | ENDCASE | ||
| 613 : | @end example | ||
| 614 : | |||
| 615 : | Executes the first @var{codei}, where the @var{ni} is equal to | ||
| 616 : | @var{n}. A default case can be added by simply writing the code after | ||
| 617 : | the last @code{ENDOF}. It may use @var{n}, which is on top of the stack, | ||
| 618 : | but must not consume it. | ||
| 619 : | |||
| 620 : | @subsection Simple Loops | ||
| 621 : | |||
| 622 : | @example | ||
| 623 : | BEGIN | ||
| 624 : | @var{code1} | ||
| 625 : | @var{flag} | ||
| 626 : | WHILE | ||
| 627 : | @var{code2} | ||
| 628 : | REPEAT | ||
| 629 : | @end example | ||
| 630 : | |||
| 631 : | @var{code1} is executed and @var{flag} is computed. If it is true, | ||
| 632 : | @var{code2} is executed and the loop is restarted; If @var{flag} is false, execution continues after the @code{REPEAT}. | ||
| 633 : | |||
| 634 : | @example | ||
| 635 : | BEGIN | ||
| 636 : | @var{code} | ||
| 637 : | @var{flag} | ||
| 638 : | UNTIL | ||
| 639 : | @end example | ||
| 640 : | |||
| 641 : | @var{code} is executed. The loop is restarted if @code{flag} is false. | ||
| 642 : | |||
| 643 : | @example | ||
| 644 : | BEGIN | ||
| 645 : | @var{code} | ||
| 646 : | AGAIN | ||
| 647 : | @end example | ||
| 648 : | |||
| 649 : | This is an endless loop. | ||
| 650 : | |||
| 651 : | @subsection Counted Loops | ||
| 652 : | |||
| 653 : | The basic counted loop is: | ||
| 654 : | @example | ||
| 655 : | @var{limit} @var{start} | ||
| 656 : | ?DO | ||
| 657 : | @var{body} | ||
| 658 : | LOOP | ||
| 659 : | @end example | ||
| 660 : | |||
| 661 : | This performs one iteration for every integer, starting from @var{start} | ||
| 662 : | and up to, but excluding @var{limit}. The counter, aka index, can be | ||
| 663 : | accessed with @code{i}. E.g., the loop | ||
| 664 : | @example | ||
| 665 : | 10 0 ?DO | ||
| 666 : | i . | ||
| 667 : | LOOP | ||
| 668 : | @end example | ||
| 669 : | prints | ||
| 670 : | @example | ||
| 671 : | 0 1 2 3 4 5 6 7 8 9 | ||
| 672 : | @end example | ||
| 673 : | The index of the innermost loop can be accessed with @code{i}, the index | ||
| 674 : | of the next loop with @code{j}, and the index of the third loop with | ||
| 675 : | @code{k}. | ||
| 676 : | |||
| 677 : | The loop control data are kept on the return stack, so there are some | ||
| 678 : | restrictions on mixing return stack accesses and counted loop | ||
| 679 : | words. E.g., if you put values on the return stack outside the loop, you | ||
| 680 : | cannot read them inside the loop. If you put values on the return stack | ||
| 681 : | within a loop, you have to remove them before the end of the loop and | ||
| 682 : | before accessing the index of the loop. | ||
| 683 : | |||
| 684 : | There are several variations on the counted loop: | ||
| 685 : | |||
| 686 : | @code{LEAVE} leaves the innermost counted loop immediately. | ||
| 687 : | |||
| 688 : | @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the | ||
| 689 : | index by @var{n} instead of by 1. The loop is terminated when the border | ||
| 690 : | between @var{limit-1} and @var{limit} is crossed. E.g.: | ||
| 691 : | |||
| 692 : | 4 0 ?DO i . 2 +LOOP prints 0 2 | ||
| 693 : | |||
| 694 : | 4 1 ?DO i . 2 +LOOP prints 1 3 | ||
| 695 : | |||
| 696 : | The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative: | ||
| 697 : | |||
| 698 : | -1 0 ?DO i . -1 +LOOP prints 0 -1 | ||
| 699 : | |||
| 700 : | 0 0 ?DO i . -1 +LOOP prints nothing | ||
| 701 : | |||
| 702 : | Therefore we recommend avoiding using @code{@var{n} +LOOP} with negative | ||
| 703 : | @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative | ||
| 704 : | case behaves symmetrical to the positive case: | ||
| 705 : | |||
| 706 : | -2 0 ?DO i . -1 +LOOP prints 0 -1 | ||
| 707 : | |||
| 708 : | -1 0 ?DO i . -1 +LOOP prints 0 | ||
| 709 : | |||
| 710 : | 0 0 ?DO i . -1 +LOOP prints nothing | ||
| 711 : | |||
| 712 : | The loop is terminated when the border between @var{limit-sgn(n)} and | ||
| 713 : | @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS | ||
| 714 : | Forth standard. | ||
| 715 : | |||
| 716 : | @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even | ||
| 717 : | when the start and the limit value are equal. We do not recommend using | ||
| 718 : | @code{DO}. It will just give you maintenance troubles. | ||
| 719 : | |||
| 720 : | @code{UNLOOP} is used to prepare for an abnormal loop exit, e.g., via | ||
| 721 : | @code{EXIT}. @code{UNLOOP} removes the loop control parameters from the | ||
| 722 : | return stack so @code{EXIT} can get to its return address. | ||
| 723 : | |||
| 724 : | Another counted loop is | ||
| 725 : | @example | ||
| 726 : | @var{n} | ||
| 727 : | FOR | ||
| 728 : | @var{body} | ||
| 729 : | NEXT | ||
| 730 : | @end example | ||
| 731 : | This is the preferred loop of native code compiler writers who are too | ||
| 732 : | lazy to optimize @code{?DO} loops properly. In GNU Forth, this loop | ||
| 733 : | iterates @var{n+1} times; @code{i} produces values starting with @var{n} | ||
| 734 : | and ending with 0. Other Forth systems may behave differently, even if | ||
| 735 : | they support @code{FOR} loops. | ||
| 736 : | |||
| 737 : | @node Locals | ||
| 738 : | @section Locals | ||
| 739 : | |||
| 740 : | |||
| 741 : | |||
| 742 : | @contents | ||
| 743 : | @bye | ||
| 744 : |
|
CVS Admin Powered by ViewCVS 1.0-dev |
ViewCVS and CVS Help |