File:  [gforth] / gforth / Attic / gforth.texi
Revision 1.5: download - view: text, annotated - select for diffs
Fri Aug 19 17:47:21 1994 UTC (26 years, 1 month ago) by anton
Branches: MAIN
CVS tags: HEAD
Added filling to gforth.el and defined some keys
Minor changes in gforth.texi
renamed ?DUP-NOT-IF to ?DUP-0=-IF
increased default sizes for kernal
renamed ansforth to gforth

    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: The goal of the GNU Forth Project is to develop a standard model for
  110: ANSI Forth. This can be split into several subgoals:
  111: 
  112: @itemize @bullet
  113: @item
  114: GNU Forth should conform to the ANSI Forth standard.
  115: @item
  116: It should be a model, i.e. it should define all the
  117: implementation-dependent things.
  118: @item
  119: It should become standard, i.e. widely accepted and used. This goal
  120: is the most difficult one.
  121: @end itemize
  122: 
  123: To achieve these goals GNU Forth should be
  124: @itemize @bullet
  125: @item
  126: Similar to previous models (fig-Forth, F83)
  127: @item
  128: Powerful. It should provide for all the things that are considered
  129: necessary today and even some that are not yet considered necessary.
  130: @item
  131: Efficient. It should not get the reputation of being exceptionally
  132: slow.
  133: @item
  134: Free.
  135: @item
  136: Available on many machines/easy to port.
  137: @end itemize
  138: 
  139: Have we achieved these goals? GNU Forth conforms to the ANS Forth
  140: standard; it may be considered a model, but we have not yet documented
  141: which parts of the model are stable and which parts we are likely to
  142: change; it certainly has not yet become a de facto standard. It has some
  143: similarities and some differences to previous models; It has some
  144: powerful features, but not yet everything that we envisioned; on RISCs
  145: it is as fast as interpreters programmed in assembly, on
  146: register-starved machines it is not so fast, but still faster than any
  147: other C-based interpretive implementation; it is free and available on
  148: many machines.
  149: 
  150: @node Other Books, Invocation, Goals, Top
  151: @chapter Other books on ANS Forth
  152: 
  153: As the standard is relatively new, there are not many books out yet. It
  154: is not recommended to learn Forth by using GNU Forth and a book that is
  155: not written for ANS Forth, as you will not know your mistakes from the
  156: deviations of the book.
  157: 
  158: There is, of course, the standard, the definite reference if you want to
  159: write ANS Forth programs. It will be available in printed form from
  160: !! somtime in spring or summer 1994. If you are lucky, you can still get
  161: dpANS6 (the draft that was approved as standard) by aftp from
  162: ftp.uu.net:/vendor/minerva/x3j14.
  163: 
  164: @cite{Forth: The new model} by Jack Woehr (!! Publisher) is an introductory
  165: book based on a draft version of the standard. It does not cover the
  166: whole standard. It also contains interesting background information
  167: (Jack Woehr was in the ANS Forth Technical Committe).
  168: 
  169: @node Invocation, Words, Other Books, Top
  170: @chapter Invocation
  171: 
  172: You will usually just say @code{gforth}. More generally, the default GNU
  173: Forth image can be invoked like this
  174: 
  175: @example
  176: gforth [--batch] [files] [-e forth-code]
  177: @end example
  178: 
  179: The @code{--batch} option makes @code{gforth} exit after processing the
  180: command line. Also, the startup message is suppressed. @file{files} are
  181: Forth source files that are executed in the order in which they
  182: appear. The @code{-e @samp{forth-code}} or @code{--evaluate
  183: @samp{forth-code}} option evaluates the forth code; it can be freely
  184: mixed with the files. This option takes only one argument; if you want
  185: to evaluate more Forth words, you have to quote them or use several
  186: @code{-e}s. !! option for suppressing default loading.
  187: 
  188: You can use the command line option @code{-i @samp{file}} or
  189: @code{--image-file @samp{file}} to specify a different image file. Note
  190: that this option must be the first in the command line. The rest of the
  191: command line is processed by the image file.
  192: 
  193: If the @code{--image-file} option is not used, GNU Forth searches for a
  194: file named @file{gforth.fi} in the path specified by the environment
  195: variable @code{GFORTHPATH}; if this does not exist, in
  196: @file{/usr/local/lib/gforth} and in @file{/usr/lib/gforth}.
  197: 
  198: @node Words,  , Invocation, Top
  199: @chapter Forth Words
  200: 
  201: @menu
  202: * Notation::
  203: * Arithmetic::
  204: * Stack Manipulation::
  205: * Memory access::
  206: * Control Structures::
  207: * Local Variables::
  208: * Defining Words::
  209: * Vocabularies::
  210: * Files::
  211: * Blocks::
  212: * Other I/O::
  213: * Programming Tools::
  214: @end menu
  215: 
  216: @node Notation, Arithmetic, Words, Words
  217: @section Notation
  218: 
  219: The Forth words are described in this section in the glossary notation
  220: that has become a de-facto standard for Forth texts, i.e.
  221: 
  222: @quotation
  223: @samp{word}     @samp{Stack effect}     @samp{pronunciation}   @samp{wordset}
  224: @samp{Description}
  225: @end quotation
  226: 
  227: @table @samp
  228: @item word
  229: The name of the word. BTW, GNU Forth is case insensitive, so you can
  230: type the words in in lower case.
  231: 
  232: @item Stack effect
  233: The stack effect is written in the notation @code{@samp{before} --
  234: @samp{after}}, where @samp{before} and @samp{after} describe the top of
  235: stack entries before and after the execution of the word. The rest of
  236: the stack is not touched by the word. The top of stack is rightmost,
  237: i.e., a stack sequence is written as it is typed in. Note that GNU Forth
  238: uses a separate floating point stack, but a unified stack
  239: notation. Also, return stack effects are not shown in @samp{stack
  240: effect}, but in @samp{Description}. The name of a stack item describes
  241: the type and/or the function of the item. See below for a discussion of
  242: the types.
  243: 
  244: @item pronunciation
  245: How the word is pronounced
  246: 
  247: @item wordset
  248: The ANS Forth standard is divided into several wordsets. A standard
  249: system need not support all of them. So, the fewer wordsets your program
  250: uses the more portable it will be in theory. However, we suspect that
  251: most ANS Forth systems on personal machines will feature all
  252: wordsets. Words that are not defined in the ANS standard have
  253: @code{gforth} as wordset.
  254: 
  255: @item Description
  256: A description of the behaviour of the word.
  257: @end table
  258: 
  259: The name of a stack item corresponds in the following way with its type:
  260: 
  261: @table @code
  262: @item name starts with
  263: Type
  264: @item f
  265: Bool, i.e. @code{false} or @code{true}.
  266: @item c
  267: Char
  268: @item w
  269: Cell, can contain an integer or an address
  270: @item n
  271: signed integer
  272: @item u
  273: unsigned integer
  274: @item d
  275: double sized signed integer
  276: @item ud
  277: double sized unsigned integer
  278: @item r
  279: Float
  280: @item a_
  281: Cell-aligned address
  282: @item c_
  283: Char-aligned address (note that a Char is two bytes in Windows NT)
  284: @item f_
  285: Float-aligned address
  286: @item df_
  287: Address aligned for IEEE double precision float
  288: @item sf_
  289: Address aligned for IEEE single precision float
  290: @item xt
  291: Execution token, same size as Cell
  292: @item wid
  293: Wordlist ID, same size as Cell
  294: @item f83name
  295: Pointer to a name structure
  296: @end table
  297: 
  298: @node Arithmetic,  , Notation, Words
  299: @section Arithmetic
  300: Forth arithmetic is not checked, i.e., you will not hear about integer
  301: overflow on addition or multiplication, you may hear about division by
  302: zero if you are lucky. The operator is written after the operands, but
  303: the operands are still in the original order. I.e., the infix @code{2-1}
  304: corresponds to @code{2 1 -}. Forth offers a variety of division
  305: operators. If you perform division with potentially negative operands,
  306: you do not want to use @code{/} or @code{/mod} with its undefined
  307: behaviour, but rather @code{fm/mod} or @code{sm/mod} (probably the
  308: former).
  309: 
  310: @subsection Single precision
  311: +
  312: -
  313: *
  314: /
  315: mod
  316: /mod
  317: negate
  318: abs
  319: min
  320: max
  321: 
  322: @subsection Bitwise operations
  323: and
  324: or
  325: xor
  326: invert
  327: 2*
  328: 2/
  329: 
  330: @subsection Mixed precision
  331: m+
  332: */
  333: */mod
  334: m*
  335: um*
  336: m*/
  337: um/mod
  338: fm/mod
  339: sm/rem
  340: 
  341: @subsection Double precision
  342: d+
  343: d-
  344: dnegate
  345: dabs
  346: dmin
  347: dmax
  348: 
  349: @node Stack Manipulation,,,
  350: @section Stack Manipulation
  351: 
  352: gforth has a data stack (aka parameter stack) for characters, cells,
  353: addresses, and double cells, a floating point stack for floating point
  354: numbers, a return stack for storing the return addresses of colon
  355: definitions and other data, and a locals stack for storing local
  356: variables. Note that while every sane Forth has a separate floating
  357: point stack, this is not strictly required; an ANS Forth system could
  358: theoretically keep floating point numbers on the data stack. As an
  359: additional difficulty, you don't know how many cells a floating point
  360: numkber takes. It is reportedly possible to write words in a way that
  361: they work also for a unified stack model, but we do not recommend trying
  362: it. Also, a Forth system is allowed to keep the local variables on the
  363: return stack. This is reasonable, as local variables usually eliminate
  364: the need to use the return stack explicitely. So, if you want to produce
  365: a standard complying program and if you are using local variables in a
  366: word, forget about return stack manipulations in that word (see the
  367: standard document for the exact rules).
  368: 
  369: @subsection Data stack
  370: drop
  371: nip
  372: dup
  373: over
  374: tuck
  375: swap
  376: rot
  377: -rot
  378: ?dup
  379: pick
  380: roll
  381: 2drop
  382: 2nip
  383: 2dup
  384: 2over
  385: 2tuck
  386: 2swap
  387: 2rot
  388: 
  389: @subsection Floating point stack
  390: fdrop
  391: fnip
  392: fdup
  393: fover
  394: ftuck
  395: fswap
  396: frot
  397: 
  398: @subsection Return stack
  399: >r
  400: r>
  401: r@
  402: rdrop
  403: 2>r
  404: 2r>
  405: 
  406: @subsection Locals stack
  407: 
  408: @subsection Stack pointer manipulation
  409: sp@
  410: sp!
  411: fp@
  412: fp!
  413: rp@
  414: rp!
  415: lp@
  416: lp!
  417: 
  418: @node Memory access
  419: @section Memory access
  420: 
  421: @subsection Stack-Memory transfers
  422: @
  423: !
  424: +!
  425: c@
  426: c!
  427: 2@
  428: 2!
  429: f@
  430: f!
  431: sf@
  432: sf!
  433: df@
  434: df!
  435: 
  436: @subsection Memory block access
  437: 
  438: move
  439: erase
  440: 
  441: While the previous words work on address units, the rest works on
  442: characters.
  443: 
  444: cmove
  445: cmove>
  446: fill
  447: blank
  448: 
  449: @node Control Structures
  450: @section Control Structures
  451: 
  452: Control structures in Forth cannot be used in interpret state, only in
  453: compile state, i.e., in a colon definition. We do not like this
  454: limitation, but have not seen a satisfying way around it yet, although
  455: many schemes have been proposed.
  456: 
  457: @subsection Selection
  458: 
  459: @example
  460: @var{flag}
  461: IF
  462:   @var{code}
  463: ENDIF
  464: @end example
  465: or
  466: @example
  467: @var{flag}
  468: IF
  469:   @var{code1}
  470: ELSE
  471:   @var{code2}
  472: ENDIF
  473: @end example
  474: 
  475: You can use @code{THEN} instead of {ENDIF}. Indeed, @code{THEN} is
  476: standard, and @code{ENDIF} is not, although it is quite popular. We
  477: recommend using @code{ENDIF}, because it is less confusing for people
  478: who also know other languages (and is not prone to reinforcing negative
  479: prejudices against Forth in these people). Adding @code{ENDIF} to a
  480: system that only supplies @code{THEN} is simple:
  481: @example
  482: : endif   POSTPONE then ; immediate
  483: @end example
  484: 
  485: [According to @cite{Webster's New Encyclopedic Dictionary}, @dfn{then
  486: (adv.)}  has the following meanings:
  487: @quotation
  488: ... 2b: following next after in order ... 3d: as a necessary consequence
  489: (if you were there, then you saw them).
  490: @end quotation
  491: Forth's @code{THEN} has the meaning 2b, @code{THEN} in Pascal
  492: and many other programming languages has the meaning 3d.]
  493: 
  494: We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you
  495: can avoid using @code{?dup}.
  496: 
  497: @example
  498: @var{n}
  499: CASE
  500:   @var{n1} OF @var{code1} ENDOF
  501:   @var{n2} OF @var{code2} ENDOF
  502:   @dots
  503: ENDCASE
  504: @end example
  505: 
  506: Executes the first @var{codei}, where the @var{ni} is equal to
  507: @var{n}. A default case can be added by simply writing the code after
  508: the last @code{ENDOF}. It may use @var{n}, which is on top of the stack,
  509: but must not consume it.
  510: 
  511: @subsection Simple Loops
  512: 
  513: @example
  514: BEGIN
  515:   @var{code1}
  516:   @var{flag}
  517: WHILE
  518:   @var{code2}
  519: REPEAT
  520: @end example
  521: 
  522: @var{code1} is executed and @var{flag} is computed. If it is true,
  523: @var{code2} is executed and the loop is restarted; If @var{flag} is false, execution continues after the @code{REPEAT}.
  524: 
  525: @example
  526: BEGIN
  527:   @var{code}
  528:   @var{flag}
  529: UNTIL
  530: @end example
  531: 
  532: @var{code} is executed. The loop is restarted if @code{flag} is false.
  533: 
  534: @example
  535: BEGIN
  536:   @var{code}
  537: AGAIN
  538: @end example
  539: 
  540: This is an endless loop.
  541: 
  542: @subsection Counted Loops
  543: 
  544: The basic counted loop is:
  545: @example
  546: @var{limit} @var{start}
  547: ?DO
  548:   @var{body}
  549: LOOP
  550: @end example
  551: 
  552: This performs one iteration for every integer, starting from @var{start}
  553: and up to, but excluding @var{limit}. The counter, aka index, can be
  554: accessed with @code{i}. E.g., the loop
  555: @example
  556: 10 0 ?DO
  557:   i .
  558: LOOP
  559: @end example
  560: prints
  561: @example
  562: 0 1 2 3 4 5 6 7 8 9
  563: @end example
  564: The index of the innermost loop can be accessed with @code{i}, the index
  565: of the next loop with @code{j}, and the index of the third loop with
  566: @code{k}.
  567: 
  568: The loop control data are kept on the return stack, so there are some
  569: restrictions on mixing return stack accesses and counted loop
  570: words. E.g., if you put values on the return stack outside the loop, you
  571: cannot read them inside the loop. If you put values on the return stack
  572: within a loop, you have to remove them before the end of the loop and
  573: before accessing the index of the loop.
  574: 
  575: There are several variations on the counted loop:
  576: 
  577: @code{LEAVE} leaves the innermost counted loop immediately.
  578: 
  579: @code{LOOP} can be replaced with @code{@var{n} +LOOP}; this updates the
  580: index by @var{n} instead of by 1. The loop is terminated when the border
  581: between @var{limit-1} and @var{limit} is crossed. E.g.:
  582: 
  583: 4 0 ?DO  i .  2 +LOOP   prints 0 2
  584: 
  585: 4 1 ?DO  i .  2 +LOOP   prints 1 3
  586: 
  587: The behaviour of @code{@var{n} +LOOP} is peculiar when @var{n} is negative:
  588: 
  589: -1 0 ?DO  i .  -1 +LOOP  prints 0 -1
  590: 
  591:  0 0 ?DO  i .  -1 +LOOP  prints nothing
  592: 
  593: Therefore we recommend avoiding using @code{@var{n} +LOOP} with negative
  594: @var{n}. One alternative is @code{@var{n} S+LOOP}, where the negative
  595: case behaves symmetrical to the positive case:
  596: 
  597: -2 0 ?DO  i .  -1 +LOOP  prints 0 -1
  598: 
  599: -1 0 ?DO  i .  -1 +LOOP  prints 0
  600: 
  601:  0 0 ?DO  i .  -1 +LOOP  prints nothing
  602: 
  603: The loop is terminated when the border between @var{limit-sgn(n)} and
  604: @var{limit} is crossed. However, @code{S+LOOP} is not part of the ANS
  605: Forth standard.
  606: 
  607: @code{?DO} can be replaced by @code{DO}. @code{DO} enters the loop even
  608: when the start and the limit value are equal. We do not recommend using
  609: @code{DO}. It will just give you maintenance troubles.
  610: 
  611: @code{UNLOOP} is used to prepare for an abnormal loop exit, e.g., via
  612: @code{EXIT}. @code{UNLOOP} removes the loop control parameters from the
  613: return stack so @code{EXIT} can get to its return address.
  614: 
  615: Another counted loop is
  616: @example
  617: @var{n}
  618: FOR
  619:   @var{body}
  620: NEXT
  621: @end example
  622: This is the preferred loop of native code compiler writers who are too
  623: lazy to optimize @code{?DO} loops properly. In GNU Forth, this loop
  624: iterates @var{n+1} times; @code{i} produces values starting with @var{n}
  625: and ending with 0. Other Forth systems may differently, even if they
  626: support @code{FOR} loops.
  627: 
  628: 
  629: @contents
  630: @bye
  631: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>