Annotation of gforth/gforth.texi, revision 1.5
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
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:
1.3 anton 219: The Forth words are described in this section in the glossary notation
1.1 anton 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
1.5 ! anton 265: Bool, i.e. @code{false} or @code{true}.
1.1 anton 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
1.3 anton 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
1.1 anton 366: word, forget about return stack manipulations in that word (see the
367: standard document for the exact rules).
368:
1.2 pazsan 369: @subsection Data stack
1.1 anton 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
1.5 ! anton 439: erase
! 440:
! 441: While the previous words work on address units, the rest works on
! 442: characters.
! 443:
! 444: cmove
! 445: cmove>
1.1 anton 446: fill
1.5 ! anton 447: blank
1.1 anton 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
1.3 anton 465: or
1.1 anton 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:
1.5 ! anton 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.]
1.4 anton 493:
1.5 ! anton 494: We also provide the words @code{?dup-if} and @code{?dup-0=-if}, so you
1.1 anton 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
1.3 anton 584:
1.1 anton 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
1.3 anton 590:
1.1 anton 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
1.3 anton 598:
1.1 anton 599: -1 0 ?DO i . -1 +LOOP prints 0
1.3 anton 600:
1.1 anton 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:
1.4 anton 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.
1.1 anton 610:
1.5 ! anton 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:
1.1 anton 628:
629: @contents
630: @bye
631:
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