Annotation of gforth/gforth.texi, revision 1.2

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: 
1.2     ! pazsan    330: @subsection Data stack
1.1       anton     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>