Annotation of gforth/gforth.texi, revision 1.1
1.1 ! anton 1: \input texinfo @c -*-texinfo-*-
! 2: @comment %**start of header (This is for running Texinfo on a region.)
! 3: @setfilename gforth-info
! 4: @settitle GNU Forth Manual
! 5: @setchapternewpage odd
! 6: @comment %**end of header (This is for running Texinfo on a region.)
! 7:
! 8: @ifinfo
! 9: This file documents GNU Forth 0.0
! 10:
! 11: Copyright @copyright{} 1994 GNU Forth Development Group
! 12:
! 13: Permission is granted to make and distribute verbatim copies of
! 14: this manual provided the copyright notice and this permission notice
! 15: are preserved on all copies.
! 16:
! 17: @ignore
! 18: Permission is granted to process this file through TeX and print the
! 19: results, provided the printed document carries a copying permission
! 20: notice identical to this one except for the removal of this paragraph
! 21: (this paragraph not being relevant to the printed manual).
! 22:
! 23: @end ignore
! 24: Permission is granted to copy and distribute modified versions of this
! 25: manual under the conditions for verbatim copying, provided also that the
! 26: sections entitled "Distribution" and "General Public License" are
! 27: included exactly as in the original, and provided that the entire
! 28: resulting derived work is distributed under the terms of a permission
! 29: notice identical to this one.
! 30:
! 31: Permission is granted to copy and distribute translations of this manual
! 32: into another language, under the above conditions for modified versions,
! 33: except that the sections entitled "Distribution" and "General Public
! 34: License" may be included in a translation approved by the author instead
! 35: of in the original English.
! 36: @end ifinfo
! 37:
! 38: @titlepage
! 39: @sp 10
! 40: @center @titlefont{GNU Forth Manual}
! 41: @sp 2
! 42: @center for version 0.0
! 43: @sp 2
! 44: @center Anton Ertl
! 45:
! 46: @comment The following two commands start the copyright page.
! 47: @page
! 48: @vskip 0pt plus 1filll
! 49: Copyright @copyright{} 1994 GNU Forth Development Group
! 50:
! 51: @comment !! Published by ... or You can get a copy of this manual ...
! 52:
! 53: Permission is granted to make and distribute verbatim copies of
! 54: this manual provided the copyright notice and this permission notice
! 55: are preserved on all copies.
! 56:
! 57: Permission is granted to copy and distribute modified versions of this
! 58: manual under the conditions for verbatim copying, provided also that the
! 59: sections entitled "Distribution" and "General Public License" are
! 60: included exactly as in the original, and provided that the entire
! 61: resulting derived work is distributed under the terms of a permission
! 62: notice identical to this one.
! 63:
! 64: Permission is granted to copy and distribute translations of this manual
! 65: into another language, under the above conditions for modified versions,
! 66: except that the sections entitled "Distribution" and "General Public
! 67: License" may be included in a translation approved by the author instead
! 68: of in the original English.
! 69: @end titlepage
! 70:
! 71:
! 72: @node Top, License, (dir), (dir)
! 73: @ifinfo
! 74: GNU Forth is a free implementation of ANS Forth available on many
! 75: personal machines. This manual corresponds to version 0.0.
! 76: @end ifinfo
! 77:
! 78: @menu
! 79: * License::
! 80: * Goals:: About the GNU Forth Project
! 81: * Other Books:: Things you might want to read
! 82: * Invocation:: Starting GNU Forth
! 83: * Words:: Forth words available in GNU Forth
! 84: * ANS conformance:: Implementation-defined options etc.
! 85: * Model:: The abstract machine of GNU Forth
! 86: @comment * Emacs and GForth:: The GForth Mode
! 87: * Internals:: Implementation details
! 88: * Bugs:: How to report them
! 89: * Pedigree:: Ancestors of GNU Forth
! 90: * Word Index:: An item for each Forth word
! 91: * Node Index:: An item for each node
! 92: @end menu
! 93:
! 94: @node License, Goals, Top, Top
! 95: @unnumbered License
! 96: !! Insert GPL here
! 97:
! 98: @iftex
! 99: @unnumbered Preface
! 100: This manual documents GNU Forth. The reader is expected to know
! 101: Forth. This manual is primarily a reference manual. @xref{Other Books}
! 102: for introductory material.
! 103: @end iftex
! 104:
! 105: @node Goals, Other Books, License, Top
! 106: @comment node-name, next, previous, up
! 107: @chapter Goals of GNU Forth
! 108: @cindex Goals
! 109: !! Insert Goals here
! 110:
! 111: @node Other Books, Invocation, Goals, Top
! 112: @chapter Other books on ANS Forth
! 113:
! 114: As the standard is relatively new, there are not many books out yet. It
! 115: is not recommended to learn Forth by using GNU Forth and a book that is
! 116: not written for ANS Forth, as you will not know your mistakes from the
! 117: deviations of the book.
! 118:
! 119: There is, of course, the standard, the definite reference if you want to
! 120: write ANS Forth programs. It will be available in printed form from
! 121: !! somtime in spring or summer 1994. If you are lucky, you can still get
! 122: dpANS6 (the draft that was approved as standard) by aftp from
! 123: ftp.uu.net:/vendor/minerva/x3j14.
! 124:
! 125: @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an introductory
! 126: book based on a draft version of the standard. It does not cover the
! 127: whole standard. It also contains interesting background information
! 128: (Jack Woehr was in the ANS Forth Technical Committe).
! 129:
! 130: @node Invocation, Words, Other Books, Top
! 131: @chapter Invocation
! 132:
! 133: You will usually just say @code{gforth}. More generally, the default GNU
! 134: Forth image can be invoked like this
! 135:
! 136: @example
! 137: gforth [--batch] [files] [-e forth-code]
! 138: @end example
! 139:
! 140: The @code{--batch} option makes @code{gforth} exit after processing the
! 141: command line. Also, the startup message is suppressed. @file{files} are
! 142: Forth source files that are executed in the order in which they
! 143: appear. The @code{-e @samp{forth-code}} or @code{--evaluate
! 144: @samp{forth-code}} option evaluates the forth code; it can be freely
! 145: mixed with the files. This option takes only one argument; if you want
! 146: to evaluate more Forth words, you have to quote them or use several
! 147: @code{-e}s. !! option for suppressing default loading.
! 148:
! 149: You can use the command line option @code{-i @samp{file}} or
! 150: @code{--image-file @samp{file}} to specify a different image file. Note
! 151: that this option must be the first in the command line. The rest of the
! 152: command line is processed by the image file.
! 153:
! 154: If the @code{--image-file} option is not used, GNU Forth searches for a
! 155: file named @file{gforth.fi} in the path specified by the environment
! 156: variable @code{GFORTHPATH}; if this does not exist, in
! 157: @file{/usr/local/lib/gforth} and in @file{/usr/lib/gforth}.
! 158:
! 159: @node Words, , Invocation, Top
! 160: @chapter Forth Words
! 161:
! 162: @menu
! 163: * Notation::
! 164: * Arithmetic::
! 165: * Stack Manipulation::
! 166: * Memory access::
! 167: * Control Structures::
! 168: * Local Variables::
! 169: * Defining Words::
! 170: * Vocabularies::
! 171: * Files::
! 172: * Blocks::
! 173: * Other I/O::
! 174: * Programming Tools::
! 175: @end menu
! 176:
! 177: @node Notation, Arithmetic, Words, Words
! 178: @section Notation
! 179:
! 180: The Forth words are describes in this section in the glossary notation
! 181: that has become a de-facto standard for Forth texts, i.e.
! 182:
! 183: @quotation
! 184: @samp{word} @samp{Stack effect} @samp{pronunciation} @samp{wordset}
! 185: @samp{Description}
! 186: @end quotation
! 187:
! 188: @table @samp
! 189: @item word
! 190: The name of the word. BTW, GNU Forth is case insensitive, so you can
! 191: type the words in in lower case.
! 192:
! 193: @item Stack effect
! 194: The stack effect is written in the notation @code{@samp{before} --
! 195: @samp{after}}, where @samp{before} and @samp{after} describe the top of
! 196: stack entries before and after the execution of the word. The rest of
! 197: the stack is not touched by the word. The top of stack is rightmost,
! 198: i.e., a stack sequence is written as it is typed in. Note that GNU Forth
! 199: uses a separate floating point stack, but a unified stack
! 200: notation. Also, return stack effects are not shown in @samp{stack
! 201: effect}, but in @samp{Description}. The name of a stack item describes
! 202: the type and/or the function of the item. See below for a discussion of
! 203: the types.
! 204:
! 205: @item pronunciation
! 206: How the word is pronounced
! 207:
! 208: @item wordset
! 209: The ANS Forth standard is divided into several wordsets. A standard
! 210: system need not support all of them. So, the fewer wordsets your program
! 211: uses the more portable it will be in theory. However, we suspect that
! 212: most ANS Forth systems on personal machines will feature all
! 213: wordsets. Words that are not defined in the ANS standard have
! 214: @code{gforth} as wordset.
! 215:
! 216: @item Description
! 217: A description of the behaviour of the word.
! 218: @end table
! 219:
! 220: The name of a stack item corresponds in the following way with its type:
! 221:
! 222: @table @code
! 223: @item name starts with
! 224: Type
! 225: @item f
! 226: Bool, i.e. false (0) or true (-1).
! 227: @item c
! 228: Char
! 229: @item w
! 230: Cell, can contain an integer or an address
! 231: @item n
! 232: signed integer
! 233: @item u
! 234: unsigned integer
! 235: @item d
! 236: double sized signed integer
! 237: @item ud
! 238: double sized unsigned integer
! 239: @item r
! 240: Float
! 241: @item a_
! 242: Cell-aligned address
! 243: @item c_
! 244: Char-aligned address (note that a Char is two bytes in Windows NT)
! 245: @item f_
! 246: Float-aligned address
! 247: @item df_
! 248: Address aligned for IEEE double precision float
! 249: @item sf_
! 250: Address aligned for IEEE single precision float
! 251: @item xt
! 252: Execution token, same size as Cell
! 253: @item wid
! 254: Wordlist ID, same size as Cell
! 255: @item f83name
! 256: Pointer to a name structure
! 257: @end table
! 258:
! 259: @node Arithmetic, , Notation, Words
! 260: @section Arithmetic
! 261: Forth arithmetic is not checked, i.e., you will not hear about integer
! 262: overflow on addition or multiplication, you may hear about division by
! 263: zero if you are lucky. The operator is written after the operands, but
! 264: the operands are still in the original order. I.e., the infix @code{2-1}
! 265: corresponds to @code{2 1 -}. Forth offers a variety of division
! 266: operators. If you perform division with potentially negative operands,
! 267: you do not want to use @code{/} or @code{/mod} with its undefined
! 268: behaviour, but rather @code{fm/mod} or @code{sm/mod} (probably the
! 269: former).
! 270:
! 271: @subsection Single precision
! 272: +
! 273: -
! 274: *
! 275: /
! 276: mod
! 277: /mod
! 278: negate
! 279: abs
! 280: min
! 281: max
! 282:
! 283: @subsection Bitwise operations
! 284: and
! 285: or
! 286: xor
! 287: invert
! 288: 2*
! 289: 2/
! 290:
! 291: @subsection Mixed precision
! 292: m+
! 293: */
! 294: */mod
! 295: m*
! 296: um*
! 297: m*/
! 298: um/mod
! 299: fm/mod
! 300: sm/rem
! 301:
! 302: @subsection Double precision
! 303: d+
! 304: d-
! 305: dnegate
! 306: dabs
! 307: dmin
! 308: dmax
! 309:
! 310: @node Stack Manipulation,,,
! 311: @section Stack Manipulation
! 312:
! 313: gforth has a data stack (aka parameter stack) for characters, cells,
! 314: addresses, and double cells, a floating point stack for floating point
! 315: numbers, a return stack for storing the return addresses of colon
! 316: definitions and other data, and a locals stack for storing local
! 317: variables. Note that while every sane Forth has a separate floating
! 318: point stack, this is not strictly required; an ANS Forth system could
! 319: theoretically keep floating point numbers on the data stack. As an
! 320: additional difficulty, you don't know how many cells a floating point
! 321: numkber takes. It is reportedly possible to write words in a way that
! 322: they work also for a unified stack model, but we do not recommend trying
! 323: it. Also, a Forth system to keep the local variables on the return
! 324: stack. This is reasonable, as local variables usually eliminate the need
! 325: to use the return stack explicitely. So, if you want to produce a
! 326: standard complying program and if you are using local variables in a
! 327: word, forget about return stack manipulations in that word (see the
! 328: standard document for the exact rules).
! 329:
! 330: @subsetion Data stack
! 331: drop
! 332: nip
! 333: dup
! 334: over
! 335: tuck
! 336: swap
! 337: rot
! 338: -rot
! 339: ?dup
! 340: pick
! 341: roll
! 342: 2drop
! 343: 2nip
! 344: 2dup
! 345: 2over
! 346: 2tuck
! 347: 2swap
! 348: 2rot
! 349:
! 350: @subsection Floating point stack
! 351: fdrop
! 352: fnip
! 353: fdup
! 354: fover
! 355: ftuck
! 356: fswap
! 357: frot
! 358:
! 359: @subsection Return stack
! 360: >r
! 361: r>
! 362: r@
! 363: rdrop
! 364: 2>r
! 365: 2r>
! 366:
! 367: @subsection Locals stack
! 368:
! 369: @subsection Stack pointer manipulation
! 370: sp@
! 371: sp!
! 372: fp@
! 373: fp!
! 374: rp@
! 375: rp!
! 376: lp@
! 377: lp!
! 378:
! 379: @node Memory access
! 380: @section Memory access
! 381:
! 382: @subsection Stack-Memory transfers
! 383: @
! 384: !
! 385: +!
! 386: c@
! 387: c!
! 388: 2@
! 389: 2!
! 390: f@
! 391: f!
! 392: sf@
! 393: sf!
! 394: df@
! 395: df!
! 396:
! 397: @subsection Memory block access
! 398:
! 399: move
! 400: fill
! 401: blanks
! 402: erase
! 403:
! 404: @node Control Structures
! 405: @section Control Structures
! 406:
! 407: Control structures in Forth cannot be used in interpret state, only in
! 408: compile state, i.e., in a colon definition. We do not like this
! 409: limitation, but have not seen a satisfying way around it yet, although
! 410: many schemes have been proposed.
! 411:
! 412: @subsection Selection
! 413:
! 414: @example
! 415: @var{flag}
! 416: IF
! 417: @var{code}
! 418: ENDIF
! 419: @end example
! 420:
! 421: @example
! 422: @var{flag}
! 423: IF
! 424: @var{code1}
! 425: ELSE
! 426: @var{code2}
! 427: ENDIF
! 428: @end example
! 429:
! 430: You can use @code{THEN} instead of {ENDIF}. Indeed, @code{THEN} is
! 431: standard, and @code{ENDIF} is not, although it is quite popular. We
! 432: recommend using @code{ENDIF}, because it is less confusing for people
! 433: who also know other languages (and is not prone to reinforcing negative
! 434: prejudices against Forth in these people). Adding @code{ENDIF} to a
! 435: system that only supplies @code{THEN} is simple:
! 436: @example
! 437: : endif POSTPONE then ; immediate
! 438: @end example
! 439:
! 440: We also provide the words @code{?dup-if} and @code{?dup-not-if}, so you
! 441: can avoid using @code{?dup}.
! 442:
! 443: @example
! 444: @var{n}
! 445: CASE
! 446: @var{n1} OF @var{code1} ENDOF
! 447: @var{n2} OF @var{code2} ENDOF
! 448: @dots
! 449: ENDCASE
! 450: @end example
! 451:
! 452: Executes the first @var{codei}, where the @var{ni} is equal to
! 453: @var{n}. A default case can be added by simply writing the code after
! 454: the last @code{ENDOF}. It may use @var{n}, which is on top of the stack,
! 455: but must not consume it.
! 456:
! 457: @subsection Simple Loops
! 458:
! 459: @example
! 460: BEGIN
! 461: @var{code1}
! 462: @var{flag}
! 463: WHILE
! 464: @var{code2}
! 465: REPEAT
! 466: @end example
! 467:
! 468: @var{code1} is executed and @var{flag} is computed. If it is true,
! 469: @var{code2} is executed and the loop is restarted; If @var{flag} is false, execution continues after the @code{REPEAT}.
! 470:
! 471: @example
! 472: BEGIN
! 473: @var{code}
! 474: @var{flag}
! 475: UNTIL
! 476: @end example
! 477:
! 478: @var{code} is executed. The loop is restarted if @code{flag} is false.
! 479:
! 480: @example
! 481: BEGIN
! 482: @var{code}
! 483: AGAIN
! 484: @end example
! 485:
! 486: This is an endless loop.
! 487:
! 488: @subsection Counted Loops
! 489:
! 490: The basic counted loop is:
! 491: @example
! 492: @var{limit} @var{start}
! 493: ?DO
! 494: @var{body}
! 495: LOOP
! 496: @end example
! 497:
! 498: This performs one iteration for every integer, starting from @var{start}
! 499: and up to, but excluding @var{limit}. The counter, aka index, can be
! 500: accessed with @code{i}. E.g., the loop
! 501: @example
! 502: 10 0 ?DO
! 503: i .
! 504: LOOP
! 505: @end example
! 506: prints
! 507: @example
! 508: 0 1 2 3 4 5 6 7 8 9
! 509: @end example
! 510: The index of the innermost loop can be accessed with @code{i}, the index
! 511: of the next loop with @code{j}, and the index of the third loop with
! 512: @code{k}.
! 513:
! 514: The loop control data are kept on the return stack, so there are some
! 515: restrictions on mixing return stack accesses and counted loop
! 516: words. E.g., if you put values on the return stack outside the loop, you
! 517: cannot read them inside the loop. If you put values on the return stack
! 518: within a loop, you have to remove them before the end of the loop and
! 519: before accessing the index of the loop.
! 520:
! 521: There are several variations on the counted loop:
! 522:
! 523: @code{LEAVE} leaves the innermost counted loop immediately.
! 524:
! 525: @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the
! 526: index by @var{n} instead of by 1. The loop is terminated when the border
! 527: between @var{limit-1} and @var{limit} is crossed. E.g.:
! 528:
! 529: 4 0 ?DO i . 2 +LOOP prints 0 2
! 530: 4 1 ?DO i . 2 +LOOP prints 1 3
! 531:
! 532: The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative:
! 533:
! 534: -1 0 ?DO i . -1 +LOOP prints 0 -1
! 535: 0 0 ?DO i . -1 +LOOP prints nothing
! 536:
! 537: Therefore we recommend avoiding using @code{@var{n} +LOOP} with negative
! 538: @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative
! 539: case behaves symmetrical to the positive case:
! 540:
! 541: -2 0 ?DO i . -1 +LOOP prints 0 -1
! 542: -1 0 ?DO i . -1 +LOOP prints 0
! 543: 0 0 ?DO i . -1 +LOOP prints nothing
! 544:
! 545: The loop is terminated when the border between @var{limit-sgn(n)} and
! 546: @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS
! 547: Forth standard.
! 548:
! 549: The @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop
! 550: even when the start and the limit value are equal. We do not recommend
! 551: using @code{DO}. It will just give you maintenance troubles.
! 552:
! 553: FOR NEXT UNLOOP
! 554:
! 555: @contents
! 556: @bye
! 557:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gforth.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [gforth] / gforth