Annotation of gforth/gforth.ds, revision 1.1
1.1 ! anton 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>