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