File:  [gforth] / gforth / Attic / gforth.texi
Revision 1.7: download - view: text, annotated - select for diffs
Mon Sep 5 17:36:19 1994 UTC (27 years ago) by anton
Branches: MAIN
CVS tags: HEAD
Added proper option processing to main.c
image and source files are now searched in $GFORTHPATH

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

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