Return to gforth.texi CVS log

Up to [gforth] / gforth

local variables
rewrote primitives2c.el in Forth (prims2x.el)
various small changes
Added Files:
 	from-cut-here gforth.el gforth.texi glocals.fs gray.fs
 	locals-test.fs prims2x.fs

    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: