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>
![[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