Annotation of gforth/gforth.texi, revision 1.7
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
1.5 anton 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:
1.1 anton 111:
1.5 anton 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:
1.1 anton 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
1.6 anton 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.
1.1 anton 170:
171: @node Invocation, Words, Other Books, Top
172: @chapter Invocation
173:
1.7 ! anton 174: You will usually just say @code{gforth}. In many other cases the default
! 175: GNU Forth image will be invoked like this:
1.1 anton 176:
177: @example
1.7 ! anton 178: gforth [files] [-e forth-code]
1.1 anton 179: @end example
180:
1.7 ! anton 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).
1.1 anton 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:
1.3 anton 276: The Forth words are described in this section in the glossary notation
1.1 anton 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
1.5 anton 322: Bool, i.e. @code{false} or @code{true}.
1.1 anton 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
1.6 anton 417: number takes. It is reportedly possible to write words in a way that
1.1 anton 418: they work also for a unified stack model, but we do not recommend trying
1.3 anton 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
1.6 anton 421: the need to use the return stack explicitly. So, if you want to produce
1.3 anton 422: a standard complying program and if you are using local variables in a
1.1 anton 423: word, forget about return stack manipulations in that word (see the
424: standard document for the exact rules).
425:
1.2 pazsan 426: @subsection Data stack
1.1 anton 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>
1.6 anton 462: 2r@
463: 2rdrop
1.1 anton 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
1.5 anton 498: erase
499:
500: While the previous words work on address units, the rest works on
501: characters.
502:
503: cmove
504: cmove>
1.1 anton 505: fill
1.5 anton 506: blank
1.1 anton 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
1.3 anton 524: or
1.1 anton 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:
1.5 anton 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.]
1.4 anton 552:
1.5 anton 553: We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you
1.1 anton 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
1.3 anton 643:
1.1 anton 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
1.3 anton 649:
1.1 anton 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
1.3 anton 657:
1.1 anton 658: -1 0 ?DO i . -1 +LOOP prints 0
1.3 anton 659:
1.1 anton 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:
1.4 anton 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.
1.1 anton 669:
1.5 anton 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:
1.1 anton 687:
688: @contents
689: @bye
690:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to gforth.texi CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [gforth] / gforth