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