[gforth] / gforth / doc / gforth.ds

gforth: gforth/doc/gforth.ds

1 :	anton	1.1	\input texinfo @c --texinfo--
2 :			@comment The source is gforth.ds, from which gforth.texi is generated
3 :	crook	1.28
4 :	crook	1.21	@comment TODO: nac29jan99 - a list of things to add in the next edit:
5 :	crook	1.28	@comment 1. x-ref all ambiguous or implementation-defined features?
6 :			@comment 2. Describe the use of Auser Avariable AConstant A, etc.
7 :			@comment 3. words in miscellaneous section need a home.
8 :			@comment 4. search for TODO for other minor and major works required.
9 :			@comment 5. [rats] change all @var to @i in Forth source so that info
10 :			@comment file looks decent.
11 :	anton	1.36	@c Not an improvement IMO - anton
12 :			@c and anyway, this should be taken up
13 :			@c with Karl Berry (the texinfo guy) - anton
14 :	crook	1.29	@comment .. would be useful to have a word that identified all deferred words
15 :			@comment should semantics stuff in intro be moved to another section
16 :
17 :	crook	1.28
18 :	anton	1.1	@comment %**start of header (This is for running Texinfo on a region.)
19 :			@setfilename gforth.info
20 :			@settitle Gforth Manual
21 :			@dircategory GNU programming tools
22 :			@direntry
23 :			* Gforth: (gforth). A fast interpreter for the Forth language.
24 :			@end direntry
25 :	anton	1.49	@c The Texinfo manual also recommends doing this, but for Gforth it may
26 :			@c not make much sense
27 :			@c @dircategory Individual utilities
28 :			@c @direntry
29 :			@c * Gforth: (gforth)Invoking Gforth. gforth, gforth-fast, gforthmi
30 :			@c @end direntry
31 :
32 :	anton	1.1	@comment @setchapternewpage odd
33 :	crook	1.29	@comment TODO this gets left in by HTML converter
34 :	anton	1.12	@macro progstyle {}
35 :			Programming style note:
36 :	anton	1.3	@end macro
37 :	anton	1.48
38 :			@macro assignment {}
39 :			@table @i
40 :			@item Assignment:
41 :			@end macro
42 :			@macro endassignment {}
43 :			@end table
44 :			@end macro
45 :
46 :	anton	1.1	@comment %**end of header (This is for running Texinfo on a region.)
47 :
48 :	crook	1.29
49 :			@comment ----------------------------------------------------------
50 :			@comment macros for beautifying glossary entries
51 :			@comment if these are used, need to strip them out for HTML converter
52 :			@comment else they get repeated verbatim in HTML output.
53 :			@comment .. not working yet.
54 :
55 :			@macro GLOSS-START {}
56 :			@iftex
57 :			@ninerm
58 :			@end iftex
59 :			@end macro
60 :
61 :			@macro GLOSS-END {}
62 :			@iftex
63 :			@rm
64 :			@end iftex
65 :			@end macro
66 :
67 :			@comment ----------------------------------------------------------
68 :
69 :
70 :	anton	1.10	@include version.texi
71 :
72 :	anton	1.49	@ifnottex
73 :	anton	1.11	This file documents Gforth @value{VERSION}
74 :	anton	1.1
75 :	crook	1.26	Copyright @copyright{} 1995-1999 Free Software Foundation, Inc.
76 :	anton	1.1
77 :			Permission is granted to make and distribute verbatim copies of
78 :			this manual provided the copyright notice and this permission notice
79 :			are preserved on all copies.
80 :
81 :			@ignore
82 :			Permission is granted to process this file through TeX and print the
83 :			results, provided the printed document carries a copying permission
84 :			notice identical to this one except for the removal of this paragraph
85 :			(this paragraph not being relevant to the printed manual).
86 :
87 :			@end ignore
88 :			Permission is granted to copy and distribute modified versions of this
89 :			manual under the conditions for verbatim copying, provided also that the
90 :			sections entitled "Distribution" and "General Public License" are
91 :			included exactly as in the original, and provided that the entire
92 :			resulting derived work is distributed under the terms of a permission
93 :			notice identical to this one.
94 :
95 :			Permission is granted to copy and distribute translations of this manual
96 :			into another language, under the above conditions for modified versions,
97 :			except that the sections entitled "Distribution" and "General Public
98 :			License" may be included in a translation approved by the author instead
99 :			of in the original English.
100 :	anton	1.49	@end ifnottex
101 :	anton	1.1
102 :			@finalout
103 :			@titlepage
104 :			@sp 10
105 :			@center @titlefont{Gforth Manual}
106 :			@sp 2
107 :	anton	1.11	@center for version @value{VERSION}
108 :	anton	1.1	@sp 2
109 :	anton	1.34	@center Neal Crook
110 :	anton	1.1	@center Anton Ertl
111 :	pazsan	1.6	@center Bernd Paysan
112 :	anton	1.5	@center Jens Wilke
113 :	anton	1.1	@sp 3
114 :	crook	1.47	@center This manual is permanently under construction and was last updated on 15-Mar-2000
115 :	anton	1.1
116 :			@comment The following two commands start the copyright page.
117 :			@page
118 :			@vskip 0pt plus 1filll
119 :	crook	1.29	Copyright @copyright{} 1995--1999 Free Software Foundation, Inc.
120 :	anton	1.1
121 :			@comment !! Published by ... or You can get a copy of this manual ...
122 :
123 :			Permission is granted to make and distribute verbatim copies of
124 :			this manual provided the copyright notice and this permission notice
125 :			are preserved on all copies.
126 :
127 :			Permission is granted to copy and distribute modified versions of this
128 :			manual under the conditions for verbatim copying, provided also that the
129 :			sections entitled "Distribution" and "General Public License" are
130 :			included exactly as in the original, and provided that the entire
131 :			resulting derived work is distributed under the terms of a permission
132 :			notice identical to this one.
133 :
134 :			Permission is granted to copy and distribute translations of this manual
135 :			into another language, under the above conditions for modified versions,
136 :			except that the sections entitled "Distribution" and "General Public
137 :			License" may be included in a translation approved by the author instead
138 :			of in the original English.
139 :			@end titlepage
140 :
141 :			@node Top, License, (dir), (dir)
142 :	anton	1.49	@ifnottex
143 :	anton	1.1	Gforth is a free implementation of ANS Forth available on many
144 :	anton	1.11	personal machines. This manual corresponds to version @value{VERSION}.
145 :	anton	1.49	@end ifnottex
146 :	anton	1.1
147 :			@menu
148 :	crook	1.21	* License:: The GPL
149 :	crook	1.26	* Goals:: About the Gforth Project
150 :	crook	1.29	* Gforth Environment:: Starting (and exiting) Gforth
151 :	anton	1.48	* Tutorial:: Hands-on Forth Tutorial
152 :	crook	1.21	* Introduction:: An introduction to ANS Forth
153 :	anton	1.1	* Words:: Forth words available in Gforth
154 :	anton	1.24	* Error messages:: How to interpret them
155 :	anton	1.1	* Tools:: Programming tools
156 :			* ANS conformance:: Implementation-defined options etc.
157 :			* Model:: The abstract machine of Gforth
158 :			* Integrating Gforth:: Forth as scripting language for applications
159 :			* Emacs and Gforth:: The Gforth Mode
160 :			* Image Files:: @code{.fi} files contain compiled code
161 :			* Engine:: The inner interpreter and the primitives
162 :	anton	1.24	* Binding to System Library::
163 :	pazsan	1.13	* Cross Compiler:: The Cross Compiler
164 :	anton	1.1	* Bugs:: How to report them
165 :			* Origin:: Authors and ancestors of Gforth
166 :	crook	1.21	* Forth-related information:: Books and places to look on the WWW
167 :	anton	1.1	* Word Index:: An item for each Forth word
168 :	anton	1.41	* Name Index:: Forth words, only names listed
169 :	anton	1.1	* Concept Index:: A menu covering many topics
170 :	anton	1.12
171 :	anton	1.48	@detailmenu --- The Detailed Node Listing ---
172 :	anton	1.12
173 :	crook	1.26	Goals of Gforth
174 :
175 :			* Gforth Extensions Sinful?::
176 :
177 :	crook	1.29	Gforth Environment
178 :
179 :	anton	1.32	* Invoking Gforth:: Getting in
180 :			* Leaving Gforth:: Getting out
181 :			* Command-line editing::
182 :	anton	1.48	* Upper and lower case::
183 :			* Environment variables:: that affect how Gforth starts up
184 :	anton	1.32	* Gforth Files:: What gets installed and where
185 :	anton	1.48	* Startup speed:: When 35ms is not fast enough ...
186 :
187 :			Forth Tutorial
188 :
189 :			* Starting Gforth Tutorial::
190 :			* Syntax Tutorial::
191 :			* Crash Course Tutorial::
192 :			* Stack Tutorial::
193 :			* Arithmetics Tutorial::
194 :			* Stack Manipulation Tutorial::
195 :			* Using files for Forth code Tutorial::
196 :			* Comments Tutorial::
197 :			* Colon Definitions Tutorial::
198 :			* Decompilation Tutorial::
199 :			* Stack-Effect Comments Tutorial::
200 :			* Types Tutorial::
201 :			* Factoring Tutorial::
202 :			* Designing the stack effect Tutorial::
203 :			* Local Variables Tutorial::
204 :			* Conditional execution Tutorial::
205 :			* Flags and Comparisons Tutorial::
206 :			* General Loops Tutorial::
207 :			* Counted loops Tutorial::
208 :			* Recursion Tutorial::
209 :			* Leaving definitions or loops Tutorial::
210 :			* Return Stack Tutorial::
211 :			* Memory Tutorial::
212 :			* Characters and Strings Tutorial::
213 :			* Alignment Tutorial::
214 :			* Interpretation and Compilation Semantics and Immediacy Tutorial::
215 :			* Execution Tokens Tutorial::
216 :			* Exceptions Tutorial::
217 :			* Defining Words Tutorial::
218 :			* Arrays and Records Tutorial::
219 :			* POSTPONE Tutorial::
220 :			* Literal Tutorial::
221 :			* Advanced macros Tutorial::
222 :			* Compilation Tokens Tutorial::
223 :			* Wordlists and Search Order Tutorial::
224 :	crook	1.29
225 :	anton	1.24	An Introduction to ANS Forth
226 :
227 :			* Introducing the Text Interpreter::
228 :			* Stacks and Postfix notation::
229 :			* Your first definition::
230 :			* How does that work?::
231 :			* Forth is written in Forth::
232 :			* Review - elements of a Forth system::
233 :	crook	1.29	* Where to go next::
234 :	anton	1.24	* Exercises::
235 :
236 :	anton	1.12	Forth Words
237 :
238 :			* Notation::
239 :	crook	1.21	* Comments::
240 :			* Boolean Flags::
241 :	anton	1.12	* Arithmetic::
242 :			* Stack Manipulation::
243 :			* Memory::
244 :			* Control Structures::
245 :			* Defining Words::
246 :	crook	1.47	* Interpretation and Compilation Semantics::
247 :			* Tokens for Words::
248 :	crook	1.21	* The Text Interpreter::
249 :			* Word Lists::
250 :			* Environmental Queries::
251 :	anton	1.12	* Files::
252 :			* Blocks::
253 :			* Other I/O::
254 :			* Programming Tools::
255 :			* Assembler and Code Words::
256 :			* Threading Words::
257 :	crook	1.26	* Locals::
258 :			* Structures::
259 :			* Object-oriented Forth::
260 :	crook	1.21	* Passing Commands to the OS::
261 :	crook	1.47	* Keeping track of Time::
262 :	crook	1.21	* Miscellaneous Words::
263 :	anton	1.12
264 :			Arithmetic
265 :
266 :			* Single precision::
267 :			* Bitwise operations::
268 :	crook	1.21	* Double precision:: Double-cell integer arithmetic
269 :			* Numeric comparison::
270 :	anton	1.32	* Mixed precision:: Operations with single and double-cell integers
271 :	anton	1.12	* Floating Point::
272 :
273 :			Stack Manipulation
274 :
275 :			* Data stack::
276 :			* Floating point stack::
277 :			* Return stack::
278 :			* Locals stack::
279 :			* Stack pointer manipulation::
280 :
281 :			Memory
282 :
283 :	anton	1.32	* Memory model::
284 :			* Dictionary allocation::
285 :			* Heap Allocation::
286 :			* Memory Access::
287 :			* Address arithmetic::
288 :			* Memory Blocks::
289 :	anton	1.12
290 :			Control Structures
291 :
292 :	anton	1.41	* Selection:: IF ... ELSE ... ENDIF
293 :			* Simple Loops:: BEGIN ...
294 :	anton	1.32	* Counted Loops:: DO
295 :			* Arbitrary control structures::
296 :			* Calls and returns::
297 :	anton	1.12	* Exception Handling::
298 :
299 :			Defining Words
300 :
301 :	crook	1.45	* CREATE::
302 :	crook	1.44	* Variables:: Variables and user variables
303 :			* Constants::
304 :			* Values:: Initialised variables
305 :	anton	1.32	* Colon Definitions::
306 :	crook	1.44	* Anonymous Definitions:: Definitions without names
307 :	anton	1.32	* User-defined Defining Words::
308 :	crook	1.44	* Deferred words:: Allow forward references
309 :			* Aliases::
310 :	anton	1.32	* Supplying names::
311 :	crook	1.47
312 :			Interpretation and Compilation Semantics
313 :
314 :	crook	1.44	* Combined words::
315 :	anton	1.12
316 :	crook	1.21	The Text Interpreter
317 :
318 :	crook	1.29	* Input Sources::
319 :	crook	1.21	* Number Conversion::
320 :			* Interpret/Compile states::
321 :			* Literals::
322 :			* Interpreter Directives::
323 :
324 :	crook	1.26	Word Lists
325 :
326 :			* Why use word lists?::
327 :			* Word list examples::
328 :
329 :			Files
330 :
331 :	anton	1.48	* Forth source files::
332 :			* General files::
333 :			* Search Paths::
334 :
335 :			Search Paths
336 :
337 :			* Forth Search Paths::
338 :	crook	1.26	* General Search Paths::
339 :
340 :			Other I/O
341 :
342 :	anton	1.32	* Simple numeric output:: Predefined formats
343 :			* Formatted numeric output:: Formatted (pictured) output
344 :			* String Formats:: How Forth stores strings in memory
345 :			* Displaying characters and strings:: Other stuff
346 :			* Input:: Input
347 :	crook	1.26
348 :			Programming Tools
349 :
350 :			* Debugging:: Simple and quick.
351 :			* Assertions:: Making your programs self-checking.
352 :	pazsan	1.46	* Singlestep Debugger:: Executing your program word by word.
353 :	crook	1.26
354 :			Locals
355 :
356 :			* Gforth locals::
357 :			* ANS Forth locals::
358 :
359 :			Gforth locals
360 :
361 :			* Where are locals visible by name?::
362 :			* How long do locals live?::
363 :			* Programming Style::
364 :			* Implementation::
365 :
366 :	anton	1.12	Structures
367 :
368 :			* Why explicit structure support?::
369 :			* Structure Usage::
370 :			* Structure Naming Convention::
371 :			* Structure Implementation::
372 :			* Structure Glossary::
373 :
374 :			Object-oriented Forth
375 :
376 :	anton	1.48	* Why object-oriented programming?::
377 :			* Object-Oriented Terminology::
378 :			* Objects::
379 :			* OOF::
380 :			* Mini-OOF::
381 :	crook	1.23	* Comparison with other object models::
382 :	anton	1.12
383 :	anton	1.24	The @file{objects.fs} model
384 :	anton	1.12
385 :			* Properties of the Objects model::
386 :			* Basic Objects Usage::
387 :	anton	1.41	* The Objects base class::
388 :	anton	1.12	* Creating objects::
389 :			* Object-Oriented Programming Style::
390 :			* Class Binding::
391 :			* Method conveniences::
392 :			* Classes and Scoping::
393 :	anton	1.41	* Dividing classes::
394 :	anton	1.12	* Object Interfaces::
395 :			* Objects Implementation::
396 :			* Objects Glossary::
397 :
398 :	anton	1.24	The @file{oof.fs} model
399 :	anton	1.12
400 :			* Properties of the OOF model::
401 :			* Basic OOF Usage::
402 :	crook	1.23	* The OOF base class::
403 :	anton	1.12	* Class Declaration::
404 :			* Class Implementation::
405 :
406 :	anton	1.24	The @file{mini-oof.fs} model
407 :	crook	1.23
408 :	anton	1.48	* Basic Mini-OOF Usage::
409 :			* Mini-OOF Example::
410 :			* Mini-OOF Implementation::
411 :			* Comparison with other object models::
412 :	crook	1.23
413 :	anton	1.12	Tools
414 :
415 :			* ANS Report:: Report the words used, sorted by wordset.
416 :
417 :			ANS conformance
418 :
419 :			* The Core Words::
420 :			* The optional Block word set::
421 :			* The optional Double Number word set::
422 :			* The optional Exception word set::
423 :			* The optional Facility word set::
424 :			* The optional File-Access word set::
425 :			* The optional Floating-Point word set::
426 :			* The optional Locals word set::
427 :			* The optional Memory-Allocation word set::
428 :			* The optional Programming-Tools word set::
429 :			* The optional Search-Order word set::
430 :
431 :			The Core Words
432 :
433 :			* core-idef:: Implementation Defined Options
434 :			* core-ambcond:: Ambiguous Conditions
435 :			* core-other:: Other System Documentation
436 :
437 :			The optional Block word set
438 :
439 :			* block-idef:: Implementation Defined Options
440 :			* block-ambcond:: Ambiguous Conditions
441 :			* block-other:: Other System Documentation
442 :
443 :			The optional Double Number word set
444 :
445 :			* double-ambcond:: Ambiguous Conditions
446 :
447 :			The optional Exception word set
448 :
449 :			* exception-idef:: Implementation Defined Options
450 :
451 :			The optional Facility word set
452 :
453 :			* facility-idef:: Implementation Defined Options
454 :			* facility-ambcond:: Ambiguous Conditions
455 :
456 :			The optional File-Access word set
457 :
458 :			* file-idef:: Implementation Defined Options
459 :			* file-ambcond:: Ambiguous Conditions
460 :
461 :			The optional Floating-Point word set
462 :
463 :			* floating-idef:: Implementation Defined Options
464 :			* floating-ambcond:: Ambiguous Conditions
465 :
466 :			The optional Locals word set
467 :
468 :			* locals-idef:: Implementation Defined Options
469 :			* locals-ambcond:: Ambiguous Conditions
470 :
471 :			The optional Memory-Allocation word set
472 :
473 :			* memory-idef:: Implementation Defined Options
474 :
475 :			The optional Programming-Tools word set
476 :
477 :			* programming-idef:: Implementation Defined Options
478 :			* programming-ambcond:: Ambiguous Conditions
479 :
480 :			The optional Search-Order word set
481 :
482 :			* search-idef:: Implementation Defined Options
483 :			* search-ambcond:: Ambiguous Conditions
484 :
485 :			Image Files
486 :
487 :	anton	1.24	* Image Licensing Issues:: Distribution terms for images.
488 :			* Image File Background:: Why have image files?
489 :	anton	1.32	* Non-Relocatable Image Files:: don't always work.
490 :	anton	1.24	* Data-Relocatable Image Files:: are better.
491 :	anton	1.32	* Fully Relocatable Image Files:: better yet.
492 :	anton	1.24	* Stack and Dictionary Sizes:: Setting the default sizes for an image.
493 :	anton	1.32	* Running Image Files:: @code{gforth -i @i{file}} or @i{file}.
494 :	anton	1.24	* Modifying the Startup Sequence:: and turnkey applications.
495 :	anton	1.12
496 :			Fully Relocatable Image Files
497 :
498 :	crook	1.27	* gforthmi:: The normal way
499 :	anton	1.12	* cross.fs:: The hard way
500 :
501 :			Engine
502 :
503 :			* Portability::
504 :			* Threading::
505 :			* Primitives::
506 :			* Performance::
507 :
508 :			Threading
509 :
510 :			* Scheduling::
511 :			* Direct or Indirect Threaded?::
512 :			* DOES>::
513 :
514 :			Primitives
515 :
516 :			* Automatic Generation::
517 :			* TOS Optimization::
518 :			* Produced code::
519 :	pazsan	1.13
520 :			Cross Compiler
521 :
522 :			* Using the Cross Compiler::
523 :			* How the Cross Compiler Works::
524 :
525 :	anton	1.24	Other Forth-related information
526 :	crook	1.21
527 :			* Internet resources::
528 :			* Books::
529 :			* The Forth Interest Group::
530 :			* Conferences::
531 :
532 :	anton	1.24	@end detailmenu
533 :	anton	1.1	@end menu
534 :
535 :	crook	1.26	@node License, Goals, Top, Top
536 :	anton	1.1	@unnumbered GNU GENERAL PUBLIC LICENSE
537 :			@center Version 2, June 1991
538 :
539 :			@display
540 :			Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
541 :			675 Mass Ave, Cambridge, MA 02139, USA
542 :
543 :			Everyone is permitted to copy and distribute verbatim copies
544 :			of this license document, but changing it is not allowed.
545 :			@end display
546 :
547 :			@unnumberedsec Preamble
548 :
549 :			The licenses for most software are designed to take away your
550 :			freedom to share and change it. By contrast, the GNU General Public
551 :			License is intended to guarantee your freedom to share and change free
552 :			software---to make sure the software is free for all its users. This
553 :			General Public License applies to most of the Free Software
554 :			Foundation's software and to any other program whose authors commit to
555 :			using it. (Some other Free Software Foundation software is covered by
556 :			the GNU Library General Public License instead.) You can apply it to
557 :			your programs, too.
558 :
559 :			When we speak of free software, we are referring to freedom, not
560 :			price. Our General Public Licenses are designed to make sure that you
561 :			have the freedom to distribute copies of free software (and charge for
562 :			this service if you wish), that you receive source code or can get it
563 :			if you want it, that you can change the software or use pieces of it
564 :			in new free programs; and that you know you can do these things.
565 :
566 :			To protect your rights, we need to make restrictions that forbid
567 :			anyone to deny you these rights or to ask you to surrender the rights.
568 :			These restrictions translate to certain responsibilities for you if you
569 :			distribute copies of the software, or if you modify it.
570 :
571 :			For example, if you distribute copies of such a program, whether
572 :			gratis or for a fee, you must give the recipients all the rights that
573 :			you have. You must make sure that they, too, receive or can get the
574 :			source code. And you must show them these terms so they know their
575 :			rights.
576 :
577 :			We protect your rights with two steps: (1) copyright the software, and
578 :			(2) offer you this license which gives you legal permission to copy,
579 :			distribute and/or modify the software.
580 :
581 :			Also, for each author's protection and ours, we want to make certain
582 :			that everyone understands that there is no warranty for this free
583 :			software. If the software is modified by someone else and passed on, we
584 :			want its recipients to know that what they have is not the original, so
585 :			that any problems introduced by others will not reflect on the original
586 :			authors' reputations.
587 :
588 :			Finally, any free program is threatened constantly by software
589 :			patents. We wish to avoid the danger that redistributors of a free
590 :			program will individually obtain patent licenses, in effect making the
591 :			program proprietary. To prevent this, we have made it clear that any
592 :			patent must be licensed for everyone's free use or not licensed at all.
593 :
594 :			The precise terms and conditions for copying, distribution and
595 :			modification follow.
596 :
597 :			@iftex
598 :			@unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
599 :			@end iftex
600 :	anton	1.49	@ifnottex
601 :	anton	1.1	@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
602 :	anton	1.49	@end ifnottex
603 :	anton	1.1
604 :			@enumerate 0
605 :			@item
606 :			This License applies to any program or other work which contains
607 :			a notice placed by the copyright holder saying it may be distributed
608 :			under the terms of this General Public License. The ``Program'', below,
609 :			refers to any such program or work, and a ``work based on the Program''
610 :			means either the Program or any derivative work under copyright law:
611 :			that is to say, a work containing the Program or a portion of it,
612 :			either verbatim or with modifications and/or translated into another
613 :			language. (Hereinafter, translation is included without limitation in
614 :			the term ``modification''.) Each licensee is addressed as ``you''.
615 :
616 :			Activities other than copying, distribution and modification are not
617 :			covered by this License; they are outside its scope. The act of
618 :			running the Program is not restricted, and the output from the Program
619 :			is covered only if its contents constitute a work based on the
620 :			Program (independent of having been made by running the Program).
621 :			Whether that is true depends on what the Program does.
622 :
623 :			@item
624 :			You may copy and distribute verbatim copies of the Program's
625 :			source code as you receive it, in any medium, provided that you
626 :			conspicuously and appropriately publish on each copy an appropriate
627 :			copyright notice and disclaimer of warranty; keep intact all the
628 :			notices that refer to this License and to the absence of any warranty;
629 :			and give any other recipients of the Program a copy of this License
630 :			along with the Program.
631 :
632 :			You may charge a fee for the physical act of transferring a copy, and
633 :			you may at your option offer warranty protection in exchange for a fee.
634 :
635 :			@item
636 :			You may modify your copy or copies of the Program or any portion
637 :			of it, thus forming a work based on the Program, and copy and
638 :			distribute such modifications or work under the terms of Section 1
639 :			above, provided that you also meet all of these conditions:
640 :
641 :			@enumerate a
642 :			@item
643 :			You must cause the modified files to carry prominent notices
644 :			stating that you changed the files and the date of any change.
645 :
646 :			@item
647 :			You must cause any work that you distribute or publish, that in
648 :			whole or in part contains or is derived from the Program or any
649 :			part thereof, to be licensed as a whole at no charge to all third
650 :			parties under the terms of this License.
651 :
652 :			@item
653 :			If the modified program normally reads commands interactively
654 :			when run, you must cause it, when started running for such
655 :			interactive use in the most ordinary way, to print or display an
656 :			announcement including an appropriate copyright notice and a
657 :			notice that there is no warranty (or else, saying that you provide
658 :			a warranty) and that users may redistribute the program under
659 :			these conditions, and telling the user how to view a copy of this
660 :			License. (Exception: if the Program itself is interactive but
661 :			does not normally print such an announcement, your work based on
662 :			the Program is not required to print an announcement.)
663 :			@end enumerate
664 :
665 :			These requirements apply to the modified work as a whole. If
666 :			identifiable sections of that work are not derived from the Program,
667 :			and can be reasonably considered independent and separate works in
668 :			themselves, then this License, and its terms, do not apply to those
669 :			sections when you distribute them as separate works. But when you
670 :			distribute the same sections as part of a whole which is a work based
671 :			on the Program, the distribution of the whole must be on the terms of
672 :			this License, whose permissions for other licensees extend to the
673 :			entire whole, and thus to each and every part regardless of who wrote it.
674 :
675 :			Thus, it is not the intent of this section to claim rights or contest
676 :			your rights to work written entirely by you; rather, the intent is to
677 :			exercise the right to control the distribution of derivative or
678 :			collective works based on the Program.
679 :
680 :			In addition, mere aggregation of another work not based on the Program
681 :			with the Program (or with a work based on the Program) on a volume of
682 :			a storage or distribution medium does not bring the other work under
683 :			the scope of this License.
684 :
685 :			@item
686 :			You may copy and distribute the Program (or a work based on it,
687 :			under Section 2) in object code or executable form under the terms of
688 :			Sections 1 and 2 above provided that you also do one of the following:
689 :
690 :			@enumerate a
691 :			@item
692 :			Accompany it with the complete corresponding machine-readable
693 :			source code, which must be distributed under the terms of Sections
694 :			1 and 2 above on a medium customarily used for software interchange; or,
695 :
696 :			@item
697 :			Accompany it with a written offer, valid for at least three
698 :			years, to give any third party, for a charge no more than your
699 :			cost of physically performing source distribution, a complete
700 :			machine-readable copy of the corresponding source code, to be
701 :			distributed under the terms of Sections 1 and 2 above on a medium
702 :			customarily used for software interchange; or,
703 :
704 :			@item
705 :			Accompany it with the information you received as to the offer
706 :			to distribute corresponding source code. (This alternative is
707 :			allowed only for noncommercial distribution and only if you
708 :			received the program in object code or executable form with such
709 :			an offer, in accord with Subsection b above.)
710 :			@end enumerate
711 :
712 :			The source code for a work means the preferred form of the work for
713 :			making modifications to it. For an executable work, complete source
714 :			code means all the source code for all modules it contains, plus any
715 :			associated interface definition files, plus the scripts used to
716 :			control compilation and installation of the executable. However, as a
717 :			special exception, the source code distributed need not include
718 :			anything that is normally distributed (in either source or binary
719 :			form) with the major components (compiler, kernel, and so on) of the
720 :			operating system on which the executable runs, unless that component
721 :			itself accompanies the executable.
722 :
723 :			If distribution of executable or object code is made by offering
724 :			access to copy from a designated place, then offering equivalent
725 :			access to copy the source code from the same place counts as
726 :			distribution of the source code, even though third parties are not
727 :			compelled to copy the source along with the object code.
728 :
729 :			@item
730 :			You may not copy, modify, sublicense, or distribute the Program
731 :			except as expressly provided under this License. Any attempt
732 :			otherwise to copy, modify, sublicense or distribute the Program is
733 :			void, and will automatically terminate your rights under this License.
734 :			However, parties who have received copies, or rights, from you under
735 :			this License will not have their licenses terminated so long as such
736 :			parties remain in full compliance.
737 :
738 :			@item
739 :			You are not required to accept this License, since you have not
740 :			signed it. However, nothing else grants you permission to modify or
741 :			distribute the Program or its derivative works. These actions are
742 :			prohibited by law if you do not accept this License. Therefore, by
743 :			modifying or distributing the Program (or any work based on the
744 :			Program), you indicate your acceptance of this License to do so, and
745 :			all its terms and conditions for copying, distributing or modifying
746 :			the Program or works based on it.
747 :
748 :			@item
749 :			Each time you redistribute the Program (or any work based on the
750 :			Program), the recipient automatically receives a license from the
751 :			original licensor to copy, distribute or modify the Program subject to
752 :			these terms and conditions. You may not impose any further
753 :			restrictions on the recipients' exercise of the rights granted herein.
754 :			You are not responsible for enforcing compliance by third parties to
755 :			this License.
756 :
757 :			@item
758 :			If, as a consequence of a court judgment or allegation of patent
759 :			infringement or for any other reason (not limited to patent issues),
760 :			conditions are imposed on you (whether by court order, agreement or
761 :			otherwise) that contradict the conditions of this License, they do not
762 :			excuse you from the conditions of this License. If you cannot
763 :			distribute so as to satisfy simultaneously your obligations under this
764 :			License and any other pertinent obligations, then as a consequence you
765 :			may not distribute the Program at all. For example, if a patent
766 :			license would not permit royalty-free redistribution of the Program by
767 :			all those who receive copies directly or indirectly through you, then
768 :			the only way you could satisfy both it and this License would be to
769 :			refrain entirely from distribution of the Program.
770 :
771 :			If any portion of this section is held invalid or unenforceable under
772 :			any particular circumstance, the balance of the section is intended to
773 :			apply and the section as a whole is intended to apply in other
774 :			circumstances.
775 :
776 :			It is not the purpose of this section to induce you to infringe any
777 :			patents or other property right claims or to contest validity of any
778 :			such claims; this section has the sole purpose of protecting the
779 :			integrity of the free software distribution system, which is
780 :			implemented by public license practices. Many people have made
781 :			generous contributions to the wide range of software distributed
782 :			through that system in reliance on consistent application of that
783 :			system; it is up to the author/donor to decide if he or she is willing
784 :			to distribute software through any other system and a licensee cannot
785 :			impose that choice.
786 :
787 :			This section is intended to make thoroughly clear what is believed to
788 :			be a consequence of the rest of this License.
789 :
790 :			@item
791 :			If the distribution and/or use of the Program is restricted in
792 :			certain countries either by patents or by copyrighted interfaces, the
793 :			original copyright holder who places the Program under this License
794 :			may add an explicit geographical distribution limitation excluding
795 :			those countries, so that distribution is permitted only in or among
796 :			countries not thus excluded. In such case, this License incorporates
797 :			the limitation as if written in the body of this License.
798 :
799 :			@item
800 :			The Free Software Foundation may publish revised and/or new versions
801 :			of the General Public License from time to time. Such new versions will
802 :			be similar in spirit to the present version, but may differ in detail to
803 :			address new problems or concerns.
804 :
805 :			Each version is given a distinguishing version number. If the Program
806 :			specifies a version number of this License which applies to it and ``any
807 :			later version'', you have the option of following the terms and conditions
808 :			either of that version or of any later version published by the Free
809 :			Software Foundation. If the Program does not specify a version number of
810 :			this License, you may choose any version ever published by the Free Software
811 :			Foundation.
812 :
813 :			@item
814 :			If you wish to incorporate parts of the Program into other free
815 :			programs whose distribution conditions are different, write to the author
816 :			to ask for permission. For software which is copyrighted by the Free
817 :			Software Foundation, write to the Free Software Foundation; we sometimes
818 :			make exceptions for this. Our decision will be guided by the two goals
819 :			of preserving the free status of all derivatives of our free software and
820 :			of promoting the sharing and reuse of software generally.
821 :
822 :			@iftex
823 :			@heading NO WARRANTY
824 :			@end iftex
825 :	anton	1.49	@ifnottex
826 :	anton	1.1	@center NO WARRANTY
827 :	anton	1.49	@end ifnottex
828 :	anton	1.1
829 :			@item
830 :			BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
831 :			FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
832 :			OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
833 :			PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
834 :			OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
835 :			MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
836 :			TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
837 :			PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
838 :			REPAIR OR CORRECTION.
839 :
840 :			@item
841 :			IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
842 :			WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
843 :			REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
844 :			INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
845 :			OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
846 :			TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
847 :			YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
848 :			PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
849 :			POSSIBILITY OF SUCH DAMAGES.
850 :			@end enumerate
851 :
852 :			@iftex
853 :			@heading END OF TERMS AND CONDITIONS
854 :			@end iftex
855 :	anton	1.49	@ifnottex
856 :	anton	1.1	@center END OF TERMS AND CONDITIONS
857 :	anton	1.49	@end ifnottex
858 :	anton	1.1
859 :			@page
860 :			@unnumberedsec How to Apply These Terms to Your New Programs
861 :
862 :			If you develop a new program, and you want it to be of the greatest
863 :			possible use to the public, the best way to achieve this is to make it
864 :			free software which everyone can redistribute and change under these terms.
865 :
866 :			To do so, attach the following notices to the program. It is safest
867 :			to attach them to the start of each source file to most effectively
868 :			convey the exclusion of warranty; and each file should have at least
869 :			the ``copyright'' line and a pointer to where the full notice is found.
870 :
871 :			@smallexample
872 :			@var{one line to give the program's name and a brief idea of what it does.}
873 :			Copyright (C) 19@var{yy} @var{name of author}
874 :
875 :			This program is free software; you can redistribute it and/or modify
876 :			it under the terms of the GNU General Public License as published by
877 :			the Free Software Foundation; either version 2 of the License, or
878 :			(at your option) any later version.
879 :
880 :			This program is distributed in the hope that it will be useful,
881 :			but WITHOUT ANY WARRANTY; without even the implied warranty of
882 :			MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
883 :			GNU General Public License for more details.
884 :
885 :			You should have received a copy of the GNU General Public License
886 :			along with this program; if not, write to the Free Software
887 :			Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
888 :			@end smallexample
889 :
890 :			Also add information on how to contact you by electronic and paper mail.
891 :
892 :			If the program is interactive, make it output a short notice like this
893 :			when it starts in an interactive mode:
894 :
895 :			@smallexample
896 :			Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
897 :			Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
898 :			type `show w'.
899 :			This is free software, and you are welcome to redistribute it
900 :			under certain conditions; type `show c' for details.
901 :			@end smallexample
902 :
903 :			The hypothetical commands @samp{show w} and @samp{show c} should show
904 :			the appropriate parts of the General Public License. Of course, the
905 :			commands you use may be called something other than @samp{show w} and
906 :			@samp{show c}; they could even be mouse-clicks or menu items---whatever
907 :			suits your program.
908 :
909 :			You should also get your employer (if you work as a programmer) or your
910 :			school, if any, to sign a ``copyright disclaimer'' for the program, if
911 :			necessary. Here is a sample; alter the names:
912 :
913 :			@smallexample
914 :			Yoyodyne, Inc., hereby disclaims all copyright interest in the program
915 :			`Gnomovision' (which makes passes at compilers) written by James Hacker.
916 :
917 :			@var{signature of Ty Coon}, 1 April 1989
918 :			Ty Coon, President of Vice
919 :			@end smallexample
920 :
921 :			This General Public License does not permit incorporating your program into
922 :			proprietary programs. If your program is a subroutine library, you may
923 :			consider it more useful to permit linking proprietary applications with the
924 :			library. If this is what you want to do, use the GNU Library General
925 :			Public License instead of this License.
926 :
927 :			@iftex
928 :			@unnumbered Preface
929 :			@cindex Preface
930 :	crook	1.21	This manual documents Gforth. Some introductory material is provided for
931 :			readers who are unfamiliar with Forth or who are migrating to Gforth
932 :			from other Forth compilers. However, this manual is primarily a
933 :			reference manual.
934 :	anton	1.1	@end iftex
935 :
936 :	crook	1.28	@comment TODO much more blurb here.
937 :	crook	1.26
938 :			@c ******************************************************************
939 :	crook	1.29	@node Goals, Gforth Environment, License, Top
940 :	crook	1.26	@comment node-name, next, previous, up
941 :			@chapter Goals of Gforth
942 :			@cindex goals of the Gforth project
943 :			The goal of the Gforth Project is to develop a standard model for
944 :			ANS Forth. This can be split into several subgoals:
945 :
946 :			@itemize @bullet
947 :			@item
948 :			Gforth should conform to the ANS Forth Standard.
949 :			@item
950 :			It should be a model, i.e. it should define all the
951 :			implementation-dependent things.
952 :			@item
953 :			It should become standard, i.e. widely accepted and used. This goal
954 :			is the most difficult one.
955 :			@end itemize
956 :
957 :			To achieve these goals Gforth should be
958 :			@itemize @bullet
959 :			@item
960 :			Similar to previous models (fig-Forth, F83)
961 :			@item
962 :			Powerful. It should provide for all the things that are considered
963 :			necessary today and even some that are not yet considered necessary.
964 :			@item
965 :			Efficient. It should not get the reputation of being exceptionally
966 :			slow.
967 :			@item
968 :			Free.
969 :			@item
970 :			Available on many machines/easy to port.
971 :			@end itemize
972 :
973 :			Have we achieved these goals? Gforth conforms to the ANS Forth
974 :			standard. It may be considered a model, but we have not yet documented
975 :			which parts of the model are stable and which parts we are likely to
976 :			change. It certainly has not yet become a de facto standard, but it
977 :			appears to be quite popular. It has some similarities to and some
978 :			differences from previous models. It has some powerful features, but not
979 :			yet everything that we envisioned. We certainly have achieved our
980 :			execution speed goals (@pxref{Performance}). It is free and available
981 :			on many machines.
982 :
983 :			@menu
984 :			* Gforth Extensions Sinful?::
985 :			@end menu
986 :
987 :	anton	1.48	@node Gforth Extensions Sinful?, , Goals, Goals
988 :	crook	1.26	@comment node-name, next, previous, up
989 :			@section Is it a Sin to use Gforth Extensions?
990 :			@cindex Gforth extensions
991 :
992 :			If you've been paying attention, you will have realised that there is an
993 :			ANS (American National Standard) for Forth. As you read through the rest
994 :	crook	1.29	of this manual, you will see documentation for @i{Standard} words, and
995 :			documentation for some appealing Gforth @i{extensions}. You might ask
996 :			yourself the question: @i{``Given that there is a standard, would I be
997 :	crook	1.45	committing a sin if I use (non-Standard) Gforth extensions?''}
998 :	crook	1.26
999 :			The answer to that question is somewhat pragmatic and somewhat
1000 :			philosophical. Consider these points:
1001 :
1002 :			@itemize @bullet
1003 :			@item
1004 :			A number of the Gforth extensions can be implemented in ANS Forth using
1005 :			files provided in the @file{compat/} directory. These are mentioned in
1006 :			the text in passing.
1007 :			@item
1008 :			Forth has a rich historical precedent for programmers taking advantage
1009 :			of implementation-dependent features of their tools (for example,
1010 :			relying on a knowledge of the dictionary structure). Sometimes these
1011 :			techniques are necessary to extract every last bit of performance from
1012 :			the hardware, sometimes they are just a programming shorthand.
1013 :			@item
1014 :			The best way to break the rules is to know what the rules are. To learn
1015 :			the rules, there is no substitute for studying the text of the Standard
1016 :			itself. In particular, Appendix A of the Standard (@var{Rationale})
1017 :			provides a valuable insight into the thought processes of the technical
1018 :			committee.
1019 :			@item
1020 :			The best reason to break a rule is because you have to; because it's
1021 :			more productive to do that, because it makes your code run fast enough
1022 :			or because you can see no Standard way to achieve what you want to
1023 :			achieve.
1024 :			@end itemize
1025 :
1026 :			The tool @file{ans-report.fs} (@pxref{ANS Report}) makes it easy to
1027 :			analyse your program and determine what non-Standard definitions it
1028 :			relies upon.
1029 :
1030 :	crook	1.29
1031 :	crook	1.26	@c ******************************************************************
1032 :	anton	1.48	@node Gforth Environment, Tutorial, Goals, Top
1033 :	crook	1.29	@chapter Gforth Environment
1034 :			@cindex Gforth environment
1035 :	crook	1.21
1036 :	crook	1.45	Note: ultimately, the Gforth man page will be auto-generated from the
1037 :	crook	1.29	material in this chapter.
1038 :	crook	1.21
1039 :			@menu
1040 :	crook	1.29	* Invoking Gforth:: Getting in
1041 :			* Leaving Gforth:: Getting out
1042 :			* Command-line editing::
1043 :	anton	1.48	* Upper and lower case::
1044 :			* Environment variables:: that affect how Gforth starts up
1045 :	crook	1.29	* Gforth Files:: What gets installed and where
1046 :	anton	1.48	* Startup speed:: When 35ms is not fast enough ...
1047 :	crook	1.21	@end menu
1048 :
1049 :	anton	1.49	For related information about the creation of images see @ref{Image Files}.
1050 :	crook	1.29
1051 :	crook	1.21	@comment ----------------------------------------------
1052 :	anton	1.48	@node Invoking Gforth, Leaving Gforth, Gforth Environment, Gforth Environment
1053 :	crook	1.29	@section Invoking Gforth
1054 :			@cindex invoking Gforth
1055 :			@cindex running Gforth
1056 :			@cindex command-line options
1057 :			@cindex options on the command line
1058 :			@cindex flags on the command line
1059 :	crook	1.21
1060 :	anton	1.30	Gforth is made up of two parts; an executable ``engine'' (named
1061 :			@file{gforth} or @file{gforth-fast}) and an image file. To start it, you
1062 :			will usually just say @code{gforth} -- this automatically loads the
1063 :			default image file @file{gforth.fi}. In many other cases the default
1064 :			Gforth image will be invoked like this:
1065 :	crook	1.21	@example
1066 :	anton	1.30	gforth [file \| -e forth-code] ...
1067 :	crook	1.21	@end example
1068 :	crook	1.29	@noindent
1069 :			This interprets the contents of the files and the Forth code in the order they
1070 :			are given.
1071 :	crook	1.21
1072 :	anton	1.30	In addition to the @file{gforth} engine, there is also an engine called
1073 :			@file{gforth-fast}, which is faster, but gives less informative error
1074 :			messages (@pxref{Error messages}).
1075 :
1076 :	crook	1.29	In general, the command line looks like this:
1077 :	crook	1.21
1078 :			@example
1079 :	anton	1.30	gforth[-fast] [engine options] [image options]
1080 :	crook	1.21	@end example
1081 :
1082 :	anton	1.30	The engine options must come before the rest of the command
1083 :	crook	1.29	line. They are:
1084 :	crook	1.26
1085 :	crook	1.29	@table @code
1086 :			@cindex -i, command-line option
1087 :			@cindex --image-file, command-line option
1088 :			@item --image-file @i{file}
1089 :			@itemx -i @i{file}
1090 :			Loads the Forth image @i{file} instead of the default
1091 :			@file{gforth.fi} (@pxref{Image Files}).
1092 :	crook	1.21
1093 :	anton	1.39	@cindex --appl-image, command-line option
1094 :			@item --appl-image @i{file}
1095 :			Loads the image @i{file} and leaves all further command-line arguments
1096 :			to the image (instead of processing them as options). This is useful
1097 :			for building executable application images on Unix, built with
1098 :			@code{gforthmi --application ...}.
1099 :
1100 :	crook	1.29	@cindex --path, command-line option
1101 :			@cindex -p, command-line option
1102 :			@item --path @i{path}
1103 :			@itemx -p @i{path}
1104 :			Uses @i{path} for searching the image file and Forth source code files
1105 :			instead of the default in the environment variable @code{GFORTHPATH} or
1106 :			the path specified at installation time (e.g.,
1107 :			@file{/usr/local/share/gforth/0.2.0:.}). A path is given as a list of
1108 :			directories, separated by @samp{:} (on Unix) or @samp{;} (on other OSs).
1109 :	crook	1.21
1110 :	crook	1.29	@cindex --dictionary-size, command-line option
1111 :			@cindex -m, command-line option
1112 :			@cindex @i{size} parameters for command-line options
1113 :			@cindex size of the dictionary and the stacks
1114 :			@item --dictionary-size @i{size}
1115 :			@itemx -m @i{size}
1116 :			Allocate @i{size} space for the Forth dictionary space instead of
1117 :			using the default specified in the image (typically 256K). The
1118 :			@i{size} specification for this and subsequent options consists of
1119 :			an integer and a unit (e.g.,
1120 :			@code{4M}). The unit can be one of @code{b} (bytes), @code{e} (element
1121 :			size, in this case Cells), @code{k} (kilobytes), @code{M} (Megabytes),
1122 :			@code{G} (Gigabytes), and @code{T} (Terabytes). If no unit is specified,
1123 :			@code{e} is used.
1124 :	crook	1.21
1125 :	crook	1.29	@cindex --data-stack-size, command-line option
1126 :			@cindex -d, command-line option
1127 :			@item --data-stack-size @i{size}
1128 :			@itemx -d @i{size}
1129 :			Allocate @i{size} space for the data stack instead of using the
1130 :			default specified in the image (typically 16K).
1131 :	crook	1.21
1132 :	crook	1.29	@cindex --return-stack-size, command-line option
1133 :			@cindex -r, command-line option
1134 :			@item --return-stack-size @i{size}
1135 :			@itemx -r @i{size}
1136 :			Allocate @i{size} space for the return stack instead of using the
1137 :			default specified in the image (typically 15K).
1138 :	crook	1.21
1139 :	crook	1.29	@cindex --fp-stack-size, command-line option
1140 :			@cindex -f, command-line option
1141 :			@item --fp-stack-size @i{size}
1142 :			@itemx -f @i{size}
1143 :			Allocate @i{size} space for the floating point stack instead of
1144 :			using the default specified in the image (typically 15.5K). In this case
1145 :			the unit specifier @code{e} refers to floating point numbers.
1146 :	crook	1.21
1147 :	anton	1.48	@cindex --locals-stack-size, command-line option
1148 :			@cindex -l, command-line option
1149 :			@item --locals-stack-size @i{size}
1150 :			@itemx -l @i{size}
1151 :			Allocate @i{size} space for the locals stack instead of using the
1152 :			default specified in the image (typically 14.5K).
1153 :
1154 :			@cindex -h, command-line option
1155 :			@cindex --help, command-line option
1156 :			@item --help
1157 :			@itemx -h
1158 :			Print a message about the command-line options
1159 :
1160 :			@cindex -v, command-line option
1161 :			@cindex --version, command-line option
1162 :			@item --version
1163 :			@itemx -v
1164 :			Print version and exit
1165 :
1166 :			@cindex --debug, command-line option
1167 :			@item --debug
1168 :			Print some information useful for debugging on startup.
1169 :
1170 :			@cindex --offset-image, command-line option
1171 :			@item --offset-image
1172 :			Start the dictionary at a slightly different position than would be used
1173 :			otherwise (useful for creating data-relocatable images,
1174 :			@pxref{Data-Relocatable Image Files}).
1175 :
1176 :			@cindex --no-offset-im, command-line option
1177 :			@item --no-offset-im
1178 :			Start the dictionary at the normal position.
1179 :
1180 :			@cindex --clear-dictionary, command-line option
1181 :			@item --clear-dictionary
1182 :			Initialize all bytes in the dictionary to 0 before loading the image
1183 :			(@pxref{Data-Relocatable Image Files}).
1184 :
1185 :			@cindex --die-on-signal, command-line-option
1186 :			@item --die-on-signal
1187 :			Normally Gforth handles most signals (e.g., the user interrupt SIGINT,
1188 :			or the segmentation violation SIGSEGV) by translating it into a Forth
1189 :			@code{THROW}. With this option, Gforth exits if it receives such a
1190 :			signal. This option is useful when the engine and/or the image might be
1191 :			severely broken (such that it causes another signal before recovering
1192 :			from the first); this option avoids endless loops in such cases.
1193 :			@end table
1194 :
1195 :			@cindex loading files at startup
1196 :			@cindex executing code on startup
1197 :			@cindex batch processing with Gforth
1198 :			As explained above, the image-specific command-line arguments for the
1199 :			default image @file{gforth.fi} consist of a sequence of filenames and
1200 :			@code{-e @var{forth-code}} options that are interpreted in the sequence
1201 :			in which they are given. The @code{-e @var{forth-code}} or
1202 :			@code{--evaluate @var{forth-code}} option evaluates the Forth
1203 :			code. This option takes only one argument; if you want to evaluate more
1204 :			Forth words, you have to quote them or use @code{-e} several times. To exit
1205 :			after processing the command line (instead of entering interactive mode)
1206 :			append @code{-e bye} to the command line.
1207 :
1208 :			@cindex versions, invoking other versions of Gforth
1209 :			If you have several versions of Gforth installed, @code{gforth} will
1210 :			invoke the version that was installed last. @code{gforth-@i{version}}
1211 :			invokes a specific version. If your environment contains the variable
1212 :			@code{GFORTHPATH}, you may want to override it by using the
1213 :			@code{--path} option.
1214 :
1215 :			Not yet implemented:
1216 :			On startup the system first executes the system initialization file
1217 :			(unless the option @code{--no-init-file} is given; note that the system
1218 :			resulting from using this option may not be ANS Forth conformant). Then
1219 :			the user initialization file @file{.gforth.fs} is executed, unless the
1220 :			option @code{--no-rc} is given; this file is first searched in @file{.},
1221 :			then in @file{~}, then in the normal path (see above).
1222 :
1223 :
1224 :
1225 :			@comment ----------------------------------------------
1226 :			@node Leaving Gforth, Command-line editing, Invoking Gforth, Gforth Environment
1227 :			@section Leaving Gforth
1228 :			@cindex Gforth - leaving
1229 :			@cindex leaving Gforth
1230 :
1231 :			You can leave Gforth by typing @code{bye} or @kbd{Ctrl-d} (at the start
1232 :			of a line) or (if you invoked Gforth with the @code{--die-on-signal}
1233 :			option) @kbd{Ctrl-c}. When you leave Gforth, all of your definitions and
1234 :	anton	1.49	data are discarded. For ways of saving the state of the system before
1235 :			leaving Gforth see @ref{Image Files}.
1236 :	anton	1.48
1237 :			doc-bye
1238 :
1239 :
1240 :			@comment ----------------------------------------------
1241 :			@node Command-line editing, Upper and lower case, Leaving Gforth, Gforth Environment
1242 :			@section Command-line editing
1243 :			@cindex command-line editing
1244 :
1245 :			Gforth maintains a history file that records every line that you type to
1246 :			the text interpreter. This file is preserved between sessions, and is
1247 :			used to provide a command-line recall facility; if you type @kbd{Ctrl-P}
1248 :			repeatedly you can recall successively older commands from this (or
1249 :			previous) session(s). The full list of command-line editing facilities is:
1250 :
1251 :			@itemize @bullet
1252 :			@item
1253 :			@kbd{Ctrl-p} (``previous'') (or up-arrow) to recall successively older
1254 :			commands from the history buffer.
1255 :			@item
1256 :			@kbd{Ctrl-n} (``next'') (or down-arrow) to recall successively newer commands
1257 :			from the history buffer.
1258 :			@item
1259 :			@kbd{Ctrl-f} (or right-arrow) to move the cursor right, non-destructively.
1260 :			@item
1261 :			@kbd{Ctrl-b} (or left-arrow) to move the cursor left, non-destructively.
1262 :			@item
1263 :			@kbd{Ctrl-h} (backspace) to delete the character to the left of the cursor,
1264 :			closing up the line.
1265 :			@item
1266 :			@kbd{Ctrl-k} to delete (``kill'') from the cursor to the end of the line.
1267 :			@item
1268 :			@kbd{Ctrl-a} to move the cursor to the start of the line.
1269 :			@item
1270 :			@kbd{Ctrl-e} to move the cursor to the end of the line.
1271 :			@item
1272 :			@key{RET} (@kbd{Ctrl-m}) or @key{LFD} (@kbd{Ctrl-j}) to submit the current
1273 :			line.
1274 :			@item
1275 :			@key{TAB} to step through all possible full-word completions of the word
1276 :			currently being typed.
1277 :			@item
1278 :			@kbd{Ctrl-d} at the start of the line to terminate Gforth (gracefully,
1279 :			using @code{bye}).
1280 :			@end itemize
1281 :
1282 :			When editing, displayable characters are inserted to the left of the
1283 :			cursor position; the line is always in ``insert'' (as opposed to
1284 :			``overstrike'') mode.
1285 :
1286 :			@cindex history file
1287 :			@cindex @file{.gforth-history}
1288 :			On Unix systems, the history file is @file{~/.gforth-history} by
1289 :			default@footnote{i.e. it is stored in the user's home directory.}. You
1290 :			can find out the name and location of your history file using:
1291 :
1292 :			@example
1293 :			history-file type \ Unix-class systems
1294 :
1295 :			history-file type \ Other systems
1296 :			history-dir type
1297 :			@end example
1298 :
1299 :			If you enter long definitions by hand, you can use a text editor to
1300 :			paste them out of the history file into a Forth source file for reuse at
1301 :			a later time.
1302 :
1303 :			Gforth never trims the size of the history file, so you should do this
1304 :			periodically, if necessary.
1305 :
1306 :			@comment this is all defined in history.fs
1307 :			@comment NAC TODO the ctrl-D behaviour can either do a bye or a beep.. how is that option
1308 :			@comment chosen?
1309 :
1310 :
1311 :
1312 :			@comment ----------------------------------------------
1313 :			@node Upper and lower case, Environment variables, Command-line editing, Gforth Environment
1314 :			@section Upper and lower case
1315 :			@cindex case-sensitivity
1316 :			@cindex upper and lower case
1317 :
1318 :			Gforth is case-insensitive; you can enter definitions and invoke
1319 :			Standard words using upper, lower or mixed case (however,
1320 :			@pxref{core-idef, Implementation-defined options, Implementation-defined
1321 :			options}).
1322 :
1323 :			ANS Forth only @i{requires} implementations to recognise Standard words
1324 :			when they are typed entirely in upper case. Therefore, a Standard
1325 :			program must use upper case for all Standard words. You can use whatever
1326 :			case you like for words that you define, but in a standard program you
1327 :			have to use the words in the same case that you defined them.
1328 :
1329 :			Gforth supports case sensitivity through @code{table}s (case-sensitive
1330 :			wordlists, @pxref{Word Lists}).
1331 :
1332 :			Two people have asked how to convert Gforth to case sensitivity; while
1333 :			we think this is a bad idea, you can change all wordlists into tables
1334 :			like this:
1335 :
1336 :			@example
1337 :			' table-find forth-wordlist wordlist-map @ !
1338 :			@end example
1339 :
1340 :			Note that you now have to type the predefined words in the same case
1341 :			that we defined them, which are varying. You may want to convert them
1342 :			to your favourite case before doing this operation (I won't explain how,
1343 :			because if you are even contemplating to do this, you'd better have
1344 :			enough knowledge of Forth systems to know this already).
1345 :
1346 :			@comment ----------------------------------------------
1347 :			@node Environment variables, Gforth Files, Upper and lower case, Gforth Environment
1348 :			@section Environment variables
1349 :			@cindex environment variables
1350 :
1351 :			Gforth uses these environment variables:
1352 :
1353 :			@itemize @bullet
1354 :			@item
1355 :			@cindex @code{GFORTHHIST} -- environment variable
1356 :			@code{GFORTHHIST} -- (Unix systems only) specifies the directory in which to
1357 :			open/create the history file, @file{.gforth-history}. Default:
1358 :			@code{$HOME}.
1359 :
1360 :			@item
1361 :			@cindex @code{GFORTHPATH} -- environment variable
1362 :			@code{GFORTHPATH} -- specifies the path used when searching for the gforth image file and
1363 :			for Forth source-code files.
1364 :
1365 :			@item
1366 :			@cindex @code{GFORTH} -- environment variable
1367 :	anton	1.49	@code{GFORTH} -- used by @file{gforthmi}, @xref{gforthmi}.
1368 :	anton	1.48
1369 :			@item
1370 :			@cindex @code{GFORTHD} -- environment variable
1371 :			@code{GFORTHD} -- used by @file{gforthmi} @xref{gforthmi}.
1372 :
1373 :			@item
1374 :			@cindex @code{TMP}, @code{TEMP} - environment variable
1375 :			@code{TMP}, @code{TEMP} - (non-Unix systems only) used as a potential
1376 :			location for the history file.
1377 :			@end itemize
1378 :
1379 :			@comment also POSIXELY_CORRECT LINES COLUMNS HOME but no interest in
1380 :			@comment mentioning these.
1381 :
1382 :			All the Gforth environment variables default to sensible values if they
1383 :			are not set.
1384 :
1385 :
1386 :			@comment ----------------------------------------------
1387 :			@node Gforth Files, Startup speed, Environment variables, Gforth Environment
1388 :			@section Gforth files
1389 :			@cindex Gforth files
1390 :
1391 :			When you install Gforth on a Unix system, it installs files in these
1392 :			locations by default:
1393 :
1394 :			@itemize @bullet
1395 :			@item
1396 :			@file{/usr/local/bin/gforth}
1397 :			@item
1398 :			@file{/usr/local/bin/gforthmi}
1399 :			@item
1400 :			@file{/usr/local/man/man1/gforth.1} - man page.
1401 :			@item
1402 :			@file{/usr/local/info} - the Info version of this manual.
1403 :			@item
1404 :			@file{/usr/local/lib/gforth/<version>/...} - Gforth @file{.fi} files.
1405 :			@item
1406 :			@file{/usr/local/share/gforth/<version>/TAGS} - Emacs TAGS file.
1407 :			@item
1408 :			@file{/usr/local/share/gforth/<version>/...} - Gforth source files.
1409 :			@item
1410 :			@file{.../emacs/site-lisp/gforth.el} - Emacs gforth mode.
1411 :			@end itemize
1412 :
1413 :			You can select different places for installation by using
1414 :			@code{configure} options (listed with @code{configure --help}).
1415 :
1416 :			@comment ----------------------------------------------
1417 :			@node Startup speed, , Gforth Files, Gforth Environment
1418 :			@section Startup speed
1419 :			@cindex Startup speed
1420 :			@cindex speed, startup
1421 :
1422 :			If Gforth is used for CGI scripts or in shell scripts, its startup
1423 :			speed may become a problem. On a 300MHz 21064a under Linux-2.2.13 with
1424 :			glibc-2.0.7, @code{gforth -e bye} takes about 24.6ms user and 11.3ms
1425 :			system time.
1426 :
1427 :			If startup speed is a problem, you may consider the following ways to
1428 :			improve it; or you may consider ways to reduce the number of startups
1429 :			(e.g., Fast-CGI).
1430 :
1431 :			The first step to improve startup speed is to statically link Gforth, by
1432 :			building it with @code{XLDFLAGS=-static}. This requires more memory for
1433 :			the code and will therefore slow down the first invocation, but
1434 :			subsequent invocations avoid the dynamic linking overhead. Another
1435 :			disadvantage is that Gforth won't profit from library upgrades. As a
1436 :			result, @code{gforth-static -e bye} takes about 17.1ms user and
1437 :			8.2ms system time.
1438 :
1439 :			The next step to improve startup speed is to use a non-relocatable image
1440 :			@ref{Non-Relocatable Image Files}. You can create this image with
1441 :			@code{gforth -e "savesystem gforthnr.fi bye"} and later use it with
1442 :			@code{gforth -i gforthnr.fi ...}. This avoids the relocation overhead
1443 :			and a part of the copy-on-write overhead. The disadvantage is that the
1444 :			nonrelocatable image does not work if the OS gives Gforth a different
1445 :			address for the dictionary, for whatever reason; so you better provide a
1446 :			fallback on a relocatable image. @code{gforth-static -i gforthnr.fi -e
1447 :			bye} takes about 15.3ms user and 7.5ms system time.
1448 :
1449 :			The final step is to disable dictionary hashing in Gforth. Gforth
1450 :			builds the hash table on startup, which takes much of the startup
1451 :			overhead. You can do this by commenting out the @code{include hash.fs}
1452 :			in @file{startup.fs} and everything that requires @file{hash.fs} (at the
1453 :			moment @file{table.fs} and @file{ekey.fs}) and then doing @code{make}.
1454 :			The disadvantages are that functionality like @code{table} and
1455 :			@code{ekey} is missing and that text interpretation (e.g., compiling)
1456 :			now takes much longer. So, you should only use this method if there is
1457 :			no significant text interpretation to perform (the script should be
1458 :			compiled into the image, among other things). @code{gforth-static -i
1459 :			gforthnrnh.fi -e bye} takes about 2.1ms user and 6.1ms system time.
1460 :
1461 :			@c ******************************************************************
1462 :			@node Tutorial, Introduction, Gforth Environment, Top
1463 :			@chapter Forth Tutorial
1464 :			@cindex Tutorial
1465 :			@cindex Forth Tutorial
1466 :
1467 :			This tutorial can be used with any ANS-compliant Forth; any places that
1468 :			mention features specific to Gforth are marked as such and you can skip
1469 :			them, if you work with another Forth. This tutorial does not explain
1470 :			all features of Forth, just enough to get you started and give you some
1471 :			ideas about the facilities available in Forth. Read the rest of the
1472 :			manual and the standard when you are through this.
1473 :
1474 :			The intended way to use this tutorial is that you work through it while
1475 :			sitting in front of the console, take a look at the examples and predict
1476 :			what they will do, then try them out; if the outcome is not as expected,
1477 :			find out why (e.g., by trying out variations of the example), so you
1478 :			understand what's going on. There are also some assignments that you
1479 :			should solve.
1480 :
1481 :			This tutorial assumes that you have programmed before and know what,
1482 :			e.g., a loop is.
1483 :
1484 :			@c !! explain compat library
1485 :
1486 :			@menu
1487 :			* Starting Gforth Tutorial::
1488 :			* Syntax Tutorial::
1489 :			* Crash Course Tutorial::
1490 :			* Stack Tutorial::
1491 :			* Arithmetics Tutorial::
1492 :			* Stack Manipulation Tutorial::
1493 :			* Using files for Forth code Tutorial::
1494 :			* Comments Tutorial::
1495 :			* Colon Definitions Tutorial::
1496 :			* Decompilation Tutorial::
1497 :			* Stack-Effect Comments Tutorial::
1498 :			* Types Tutorial::
1499 :			* Factoring Tutorial::
1500 :			* Designing the stack effect Tutorial::
1501 :			* Local Variables Tutorial::
1502 :			* Conditional execution Tutorial::
1503 :			* Flags and Comparisons Tutorial::
1504 :			* General Loops Tutorial::
1505 :			* Counted loops Tutorial::
1506 :			* Recursion Tutorial::
1507 :			* Leaving definitions or loops Tutorial::
1508 :			* Return Stack Tutorial::
1509 :			* Memory Tutorial::
1510 :			* Characters and Strings Tutorial::
1511 :			* Alignment Tutorial::
1512 :			* Interpretation and Compilation Semantics and Immediacy Tutorial::
1513 :			* Execution Tokens Tutorial::
1514 :			* Exceptions Tutorial::
1515 :			* Defining Words Tutorial::
1516 :			* Arrays and Records Tutorial::
1517 :			* POSTPONE Tutorial::
1518 :			* Literal Tutorial::
1519 :			* Advanced macros Tutorial::
1520 :			* Compilation Tokens Tutorial::
1521 :			* Wordlists and Search Order Tutorial::
1522 :			@end menu
1523 :
1524 :			@node Starting Gforth Tutorial, Syntax Tutorial, Tutorial, Tutorial
1525 :			@section Starting Gforth
1526 :
1527 :			You can start Gforth by typing its name:
1528 :
1529 :			@example
1530 :			gforth
1531 :			@end example
1532 :
1533 :			That puts you into interactive mode; you can leave Gforth by typing
1534 :			@code{bye}. While in Gforth, you can edit the command line and access
1535 :			the command line history with cursor keys, similar to bash.
1536 :
1537 :
1538 :			@node Syntax Tutorial, Crash Course Tutorial, Starting Gforth Tutorial, Tutorial
1539 :			@section Syntax
1540 :
1541 :			A @dfn{word} is a sequence of arbitrary characters (expcept white
1542 :			space). Words are separated by white space. E.g., each of the
1543 :			following lines contains exactly one word:
1544 :
1545 :			@example
1546 :			word
1547 :			!@@#$%^&*()
1548 :			1234567890
1549 :			5!a
1550 :			@end example
1551 :
1552 :			A frequent beginner's error is to leave away necessary white space,
1553 :			resulting in an error like @samp{Undefined word}; so if you see such an
1554 :			error, check if you have put spaces wherever necessary.
1555 :
1556 :			@example
1557 :			." hello, world" \ correct
1558 :			."hello, world" \ gives an "Undefined word" error
1559 :			@end example
1560 :
1561 :			Gforth and most other Forth systems ignores differences in case (it is
1562 :			case-insensitive), i.e., @samp{word} is the same as @samp{Word}. If
1563 :			your system is case-sensitive, you may have to type all the examples
1564 :			given here in upper case.
1565 :
1566 :
1567 :			@node Crash Course Tutorial, Stack Tutorial, Syntax Tutorial, Tutorial
1568 :			@section Crash Course
1569 :
1570 :			Type
1571 :
1572 :			@example
1573 :			0 0 !
1574 :			here execute
1575 :			' catch >body 20 erase abort
1576 :			' (quit) >body 20 erase
1577 :			@end example
1578 :
1579 :			The last two examples are guaranteed to destroy parts of Gforth (and
1580 :			most other systems), so you better leave Gforth afterwards (if it has
1581 :			not finished by itself). On some systems you may have to kill gforth
1582 :			from outside (e.g., in Unix with @code{kill}).
1583 :
1584 :			Now that you know how to produce crashes (and that there's not much to
1585 :			them), let's learn how to produce meaningful programs.
1586 :
1587 :
1588 :			@node Stack Tutorial, Arithmetics Tutorial, Crash Course Tutorial, Tutorial
1589 :			@section Stack
1590 :
1591 :			The most obvious feature of Forth is the stack. When you type in a
1592 :			number, it is pushed on the stack. You can display the content of the
1593 :			stack with @code{.s}.
1594 :
1595 :			@example
1596 :			1 2 .s
1597 :			3 .s
1598 :			@end example
1599 :
1600 :			@code{.s} displays the top-of-stack to the right, i.e., the numbers
1601 :			appear in @code{.s} output as they appeared in the input.
1602 :
1603 :			You can print the top of stack element with @code{.}.
1604 :
1605 :			@example
1606 :			1 2 3 . . .
1607 :			@end example
1608 :
1609 :			In general, words consume their stack arguments (@code{.s} is an
1610 :			exception).
1611 :
1612 :			@assignment
1613 :			What does the stack contain after @code{5 6 7 .}?
1614 :			@endassignment
1615 :
1616 :
1617 :			@node Arithmetics Tutorial, Stack Manipulation Tutorial, Stack Tutorial, Tutorial
1618 :			@section Arithmetics
1619 :
1620 :			The words @code{+}, @code{-}, @code{*}, @code{/}, and @code{mod} always
1621 :			operate on the top two stack items:
1622 :
1623 :			@example
1624 :			2 2 + .
1625 :			2 1 - .
1626 :			7 3 mod .
1627 :			@end example
1628 :
1629 :			The operands of @code{-}, @code{/}, and @code{mod} are in the same order
1630 :			as in the corresponding infix expression (this is generally the case in
1631 :			Forth).
1632 :
1633 :			Parentheses are superfluous (and not available), because the order of
1634 :			the words unambiguously determines the order of evaluation and the
1635 :			operands:
1636 :
1637 :			@example
1638 :			3 4 + 5 * .
1639 :			3 4 5 * + .
1640 :			@end example
1641 :
1642 :			@assignment
1643 :			What are the infix expressions corresponding to the Forth code above?
1644 :			Write @code{6-7*8+9} in Forth notation@footnote{This notation is also
1645 :			known as Postfix or RPN (Reverse Polish Notation).}.
1646 :			@endassignment
1647 :
1648 :			To change the sign, use @code{negate}:
1649 :
1650 :			@example
1651 :			2 negate .
1652 :			@end example
1653 :
1654 :			@assignment
1655 :			Convert -(-3)*4-5 to Forth.
1656 :			@endassignment
1657 :
1658 :			@code{/mod} performs both @code{/} and @code{mod}.
1659 :
1660 :			@example
1661 :			7 3 /mod . .
1662 :			@end example
1663 :
1664 :			@node Stack Manipulation Tutorial, Using files for Forth code Tutorial, Arithmetics Tutorial, Tutorial
1665 :			@section Stack Manipulation
1666 :
1667 :			Stack manipulation words rearrange the data on the stack.
1668 :
1669 :			@example
1670 :			1 .s drop .s
1671 :			1 .s dup .s drop drop .s
1672 :			1 2 .s over .s drop drop drop
1673 :			1 2 .s swap .s drop drop
1674 :			1 2 3 .s rot .s drop drop drop
1675 :			@end example
1676 :
1677 :			These are the most important stack manipulation words. There are also
1678 :			variants that manipulate twice as many stack items:
1679 :
1680 :			@example
1681 :			1 2 3 4 .s 2swap .s 2drop 2drop
1682 :			@end example
1683 :
1684 :			Two more stack manipulation words are:
1685 :
1686 :			@example
1687 :			1 2 .s nip .s drop
1688 :			1 2 .s tuck .s 2drop drop
1689 :			@end example
1690 :
1691 :			@assignment
1692 :			Replace @code{nip} and @code{tuck} with combinations of other stack
1693 :			manipulation words.
1694 :
1695 :			@example
1696 :			Given: How do you get:
1697 :			1 2 3 3 2 1
1698 :			1 2 3 1 2 3 2
1699 :			1 2 3 1 2 3 3
1700 :			1 2 3 1 3 3
1701 :			1 2 3 2 1 3
1702 :			1 2 3 4 4 3 2 1
1703 :			1 2 3 1 2 3 1 2 3
1704 :			1 2 3 4 1 2 3 4 1 2
1705 :			1 2 3
1706 :			1 2 3 1 2 3 4
1707 :			1 2 3 1 3
1708 :			@end example
1709 :			@endassignment
1710 :
1711 :			@example
1712 :			5 dup * .
1713 :			@end example
1714 :
1715 :			@assignment
1716 :			Write 17^3 and 17^4 in Forth, without writing @code{17} more than once.
1717 :			Write a piece of Forth code that expects two numbers on the stack
1718 :			(@var{a} and @var{b}, with @var{b} on top) and computes
1719 :			@code{(a-b)(a+1)}.
1720 :			@endassignment
1721 :
1722 :			@node Using files for Forth code Tutorial, Comments Tutorial, Stack Manipulation Tutorial, Tutorial
1723 :			@section Using files for Forth code
1724 :
1725 :			While working at the Forth command line is convenient for one-line
1726 :			examples and short one-off code, you probably want to store your source
1727 :			code in files for convenient editing and persistence. You can use your
1728 :			favourite editor (Gforth includes Emacs support, @pxref{Emacs and
1729 :			Gforth}) to create @var{file} and use
1730 :
1731 :			@example
1732 :			s" @var{file}" included
1733 :			@end example
1734 :
1735 :			to load it into your Forth system. The file name extension I use for
1736 :			Forth files is @samp{.fs}.
1737 :
1738 :			You can easily start Gforth with some files loaded like this:
1739 :
1740 :			@example
1741 :			gforth @var{file1} @var{file2}
1742 :			@end example
1743 :
1744 :			If an error occurs during loading these files, Gforth terminates,
1745 :			whereas an error during @code{INCLUDED} within Gforth usually gives you
1746 :			a Gforth command line. Starting the Forth system every time gives you a
1747 :			clean start every time, without interference from the results of earlier
1748 :			tries.
1749 :
1750 :			I often put all the tests in a file, then load the code and run the
1751 :			tests with
1752 :
1753 :			@example
1754 :			gforth @var{code} @var{tests} -e bye
1755 :			@end example
1756 :
1757 :			(often by performing this command with @kbd{C-x C-e} in Emacs). The
1758 :			@code{-e bye} ensures that Gforth terminates afterwards so that I can
1759 :			restart this command without ado.
1760 :
1761 :			The advantage of this approach is that the tests can be repeated easily
1762 :			every time the program ist changed, making it easy to catch bugs
1763 :			introduced by the change.
1764 :
1765 :
1766 :			@node Comments Tutorial, Colon Definitions Tutorial, Using files for Forth code Tutorial, Tutorial
1767 :			@section Comments
1768 :
1769 :			@example
1770 :			\ That's a comment; it ends at the end of the line
1771 :			( Another comment; it ends here: ) .s
1772 :			@end example
1773 :
1774 :			@code{\} and @code{(} are ordinary Forth words and therefore have to be
1775 :			separated with white space from the following text.
1776 :
1777 :			@example
1778 :			\This gives an "Undefined word" error
1779 :			@end example
1780 :
1781 :			The first @code{)} ends a comment started with @code{(}, so you cannot
1782 :			nest @code{(}-comments; and you cannot comment out text containing a
1783 :			@code{)} with @code{( ... )}@footnote{therefore it's a good idea to
1784 :			avoid @code{)} in word names.}.
1785 :
1786 :			I use @code{\}-comments for descriptive text and for commenting out code
1787 :			of one or more line; I use @code{(}-comments for describing the stack
1788 :			effect, the stack contents, or for commenting out sub-line pieces of
1789 :			code.
1790 :
1791 :			The Emacs mode @file{gforth.el} (@pxref{Emacs and Gforth}) supports
1792 :			these uses by commenting out a region with @kbd{C-x \}, uncommenting a
1793 :			region with @kbd{C-u C-x \}, and filling a @code{\}-commented region
1794 :			with @kbd{M-q}.
1795 :
1796 :
1797 :			@node Colon Definitions Tutorial, Decompilation Tutorial, Comments Tutorial, Tutorial
1798 :			@section Colon Definitions
1799 :
1800 :			are similar to procedures and functions in other programming languages.
1801 :
1802 :			@example
1803 :			: squared ( n -- n^2 )
1804 :			dup * ;
1805 :			5 squared .
1806 :			7 squared .
1807 :			@end example
1808 :
1809 :			@code{:} starts the colon definition; its name is @code{squared}. The
1810 :			following comment describes its stack effect. The words @code{dup *}
1811 :			are not executed, but compiled into the definition. @code{;} ends the
1812 :			colon definition.
1813 :
1814 :			The newly-defined word can be used like any other word, including using
1815 :			it in other definitions:
1816 :
1817 :			@example
1818 :			: cubed ( n -- n^3 )
1819 :			dup squared * ;
1820 :			-5 cubed .
1821 :			: fourth-power ( n -- n^4 )
1822 :			squared squared ;
1823 :			3 fourth-power .
1824 :			@end example
1825 :
1826 :			@assignment
1827 :			Write colon definitions for @code{nip}, @code{tuck}, @code{negate}, and
1828 :			@code{/mod} in terms of other Forth words, and check if they work (hint:
1829 :			test your tests on the originals first). Don't let the
1830 :			@samp{redefined}-Messages spook you, they are just warnings.
1831 :			@endassignment
1832 :
1833 :
1834 :			@node Decompilation Tutorial, Stack-Effect Comments Tutorial, Colon Definitions Tutorial, Tutorial
1835 :			@section Decompilation
1836 :
1837 :			You can decompile colon definitions with @code{see}:
1838 :
1839 :			@example
1840 :			see squared
1841 :			see cubed
1842 :			@end example
1843 :
1844 :			In Gforth @code{see} shows you a reconstruction of the source code from
1845 :			the executable code. Informations that were present in the source, but
1846 :			not in the executable code, are lost (e.g., comments).
1847 :
1848 :			@node Stack-Effect Comments Tutorial, Types Tutorial, Decompilation Tutorial, Tutorial
1849 :			@section Stack-Effect Comments
1850 :
1851 :			By convention the comment after the name of a definition describes the
1852 :			stack effect: The part in from of the @samp{--} describes the state of
1853 :			the stack before the execution of the definition, i.e., the parameters
1854 :			that are passed into the colon definition; the part behind the @samp{--}
1855 :			is the state of the stack after the execution of the definition, i.e.,
1856 :			the results of the definition. The stack comment only shows the top
1857 :			stack items that the definition accesses and/or changes.
1858 :
1859 :			You should put a correct stack effect on every definition, even if it is
1860 :			just @code{( -- )}. You should also add some descriptive comment to
1861 :			more complicated words (I usually do this in the lines following
1862 :			@code{:}). If you don't do this, your code becomes unreadable (because
1863 :			you have to work through every definition before you can undertsand
1864 :			any).
1865 :
1866 :			@assignment
1867 :			The stack effect of @code{swap} can be written like this: @code{x1 x2 --
1868 :			x2 x1}. Describe the stack effect of @code{-}, @code{drop}, @code{dup},
1869 :			@code{over}, @code{rot}, @code{nip}, and @code{tuck}. Hint: When you
1870 :			are done, you can compare your stack effects to this in this manual
1871 :			(@pxref{Word Index}).
1872 :			@endassignment
1873 :
1874 :			Sometimes programmers put comments at various places in colon
1875 :			definitions that describe the contents of the stack at that place (stack
1876 :			comments); i.e., they are like the first part of a stack-effect
1877 :			comment. E.g.,
1878 :
1879 :			@example
1880 :			: cubed ( n -- n^3 )
1881 :			dup squared ( n n^2 ) * ;
1882 :			@end example
1883 :
1884 :			In this case the stack comment is pretty superfluous, because the word
1885 :			is simple enough. If you think it would be a good idea to add such a
1886 :			comment to increase readability, you should also consider factoring the
1887 :			word into several simpler words (@pxref{Factoring Tutorial,,
1888 :			Factoring}), which typically eliminates the need for the stack effect;
1889 :			however, if you decide not to refactor it, then having such a comment is
1890 :			better than not having it.
1891 :
1892 :			The names of the stack items in stack-effect and stack comments in the
1893 :			standard, in this manual, and in many programs specify the type through
1894 :			a type prefix, similar to Fortran and Hungarian notation. The most
1895 :			frequent prefixes are:
1896 :
1897 :			@table @code
1898 :			@item n
1899 :			signed integer
1900 :			@item u
1901 :			unsigned integer
1902 :			@item c
1903 :			character
1904 :			@item f
1905 :			Boolean flags, i.e. @code{false} or @code{true}.
1906 :			@item a-addr,a-
1907 :			Cell-aligned address
1908 :			@item c-addr,c-
1909 :			Char-aligned address (note that a Char may have two bytes in Windows NT)
1910 :			@item xt
1911 :			Execution token, same size as Cell
1912 :			@item w,x
1913 :			Cell, can contain an integer or an address. It usually takes 32, 64 or
1914 :			16 bits (depending on your platform and Forth system). A cell is more
1915 :			commonly known as machine word, but the term @emph{word} already means
1916 :			something different in Forth.
1917 :			@item d
1918 :			signed double-cell integer
1919 :			@item ud
1920 :			unsigned double-cell integer
1921 :			@item r
1922 :			Float (on the FP stack)
1923 :			@end table
1924 :
1925 :			You can find a more complete list in @ref{Notation}.
1926 :
1927 :			@assignment
1928 :			Write stack-effect comments for all definitions you have written up to
1929 :			now.
1930 :			@endassignment
1931 :
1932 :
1933 :			@node Types Tutorial, Factoring Tutorial, Stack-Effect Comments Tutorial, Tutorial
1934 :			@section Types
1935 :
1936 :			In Forth the names of the operations are not overloaded; so similar
1937 :			operations on different types need different names; e.g., @code{+} adds
1938 :			integers, and you have to use @code{f+} to add floating-point numbers.
1939 :			The following prefixes are often used for related operations on
1940 :			different types:
1941 :
1942 :			@table @code
1943 :			@item (none)
1944 :			signed integer
1945 :			@item u
1946 :			unsigned integer
1947 :			@item c
1948 :			character
1949 :			@item d
1950 :			signed double-cell integer
1951 :			@item ud, du
1952 :			unsigned double-cell integer
1953 :			@item 2
1954 :			two cells (not-necessarily double-cell numbers)
1955 :			@item m, um
1956 :			mixed single-cell and double-cell operations
1957 :			@item f
1958 :			floating-point (note that in stack comments @samp{f} represents flags,
1959 :			and @samp{r} represents FP number).
1960 :			@end table
1961 :
1962 :			If there are no differences between the signed and the unsigned variant
1963 :			(e.g., for @code{+}), there is only the prefix-less variant.
1964 :
1965 :			Forth does not perform type checking, neither at compile time, nor at
1966 :			run time. If you use the wrong oeration, the data are interpreted
1967 :			incorrectly:
1968 :
1969 :			@example
1970 :			-1 u.
1971 :			@end example
1972 :
1973 :			If you have only experience with type-checked languages until now, and
1974 :			have heard how important type-checking is, don't panic! In my
1975 :			experience (and that of other Forthers), type errors in Forth code are
1976 :			usually easy to find (once you get used to it), the increased vigilance
1977 :			of the programmer tends to catch some harder errors in addition to most
1978 :			type errors, and you never have to work around the type system, so in
1979 :			most situations the lack of type-checking seems to be a win (projects to
1980 :			add type checking to Forth have not caught on).
1981 :
1982 :
1983 :			@node Factoring Tutorial, Designing the stack effect Tutorial, Types Tutorial, Tutorial
1984 :			@section Factoring
1985 :
1986 :			If you try to write longer definitions, you will soon find it hard to
1987 :			keep track of the stack contents. Therefore, good Forth programmers
1988 :			tend to write only short definitions (e.g., three lines). The art of
1989 :			finding meaningful short definitions is known as factoring (as in
1990 :			factoring polynomials).
1991 :
1992 :			Well-factored programs offer additional advantages: smaller, more
1993 :			general words, are easier to test and debug and can be reused more and
1994 :			better than larger, specialized words.
1995 :
1996 :			So, if you run into difficulties with stack management, when writing
1997 :			code, try to define meaningful factors for the word, and define the word
1998 :			in terms of those. Even if a factor contains only two words, it is
1999 :			often helpful.
2000 :
2001 :			Good factoring is not easy, and even experienced Forth programmers often
2002 :			don't find the right solution right away, but only when rewriting the
2003 :			program. So, if you don't come up with a good solution immediately,
2004 :			keep trying, don't despair.
2005 :
2006 :			@c example !!
2007 :
2008 :
2009 :			@node Designing the stack effect Tutorial, Local Variables Tutorial, Factoring Tutorial, Tutorial
2010 :			@section Designing the stack effect
2011 :
2012 :			In other languages you can use an arbitrary order of parameters for a
2013 :			function; and since ther is only one result, you don't have to deal with
2014 :			the order of results, either.
2015 :
2016 :			In Forth (and other stack-based languages, e.g., Postscript) the
2017 :			parameter and result order of a definition is important and should be
2018 :			designed well. The general guideline is to design the stack effect such
2019 :			that the word is simple to use in most cases, even if that complicates
2020 :			the implementation of the word. Some concrete rules are:
2021 :
2022 :			@itemize @bullet
2023 :
2024 :			@item
2025 :			Words consume all of their parameters (e.g., @code{.}).
2026 :
2027 :			@item
2028 :			If there is a convention on the order of parameters (e.g., from
2029 :			mathematics or another programming language), stick with it (e.g.,
2030 :			@code{-}).
2031 :
2032 :			@item
2033 :			If one parameter usually requires only a short computation (e.g., it is
2034 :			a constant), pass it on the top of the stack. Conversely, parameters
2035 :			that usually require a long sequence of code to compute should be passed
2036 :			as the bottom (i.e., first) parameter. This makes the code easier to
2037 :			read, because reader does not need to keep track of the bottom item
2038 :			through a long sequence of code (or, alternatively, through stack
2039 :	anton	1.49	manipulations). E.g., @code{!} (store, @pxref{Memory}) expects the
2040 :	anton	1.48	address on top of the stack because it is usually simpler to compute
2041 :			than the stored value (often the address is just a variable).
2042 :
2043 :			@item
2044 :			Similarly, results that are usually consumed quickly should be returned
2045 :			on the top of stack, whereas a result that is often used in long
2046 :			computations should be passed as bottom result. E.g., the file words
2047 :			like @code{open-file} return the error code on the top of stack, because
2048 :			it is usually consumed quickly by @code{throw}; moreover, the error code
2049 :			has to be checked before doing anything with the other results.
2050 :
2051 :			@end itemize
2052 :
2053 :			These rules are just general guidelines, don't lose sight of the overall
2054 :			goal to make the words easy to use. E.g., if the convention rule
2055 :			conflicts with the computation-length rule, you might decide in favour
2056 :			of the convention if the word will be used rarely, and in favour of the
2057 :			computation-length rule if the word will be used frequently (because
2058 :			with frequent use the cost of breaking the computation-length rule would
2059 :			be quite high, and frequent use makes it easier to remember an
2060 :			unconventional order).
2061 :
2062 :			@c example !! structure package
2063 :
2064 :			@node Local Variables Tutorial, Conditional execution Tutorial, Designing the stack effect Tutorial, Tutorial
2065 :			@section Local Variables
2066 :
2067 :			You can define local variables (@emph{locals}) in a colon definition:
2068 :
2069 :			@example
2070 :			: swap @{ a b -- b a @}
2071 :			b a ;
2072 :			1 2 swap .s 2drop
2073 :			@end example
2074 :
2075 :			(If your Forth system does not support this syntax, include
2076 :			@file{compat/anslocals.fs} first).
2077 :
2078 :			In this example @code{@{ a b -- b a @}} is the locals definition; it
2079 :			takes two cells from the stack, puts the top of stack in @code{b} and
2080 :			the next stack element in @code{a}. @code{--} starts a comment ending
2081 :			with @code{@}}. After the locals definition, using the name of the
2082 :			local will push its value on the stack. You can leave the comment
2083 :			part (@code{-- b a}) away:
2084 :
2085 :			@example
2086 :			: swap ( x1 x2 -- x2 x1 )
2087 :			@{ a b @} b a ;
2088 :			@end example
2089 :
2090 :			In Gforth you can have several locals definitions, anywhere in a colon
2091 :			definition; in contrast, in a standard program you can have only one
2092 :			locals definition per colon definition, and that locals definition must
2093 :			be outside any controll structure.
2094 :
2095 :			With locals you can write slightly longer definitions without running
2096 :			into stack trouble. However, I recommend trying to write colon
2097 :			definitions without locals for exercise purposes to help you gain the
2098 :			essential factoring skills.
2099 :
2100 :			@assignment
2101 :			Rewrite your definitions until now with locals
2102 :			@endassignment
2103 :
2104 :
2105 :			@node Conditional execution Tutorial, Flags and Comparisons Tutorial, Local Variables Tutorial, Tutorial
2106 :			@section Conditional execution
2107 :
2108 :			In Forth you can use control structures only inside colon definitions.
2109 :			An @code{if}-structure looks like this:
2110 :
2111 :			@example
2112 :			: abs ( n1 -- +n2 )
2113 :			dup 0 < if
2114 :			negate
2115 :			endif ;
2116 :			5 abs .
2117 :			-5 abs .
2118 :			@end example
2119 :
2120 :			@code{if} takes a flag from the stack. If the flag is non-zero (true),
2121 :			the following code is performed, otherwise execution continues after the
2122 :	pazsan	1.51	@code{endif} (or @code{else}). @code{<} compares the top two stack
2123 :	anton	1.48	elements and prioduces a flag:
2124 :
2125 :			@example
2126 :			1 2 < .
2127 :			2 1 < .
2128 :			1 1 < .
2129 :			@end example
2130 :
2131 :			Actually the standard name for @code{endif} is @code{then}. This
2132 :			tutorial presents the examples using @code{endif}, because this is often
2133 :			less confusing for people familiar with other programming languages
2134 :			where @code{then} has a different meaning. If your system does not have
2135 :			@code{endif}, define it with
2136 :
2137 :			@example
2138 :			: endif postpone then ; immediate
2139 :			@end example
2140 :
2141 :			You can optionally use an @code{else}-part:
2142 :
2143 :			@example
2144 :			: min ( n1 n2 -- n )
2145 :			2dup < if
2146 :			drop
2147 :			else
2148 :			nip
2149 :			endif ;
2150 :			2 3 min .
2151 :			3 2 min .
2152 :			@end example
2153 :
2154 :			@assignment
2155 :			Write @code{min} without @code{else}-part (hint: what's the definition
2156 :			of @code{nip}?).
2157 :			@endassignment
2158 :
2159 :
2160 :			@node Flags and Comparisons Tutorial, General Loops Tutorial, Conditional execution Tutorial, Tutorial
2161 :			@section Flags and Comparisons
2162 :
2163 :			In a false-flag all bits are clear (0 when interpreted as integer). In
2164 :			a canonical true-flag all bits are set (-1 as a twos-complement signed
2165 :			integer); in many contexts (e.g., @code{if}) any non-zero value is
2166 :			treated as true flag.
2167 :
2168 :			@example
2169 :			false .
2170 :			true .
2171 :			true hex u. decimal
2172 :			@end example
2173 :
2174 :			Comparison words produce canonical flags:
2175 :
2176 :			@example
2177 :			1 1 = .
2178 :			1 0= .
2179 :			0 1 < .
2180 :			0 0 < .
2181 :			-1 1 u< . \ type error, u< interprets -1 as large unsigned number
2182 :			-1 1 < .
2183 :			@end example
2184 :
2185 :			Gforth supports all combinations of the prefixes @code{0 u d d0 du} (or
2186 :			none) and the comparisons @code{= <> < > <= >=}. Only a part of these
2187 :			combinations are standard (see the standard or !! the glossary for
2188 :			details).
2189 :
2190 :			You can use @code{and or xor invert} can be used as operations on
2191 :			canonical flags. Actually they are bitwise operations:
2192 :
2193 :			@example
2194 :			1 2 and .
2195 :			1 2 or .
2196 :			1 3 xor .
2197 :			1 invert .
2198 :			@end example
2199 :
2200 :			You can convert a zero/non-zero flag into a canonical flag with
2201 :			@code{0<>} (and complement it on the way with @code{0=}).
2202 :
2203 :			@example
2204 :			1 0= .
2205 :			1 0<> .
2206 :			@end example
2207 :
2208 :			You can use the all-bits-set feature of canonicasl flags and the bitwise
2209 :			operation of the Boolean operations to avoid @code{if}s:
2210 :
2211 :			@example
2212 :			: foo ( n1 -- n2 )
2213 :			0= if
2214 :			14
2215 :			else
2216 :			0
2217 :			endif ;
2218 :			0 foo .
2219 :			1 foo .
2220 :
2221 :			: foo ( n1 -- n2 )
2222 :			0= 14 and ;
2223 :			0 foo .
2224 :			1 foo .
2225 :			@end example
2226 :
2227 :			@assignment
2228 :			Write @code{min} without @code{if}.
2229 :			@endassignment
2230 :
2231 :
2232 :			@node General Loops Tutorial, Counted loops Tutorial, Flags and Comparisons Tutorial, Tutorial
2233 :			@section General Loops
2234 :
2235 :			The endless loop is the most simple one:
2236 :
2237 :			@example
2238 :			: endless ( -- )
2239 :			0 begin
2240 :			dup . 1+
2241 :			again ;
2242 :			endless
2243 :			@end example
2244 :
2245 :			Terminate this loop by pressing @kbd{Ctrl-C} (in Gforth). @code{begin}
2246 :			does nothing at run-time, @code{again} jumps back to @code{begin}.
2247 :
2248 :			A loop with one exit at any place looks like this:
2249 :
2250 :			@example
2251 :			: log2 ( +n1 -- n2 )
2252 :			\ logarithmus dualis of n1>0, rounded down to the next integer
2253 :			assert( dup 0> )
2254 :			2/ 0 begin
2255 :			over 0> while
2256 :			1+ swap 2/ swap
2257 :			repeat
2258 :			nip ;
2259 :			7 log2 .
2260 :			8 log2 .
2261 :			@end example
2262 :
2263 :			At run-time @code{while} consumes a flag; if it is 0, execution
2264 :	pazsan	1.51	continues behind the @code{repeat}; if the flag is non-zero, execution
2265 :	anton	1.48	continues behind the @code{while}. @code{Repeat} jumps back to
2266 :			@code{begin}, just like @code{again}.
2267 :
2268 :			In Forth there are many combinations/abbreviations, like @code{1+}.
2269 :			However, @code{2/} is not one of them; it shifts it's argument right by
2270 :			one bit (arithmetic shift right):
2271 :
2272 :			@example
2273 :			-5 2 / .
2274 :			-5 2/ .
2275 :			@end example
2276 :
2277 :			@code{assert(} is no standard word, but you can get it on systems other
2278 :			then Gforth by including @file{compat/assert.fs}. You can see what it
2279 :			does by trying
2280 :
2281 :			@example
2282 :			0 log2 .
2283 :			@end example
2284 :
2285 :			Here's a loop with an exit at the end:
2286 :
2287 :			@example
2288 :			: log2 ( +n1 -- n2 )
2289 :			\ logarithmus dualis of n1>0, rounded down to the next integer
2290 :			assert( dup 0 > )
2291 :			-1 begin
2292 :			1+ swap 2/ swap
2293 :			over 0 <=
2294 :			until
2295 :			nip ;
2296 :			@end example
2297 :
2298 :			@code{Until} consumes a flag; if it is non-zero, execution continues at
2299 :			the @code{begin}, otherwise after the @code{until}.
2300 :
2301 :			@assignment
2302 :			Write a definition for computing the greatest common divisor.
2303 :			@endassignment
2304 :
2305 :
2306 :			@node Counted loops Tutorial, Recursion Tutorial, General Loops Tutorial, Tutorial
2307 :			@section Counted loops
2308 :
2309 :			@example
2310 :			: ^ ( n1 u -- n )
2311 :			\ n = the uth power of u1
2312 :			1 swap 0 u+do
2313 :			over *
2314 :			loop
2315 :			nip ;
2316 :			3 2 ^ .
2317 :			4 3 ^ .
2318 :			@end example
2319 :
2320 :			@code{U+do} (from @file{compat/loops.fs}, if your Forth system doesn't
2321 :			have it) takes two numbers of the stack @code{( u3 u4 -- )}, and then
2322 :			performs the code between @code{u+do} and @code{loop} for @code{u3-u4}
2323 :			times (or not at all, if @code{u3-u4<0}).
2324 :
2325 :			You can see the stack effect design rules at work in the stack effect of
2326 :			the loop start words: Since the start value of the loop is more
2327 :			frequently constant than the end value, the start value is passed on
2328 :			the top-of-stack.
2329 :
2330 :			You can access the counter of a counted loop with @code{i}:
2331 :
2332 :			@example
2333 :			: fac ( u -- u! )
2334 :			1 swap 1+ 1 u+do
2335 :			i *
2336 :			loop ;
2337 :			5 fac .
2338 :			7 fac .
2339 :			@end example
2340 :
2341 :			There is also @code{+do}, which expects signed numbers (important for
2342 :			deciding whether to enter the loop).
2343 :
2344 :			@assignment
2345 :			Write a definition for computing the nth Fibonacci number.
2346 :			@endassignment
2347 :
2348 :			!! +DO...+LOOP
2349 :			!! -DO...-LOOP
2350 :
2351 :
2352 :			@node Recursion Tutorial, Leaving definitions or loops Tutorial, Counted loops Tutorial, Tutorial
2353 :			@section Recursion
2354 :
2355 :			Usually the name of a definition is not visible in the definition; but
2356 :			earlier definitions are usually visible:
2357 :
2358 :			@example
2359 :			1 0 / . \ "Floating-point unidentified fault" in Gforth on most platforms
2360 :			: / ( n1 n2 -- n )
2361 :			dup 0= if
2362 :			-10 throw \ report division by zero
2363 :			endif
2364 :			/ \ old version
2365 :			;
2366 :			1 0 /
2367 :			@end example
2368 :
2369 :			For recursive definitions you can use @code{recursive} (non-standard) or
2370 :			@code{recurse}:
2371 :
2372 :			@example
2373 :			: fac1 ( n -- n! ) recursive
2374 :			dup 0> if
2375 :			dup 1- fac1 *
2376 :			else
2377 :			drop 1
2378 :			endif ;
2379 :			7 fac1 .
2380 :
2381 :			: fac2 ( n -- n! )
2382 :			dup 0> if
2383 :			dup 1- recurse *
2384 :			else
2385 :			drop 1
2386 :			endif ;
2387 :			8 fac2 .
2388 :			@end example
2389 :
2390 :			@assignment
2391 :			Write a recursive definition for computing the nth Fibonacci number.
2392 :			@endassignment
2393 :
2394 :
2395 :			@node Leaving definitions or loops Tutorial, Return Stack Tutorial, Recursion Tutorial, Tutorial
2396 :			@section Leaving definitions or loops
2397 :
2398 :			@code{EXIT} exits the current definition right away. For every counted
2399 :			loop that is left in this way, an @code{UNLOOP} has to be performed
2400 :			before the @code{EXIT}:
2401 :
2402 :			@c !! real examples
2403 :			@example
2404 :			: ...
2405 :			... u+do
2406 :			... if
2407 :			... unloop exit
2408 :			endif
2409 :			...
2410 :			loop
2411 :			... ;
2412 :			@end example
2413 :
2414 :			@code{LEAVE} leaves the innermost counted loop right away:
2415 :
2416 :			@example
2417 :			: ...
2418 :			... u+do
2419 :			... if
2420 :			... leave
2421 :			endif
2422 :			...
2423 :			loop
2424 :			... ;
2425 :			@end example
2426 :
2427 :
2428 :			@node Return Stack Tutorial, Memory Tutorial, Leaving definitions or loops Tutorial, Tutorial
2429 :			@section Return Stack
2430 :
2431 :			In addition to the data stack Forth also has a second stack, the return
2432 :			stack; most Forth systems store the return addresses of procedure calls
2433 :			there (thus its name). Programmers can also use this stack:
2434 :
2435 :			@example
2436 :			: foo ( n1 n2 -- )
2437 :			.s
2438 :			>r .s
2439 :	anton	1.50	r@@ .
2440 :	anton	1.48	>r .s
2441 :	anton	1.50	r@@ .
2442 :	anton	1.48	r> .
2443 :	anton	1.50	r@@ .
2444 :	anton	1.48	r> . ;
2445 :			1 2 foo
2446 :			@end example
2447 :
2448 :			@code{>r} takes an element from the data stack and pushes it onto the
2449 :			return stack; conversely, @code{r>} moves an elementm from the return to
2450 :			the data stack; @code{r@@} pushes a copy of the top of the return stack
2451 :			on the return stack.
2452 :
2453 :			Forth programmers usually use the return stack for storing data
2454 :			temporarily, if using the data stack alone would be too complex, and
2455 :			factoring and locals are not an option:
2456 :
2457 :			@example
2458 :			: 2swap ( x1 x2 x3 x4 -- x3 x4 x1 x2 )
2459 :			rot >r rot r> ;
2460 :			@end example
2461 :
2462 :			The return address of the definition and the loop control parameters of
2463 :			counted loops usually reside on the return stack, so you have to take
2464 :			all items, that you have pushed on the return stack in a colon
2465 :			definition or counted loop, from the return stack before the definition
2466 :			or loop ends. You cannot access items that you pushed on the return
2467 :			stack outside some definition or loop within the definition of loop.
2468 :
2469 :			If you miscount the return stack items, this usually ends in a crash:
2470 :
2471 :			@example
2472 :			: crash ( n -- )
2473 :			>r ;
2474 :			5 crash
2475 :			@end example
2476 :
2477 :			You cannot mix using locals and using the return stack (according to the
2478 :			standard; Gforth has no problem). However, they solve the same
2479 :			problems, so this shouldn't be an issue.
2480 :
2481 :			@assignment
2482 :			Can you rewrite any of the definitions you wrote until now in a better
2483 :			way using the return stack?
2484 :			@endassignment
2485 :
2486 :
2487 :			@node Memory Tutorial, Characters and Strings Tutorial, Return Stack Tutorial, Tutorial
2488 :			@section Memory
2489 :
2490 :			You can create a global variable @code{v} with
2491 :
2492 :			@example
2493 :			variable v ( -- addr )
2494 :			@end example
2495 :
2496 :			@code{v} pushes the address of a cell in memory on the stack. This cell
2497 :			was reserved by @code{variable}. You can use @code{!} (store) to store
2498 :			values into this cell and @code{@@} (fetch) to load the value from the
2499 :			stack into memory:
2500 :
2501 :			@example
2502 :			v .
2503 :			5 v ! .s
2504 :	anton	1.50	v @@ .
2505 :	anton	1.48	@end example
2506 :
2507 :			You can also reserve more memory:
2508 :
2509 :			@example
2510 :			create v2 20 cells allot
2511 :			@end example
2512 :
2513 :			creates a word @code{v2} and reserves 20 cells; the address pushed by
2514 :			@code{v2} points to the start of these 20 cells. You can use address
2515 :			arithmetic to access these cells:
2516 :
2517 :			@example
2518 :			3 v2 5 cells + !
2519 :			@end example
2520 :
2521 :			You can reserve and initialize memory with @code{,}:
2522 :
2523 :			@example
2524 :			create v3
2525 :			5 , 4 , 3 , 2 , 1 ,
2526 :	anton	1.50	v3 @@ .
2527 :			v3 cell+ @@ .
2528 :			v3 2 cells + @@ .
2529 :	anton	1.48	@end example
2530 :
2531 :			@assignment
2532 :			Write a definition @code{vsum ( addr u -- n )} that computes the sum of
2533 :			@code{u} cells, with the first of these cells at @code{addr}, the next
2534 :			one at @code{addr cell+} etc.
2535 :			@endassignment
2536 :
2537 :			You can also reserve memory without creating a new word:
2538 :
2539 :			@example
2540 :			here 10 cells allot
2541 :			.s
2542 :			@end example
2543 :
2544 :			@code{Here} pushes the start address of the memory area. You should
2545 :			store it somewhere, or you will have a hard time finding the memory area
2546 :			again.
2547 :
2548 :			@code{Allot} manages dictionary memory. The dictionary memory contains
2549 :			the system's data structures for words etc. on Gforth and most other
2550 :			Forth systems. It is managed like a stack: You can free the memory that
2551 :			you have just @code{allot}ed with
2552 :
2553 :			@example
2554 :			-10 cells allot
2555 :			@end example
2556 :
2557 :			Note that you cannot do this if you have created a new word in the
2558 :			meantime (because then your @code{allot}ed memory is no longer on the
2559 :			top of the dictionary ``stack'').
2560 :
2561 :			Alternatively, you can use @code{allocate} and @code{free} which allow
2562 :			freeing memory in any order:
2563 :
2564 :			@example
2565 :			10 cells allocate throw .s
2566 :			20 cells allocate throw .s
2567 :			swap
2568 :			free throw
2569 :			free throw
2570 :			@end example
2571 :
2572 :			The @code{throw}s deal with errors (e.g., out of memory).
2573 :
2574 :			And there is also a garbage collector @url{!!}, which eliminates the
2575 :			need to @code{free} memory explicitly.
2576 :
2577 :
2578 :			@node Characters and Strings Tutorial, Alignment Tutorial, Memory Tutorial, Tutorial
2579 :			@section Characters and Strings
2580 :
2581 :			On the stack characters take up a cell, like numbers. In memory they
2582 :			have their own size (one 8-bit byte on most systems), and therefore
2583 :			require their own words for memory access:
2584 :
2585 :			@example
2586 :			create v4
2587 :			104 c, 97 c, 108 c, 108 c, 111 c,
2588 :	anton	1.50	v4 4 chars + c@@ .
2589 :	anton	1.48	@end example
2590 :
2591 :			The preferred representation of strings on the stack is @code{addr
2592 :			u-count}, where @code{addr} is the address of the first character and
2593 :			@code{u-count} is the number of characters in the string.
2594 :
2595 :			@example
2596 :			v4 5 type
2597 :			@end example
2598 :
2599 :			You get a string constant with
2600 :
2601 :			@example
2602 :			s" hello, world" .s
2603 :			type
2604 :			@end example
2605 :
2606 :			Make sure you have a space between @code{s"} and the string; @code{s"}
2607 :			is a normal Forth word and must be delimited with white space (try what
2608 :			happens when you remove the space).
2609 :
2610 :			However, this interpretive use of @code{s"} is quite restricted: the
2611 :			string exists only until the next call of @code{s"} (some Forth systems
2612 :			keep more than one of these strings, but usually they still have a
2613 :			limited lifetime.
2614 :
2615 :			@example
2616 :			s" hello," s" world" .s
2617 :			type
2618 :			type
2619 :			@end example
2620 :
2621 :			However, you can also use @code{s"} in a definition, and the resulting
2622 :			strings then live forever (well, as long as the definition):
2623 :
2624 :			@example
2625 :			: foo s" hello," s" world" ;
2626 :			foo .s
2627 :			type
2628 :			type
2629 :			@end example
2630 :
2631 :			@assignment
2632 :			@code{Emit ( c -- )} types @code{c} as character (not a number).
2633 :			Implement @code{type ( addr u -- )}.
2634 :			@endassignment
2635 :
2636 :			@node Alignment Tutorial, Interpretation and Compilation Semantics and Immediacy Tutorial, Characters and Strings Tutorial, Tutorial
2637 :			@section Alignment
2638 :
2639 :			On many processors cells have to be aligned in memory, if you want to
2640 :			access them with @code{@@} and @code{!} (and even if the processor does
2641 :			not require alignment, access to aligned cells are faster).
2642 :
2643 :			@code{Create} aligns @code{here} (i.e., the place where the next
2644 :			allocation will occur, and that the @code{create}d word points to).
2645 :			Likewise, the memory produced by @code{allocate} starts at an aligned
2646 :			address. Adding a number of @code{cells} to an aligned address produces
2647 :			another aligned address.
2648 :
2649 :			However, address arithmetic involving @code{char+} and @code{chars} can
2650 :			create an address that is not cell-aligned. @code{Aligned ( addr --
2651 :			a-addr )} produces the next aligned address:
2652 :
2653 :			@example
2654 :	anton	1.50	v3 char+ aligned .s @@ .
2655 :			v3 char+ .s @@ .
2656 :	anton	1.48	@end example
2657 :
2658 :			Similarly, @code{align} advances @code{here} to the next aligned
2659 :			address:
2660 :
2661 :			@example
2662 :			create v5 97 c,
2663 :			here .
2664 :			align here .
2665 :			1000 ,
2666 :			@end example
2667 :
2668 :			Note that you should use aligned addresses even if your processor does
2669 :			not require them, if you want your program to be portable.
2670 :
2671 :
2672 :			@node Interpretation and Compilation Semantics and Immediacy Tutorial, Execution Tokens Tutorial, Alignment Tutorial, Tutorial
2673 :			@section Interpretation and Compilation Semantics and Immediacy
2674 :
2675 :			When a word is compiled, it behaves differently from being interpreted.
2676 :			E.g., consider @code{+}:
2677 :
2678 :			@example
2679 :			1 2 + .
2680 :			: foo + ;
2681 :			@end example
2682 :
2683 :			These two behaviours are known as compilation and interpretation
2684 :			semantics. For normal words (e.g., @code{+}), the compilation semantics
2685 :			is to append the interpretation semantics to the currently defined word
2686 :			(@code{foo} in the example above). I.e., when @code{foo} is executed
2687 :			later, the interpretation semantics of @code{+} (i.e., adding two
2688 :			numbers) will be performed.
2689 :
2690 :			However, there are words with non-default compilation semantics, e.g.,
2691 :			the control-flow words like @code{if}. You can use @code{immediate} to
2692 :			change the compilation semantics of the last defined word to be equal to
2693 :			the interpretation semantics:
2694 :
2695 :			@example
2696 :			: [FOO] ( -- )
2697 :			5 . ; immediate
2698 :
2699 :			[FOO]
2700 :			: bar ( -- )
2701 :			[FOO] ;
2702 :			bar
2703 :			see bar
2704 :			@end example
2705 :
2706 :			Two conventions to mark words with non-default compilation semnatics are
2707 :			names with brackets (more frequently used) and to write them all in
2708 :			upper case (less frequently used).
2709 :
2710 :			In Gforth (and many other systems) you can also remove the
2711 :			interpretation semantics with @code{compile-only} (the compilation
2712 :			semantics is derived from the original interpretation semantics):
2713 :
2714 :			@example
2715 :			: flip ( -- )
2716 :			6 . ; compile-only \ but not immediate
2717 :			flip
2718 :
2719 :			: flop ( -- )
2720 :			flip ;
2721 :			flop
2722 :			@end example
2723 :
2724 :			In this example the interpretation semantics of @code{flop} is equal to
2725 :			the original interpretation semantics of @code{flip}.
2726 :
2727 :			The text interpreter has two states: in interpret state, it performs the
2728 :			interpretation semantics of words it encounters; in compile state, it
2729 :			performs the compilation semantics of these words.
2730 :
2731 :			Among other things, @code{:} switches into compile state, and @code{;}
2732 :			switches back to interpret state. They contain the factors @code{]}
2733 :			(switch to compile state) and @code{[} (switch to interpret state), that
2734 :			do nothing but switch the state.
2735 :
2736 :			@example
2737 :			: xxx ( -- )
2738 :			[ 5 . ]
2739 :			;
2740 :
2741 :			xxx
2742 :			see xxx
2743 :			@end example
2744 :
2745 :			These brackets are also the source of the naming convention mentioned
2746 :			above.
2747 :
2748 :
2749 :			@node Execution Tokens Tutorial, Exceptions Tutorial, Interpretation and Compilation Semantics and Immediacy Tutorial, Tutorial
2750 :			@section Execution Tokens
2751 :
2752 :			@code{' word} gives you the execution token (XT) of a word. The XT is a
2753 :			cell representing the interpretation semantics of a word. You can
2754 :			execute this semantics with @code{execute}:
2755 :
2756 :			@example
2757 :			' + .s
2758 :			1 2 rot execute .
2759 :			@end example
2760 :
2761 :			The XT is similar to a function pointer in C. However, parameter
2762 :			passing through the stack makes it a little more flexible:
2763 :
2764 :			@example
2765 :			: map-array ( ... addr u xt -- ... )
2766 :	anton	1.50	\ executes xt ( ... x -- ... ) for every element of the array starting
2767 :			\ at addr and containing u elements
2768 :	anton	1.48	@{ xt @}
2769 :			cells over + swap ?do
2770 :	anton	1.50	i @@ xt execute
2771 :	anton	1.48	1 cells +loop ;
2772 :
2773 :			create a 3 , 4 , 2 , -1 , 4 ,
2774 :			a 5 ' . map-array .s
2775 :			0 a 5 ' + map-array .
2776 :			s" max-n" environment? drop .s
2777 :			a 5 ' min map-array .
2778 :			@end example
2779 :
2780 :			You can use map-array with the XTs of words that consume one element
2781 :			more than they produce. In theory you can also use it with other XTs,
2782 :			but the stack effect then depends on the size of the array, which is
2783 :			hard to understand.
2784 :
2785 :	pazsan	1.51	Since XTs are cell-sized, you can store them in memory and manipulate
2786 :			them on the stack like other cells. You can also compile the XT into a
2787 :	anton	1.48	word with @code{compile,}:
2788 :
2789 :			@example
2790 :			: foo1 ( n1 n2 -- n )
2791 :			[ ' + compile, ] ;
2792 :			see foo
2793 :			@end example
2794 :
2795 :			This is non-standard, because @code{compile,} has no compilation
2796 :			semantics in the standard, but it works in good Forth systems. For the
2797 :			broken ones, use
2798 :
2799 :			@example
2800 :			: [compile,] compile, ; immediate
2801 :
2802 :			: foo1 ( n1 n2 -- n )
2803 :			[ ' + ] [compile,] ;
2804 :			see foo
2805 :			@end example
2806 :
2807 :			@code{'} is a word with default compilation semantics; it parses the
2808 :			next word when its interpretation semantics are executed, not during
2809 :			compilation:
2810 :
2811 :			@example
2812 :			: foo ( -- xt )
2813 :			' ;
2814 :			see foo
2815 :			: bar ( ... "word" -- ... )
2816 :			' execute ;
2817 :			see bar
2818 :			1 2 bar +
2819 :			@end example
2820 :
2821 :			You often want to parse a word during compilation and compile its XT so
2822 :			it will be pushed on the stack at run-time. @code{[']} does this:
2823 :
2824 :			@example
2825 :			: xt-+ ( -- xt )
2826 :			['] + ;
2827 :			see xt-+
2828 :			1 2 xt-+ execute .
2829 :			@end example
2830 :
2831 :			Many programmers tend to see @code{'} and the word it parses as one
2832 :			unit, and expect it to behave like @code{[']} when compiled, and are
2833 :			confused by the actual behaviour. If you are, just remember that the
2834 :			Forth system just takes @code{'} as one unit and has no idea that it is
2835 :			a parsing word (attempts to convenience programmers in this issue have
2836 :			usually resulted in even worse pitfalls, see
2837 :			@uref{http://www.complang.tuwien.ac.at/papers/ertl98.ps.gz}).
2838 :
2839 :			Note that the state of the interpreter does not come into play when
2840 :	pazsan	1.51	creating and executing XTs. I.e., even when you execute @code{'} in
2841 :	anton	1.48	compile state, it still gives you the interpretation semantics. And
2842 :			whatever that state is, @code{execute} performs the semantics
2843 :	pazsan	1.51	represented by the XT (i.e., the interpretation semantics).
2844 :	anton	1.48
2845 :
2846 :			@node Exceptions Tutorial, Defining Words Tutorial, Execution Tokens Tutorial, Tutorial
2847 :			@section Exceptions
2848 :
2849 :			@code{throw ( n -- )} causes an exception unless n is zero.
2850 :
2851 :			@example
2852 :			100 throw .s
2853 :			0 throw .s
2854 :			@end example
2855 :
2856 :			@code{catch ( ... xt -- ... n )} behaves similar to @code{execute}, but
2857 :			it catches exceptions and pushes the number of the exception on the
2858 :			stack (or 0, if the xt executed without exception). If there was an
2859 :			exception, the stacks have the same depth as when entering @code{catch}:
2860 :
2861 :			@example
2862 :			.s
2863 :			3 0 ' / catch .s
2864 :			3 2 ' / catch .s
2865 :			@end example
2866 :
2867 :			@assignment
2868 :			Try the same with @code{execute} instead of @code{catch}.
2869 :			@endassignment
2870 :
2871 :			@code{Throw} always jumps to the dynamically next enclosing
2872 :			@code{catch}, even if it has to leave several call levels to achieve
2873 :			this:
2874 :
2875 :			@example
2876 :			: foo 100 throw ;
2877 :			: foo1 foo ." after foo" ;
2878 :	pazsan	1.51	: bar ['] foo1 catch ;
2879 :	anton	1.48	bar
2880 :			@end example
2881 :
2882 :			It is often important to restore a value upon leaving a definition, even
2883 :			if the definition is left through an exception. You can ensure this
2884 :			like this:
2885 :
2886 :			@example
2887 :			: ...
2888 :			save-x
2889 :	pazsan	1.51	['] word-changing-x catch ( ... n )
2890 :	anton	1.48	restore-x
2891 :			( ... n ) throw ;
2892 :			@end example
2893 :
2894 :			Gforth provides an alternative syntax in addition to @code{cacth}:
2895 :			@code{try ... recover ... endtry}. If the code between @code{try} and
2896 :			@code{recover} has an exception, the stack depths are restored, the
2897 :			exception number is pushed on the stack, and the code between
2898 :			@code{recover} and @code{endtry} is performed. E.g., the definition for
2899 :			@code{catch} is
2900 :
2901 :			@example
2902 :			: catch ( x1 .. xn xt -- y1 .. ym 0 / z1 .. zn error ) \ exception
2903 :			try
2904 :			execute 0
2905 :			recover
2906 :			nip
2907 :			endtry ;
2908 :			@end example
2909 :
2910 :			The equivalent to the restoration code above is
2911 :
2912 :			@example
2913 :			: ...
2914 :			save-x
2915 :			try
2916 :			word-changing-x
2917 :			end-try
2918 :			restore-x
2919 :			throw ;
2920 :			@end example
2921 :
2922 :			As you can see, the @code{recover} part is optional.
2923 :
2924 :
2925 :			@node Defining Words Tutorial, Arrays and Records Tutorial, Exceptions Tutorial, Tutorial
2926 :			@section Defining Words
2927 :
2928 :			@code{:}, @code{create}, and @code{variable} are definition words: They
2929 :			define other words. @code{Constant} is another definition word:
2930 :
2931 :			@example
2932 :			5 constant foo
2933 :			foo .
2934 :			@end example
2935 :
2936 :			You can also use the prefixes @code{2} (double-cell) and @code{f}
2937 :			(floating point) with @code{variable} and @code{constant}.
2938 :
2939 :			You can also define your own defining words. E.g.:
2940 :
2941 :			@example
2942 :			: variable ( "name" -- )
2943 :			create 0 , ;
2944 :			@end example
2945 :
2946 :			You can also define defining words that create words that do something
2947 :			other than just producing their address:
2948 :
2949 :			@example
2950 :			: constant ( n "name" -- )
2951 :			create ,
2952 :			does> ( -- n )
2953 :	anton	1.50	( addr ) @@ ;
2954 :	anton	1.48
2955 :			5 constant foo
2956 :			foo .
2957 :			@end example
2958 :
2959 :			The definition of @code{constant} above ends at the @code{does>}; i.e.,
2960 :			@code{does>} replaces @code{;}, but it also does something else: It
2961 :			changes the last defined word such that it pushes the address of the
2962 :			body of the word and then performs the code after the @code{does>}
2963 :			whenever it is called.
2964 :
2965 :			In the example above, @code{constant} uses @code{,} to store 5 into the
2966 :			body of @code{foo}. When @code{foo} executes, it pushes the address of
2967 :			the body onto the stack, then (in the code after the @code{does>})
2968 :			fetches the 5 from there.
2969 :
2970 :			The stack comment near the @code{does>} reflects the stack effect of the
2971 :			defined word, not the stack effect of the code after the @code{does>}
2972 :			(the difference is that the code expects the address of the body that
2973 :			the stack comment does not show).
2974 :
2975 :			You can use these definition words to do factoring in cases that involve
2976 :			(other) definition words. E.g., a field offset is always added to an
2977 :			address. Instead of defining
2978 :
2979 :			@example
2980 :			2 cells constant offset-field1
2981 :			@end example
2982 :
2983 :			and using this like
2984 :
2985 :			@example
2986 :			( addr ) offset-field1 +
2987 :			@end example
2988 :
2989 :			you can define a definition word
2990 :
2991 :			@example
2992 :			: simple-field ( n "name" -- )
2993 :			create ,
2994 :			does> ( n1 -- n1+n )
2995 :	anton	1.50	( addr ) @@ + ;
2996 :	anton	1.48	@end example
2997 :	crook	1.21
2998 :	anton	1.48	Definition and use of field offsets now look like this:
2999 :	crook	1.21
3000 :	anton	1.48	@example
3001 :			2 cells simple-field field1
3002 :			( addr ) field1
3003 :			@end example
3004 :	crook	1.21
3005 :	anton	1.48	If you want to do something with the word without performing the code
3006 :			after the @code{does>}, you can access the body of a @code{create}d word
3007 :			with @code{>body ( xt -- addr )}:
3008 :	crook	1.21
3009 :	anton	1.48	@example
3010 :			: value ( n "name" -- )
3011 :			create ,
3012 :			does> ( -- n1 )
3013 :	anton	1.50	@@ ;
3014 :	anton	1.48	: to ( n "name" -- )
3015 :			' >body ! ;
3016 :	crook	1.21
3017 :	anton	1.48	5 value foo
3018 :			foo .
3019 :			7 to foo
3020 :			foo .
3021 :			@end example
3022 :	crook	1.21
3023 :	anton	1.48	@assignment
3024 :			Define @code{defer ( "name" -- )}, which creates a word that stores an
3025 :			XT (at the start the XT of @code{abort}), and upon execution
3026 :			@code{execute}s the XT. Define @code{is ( xt "name" -- )} that stores
3027 :			@code{xt} into @code{name}, a word defined with @code{defer}. Indirect
3028 :			recursion is one application of @code{defer}.
3029 :			@endassignment
3030 :	crook	1.29
3031 :	anton	1.48	@node Arrays and Records Tutorial, POSTPONE Tutorial, Defining Words Tutorial, Tutorial
3032 :			@section Arrays and Records
3033 :	crook	1.29
3034 :	anton	1.48	Forth has no standard words for defining data structures such as arrays
3035 :			and records (structs in C terminology), but you can build them yourself
3036 :			based on address arithmetic. You can also define words for defining
3037 :			arrays and records (@pxref{Defining Words Tutorial,, Defining Words}).
3038 :	crook	1.29
3039 :	anton	1.48	One of the first projects a Forth newcomer sets out upon when learning
3040 :			about defining words is an array defining word (possibly for
3041 :			n-dimensional arrays). Go ahead and do it, I did it, too; you will
3042 :			learn something from it. However, don't be disappointed when you later
3043 :			learn that you have little use for these words (inappropriate use would
3044 :			be even worse). I have not yet found a set of useful array words yet;
3045 :			the needs are just too diverse, and named, global arrays (the result of
3046 :			naive use of defining words) are often not flexible enough (e.g.,
3047 :			consider how to pass them as parameters).
3048 :	crook	1.29
3049 :	anton	1.48	On the other hand, there is a useful set of record words, and it has
3050 :			been defined in @file{compat/struct.fs}; these words are predefined in
3051 :			Gforth. They are explained in depth elsewhere in this manual (see
3052 :			@pxref{Structures}). The @code{simple-field} example above is
3053 :			simplified variant of fields in this package.
3054 :	crook	1.21
3055 :
3056 :	anton	1.48	@node POSTPONE Tutorial, Literal Tutorial, Arrays and Records Tutorial, Tutorial
3057 :			@section @code{POSTPONE}
3058 :	crook	1.21
3059 :	anton	1.48	You can compile the compilation semantics (instead of compiling the
3060 :			interpretation semantics) of a word with @code{POSTPONE}:
3061 :	crook	1.21
3062 :	anton	1.48	@example
3063 :			: MY-+ ( Compilation: -- ; Run-time of compiled code: n1 n2 -- n )
3064 :	pazsan	1.51	POSTPONE + ; immediate
3065 :	anton	1.48	: foo ( n1 n2 -- n )
3066 :			MY-+ ;
3067 :			1 2 foo .
3068 :			see foo
3069 :			@end example
3070 :	crook	1.21
3071 :	anton	1.48	During the definition of @code{foo} the text interpreter performs the
3072 :			compilation semantics of @code{MY-+}, which performs the compilation
3073 :			semantics of @code{+}, i.e., it compiles @code{+} into @code{foo}.
3074 :
3075 :			This example also displays separate stack comments for the compilation
3076 :			semantics and for the stack effect of the compiled code. For words with
3077 :			default compilation semantics these stack effects are usually not
3078 :			displayed; the stack effect of the compilation semantics is always
3079 :			@code{( -- )} for these words, the stack effect for the compiled code is
3080 :			the stack effect of the interpretation semantics.
3081 :
3082 :			Note that the state of the interpreter does not come into play when
3083 :			performing the compilation semantics in this way. You can also perform
3084 :			it interpretively, e.g.:
3085 :
3086 :			@example
3087 :			: foo2 ( n1 n2 -- n )
3088 :			[ MY-+ ] ;
3089 :			1 2 foo .
3090 :			see foo
3091 :			@end example
3092 :	crook	1.21
3093 :	anton	1.48	However, there are some broken Forth systems where this does not always
3094 :			work, and therefore this practice has been declared non-standard in
3095 :			1999.
3096 :			@c !! repair.fs
3097 :
3098 :			Here is another example for using @code{POSTPONE}:
3099 :	crook	1.44
3100 :	anton	1.48	@example
3101 :			: MY-- ( Compilation: -- ; Run-time of compiled code: n1 n2 -- n )
3102 :			POSTPONE negate POSTPONE + ; immediate compile-only
3103 :			: bar ( n1 n2 -- n )
3104 :			MY-- ;
3105 :			2 1 bar .
3106 :			see bar
3107 :			@end example
3108 :	crook	1.21
3109 :	anton	1.48	You can define @code{ENDIF} in this way:
3110 :	crook	1.21
3111 :	anton	1.48	@example
3112 :			: ENDIF ( Compilation: orig -- )
3113 :			POSTPONE then ; immediate
3114 :			@end example
3115 :	crook	1.21
3116 :	anton	1.48	@assignment
3117 :			Write @code{MY-2DUP} that has compilation semantics equivalent to
3118 :			@code{2dup}, but compiles @code{over over}.
3119 :			@endassignment
3120 :	crook	1.29
3121 :	anton	1.48	@node Literal Tutorial, Advanced macros Tutorial, POSTPONE Tutorial, Tutorial
3122 :			@section @code{Literal}
3123 :	crook	1.29
3124 :	anton	1.48	You cannot @code{POSTPONE} numbers:
3125 :	crook	1.21
3126 :	anton	1.48	@example
3127 :			: [FOO] POSTPONE 500 ; immediate
3128 :	crook	1.21	@end example
3129 :
3130 :	anton	1.48	Instead, you can use @code{LITERAL (compilation: n --; run-time: -- n )}:
3131 :	crook	1.29
3132 :	anton	1.48	@example
3133 :			: [FOO] ( compilation: --; run-time: -- n )
3134 :			500 POSTPONE literal ; immediate
3135 :	crook	1.29
3136 :	anton	1.48	: flip foo ;
3137 :			flip .
3138 :			see flip
3139 :			@end example
3140 :	crook	1.29
3141 :	anton	1.48	@code{LITERAL} consumes a number at compile-time (when it's compilation
3142 :			semantics are executed) and pushes it at run-time (when the code it
3143 :			compiled is executed). A frequent use of @code{LITERAL} is to compile a
3144 :			number computed at compile time into the current word:
3145 :	crook	1.29
3146 :	anton	1.48	@example
3147 :			: bar ( -- n )
3148 :			[ 2 2 + ] literal ;
3149 :			see bar
3150 :			@end example
3151 :	crook	1.29
3152 :	anton	1.48	@assignment
3153 :			Write @code{]L} which allows writing the example above as @code{: bar (
3154 :			-- n ) [ 2 2 + ]L ;}
3155 :			@endassignment
3156 :
3157 :
3158 :			@node Advanced macros Tutorial, Compilation Tokens Tutorial, Literal Tutorial, Tutorial
3159 :			@section Advanced macros
3160 :
3161 :			Reconsider @code{map-array} from @ref{Execution Tokens
3162 :			Tutorial,, Execution Tokens}. It frequently performs @code{execute}, a
3163 :			relatively expensive operation in some implementations. You can use
3164 :			@code{compile,} and @code{POSTPONE} to eliminate these @code{execute}s
3165 :			and produce a word that contains the word to be performed directly:
3166 :
3167 :			@c use ]] ... [[
3168 :			@example
3169 :			: compile-map-array ( compilation: xt -- ; run-time: ... addr u -- ... )
3170 :			\ at run-time, execute xt ( ... x -- ... ) for each element of the
3171 :			\ array beginning at addr and containing u elements
3172 :			@{ xt @}
3173 :			POSTPONE cells POSTPONE over POSTPONE + POSTPONE swap POSTPONE ?do
3174 :	anton	1.50	POSTPONE i POSTPONE @@ xt compile,
3175 :	anton	1.48	1 cells POSTPONE literal POSTPONE +loop ;
3176 :
3177 :			: sum-array ( addr u -- n )
3178 :			0 rot rot [ ' + compile-map-array ] ;
3179 :			see sum-array
3180 :			a 5 sum-array .
3181 :			@end example
3182 :
3183 :			You can use the full power of Forth for generating the code; here's an
3184 :			example where the code is generated in a loop:
3185 :
3186 :			@example
3187 :			: compile-vmul-step ( compilation: n --; run-time: n1 addr1 -- n2 addr2 )
3188 :			\ n2=n1+(addr1)*n, addr2=addr1+cell
3189 :	anton	1.50	POSTPONE tuck POSTPONE @@
3190 :	anton	1.48	POSTPONE literal POSTPONE * POSTPONE +
3191 :			POSTPONE swap POSTPONE cell+ ;
3192 :
3193 :			: compile-vmul ( compilation: addr1 u -- ; run-time: addr2 -- n )
3194 :	pazsan	1.51	\ n=v1*v2 (inner product), where the v_i are represented as addr_i u
3195 :	anton	1.48	0 postpone literal postpone swap
3196 :			[ ' compile-vmul-step compile-map-array ]
3197 :			postpone drop ;
3198 :			see compile-vmul
3199 :
3200 :			: a-vmul ( addr -- n )
3201 :	pazsan	1.51	\ n=a*v, where v is a vector that's as long as a and starts at addr
3202 :	anton	1.48	[ a 5 compile-vmul ] ;
3203 :			see a-vmul
3204 :			a a-vmul .
3205 :			@end example
3206 :
3207 :			This example uses @code{compile-map-array} to show off, but you could
3208 :			also use @code{map-array} instead (try it now).
3209 :
3210 :			You can use this technique for efficient multiplication of large
3211 :			matrices. In matrix multiplication, you multiply every line of one
3212 :			matrix with every column of the other matrix. You can generate the code
3213 :			for one line once, and use it for every column. The only downside of
3214 :			this technique is that it is cumbersome to recover the memory consumed
3215 :			by the generated code when you are done (and in more complicated cases
3216 :			it is not possible portably).
3217 :
3218 :			@node Compilation Tokens Tutorial, Wordlists and Search Order Tutorial, Advanced macros Tutorial, Tutorial
3219 :			@section Compilation Tokens
3220 :
3221 :			This section is Gforth-specific. You can skip it.
3222 :
3223 :			@code{' word compile,} compiles the interpretation semantics. For words
3224 :			with default compilation semantics this is the same as performing the
3225 :			compilation semantics. To represent the compilation semantics of other
3226 :			words (e.g., words like @code{if} that have no interpretation
3227 :			semantics), Gforth has the concept of a compilation token (CT,
3228 :			consisting of two cells), and words @code{comp'} and @code{[comp']}.
3229 :			You can perform the compilation semantics represented by a CT with
3230 :			@code{execute}:
3231 :	crook	1.29
3232 :	anton	1.48	@example
3233 :			: foo2 ( n1 n2 -- n )
3234 :			[ comp' + execute ] ;
3235 :			see foo
3236 :			@end example
3237 :	crook	1.29
3238 :	anton	1.48	You can compile the compilation semantics represented by a CT with
3239 :			@code{postpone,}:
3240 :	anton	1.30
3241 :	anton	1.48	@example
3242 :			: foo3 ( -- )
3243 :			[ comp' + postpone, ] ;
3244 :			see foo3
3245 :			@end example
3246 :	anton	1.30
3247 :	pazsan	1.51	@code{[ comp' word postpone, ]} is equivalent to @code{POSTPONE word}.
3248 :	anton	1.48	@code{comp'} is particularly useful for words that have no
3249 :			interpretation semantics:
3250 :	crook	1.29
3251 :	anton	1.30	@example
3252 :	anton	1.48	' if
3253 :			comp' if .s
3254 :	anton	1.30	@end example
3255 :
3256 :	crook	1.29
3257 :	anton	1.48	@node Wordlists and Search Order Tutorial, , Compilation Tokens Tutorial, Tutorial
3258 :			@section Wordlists and Search Order
3259 :
3260 :			The dictionary is not just a memory area that allows you to allocate
3261 :			memory with @code{allot}, it also contains the Forth words, arranged in
3262 :			several wordlists. When searching for a word in a wordlist,
3263 :			conceptually you start searching at the youngest and proceed towards
3264 :			older words (in reality most systems nowadays use hash-tables); i.e., if
3265 :			you define a word with the same name as an older word, the new word
3266 :			shadows the older word.
3267 :
3268 :			Which wordlists are searched in which order is determined by the search
3269 :			order. You can display the search order with @code{order}. It displays
3270 :			first the search order, starting with the wordlist searched first, then
3271 :			it displays the wordlist that will contain newly defined words.
3272 :	crook	1.21
3273 :	anton	1.48	You can create a new, empty wordlist with @code{wordlist ( -- wid )}:
3274 :	crook	1.21
3275 :	anton	1.48	@example
3276 :			wordlist constant mywords
3277 :			@end example
3278 :	crook	1.21
3279 :	anton	1.48	@code{Set-current ( wid -- )} sets the wordlist that will contain newly
3280 :			defined words (the @emph{current} wordlist):
3281 :	crook	1.21
3282 :	anton	1.48	@example
3283 :			mywords set-current
3284 :			order
3285 :			@end example
3286 :	crook	1.26
3287 :	anton	1.48	Gforth does not display a name for the wordlist in @code{mywords}
3288 :			because this wordlist was created anonymously with @code{wordlist}.
3289 :	crook	1.21
3290 :	anton	1.48	You can get the current wordlist with @code{get-current ( -- wid)}. If
3291 :			you want to put something into a specific wordlist without overall
3292 :			effect on the current wordlist, this typically looks like this:
3293 :	crook	1.21
3294 :	anton	1.48	@example
3295 :			get-current mywords set-current ( wid )
3296 :			create someword
3297 :			( wid ) set-current
3298 :			@end example
3299 :	crook	1.21
3300 :	anton	1.48	You can write the search order with @code{set-order ( wid1 .. widn n --
3301 :			)} and read it with @code{get-order ( -- wid1 .. widn n )}. The first
3302 :			searched wordlist is topmost.
3303 :	crook	1.21
3304 :	anton	1.48	@example
3305 :			get-order mywords swap 1+ set-order
3306 :			order
3307 :			@end example
3308 :	crook	1.21
3309 :	anton	1.48	Yes, the order of wordlists in the output of @code{order} is reversed
3310 :			from stack comments and the output of @code{.s} and thus unintuitive.
3311 :	crook	1.21
3312 :	anton	1.48	@assignment
3313 :			Define @code{>order ( wid -- )} with adds @code{wid} as first searched
3314 :			wordlist to the search order. Define @code{previous ( -- )}, which
3315 :			removes the first searched wordlist from the search order. Experiment
3316 :			with boundary conditions (you will see some crashes or situations that
3317 :			are hard or impossible to leave).
3318 :			@endassignment
3319 :	crook	1.21
3320 :	anton	1.48	The search order is a powerful foundation for providing features similar
3321 :			to Modula-2 modules and C++ namespaces. However, trying to modularize
3322 :			programs in this way has disadvantages for debugging and reuse/factoring
3323 :			that overcome the advantages in my experience (I don't do huge projects,
3324 :			though). These disadvanategs are not so clear in other
3325 :			languages/programming environments, because these langauges are not so
3326 :			strong in debugging and reuse.
3327 :	crook	1.21
3328 :
3329 :	crook	1.29	@c ******************************************************************
3330 :	anton	1.48	@node Introduction, Words, Tutorial, Top
3331 :	crook	1.29	@comment node-name, next, previous, up
3332 :			@chapter An Introduction to ANS Forth
3333 :			@cindex Forth - an introduction
3334 :	crook	1.21
3335 :	crook	1.29	The primary purpose of this manual is to document Gforth. However, since
3336 :			Forth is not a widely-known language and there is a lack of up-to-date
3337 :			teaching material, it seems worthwhile to provide some introductory
3338 :	anton	1.49	material. For other sources of Forth-related
3339 :			information, see @ref{Forth-related information}.
3340 :	crook	1.21
3341 :	crook	1.29	The examples in this section should work on any ANS Forth; the
3342 :			output shown was produced using Gforth. Each example attempts to
3343 :			reproduce the exact output that Gforth produces. If you try out the
3344 :			examples (and you should), what you should type is shown @kbd{like this}
3345 :			and Gforth's response is shown @code{like this}. The single exception is
3346 :	anton	1.30	that, where the example shows @key{RET} it means that you should
3347 :	crook	1.29	press the ``carriage return'' key. Unfortunately, some output formats for
3348 :			this manual cannot show the difference between @kbd{this} and
3349 :			@code{this} which will make trying out the examples harder (but not
3350 :			impossible).
3351 :	crook	1.21
3352 :	crook	1.29	Forth is an unusual language. It provides an interactive development
3353 :			environment which includes both an interpreter and compiler. Forth
3354 :			programming style encourages you to break a problem down into many
3355 :			@cindex factoring
3356 :			small fragments (@dfn{factoring}), and then to develop and test each
3357 :			fragment interactively. Forth advocates assert that breaking the
3358 :			edit-compile-test cycle used by conventional programming languages can
3359 :			lead to great productivity improvements.
3360 :	crook	1.21
3361 :	crook	1.29	@menu
3362 :			* Introducing the Text Interpreter::
3363 :			* Stacks and Postfix notation::
3364 :			* Your first definition::
3365 :			* How does that work?::
3366 :			* Forth is written in Forth::
3367 :			* Review - elements of a Forth system::
3368 :			* Where to go next::
3369 :			* Exercises::
3370 :			@end menu
3371 :	crook	1.21
3372 :	crook	1.29	@comment ----------------------------------------------
3373 :			@node Introducing the Text Interpreter, Stacks and Postfix notation, Introduction, Introduction
3374 :			@section Introducing the Text Interpreter
3375 :			@cindex text interpreter
3376 :			@cindex outer interpreter
3377 :	crook	1.21
3378 :	anton	1.30	@c IMO this is too detailed and the pace is too slow for
3379 :			@c an introduction. If you know German, take a look at
3380 :			@c http://www.complang.tuwien.ac.at/anton/lvas/skriptum-stack.html
3381 :			@c to see how I do it - anton
3382 :
3383 :	crook	1.44	@c nac-> Where I have accepted your comments 100% and modified the text
3384 :			@c accordingly, I have deleted your comments. Elsewhere I have added a
3385 :			@c response like this to attempt to rationalise what I have done. Of
3386 :			@c course, this is a very clumsy mechanism for something that would be
3387 :			@c done far more efficiently over a beer. Please delete any dialogue
3388 :			@c you consider closed.
3389 :
3390 :	crook	1.29	When you invoke the Forth image, you will see a startup banner printed
3391 :			and nothing else (if you have Gforth installed on your system, try
3392 :	anton	1.30	invoking it now, by typing @kbd{gforth@key{RET}}). Forth is now running
3393 :	crook	1.29	its command line interpreter, which is called the @dfn{Text Interpreter}
3394 :			(also known as the @dfn{Outer Interpreter}). (You will learn a lot
3395 :	anton	1.49	about the text interpreter as you read through this chapter, for more
3396 :			detail @pxref{The Text Interpreter}).
3397 :	crook	1.21
3398 :	crook	1.29	Although it's not obvious, Forth is actually waiting for your
3399 :	anton	1.30	input. Type a number and press the @key{RET} key:
3400 :	crook	1.21
3401 :	crook	1.26	@example
3402 :	anton	1.30	@kbd{45@key{RET}} ok
3403 :	crook	1.26	@end example
3404 :	crook	1.21
3405 :	crook	1.29	Rather than give you a prompt to invite you to input something, the text
3406 :			interpreter prints a status message @i{after} it has processed a line
3407 :			of input. The status message in this case (``@code{ ok}'' followed by
3408 :			carriage-return) indicates that the text interpreter was able to process
3409 :			all of your input successfully. Now type something illegal:
3410 :
3411 :			@example
3412 :	anton	1.30	@kbd{qwer341@key{RET}}
3413 :	crook	1.29	:1: Undefined word
3414 :			qwer341
3415 :			^^^^^^^
3416 :			$400D2BA8 Bounce
3417 :			$400DBDA8 no.extensions
3418 :			@end example
3419 :	crook	1.23
3420 :	crook	1.29	The exact text, other than the ``Undefined word'' may differ slightly on
3421 :			your system, but the effect is the same; when the text interpreter
3422 :			detects an error, it discards any remaining text on a line, resets
3423 :	anton	1.49	certain internal state and prints an error message. For a detailed description of error messages see @ref{Error
3424 :			messages}.
3425 :	crook	1.23
3426 :	crook	1.29	The text interpreter waits for you to press carriage-return, and then
3427 :			processes your input line. Starting at the beginning of the line, it
3428 :			breaks the line into groups of characters separated by spaces. For each
3429 :			group of characters in turn, it makes two attempts to do something:
3430 :	crook	1.23
3431 :	crook	1.29	@itemize @bullet
3432 :			@item
3433 :	crook	1.44	@cindex name dictionary
3434 :	crook	1.29	It tries to treat it as a command. It does this by searching a @dfn{name
3435 :			dictionary}. If the group of characters matches an entry in the name
3436 :			dictionary, the name dictionary provides the text interpreter with
3437 :			information that allows the text interpreter perform some actions. In
3438 :			Forth jargon, we say that the group
3439 :			@cindex word
3440 :			@cindex definition
3441 :			@cindex execution token
3442 :			@cindex xt
3443 :			of characters names a @dfn{word}, that the dictionary search returns an
3444 :			@dfn{execution token (xt)} corresponding to the @dfn{definition} of the
3445 :			word, and that the text interpreter executes the xt. Often, the terms
3446 :			@dfn{word} and @dfn{definition} are used interchangeably.
3447 :			@item
3448 :			If the text interpreter fails to find a match in the name dictionary, it
3449 :			tries to treat the group of characters as a number in the current number
3450 :			base (when you start up Forth, the current number base is base 10). If
3451 :			the group of characters legitimately represents a number, the text
3452 :			interpreter pushes the number onto a stack (we'll learn more about that
3453 :			in the next section).
3454 :			@end itemize
3455 :	crook	1.23
3456 :	crook	1.29	If the text interpreter is unable to do either of these things with any
3457 :			group of characters, it discards the group of characters and the rest of
3458 :			the line, then prints an error message. If the text interpreter reaches
3459 :			the end of the line without error, it prints the status message ``@code{ ok}''
3460 :			followed by carriage-return.
3461 :	crook	1.21
3462 :	crook	1.29	This is the simplest command we can give to the text interpreter:
3463 :	crook	1.23
3464 :			@example
3465 :	anton	1.30	@key{RET} ok
3466 :	crook	1.23	@end example
3467 :	crook	1.21
3468 :	crook	1.29	The text interpreter did everything we asked it to do (nothing) without
3469 :			an error, so it said that everything is ``@code{ ok}''. Try a slightly longer
3470 :			command:
3471 :	crook	1.21
3472 :	crook	1.23	@example
3473 :	anton	1.30	@kbd{12 dup fred dup@key{RET}}
3474 :	crook	1.29	:1: Undefined word
3475 :			12 dup fred dup
3476 :			^^^^
3477 :			$400D2BA8 Bounce
3478 :			$400DBDA8 no.extensions
3479 :	crook	1.23	@end example
3480 :	crook	1.21
3481 :	crook	1.29	When you press the carriage-return key, the text interpreter starts to
3482 :			work its way along the line:
3483 :	crook	1.21
3484 :	crook	1.29	@itemize @bullet
3485 :			@item
3486 :			When it gets to the space after the @code{2}, it takes the group of
3487 :			characters @code{12} and looks them up in the name
3488 :			dictionary@footnote{We can't tell if it found them or not, but assume
3489 :			for now that it did not}. There is no match for this group of characters
3490 :			in the name dictionary, so it tries to treat them as a number. It is
3491 :			able to do this successfully, so it puts the number, 12, ``on the stack''
3492 :			(whatever that means).
3493 :			@item
3494 :			The text interpreter resumes scanning the line and gets the next group
3495 :			of characters, @code{dup}. It looks it up in the name dictionary and
3496 :			(you'll have to take my word for this) finds it, and executes the word
3497 :			@code{dup} (whatever that means).
3498 :			@item
3499 :			Once again, the text interpreter resumes scanning the line and gets the
3500 :			group of characters @code{fred}. It looks them up in the name
3501 :			dictionary, but can't find them. It tries to treat them as a number, but
3502 :			they don't represent any legal number.
3503 :			@end itemize
3504 :	crook	1.21
3505 :	crook	1.29	At this point, the text interpreter gives up and prints an error
3506 :			message. The error message shows exactly how far the text interpreter
3507 :			got in processing the line. In particular, it shows that the text
3508 :			interpreter made no attempt to do anything with the final character
3509 :			group, @code{dup}, even though we have good reason to believe that the
3510 :			text interpreter would have no problem looking that word up and
3511 :			executing it a second time.
3512 :	crook	1.21
3513 :
3514 :	crook	1.29	@comment ----------------------------------------------
3515 :			@node Stacks and Postfix notation, Your first definition, Introducing the Text Interpreter, Introduction
3516 :			@section Stacks, postfix notation and parameter passing
3517 :			@cindex text interpreter
3518 :			@cindex outer interpreter
3519 :	crook	1.21
3520 :	crook	1.29	In procedural programming languages (like C and Pascal), the
3521 :			building-block of programs is the @dfn{function} or @dfn{procedure}. These
3522 :			functions or procedures are called with @dfn{explicit parameters}. For
3523 :			example, in C we might write:
3524 :	crook	1.21
3525 :	crook	1.23	@example
3526 :	crook	1.29	total = total + new_volume(length,height,depth);
3527 :	crook	1.23	@end example
3528 :	crook	1.21
3529 :	crook	1.23	@noindent
3530 :	crook	1.29	where new_volume is a function-call to another piece of code, and total,
3531 :			length, height and depth are all variables. length, height and depth are
3532 :			parameters to the function-call.
3533 :	crook	1.21
3534 :	crook	1.29	In Forth, the equivalent of the function or procedure is the
3535 :			@dfn{definition} and parameters are implicitly passed between
3536 :			definitions using a shared stack that is visible to the
3537 :			programmer. Although Forth does support variables, the existence of the
3538 :			stack means that they are used far less often than in most other
3539 :			programming languages. When the text interpreter encounters a number, it
3540 :			will place (@dfn{push}) it on the stack. There are several stacks (the
3541 :	anton	1.30	actual number is implementation-dependent ...) and the particular stack
3542 :	crook	1.29	used for any operation is implied unambiguously by the operation being
3543 :			performed. The stack used for all integer operations is called the @dfn{data
3544 :			stack} and, since this is the stack used most commonly, references to
3545 :			``the data stack'' are often abbreviated to ``the stack''.
3546 :	crook	1.21
3547 :	crook	1.29	The stacks have a last-in, first-out (LIFO) organisation. If you type:
3548 :	crook	1.21
3549 :	crook	1.23	@example
3550 :	anton	1.30	@kbd{1 2 3@key{RET}} ok
3551 :	crook	1.23	@end example
3552 :	crook	1.21
3553 :	crook	1.29	Then this instructs the text interpreter to placed three numbers on the
3554 :			(data) stack. An analogy for the behaviour of the stack is to take a
3555 :			pack of playing cards and deal out the ace (1), 2 and 3 into a pile on
3556 :			the table. The 3 was the last card onto the pile (``last-in'') and if
3557 :			you take a card off the pile then, unless you're prepared to fiddle a
3558 :			bit, the card that you take off will be the 3 (``first-out''). The
3559 :			number that will be first-out of the stack is called the @dfn{top of
3560 :			stack}, which
3561 :			@cindex TOS definition
3562 :			is often abbreviated to @dfn{TOS}.
3563 :	crook	1.21
3564 :	crook	1.29	To understand how parameters are passed in Forth, consider the
3565 :			behaviour of the definition @code{+} (pronounced ``plus''). You will not
3566 :			be surprised to learn that this definition performs addition. More
3567 :			precisely, it adds two number together and produces a result. Where does
3568 :			it get the two numbers from? It takes the top two numbers off the
3569 :			stack. Where does it place the result? On the stack. You can act-out the
3570 :			behaviour of @code{+} with your playing cards like this:
3571 :	crook	1.21
3572 :			@itemize @bullet
3573 :			@item
3574 :	crook	1.29	Pick up two cards from the stack on the table
3575 :	crook	1.21	@item
3576 :	crook	1.29	Stare at them intently and ask yourself ``what @i{is} the sum of these two
3577 :			numbers''
3578 :	crook	1.21	@item
3579 :	crook	1.29	Decide that the answer is 5
3580 :	crook	1.21	@item
3581 :	crook	1.29	Shuffle the two cards back into the pack and find a 5
3582 :	crook	1.21	@item
3583 :	crook	1.29	Put a 5 on the remaining ace that's on the table.
3584 :	crook	1.21	@end itemize
3585 :
3586 :	crook	1.29	If you don't have a pack of cards handy but you do have Forth running,
3587 :			you can use the definition @code{.s} to show the current state of the stack,
3588 :			without affecting the stack. Type:
3589 :	crook	1.21
3590 :			@example
3591 :	anton	1.30	@kbd{clearstack 1 2 3@key{RET}} ok
3592 :			@kbd{.s@key{RET}} <3> 1 2 3 ok
3593 :	crook	1.23	@end example
3594 :
3595 :	crook	1.29	The text interpreter looks up the word @code{clearstack} and executes
3596 :			it; it tidies up the stack and removes any entries that may have been
3597 :			left on it by earlier examples. The text interpreter pushes each of the
3598 :			three numbers in turn onto the stack. Finally, the text interpreter
3599 :			looks up the word @code{.s} and executes it. The effect of executing
3600 :			@code{.s} is to print the ``<3>'' (the total number of items on the stack)
3601 :			followed by a list of all the items on the stack; the item on the far
3602 :			right-hand side is the TOS.
3603 :	crook	1.21
3604 :	crook	1.29	You can now type:
3605 :	crook	1.21
3606 :	crook	1.29	@example
3607 :	anton	1.30	@kbd{+ .s@key{RET}} <2> 1 5 ok
3608 :	crook	1.29	@end example
3609 :	crook	1.21
3610 :	crook	1.29	@noindent
3611 :			which is correct; there are now 2 items on the stack and the result of
3612 :			the addition is 5.
3613 :	crook	1.23
3614 :	crook	1.29	If you're playing with cards, try doing a second addition: pick up the
3615 :			two cards, work out that their sum is 6, shuffle them into the pack,
3616 :			look for a 6 and place that on the table. You now have just one item on
3617 :			the stack. What happens if you try to do a third addition? Pick up the
3618 :			first card, pick up the second card -- ah! There is no second card. This
3619 :			is called a @dfn{stack underflow} and consitutes an error. If you try to
3620 :			do the same thing with Forth it will report an error (probably a Stack
3621 :			Underflow or an Invalid Memory Address error).
3622 :	crook	1.23
3623 :	crook	1.29	The opposite situation to a stack underflow is a @dfn{stack overflow},
3624 :			which simply accepts that there is a finite amount of storage space
3625 :			reserved for the stack. To stretch the playing card analogy, if you had
3626 :			enough packs of cards and you piled the cards up on the table, you would
3627 :			eventually be unable to add another card; you'd hit the ceiling. Gforth
3628 :			allows you to set the maximum size of the stacks. In general, the only
3629 :			time that you will get a stack overflow is because a definition has a
3630 :			bug in it and is generating data on the stack uncontrollably.
3631 :	crook	1.23
3632 :	crook	1.29	There's one final use for the playing card analogy. If you model your
3633 :			stack using a pack of playing cards, the maximum number of items on
3634 :			your stack will be 52 (I assume you didn't use the Joker). The maximum
3635 :			@i{value} of any item on the stack is 13 (the King). In fact, the only
3636 :			possible numbers are positive integer numbers 1 through 13; you can't
3637 :			have (for example) 0 or 27 or 3.52 or -2. If you change the way you
3638 :			think about some of the cards, you can accommodate different
3639 :			numbers. For example, you could think of the Jack as representing 0,
3640 :			the Queen as representing -1 and the King as representing -2. Your
3641 :	crook	1.45	@i{range} remains unchanged (you can still only represent a total of 13
3642 :	crook	1.29	numbers) but the numbers that you can represent are -2 through 10.
3643 :	crook	1.28
3644 :	crook	1.29	In that analogy, the limit was the amount of information that a single
3645 :			stack entry could hold, and Forth has a similar limit. In Forth, the
3646 :			size of a stack entry is called a @dfn{cell}. The actual size of a cell is
3647 :			implementation dependent and affects the maximum value that a stack
3648 :			entry can hold. A Standard Forth provides a cell size of at least
3649 :			16-bits, and most desktop systems use a cell size of 32-bits.
3650 :	crook	1.21
3651 :	crook	1.29	Forth does not do any type checking for you, so you are free to
3652 :			manipulate and combine stack items in any way you wish. A convenient way
3653 :			of treating stack items is as 2's complement signed integers, and that
3654 :			is what Standard words like @code{+} do. Therefore you can type:
3655 :	crook	1.21
3656 :	crook	1.29	@example
3657 :	anton	1.30	@kbd{-5 12 + .s@key{RET}} <1> 7 ok
3658 :	crook	1.29	@end example
3659 :	crook	1.21
3660 :	crook	1.29	If you use numbers and definitions like @code{+} in order to turn Forth
3661 :			into a great big pocket calculator, you will realise that it's rather
3662 :			different from a normal calculator. Rather than typing 2 + 3 = you had
3663 :			to type 2 3 + (ignore the fact that you had to use @code{.s} to see the
3664 :			result). The terminology used to describe this difference is to say that
3665 :			your calculator uses @dfn{Infix Notation} (parameters and operators are
3666 :			mixed) whilst Forth uses @dfn{Postfix Notation} (parameters and
3667 :			operators are separate), also called @dfn{Reverse Polish Notation}.
3668 :	crook	1.21
3669 :	crook	1.29	Whilst postfix notation might look confusing to begin with, it has
3670 :			several important advantages:
3671 :	crook	1.21
3672 :	crook	1.23	@itemize @bullet
3673 :			@item
3674 :	crook	1.29	it is unambiguous
3675 :	crook	1.23	@item
3676 :	crook	1.29	it is more concise
3677 :	crook	1.23	@item
3678 :	crook	1.29	it fits naturally with a stack-based system
3679 :	crook	1.23	@end itemize
3680 :	crook	1.21
3681 :	crook	1.29	To examine these claims in more detail, consider these sums:
3682 :	crook	1.21
3683 :	crook	1.29	@example
3684 :			6 + 5 * 4 =
3685 :			4 * 5 + 6 =
3686 :			@end example
3687 :	crook	1.21
3688 :	crook	1.29	If you're just learning maths or your maths is very rusty, you will
3689 :			probably come up with the answer 44 for the first and 26 for the
3690 :			second. If you are a bit of a whizz at maths you will remember the
3691 :			@i{convention} that multiplication takes precendence over addition, and
3692 :			you'd come up with the answer 26 both times. To explain the answer 26
3693 :			to someone who got the answer 44, you'd probably rewrite the first sum
3694 :			like this:
3695 :	crook	1.21
3696 :	crook	1.29	@example
3697 :			6 + (5 * 4) =
3698 :			@end example
3699 :	crook	1.21
3700 :	crook	1.29	If what you really wanted was to perform the addition before the
3701 :			multiplication, you would have to use parentheses to force it.
3702 :	crook	1.21
3703 :	crook	1.29	If you did the first two sums on a pocket calculator you would probably
3704 :			get the right answers, unless you were very cautious and entered them using
3705 :			these keystroke sequences:
3706 :	crook	1.21
3707 :	crook	1.29	6 + 5 = * 4 =
3708 :			4 * 5 = + 6 =
3709 :	crook	1.21
3710 :	crook	1.29	Postfix notation is unambiguous because the order that the operators
3711 :			are applied is always explicit; that also means that parentheses are
3712 :			never required. The operators are @i{active} (the act of quoting the
3713 :			operator makes the operation occur) which removes the need for ``=''.
3714 :	crook	1.28
3715 :	crook	1.29	The sum 6 + 5 * 4 can be written (in postfix notation) in two
3716 :			equivalent ways:
3717 :	crook	1.26
3718 :			@example
3719 :	crook	1.29	6 5 4 * + or:
3720 :			5 4 * 6 +
3721 :	crook	1.26	@end example
3722 :	crook	1.23
3723 :	crook	1.29	An important thing that you should notice about this notation is that
3724 :			the @i{order} of the numbers does not change; if you want to subtract
3725 :			2 from 10 you type @code{10 2 -}.
3726 :	anton	1.1
3727 :	crook	1.29	The reason that Forth uses postfix notation is very simple to explain: it
3728 :			makes the implementation extremely simple, and it follows naturally from
3729 :			using the stack as a mechanism for passing parameters. Another way of
3730 :			thinking about this is to realise that all Forth definitions are
3731 :			@i{active}; they execute as they are encountered by the text
3732 :			interpreter. The result of this is that the syntax of Forth is trivially
3733 :			simple.
3734 :	anton	1.1
3735 :
3736 :
3737 :	crook	1.29	@comment ----------------------------------------------
3738 :			@node Your first definition, How does that work?, Stacks and Postfix notation, Introduction
3739 :			@section Your first Forth definition
3740 :			@cindex first definition
3741 :	anton	1.1
3742 :	crook	1.29	Until now, the examples we've seen have been trivial; we've just been
3743 :			using Forth as a bigger-than-pocket calculator. Also, each calculation
3744 :			we've shown has been a ``one-off'' -- to repeat it we'd need to type it in
3745 :			again@footnote{That's not quite true. If you press the up-arrow key on
3746 :			your keyboard you should be able to scroll back to any earlier command,
3747 :			edit it and re-enter it.} In this section we'll see how to add new
3748 :			words to Forth's vocabulary.
3749 :	anton	1.1
3750 :	crook	1.29	The easiest way to create a new word is to use a @dfn{colon
3751 :			definition}. We'll define a few and try them out before worrying too
3752 :			much about how they work. Try typing in these examples; be careful to
3753 :			copy the spaces accurately:
3754 :	anton	1.1
3755 :	crook	1.29	@example
3756 :			: add-two 2 + . ;
3757 :			: greet ." Hello and welcome" ;
3758 :			: demo 5 add-two ;
3759 :			@end example
3760 :	anton	1.1
3761 :	crook	1.29	@noindent
3762 :			Now try them out:
3763 :	anton	1.1
3764 :	crook	1.29	@example
3765 :	anton	1.30	@kbd{greet@key{RET}} Hello and welcome ok
3766 :			@kbd{greet greet@key{RET}} Hello and welcomeHello and welcome ok
3767 :			@kbd{4 add-two@key{RET}} 6 ok
3768 :			@kbd{demo@key{RET}} 7 ok
3769 :			@kbd{9 greet demo add-two@key{RET}} Hello and welcome7 11 ok
3770 :	crook	1.29	@end example
3771 :	anton	1.1
3772 :	crook	1.29	The first new thing that we've introduced here is the pair of words
3773 :			@code{:} and @code{;}. These are used to start and terminate a new
3774 :			definition, respectively. The first word after the @code{:} is the name
3775 :			for the new definition.
3776 :	anton	1.1
3777 :	crook	1.29	As you can see from the examples, a definition is built up of words that
3778 :			have already been defined; Forth makes no distinction between
3779 :			definitions that existed when you started the system up, and those that
3780 :			you define yourself.
3781 :	anton	1.1
3782 :	crook	1.29	The examples also introduce the words @code{.} (dot), @code{."}
3783 :			(dot-quote) and @code{dup} (dewp). Dot takes the value from the top of
3784 :			the stack and displays it. It's like @code{.s} except that it only
3785 :			displays the top item of the stack and it is destructive; after it has
3786 :			executed, the number is no longer on the stack. There is always one
3787 :			space printed after the number, and no spaces before it. Dot-quote
3788 :			defines a string (a sequence of characters) that will be printed when
3789 :			the word is executed. The string can contain any printable characters
3790 :			except @code{"}. A @code{"} has a special function; it is not a Forth
3791 :			word but it acts as a delimiter (the way that delimiters work is
3792 :			described in the next section). Finally, @code{dup} duplicates the value
3793 :			at the top of the stack. Try typing @code{5 dup .s} to see what it does.
3794 :	anton	1.1
3795 :	crook	1.29	We already know that the text interpreter searches through the
3796 :			dictionary to locate names. If you've followed the examples earlier, you
3797 :			will already have a definition called @code{add-two}. Lets try modifying
3798 :			it by typing in a new definition:
3799 :	anton	1.1
3800 :	crook	1.29	@example
3801 :	anton	1.30	@kbd{: add-two dup . ." + 2 =" 2 + . ;@key{RET}} redefined add-two ok
3802 :	crook	1.29	@end example
3803 :	anton	1.5
3804 :	crook	1.29	Forth recognised that we were defining a word that already exists, and
3805 :			printed a message to warn us of that fact. Let's try out the new
3806 :			definition:
3807 :	anton	1.5
3808 :	crook	1.29	@example
3809 :	anton	1.30	@kbd{9 add-two@key{RET}} 9 + 2 =11 ok
3810 :	crook	1.29	@end example
3811 :	anton	1.1
3812 :	crook	1.29	@noindent
3813 :			All that we've actually done here, though, is to create a new
3814 :			definition, with a particular name. The fact that there was already a
3815 :			definition with the same name did not make any difference to the way
3816 :			that the new definition was created (except that Forth printed a warning
3817 :			message). The old definition of add-two still exists (try @code{demo}
3818 :			again to see that this is true). Any new definition will use the new
3819 :			definition of @code{add-two}, but old definitions continue to use the
3820 :			version that already existed at the time that they were @code{compiled}.
3821 :	anton	1.1
3822 :	crook	1.29	Before you go on to the next section, try defining and redefining some
3823 :			words of your own.
3824 :	anton	1.1
3825 :	crook	1.29	@comment ----------------------------------------------
3826 :			@node How does that work?, Forth is written in Forth, Your first definition, Introduction
3827 :			@section How does that work?
3828 :			@cindex parsing words
3829 :	anton	1.1
3830 :	anton	1.30	@c That's pretty deep (IMO way too deep) for an introduction. - anton
3831 :
3832 :			@c Is it a good idea to talk about the interpretation semantics of a
3833 :			@c number? We don't have an xt to go along with it. - anton
3834 :
3835 :			@c Now that I have eliminated execution semantics, I wonder if it would not
3836 :			@c be better to keep them (or add run-time semantics), to make it easier to
3837 :			@c explain what compilation semantics usually does. - anton
3838 :
3839 :	crook	1.44	@c nac-> I removed the term ``default compilation sematics'' from the
3840 :			@c introductory chapter. Removing ``execution semantics'' was making
3841 :			@c everything simpler to explain, then I think the use of this term made
3842 :			@c everything more complex again. I replaced it with ``default
3843 :			@c semantics'' (which is used elsewhere in the manual) by which I mean
3844 :			@c ``a definition that has neither the immediate nor the compile-only
3845 :			@c flag set''. I reworded big chunks of the ``how does that work''
3846 :			@c section (and, unusually for me, I think I even made it shorter!). See
3847 :			@c what you think -- I know I have not addressed your primary concern
3848 :			@c that it is too heavy-going for an introduction. From what I understood
3849 :			@c of your course notes it looks as though they might be a good framework.
3850 :			@c Things that I've tried to capture here are some things that came as a
3851 :			@c great revelation here when I first understood them. Also, I like the
3852 :			@c fact that a very simple code example shows up almost all of the issues
3853 :			@c that you need to understand to see how Forth works. That's unique and
3854 :			@c worthwhile to emphasise.
3855 :
3856 :	crook	1.29	Now we're going to take another look at the definition of @code{add-two}
3857 :			from the previous section. From our knowledge of the way that the text
3858 :			interpreter works, we would have expected this result when we tried to
3859 :			define @code{add-two}:
3860 :	crook	1.21
3861 :	crook	1.29	@example
3862 :	crook	1.44	@kbd{: add-two 2 + . ;@key{RET}}
3863 :	crook	1.29	^^^^^^^
3864 :			Error: Undefined word
3865 :			@end example
3866 :	crook	1.28
3867 :	crook	1.29	The reason that this didn't happen is bound up in the way that @code{:}
3868 :			works. The word @code{:} does two special things. The first special
3869 :			thing that it does prevents the text interpreter from ever seeing the
3870 :			characters @code{add-two}. The text interpreter uses a variable called
3871 :			@cindex modifying >IN
3872 :	crook	1.44	@code{>IN} (pronounced ``to-in'') to keep track of where it is in the
3873 :	crook	1.29	input line. When it encounters the word @code{:} it behaves in exactly
3874 :			the same way as it does for any other word; it looks it up in the name
3875 :			dictionary, finds its xt and executes it. When @code{:} executes, it
3876 :			looks at the input buffer, finds the word @code{add-two} and advances the
3877 :			value of @code{>IN} to point past it. It then does some other stuff
3878 :			associated with creating the new definition (including creating an entry
3879 :			for @code{add-two} in the name dictionary). When the execution of @code{:}
3880 :			completes, control returns to the text interpreter, which is oblivious
3881 :			to the fact that it has been tricked into ignoring part of the input
3882 :			line.
3883 :	crook	1.21
3884 :	crook	1.29	@cindex parsing words
3885 :			Words like @code{:} -- words that advance the value of @code{>IN} and so
3886 :			prevent the text interpreter from acting on the whole of the input line
3887 :			-- are called @dfn{parsing words}.
3888 :	crook	1.21
3889 :	crook	1.29	@cindex @code{state} - effect on the text interpreter
3890 :			@cindex text interpreter - effect of state
3891 :			The second special thing that @code{:} does is change the value of a
3892 :			variable called @code{state}, which affects the way that the text
3893 :			interpreter behaves. When Gforth starts up, @code{state} has the value
3894 :			0, and the text interpreter is said to be @dfn{interpreting}. During a
3895 :			colon definition (started with @code{:}), @code{state} is set to -1 and
3896 :	crook	1.44	the text interpreter is said to be @dfn{compiling}.
3897 :
3898 :			In this example, the text interpreter is compiling when it processes the
3899 :			string ``@code{2 + . ;}''. It still breaks the string down into
3900 :			character sequences in the same way. However, instead of pushing the
3901 :			number @code{2} onto the stack, it lays down (@dfn{compiles}) some magic
3902 :			into the definition of @code{add-two} that will make the number @code{2} get
3903 :			pushed onto the stack when @code{add-two} is @dfn{executed}. Similarly,
3904 :			the behaviours of @code{+} and @code{.} are also compiled into the
3905 :			definition.
3906 :
3907 :			One category of words don't get compiled. These so-called @dfn{immediate
3908 :			words} get executed (performed @i{now}) regardless of whether the text
3909 :			interpreter is interpreting or compiling. The word @code{;} is an
3910 :			immediate word. Rather than being compiled into the definition, it
3911 :			executes. Its effect is to terminate the current definition, which
3912 :			includes changing the value of @code{state} back to 0.
3913 :
3914 :			When you execute @code{add-two}, it has a @dfn{run-time effect} that is
3915 :			exactly the same as if you had typed @code{2 + . @key{RET}} outside of a
3916 :			definition.
3917 :	crook	1.28
3918 :	anton	1.30	In Forth, every word or number can be described in terms of two
3919 :	crook	1.29	properties:
3920 :	crook	1.28
3921 :			@itemize @bullet
3922 :			@item
3923 :	crook	1.29	@cindex interpretation semantics
3924 :	crook	1.44	Its @dfn{interpretation semantics} describe how it will behave when the
3925 :			text interpreter encounters it in @dfn{interpret} state. The
3926 :			interpretation semantics of a word are represented by an @dfn{execution
3927 :			token}.
3928 :	crook	1.28	@item
3929 :	crook	1.29	@cindex compilation semantics
3930 :	crook	1.44	Its @dfn{compilation semantics} describe how it will behave when the
3931 :			text interpreter encounters it in @dfn{compile} state. The compilation
3932 :			semantics of a word are represented in an implementation-dependent way;
3933 :			Gforth uses a @dfn{compilation token}.
3934 :	crook	1.29	@end itemize
3935 :
3936 :			@noindent
3937 :			Numbers are always treated in a fixed way:
3938 :
3939 :			@itemize @bullet
3940 :	crook	1.28	@item
3941 :	crook	1.44	When the number is @dfn{interpreted}, its behaviour is to push the
3942 :			number onto the stack.
3943 :	crook	1.28	@item
3944 :	anton	1.30	When the number is @dfn{compiled}, a piece of code is appended to the
3945 :			current definition that pushes the number when it runs. (In other words,
3946 :			the compilation semantics of a number are to postpone its interpretation
3947 :			semantics until the run-time of the definition that it is being compiled
3948 :			into.)
3949 :	crook	1.29	@end itemize
3950 :
3951 :	crook	1.44	Words don't behave in such a regular way, but most have @i{default
3952 :			semantics} which means that they behave like this:
3953 :	crook	1.29
3954 :			@itemize @bullet
3955 :	crook	1.28	@item
3956 :	anton	1.30	The @dfn{interpretation semantics} of the word are to do something useful.
3957 :			@item
3958 :	crook	1.29	The @dfn{compilation semantics} of the word are to append its
3959 :	anton	1.30	@dfn{interpretation semantics} to the current definition (so that its
3960 :			run-time behaviour is to do something useful).
3961 :	crook	1.28	@end itemize
3962 :
3963 :	anton	1.30	@cindex immediate words
3964 :	crook	1.44	The actual behaviour of any particular word can be controlled by using
3965 :			the words @code{immediate} and @code{compile-only} when the word is
3966 :			defined. These words set flags in the name dictionary entry of the most
3967 :			recently defined word, and these flags are retrieved by the text
3968 :			interpreter when it finds the word in the name dictionary.
3969 :
3970 :			A word that is marked as @dfn{immediate} has compilation semantics that
3971 :			are identical to its interpretation semantics. In other words, it
3972 :			behaves like this:
3973 :	crook	1.29
3974 :			@itemize @bullet
3975 :			@item
3976 :	anton	1.30	The @dfn{interpretation semantics} of the word are to do something useful.
3977 :	crook	1.29	@item
3978 :	anton	1.30	The @dfn{compilation semantics} of the word are to do something useful
3979 :			(and actually the same thing); i.e., it is executed during compilation.
3980 :	crook	1.29	@end itemize
3981 :	crook	1.28
3982 :	crook	1.44	Marking a word as @dfn{compile-only} prohibits the text interpreter from
3983 :			performing the interpretation semantics of the word directly; an attempt
3984 :			to do so will generate an error. It is never necessary to use
3985 :			@code{compile-only} (and it is not even part of ANS Forth, though it is
3986 :			provided by many implementations) but it is good etiquette to apply it
3987 :			to a word that will not behave correctly (and might have unexpected
3988 :			side-effects) in interpret state. For example, it is only legal to use
3989 :			the conditional word @code{IF} within a definition. If you forget this
3990 :			and try to use it elsewhere, the fact that (in Gforth) it is marked as
3991 :			@code{compile-only} allows the text interpreter to generate a helpful
3992 :			error message rather than subjecting you to the consequences of your
3993 :			folly.
3994 :
3995 :	crook	1.29	This example shows the difference between an immediate and a
3996 :			non-immediate word:
3997 :	crook	1.28
3998 :	crook	1.29	@example
3999 :			: show-state state @@ . ;
4000 :			: show-state-now show-state ; immediate
4001 :			: word1 show-state ;
4002 :			: word2 show-state-now ;
4003 :	crook	1.28	@end example
4004 :	crook	1.23
4005 :	crook	1.29	The word @code{immediate} after the definition of @code{show-state-now}
4006 :			makes that word an immediate word. These definitions introduce a new
4007 :			word: @code{@@} (pronounced ``fetch''). This word fetches the value of a
4008 :			variable, and leaves it on the stack. Therefore, the behaviour of
4009 :			@code{show-state} is to print a number that represents the current value
4010 :			of @code{state}.
4011 :	crook	1.28
4012 :	crook	1.29	When you execute @code{word1}, it prints the number 0, indicating that
4013 :			the system is interpreting. When the text interpreter compiled the
4014 :			definition of @code{word1}, it encountered @code{show-state} whose
4015 :	anton	1.30	compilation semantics are to append its interpretation semantics to the
4016 :	crook	1.29	current definition. When you execute @code{word1}, it performs the
4017 :	anton	1.30	interpretation semantics of @code{show-state}. At the time that @code{word1}
4018 :	crook	1.29	(and therefore @code{show-state}) are executed, the system is
4019 :			interpreting.
4020 :	crook	1.28
4021 :	anton	1.30	When you pressed @key{RET} after entering the definition of @code{word2},
4022 :	crook	1.29	you should have seen the number -1 printed, followed by ``@code{
4023 :			ok}''. When the text interpreter compiled the definition of
4024 :			@code{word2}, it encountered @code{show-state-now}, an immediate word,
4025 :	anton	1.30	whose compilation semantics are therefore to perform its interpretation
4026 :	crook	1.29	semantics. It is executed straight away (even before the text
4027 :			interpreter has moved on to process another group of characters; the
4028 :			@code{;} in this example). The effect of executing it are to display the
4029 :			value of @code{state} @i{at the time that the definition of}
4030 :			@code{word2} @i{is being defined}. Printing -1 demonstrates that the
4031 :			system is compiling at this time. If you execute @code{word2} it does
4032 :			nothing at all.
4033 :	crook	1.28
4034 :	crook	1.29	@cindex @code{."}, how it works
4035 :			Before leaving the subject of immediate words, consider the behaviour of
4036 :			@code{."} in the definition of @code{greet}, in the previous
4037 :			section. This word is both a parsing word and an immediate word. Notice
4038 :			that there is a space between @code{."} and the start of the text
4039 :			@code{Hello and welcome}, but that there is no space between the last
4040 :			letter of @code{welcome} and the @code{"} character. The reason for this
4041 :			is that @code{."} is a Forth word; it must have a space after it so that
4042 :			the text interpreter can identify it. The @code{"} is not a Forth word;
4043 :			it is a @dfn{delimiter}. The examples earlier show that, when the string
4044 :			is displayed, there is neither a space before the @code{H} nor after the
4045 :			@code{e}. Since @code{."} is an immediate word, it executes at the time
4046 :			that @code{greet} is defined. When it executes, its behaviour is to
4047 :			search forward in the input line looking for the delimiter. When it
4048 :			finds the delimiter, it updates @code{>IN} to point past the
4049 :			delimiter. It also compiles some magic code into the definition of
4050 :			@code{greet}; the xt of a run-time routine that prints a text string. It
4051 :			compiles the string @code{Hello and welcome} into memory so that it is
4052 :			available to be printed later. When the text interpreter gains control,
4053 :			the next word it finds in the input stream is @code{;} and so it
4054 :			terminates the definition of @code{greet}.
4055 :	crook	1.28
4056 :
4057 :			@comment ----------------------------------------------
4058 :	crook	1.29	@node Forth is written in Forth, Review - elements of a Forth system, How does that work?, Introduction
4059 :			@section Forth is written in Forth
4060 :			@cindex structure of Forth programs
4061 :
4062 :			When you start up a Forth compiler, a large number of definitions
4063 :			already exist. In Forth, you develop a new application using bottom-up
4064 :			programming techniques to create new definitions that are defined in
4065 :			terms of existing definitions. As you create each definition you can
4066 :			test and debug it interactively.
4067 :
4068 :			If you have tried out the examples in this section, you will probably
4069 :			have typed them in by hand; when you leave Gforth, your definitions will
4070 :			be lost. You can avoid this by using a text editor to enter Forth source
4071 :			code into a file, and then loading code from the file using
4072 :	anton	1.49	@code{include} (@pxref{Forth source files}). A Forth source file is
4073 :	crook	1.29	processed by the text interpreter, just as though you had typed it in by
4074 :			hand@footnote{Actually, there are some subtle differences -- see
4075 :			@ref{The Text Interpreter}.}.
4076 :
4077 :			Gforth also supports the traditional Forth alternative to using text
4078 :	anton	1.49	files for program entry (@pxref{Blocks}).
4079 :	crook	1.28
4080 :	crook	1.29	In common with many, if not most, Forth compilers, most of Gforth is
4081 :			actually written in Forth. All of the @file{.fs} files in the
4082 :			installation directory@footnote{For example,
4083 :	anton	1.30	@file{/usr/local/share/gforth...}} are Forth source files, which you can
4084 :	crook	1.29	study to see examples of Forth programming.
4085 :	crook	1.28
4086 :	crook	1.29	Gforth maintains a history file that records every line that you type to
4087 :			the text interpreter. This file is preserved between sessions, and is
4088 :			used to provide a command-line recall facility. If you enter long
4089 :			definitions by hand, you can use a text editor to paste them out of the
4090 :			history file into a Forth source file for reuse at a later time
4091 :	anton	1.49	(for more information @pxref{Command-line editing}).
4092 :	crook	1.28
4093 :
4094 :			@comment ----------------------------------------------
4095 :	crook	1.29	@node Review - elements of a Forth system, Where to go next, Forth is written in Forth, Introduction
4096 :			@section Review - elements of a Forth system
4097 :			@cindex elements of a Forth system
4098 :	crook	1.28
4099 :	crook	1.29	To summarise this chapter:
4100 :	crook	1.28
4101 :			@itemize @bullet
4102 :			@item
4103 :	crook	1.29	Forth programs use @dfn{factoring} to break a problem down into small
4104 :			fragments called @dfn{words} or @dfn{definitions}.
4105 :			@item
4106 :			Forth program development is an interactive process.
4107 :			@item
4108 :			The main command loop that accepts input, and controls both
4109 :			interpretation and compilation, is called the @dfn{text interpreter}
4110 :			(also known as the @dfn{outer interpreter}).
4111 :			@item
4112 :			Forth has a very simple syntax, consisting of words and numbers
4113 :			separated by spaces or carriage-return characters. Any additional syntax
4114 :			is imposed by @dfn{parsing words}.
4115 :			@item
4116 :			Forth uses a stack to pass parameters between words. As a result, it
4117 :			uses postfix notation.
4118 :			@item
4119 :			To use a word that has previously been defined, the text interpreter
4120 :			searches for the word in the @dfn{name dictionary}.
4121 :			@item
4122 :	anton	1.30	Words have @dfn{interpretation semantics} and @dfn{compilation semantics}.
4123 :	crook	1.28	@item
4124 :	crook	1.29	The text interpreter uses the value of @code{state} to select between
4125 :			the use of the @dfn{interpretation semantics} and the @dfn{compilation
4126 :			semantics} of a word that it encounters.
4127 :	crook	1.28	@item
4128 :	anton	1.30	The relationship between the @dfn{interpretation semantics} and
4129 :			@dfn{compilation semantics} for a word
4130 :	crook	1.29	depend upon the way in which the word was defined (for example, whether
4131 :			it is an @dfn{immediate} word).
4132 :	crook	1.28	@item
4133 :	crook	1.29	Forth definitions can be implemented in Forth (called @dfn{high-level
4134 :			definitions}) or in some other way (usually a lower-level language and
4135 :			as a result often called @dfn{low-level definitions}, @dfn{code
4136 :			definitions} or @dfn{primitives}).
4137 :	crook	1.28	@item
4138 :	crook	1.29	Many Forth systems are implemented mainly in Forth.
4139 :	crook	1.28	@end itemize
4140 :
4141 :
4142 :	crook	1.29	@comment ----------------------------------------------
4143 :	anton	1.48	@node Where to go next, Exercises, Review - elements of a Forth system, Introduction
4144 :	crook	1.29	@section Where To Go Next
4145 :			@cindex where to go next
4146 :	crook	1.28
4147 :	crook	1.29	Amazing as it may seem, if you have read (and understood) this far, you
4148 :			know almost all the fundamentals about the inner workings of a Forth
4149 :			system. You certainly know enough to be able to read and understand the
4150 :			rest of this manual and the ANS Forth document, to learn more about the
4151 :			facilities that Forth in general and Gforth in particular provide. Even
4152 :			scarier, you know almost enough to implement your own Forth system.
4153 :	anton	1.30	However, that's not a good idea just yet... better to try writing some
4154 :	crook	1.29	programs in Gforth.
4155 :	crook	1.28
4156 :	crook	1.29	Forth has such a rich vocabulary that it can be hard to know where to
4157 :			start in learning it. This section suggests a few sets of words that are
4158 :			enough to write small but useful programs. Use the word index in this
4159 :			document to learn more about each word, then try it out and try to write
4160 :			small definitions using it. Start by experimenting with these words:
4161 :	crook	1.28
4162 :			@itemize @bullet
4163 :			@item
4164 :	crook	1.29	Arithmetic: @code{+ - * / /MOD */ ABS INVERT}
4165 :			@item
4166 :			Comparison: @code{MIN MAX =}
4167 :			@item
4168 :			Logic: @code{AND OR XOR NOT}
4169 :			@item
4170 :			Stack manipulation: @code{DUP DROP SWAP OVER}
4171 :	crook	1.28	@item
4172 :	crook	1.29	Loops and decisions: @code{IF ELSE ENDIF ?DO I LOOP}
4173 :	crook	1.28	@item
4174 :	crook	1.29	Input/Output: @code{. ." EMIT CR KEY}
4175 :	crook	1.28	@item
4176 :	crook	1.29	Defining words: @code{: ; CREATE}
4177 :	crook	1.28	@item
4178 :	crook	1.29	Memory allocation words: @code{ALLOT ,}
4179 :	crook	1.28	@item
4180 :	crook	1.29	Tools: @code{SEE WORDS .S MARKER}
4181 :			@end itemize
4182 :
4183 :			When you have mastered those, go on to:
4184 :
4185 :			@itemize @bullet
4186 :	crook	1.28	@item
4187 :	crook	1.29	More defining words: @code{VARIABLE CONSTANT VALUE TO CREATE DOES>}
4188 :	crook	1.28	@item
4189 :	crook	1.29	Memory access: @code{@@ !}
4190 :	crook	1.28	@end itemize
4191 :	crook	1.23
4192 :	crook	1.29	When you have mastered these, there's nothing for it but to read through
4193 :			the whole of this manual and find out what you've missed.
4194 :
4195 :			@comment ----------------------------------------------
4196 :	anton	1.48	@node Exercises, , Where to go next, Introduction
4197 :	crook	1.29	@section Exercises
4198 :			@cindex exercises
4199 :
4200 :			TODO: provide a set of programming excercises linked into the stuff done
4201 :			already and into other sections of the manual. Provide solutions to all
4202 :			the exercises in a .fs file in the distribution.
4203 :
4204 :			@c Get some inspiration from Starting Forth and Kelly&Spies.
4205 :
4206 :			@c excercises:
4207 :			@c 1. take inches and convert to feet and inches.
4208 :			@c 2. take temperature and convert from fahrenheight to celcius;
4209 :			@c may need to care about symmetric vs floored??
4210 :			@c 3. take input line and do character substitution
4211 :			@c to encipher or decipher
4212 :			@c 4. as above but work on a file for in and out
4213 :			@c 5. take input line and convert to pig-latin
4214 :			@c
4215 :			@c thing of sets of things to exercise then come up with
4216 :			@c problems that need those things.
4217 :
4218 :
4219 :	crook	1.26	@c ******************************************************************
4220 :	crook	1.29	@node Words, Error messages, Introduction, Top
4221 :	anton	1.1	@chapter Forth Words
4222 :	crook	1.26	@cindex words
4223 :	anton	1.1
4224 :			@menu
4225 :			* Notation::
4226 :	crook	1.21	* Comments::
4227 :			* Boolean Flags::
4228 :	anton	1.1	* Arithmetic::
4229 :			* Stack Manipulation::
4230 :	anton	1.5	* Memory::
4231 :	anton	1.1	* Control Structures::
4232 :			* Defining Words::
4233 :	crook	1.47	* Interpretation and Compilation Semantics::
4234 :			* Tokens for Words::
4235 :	crook	1.21	* The Text Interpreter::
4236 :			* Word Lists::
4237 :			* Environmental Queries::
4238 :	anton	1.12	* Files::
4239 :			* Blocks::
4240 :			* Other I/O::
4241 :			* Programming Tools::
4242 :			* Assembler and Code Words::
4243 :			* Threading Words::
4244 :	crook	1.26	* Locals::
4245 :			* Structures::
4246 :			* Object-oriented Forth::
4247 :	crook	1.21	* Passing Commands to the OS::
4248 :	crook	1.47	* Keeping track of Time::
4249 :	crook	1.21	* Miscellaneous Words::
4250 :	anton	1.1	@end menu
4251 :
4252 :	crook	1.21	@node Notation, Comments, Words, Words
4253 :	anton	1.1	@section Notation
4254 :			@cindex notation of glossary entries
4255 :			@cindex format of glossary entries
4256 :			@cindex glossary notation format
4257 :			@cindex word glossary entry format
4258 :
4259 :			The Forth words are described in this section in the glossary notation
4260 :			that has become a de-facto standard for Forth texts, i.e.,
4261 :
4262 :			@format
4263 :	crook	1.29	@i{word} @i{Stack effect} @i{wordset} @i{pronunciation}
4264 :	anton	1.1	@end format
4265 :	crook	1.29	@i{Description}
4266 :	anton	1.1
4267 :			@table @var
4268 :			@item word
4269 :	crook	1.28	The name of the word.
4270 :	anton	1.1
4271 :			@item Stack effect
4272 :			@cindex stack effect
4273 :	crook	1.29	The stack effect is written in the notation @code{@i{before} --
4274 :			@i{after}}, where @i{before} and @i{after} describe the top of
4275 :	anton	1.1	stack entries before and after the execution of the word. The rest of
4276 :			the stack is not touched by the word. The top of stack is rightmost,
4277 :			i.e., a stack sequence is written as it is typed in. Note that Gforth
4278 :			uses a separate floating point stack, but a unified stack
4279 :	crook	1.29	notation. Also, return stack effects are not shown in @i{stack
4280 :			effect}, but in @i{Description}. The name of a stack item describes
4281 :	anton	1.1	the type and/or the function of the item. See below for a discussion of
4282 :			the types.
4283 :
4284 :			All words have two stack effects: A compile-time stack effect and a
4285 :			run-time stack effect. The compile-time stack-effect of most words is
4286 :	crook	1.29	@i{ -- }. If the compile-time stack-effect of a word deviates from
4287 :	anton	1.1	this standard behaviour, or the word does other unusual things at
4288 :			compile time, both stack effects are shown; otherwise only the run-time
4289 :			stack effect is shown.
4290 :
4291 :			@cindex pronounciation of words
4292 :			@item pronunciation
4293 :			How the word is pronounced.
4294 :
4295 :			@cindex wordset
4296 :			@item wordset
4297 :	crook	1.21	The ANS Forth standard is divided into several word sets. A standard
4298 :			system need not support all of them. Therefore, in theory, the fewer
4299 :			word sets your program uses the more portable it will be. However, we
4300 :			suspect that most ANS Forth systems on personal machines will feature
4301 :	crook	1.26	all word sets. Words that are not defined in ANS Forth have
4302 :	crook	1.21	@code{gforth} or @code{gforth-internal} as word set. @code{gforth}
4303 :	anton	1.1	describes words that will work in future releases of Gforth;
4304 :			@code{gforth-internal} words are more volatile. Environmental query
4305 :			strings are also displayed like words; you can recognize them by the
4306 :	crook	1.21	@code{environment} in the word set field.
4307 :	anton	1.1
4308 :			@item Description
4309 :			A description of the behaviour of the word.
4310 :			@end table
4311 :
4312 :			@cindex types of stack items
4313 :			@cindex stack item types
4314 :			The type of a stack item is specified by the character(s) the name
4315 :			starts with:
4316 :
4317 :			@table @code
4318 :			@item f
4319 :			@cindex @code{f}, stack item type
4320 :			Boolean flags, i.e. @code{false} or @code{true}.
4321 :			@item c
4322 :			@cindex @code{c}, stack item type
4323 :			Char
4324 :			@item w
4325 :			@cindex @code{w}, stack item type
4326 :			Cell, can contain an integer or an address
4327 :			@item n
4328 :			@cindex @code{n}, stack item type
4329 :			signed integer
4330 :			@item u
4331 :			@cindex @code{u}, stack item type
4332 :			unsigned integer
4333 :			@item d
4334 :			@cindex @code{d}, stack item type
4335 :			double sized signed integer
4336 :			@item ud
4337 :			@cindex @code{ud}, stack item type
4338 :			double sized unsigned integer
4339 :			@item r
4340 :			@cindex @code{r}, stack item type
4341 :			Float (on the FP stack)
4342 :	crook	1.21	@item a-
4343 :	anton	1.1	@cindex @code{a_}, stack item type
4344 :			Cell-aligned address
4345 :	crook	1.21	@item c-
4346 :	anton	1.1	@cindex @code{c_}, stack item type
4347 :			Char-aligned address (note that a Char may have two bytes in Windows NT)
4348 :	crook	1.21	@item f-
4349 :	anton	1.1	@cindex @code{f_}, stack item type
4350 :			Float-aligned address
4351 :	crook	1.21	@item df-
4352 :	anton	1.1	@cindex @code{df_}, stack item type
4353 :			Address aligned for IEEE double precision float
4354 :	crook	1.21	@item sf-
4355 :	anton	1.1	@cindex @code{sf_}, stack item type
4356 :			Address aligned for IEEE single precision float
4357 :			@item xt
4358 :			@cindex @code{xt}, stack item type
4359 :			Execution token, same size as Cell
4360 :			@item wid
4361 :			@cindex @code{wid}, stack item type
4362 :	crook	1.21	Word list ID, same size as Cell
4363 :	anton	1.1	@item f83name
4364 :			@cindex @code{f83name}, stack item type
4365 :			Pointer to a name structure
4366 :			@item "
4367 :			@cindex @code{"}, stack item type
4368 :	anton	1.12	string in the input stream (not on the stack). The terminating character
4369 :			is a blank by default. If it is not a blank, it is shown in @code{<>}
4370 :	anton	1.1	quotes.
4371 :			@end table
4372 :
4373 :	crook	1.21	@node Comments, Boolean Flags, Notation, Words
4374 :			@section Comments
4375 :	crook	1.26	@cindex comments
4376 :	crook	1.21
4377 :	crook	1.29	Forth supports two styles of comment; the traditional @i{in-line} comment,
4378 :			@code{(} and its modern cousin, the @i{comment to end of line}; @code{\}.
4379 :	crook	1.21
4380 :	crook	1.44
4381 :	crook	1.23	doc-(
4382 :	crook	1.21	doc-\
4383 :	crook	1.23	doc-\G
4384 :	crook	1.21
4385 :	crook	1.44
4386 :	crook	1.21	@node Boolean Flags, Arithmetic, Comments, Words
4387 :			@section Boolean Flags
4388 :	crook	1.26	@cindex Boolean flags
4389 :	crook	1.21
4390 :			A Boolean flag is cell-sized. A cell with all bits clear represents the
4391 :			flag @code{false} and a flag with all bits set represents the flag
4392 :	crook	1.26	@code{true}. Words that check a flag (for example, @code{IF}) will treat
4393 :	crook	1.29	a cell that has @i{any} bit set as @code{true}.
4394 :	crook	1.21
4395 :	crook	1.44
4396 :	crook	1.21	doc-true
4397 :			doc-false
4398 :	crook	1.29	doc-on
4399 :			doc-off
4400 :	crook	1.21
4401 :	crook	1.44
4402 :	crook	1.21	@node Arithmetic, Stack Manipulation, Boolean Flags, Words
4403 :	anton	1.1	@section Arithmetic
4404 :			@cindex arithmetic words
4405 :
4406 :			@cindex division with potentially negative operands
4407 :			Forth arithmetic is not checked, i.e., you will not hear about integer
4408 :			overflow on addition or multiplication, you may hear about division by
4409 :			zero if you are lucky. The operator is written after the operands, but
4410 :			the operands are still in the original order. I.e., the infix @code{2-1}
4411 :			corresponds to @code{2 1 -}. Forth offers a variety of division
4412 :			operators. If you perform division with potentially negative operands,
4413 :			you do not want to use @code{/} or @code{/mod} with its undefined
4414 :			behaviour, but rather @code{fm/mod} or @code{sm/mod} (probably the
4415 :			former, @pxref{Mixed precision}).
4416 :	crook	1.26	@comment TODO discuss the different division forms and the std approach
4417 :	anton	1.1
4418 :			@menu
4419 :			* Single precision::
4420 :			* Bitwise operations::
4421 :	crook	1.21	* Double precision:: Double-cell integer arithmetic
4422 :			* Numeric comparison::
4423 :	crook	1.29	* Mixed precision:: Operations with single and double-cell integers
4424 :	anton	1.1	* Floating Point::
4425 :			@end menu
4426 :
4427 :			@node Single precision, Bitwise operations, Arithmetic, Arithmetic
4428 :			@subsection Single precision
4429 :			@cindex single precision arithmetic words
4430 :
4431 :	crook	1.21	By default, numbers in Forth are single-precision integers that are 1
4432 :	crook	1.26	cell in size. They can be signed or unsigned, depending upon how you
4433 :	anton	1.49	treat them. For the rules used by the text interpreter for recognising
4434 :			single-precision integers see @ref{Number Conversion}.
4435 :	crook	1.21
4436 :	crook	1.44
4437 :	anton	1.1	doc-+
4438 :	crook	1.21	doc-1+
4439 :	anton	1.1	doc--
4440 :	crook	1.21	doc-1-
4441 :	anton	1.1	doc-*
4442 :			doc-/
4443 :			doc-mod
4444 :			doc-/mod
4445 :			doc-negate
4446 :			doc-abs
4447 :			doc-min
4448 :			doc-max
4449 :	crook	1.21	doc-d>s
4450 :	crook	1.27	doc-floored
4451 :	anton	1.1
4452 :	crook	1.44
4453 :	crook	1.21	@node Bitwise operations, Double precision, Single precision, Arithmetic
4454 :	anton	1.1	@subsection Bitwise operations
4455 :			@cindex bitwise operation words
4456 :
4457 :	crook	1.44
4458 :	anton	1.1	doc-and
4459 :			doc-or
4460 :			doc-xor
4461 :			doc-invert
4462 :	crook	1.21	doc-lshift
4463 :			doc-rshift
4464 :	anton	1.1	doc-2*
4465 :	crook	1.21	doc-d2*
4466 :	anton	1.1	doc-2/
4467 :	crook	1.21	doc-d2/
4468 :
4469 :	crook	1.44
4470 :	crook	1.21	@node Double precision, Numeric comparison, Bitwise operations, Arithmetic
4471 :			@subsection Double precision
4472 :			@cindex double precision arithmetic words
4473 :
4474 :	anton	1.49	For the rules used by the text interpreter for
4475 :			recognising double-precision integers, see @ref{Number Conversion}.
4476 :	crook	1.21
4477 :			A double precision number is represented by a cell pair, with the most
4478 :	anton	1.31	significant cell at the TOS. It is trivial to convert an unsigned
4479 :	crook	1.26	single to an (unsigned) double; simply push a @code{0} onto the
4480 :			TOS. Since numbers are represented by Gforth using 2's complement
4481 :			arithmetic, converting a signed single to a (signed) double requires
4482 :	anton	1.31	sign-extension across the most significant cell. This can be achieved
4483 :	crook	1.26	using @code{s>d}. The moral of the story is that you cannot convert a
4484 :			number without knowing whether it represents an unsigned or a
4485 :			signed number.
4486 :	crook	1.21
4487 :	crook	1.44
4488 :	crook	1.21	doc-s>d
4489 :			doc-d+
4490 :			doc-d-
4491 :			doc-dnegate
4492 :			doc-dabs
4493 :			doc-dmin
4494 :			doc-dmax
4495 :
4496 :	crook	1.44
4497 :	crook	1.21	@node Numeric comparison, Mixed precision, Double precision, Arithmetic
4498 :			@subsection Numeric comparison
4499 :			@cindex numeric comparison words
4500 :
4501 :	crook	1.44
4502 :	crook	1.28	doc-<
4503 :			doc-<=
4504 :			doc-<>
4505 :			doc-=
4506 :			doc->
4507 :			doc->=
4508 :
4509 :	crook	1.21	doc-0<
4510 :	crook	1.23	doc-0<=
4511 :	crook	1.21	doc-0<>
4512 :			doc-0=
4513 :	crook	1.23	doc-0>
4514 :			doc-0>=
4515 :	crook	1.28
4516 :			doc-u<
4517 :			doc-u<=
4518 :	crook	1.44	@c u<> and u= exist but are the same as <> and =
4519 :	anton	1.31	@c doc-u<>
4520 :			@c doc-u=
4521 :	crook	1.28	doc-u>
4522 :			doc-u>=
4523 :
4524 :			doc-within
4525 :
4526 :			doc-d<
4527 :			doc-d<=
4528 :			doc-d<>
4529 :			doc-d=
4530 :			doc-d>
4531 :			doc-d>=
4532 :	crook	1.23
4533 :	crook	1.21	doc-d0<
4534 :	crook	1.23	doc-d0<=
4535 :			doc-d0<>
4536 :	crook	1.21	doc-d0=
4537 :	crook	1.23	doc-d0>
4538 :			doc-d0>=
4539 :
4540 :	crook	1.21	doc-du<
4541 :	crook	1.28	doc-du<=
4542 :	crook	1.44	@c du<> and du= exist but are the same as d<> and d=
4543 :	anton	1.31	@c doc-du<>
4544 :			@c doc-du=
4545 :	crook	1.28	doc-du>
4546 :			doc-du>=
4547 :	anton	1.1
4548 :	crook	1.44
4549 :	crook	1.21	@node Mixed precision, Floating Point, Numeric comparison, Arithmetic
4550 :	anton	1.1	@subsection Mixed precision
4551 :			@cindex mixed precision arithmetic words
4552 :
4553 :	crook	1.44
4554 :	anton	1.1	doc-m+
4555 :			doc-*/
4556 :			doc-*/mod
4557 :			doc-m*
4558 :			doc-um*