Gforth Manual

Gforth
1 Goals of Gforth
- 1.1 Stability Goals
2 Gforth Environment
- 2.1 Invoking Gforth
- 2.2 Leaving Gforth
- 2.3 Help on Gforth
- 2.4 Command-line editing
- 2.5 Environment variables
- 2.6 Gforth files
- 2.7 Gforth in pipes
- 2.8 Startup speed
3 Forth Tutorial
- 3.1 Starting Gforth
- 3.2 Syntax
- 3.3 Crash Course
- 3.4 Stack
- 3.5 Arithmetics
- 3.6 Stack Manipulation
- 3.7 Using files for Forth code
- 3.8 Comments
- 3.9 Colon Definitions
- 3.10 Decompilation
- 3.11 Stack-Effect Comments
- 3.12 Types
- 3.13 Factoring
- 3.14 Designing the stack effect
- 3.15 Local Variables
- 3.16 Conditional execution
- 3.17 Flags and Comparisons
- 3.18 General Loops
- 3.19 Counted loops
- 3.20 Recursion
- 3.21 Leaving definitions or loops
- 3.22 Return Stack
- 3.23 Memory
- 3.24 Characters and Strings
- 3.25 Alignment
- 3.26 Floating Point
- 3.27 Files
  - 3.27.1 Open file for input
  - 3.27.2 Create file for output
  - 3.27.3 Scan file for a particular line
  - 3.27.4 Copy input to output
  - 3.27.5 Close files
- 3.28 Interpretation and Compilation Semantics and Immediacy
- 3.29 Execution Tokens
- 3.30 Exceptions
- 3.31 Defining Words
- 3.32 Arrays and Records
- 3.33 POSTPONE
- 3.34 Literal
- 3.35 Advanced macros
- 3.36 Compilation Tokens
- 3.37 Wordlists and Search Order
4 An Introduction to Standard Forth
- 4.1 Introducing the Text Interpreter
- 4.2 Stacks, postfix notation and parameter passing
- 4.3 Your first Forth definition
- 4.4 How does that work?
- 4.5 Forth is written in Forth
- 4.6 Review - elements of a Forth system
- 4.7 Where To Go Next
- 4.8 Exercises
5 Literals in source code
6 Forth Words
- 6.1 Notation
- 6.2 Case insensitivity
- 6.3 Comments
- 6.4 Boolean Flags
- 6.5 Arithmetic
  - 6.5.1 Single precision
  - 6.5.2 Double precision
  - 6.5.3 Mixed precision
  - 6.5.4 Integer division
  - 6.5.5 Two-stage integer division
  - 6.5.6 Bitwise operations
  - 6.5.7 Numeric comparison
  - 6.5.8 Floating Point
- 6.6 Stack Manipulation
  - 6.6.1 Data stack
  - 6.6.2 Floating point stack
  - 6.6.3 Return stack
  - 6.6.4 Locals stack
  - 6.6.5 Stack pointer manipulation
- 6.7 Memory
  - 6.7.1 Memory model
  - 6.7.2 Dictionary allocation
  - 6.7.3 Heap allocation
  - 6.7.4 Memory Access
  - 6.7.5 Special Memory Accesses
  - 6.7.6 Address arithmetic
  - 6.7.7 Memory Blocks
- 6.8 Strings and Characters
  - 6.8.1 Characters
  - 6.8.2 String representations
  - 6.8.3 String and Character literals
  - 6.8.4 String words
  - 6.8.5 $tring words
  - 6.8.6 Counted string words
- 6.9 Control Structures
  - 6.9.1 Selection
  - 6.9.2 Simple Loops
  - 6.9.3 Counted Loops
  - 6.9.4 Begin loops with multiple exits
  - 6.9.5 General control structures with case
  - 6.9.6 Arbitrary control structures
    - 6.9.6.1 Programming Style
  - 6.9.7 Calls and returns
  - 6.9.8 Exception Handling
- 6.10 Defining Words
  - 6.10.1 CREATE
  - 6.10.2 Variables
  - 6.10.3 Constants
  - 6.10.4 Values
  - 6.10.5 Colon Definitions
  - 6.10.6 Anonymous Definitions
  - 6.10.7 Quotations
  - 6.10.8 Supplying the name of a defined word
  - 6.10.9 User-defined Defining Words
  - 6.10.10 Deferred Words
  - 6.10.11 Forward
  - 6.10.12 Aliases
- 6.11 Interpretation and Compilation Semantics
  - 6.11.1 Combined Words
- 6.12 Tokens for Words
  - 6.12.1 Execution token
  - 6.12.2 Name token
  - 6.12.3 Compilation token
- 6.13 Compiling words
  - 6.13.1 Literals
  - 6.13.2 Macros
- 6.14 The Text Interpreter
  - 6.14.1 Input Sources
  - 6.14.2 Number Conversion
  - 6.14.3 Interpret/Compile states
  - 6.14.4 Interpreter Directives
  - 6.14.5 Recognizers
- 6.15 The Input Stream
- 6.16 Word Lists
  - 6.16.1 Vocabularies
  - 6.16.2 Why use word lists?
  - 6.16.3 Word list example
- 6.17 Environmental Queries
- 6.18 Files
  - 6.18.1 Forth source files
  - 6.18.2 General files
  - 6.18.3 Redirection
  - 6.18.4 Directories
  - 6.18.5 Search Paths
    - 6.18.5.1 Source Search Paths
    - 6.18.5.2 General Search Paths
- 6.19 Blocks
- 6.20 Other I/O
  - 6.20.1 Simple numeric output
  - 6.20.2 Formatted numeric output
  - 6.20.3 Floating-point output
  - 6.20.4 Miscellaneous output
  - 6.20.5 Displaying characters and strings
  - 6.20.6 Terminal output
    - 6.20.6.1 Color output
    - 6.20.6.2 Color themes
  - 6.20.7 Single-key input
  - 6.20.8 Line input and conversion
  - 6.20.9 Pipes
  - 6.20.10 Xchars and Unicode
  - 6.20.11 Internationalization and Localization
  - 6.20.12 Substitute
  - 6.20.13 CSV Reader
- 6.21 OS command line arguments
- 6.22 Locals
  - 6.22.1 Gforth locals
  - 6.22.2 Standard Forth locals
- 6.23 Structures
  - 6.23.1 Why explicit structure support?
  - 6.23.2 Structure Usage
  - 6.23.3 Structure Naming Convention
  - 6.23.4 Structure Implementation
  - 6.23.5 Structure Glossary
  - 6.23.6 Forth200x Structures
- 6.24 Object-oriented Forth
  - 6.24.1 Why object-oriented programming?
  - 6.24.2 Object-Oriented Terminology
  - 6.24.3 The objects.fs model
  - 6.24.4 The oof.fs model
  - 6.24.5 The mini-oof.fs model
  - 6.24.6 Comparison with other object models
- 6.25 Programming Tools
  - 6.25.1 Locating source code definitions
  - 6.25.2 Locating documentation
  - 6.25.3 Locating uses of a word
  - 6.25.4 Locating exception source
  - 6.25.5 Examining compiled code
  - 6.25.6 Examining data and code
  - 6.25.7 Forgetting words
  - 6.25.8 Debugging
  - 6.25.9 Assertions
  - 6.25.10 Singlestep Debugger
  - 6.25.11 Code Coverage and Execution Frequency
- 6.26 Multitasker
  - 6.26.1 Ptheads
- 6.27 C Interface
  - 6.27.1 Calling C functions
  - 6.27.2 Declaring C Functions
  - 6.27.3 Calling C function pointers from Forth
  - 6.27.4 Defining library interfaces
  - 6.27.5 Declaring OS-level libraries
  - 6.27.6 Callbacks
  - 6.27.7 How the C interface works
  - 6.27.8 Low-Level C Interface Words
  - 6.27.9 Automated interface generation using SWIG
  - 6.27.10 Migrating from Gforth 0.7
- 6.28 Assembler and Code Words
  - 6.28.1 Definitions in assembly language
  - 6.28.2 Common Assembler
  - 6.28.3 Common Disassembler
  - 6.28.4 386 Assembler
  - 6.28.5 AMD64 (x86_64) Assembler
  - 6.28.6 Alpha Assembler
  - 6.28.7 MIPS assembler
  - 6.28.8 PowerPC assembler
  - 6.28.9 ARM Assembler
  - 6.28.10 Other assemblers
- 6.29 Carnal words
  - 6.29.1 Header fields
  - 6.29.2 Header methods
  - 6.29.3 Threading Words
- 6.30 Passing Commands to the Operating System
- 6.31 Keeping track of Time
- 6.32 Miscellaneous Words
7 Error messages
8 Tools
- 8.1 ans-report.fs: Report the words used, sorted by wordset
  - 8.1.1 Caveats
- 8.2 Stack depth changes during interpretation
9 Standard conformance
- 9.1 The Core Words
- 9.2 The optional Block word set
- 9.3 The optional Double Number word set
  - 9.3.1 Ambiguous conditions
- 9.4 The optional Exception word set
  - 9.4.1 Implementation Defined Options
- 9.5 The optional Facility word set
  - 9.5.1 Implementation Defined Options
  - 9.5.2 Ambiguous conditions
- 9.6 The optional File-Access word set
  - 9.6.1 Implementation Defined Options
  - 9.6.2 Ambiguous conditions
- 9.7 The optional Floating-Point word set
  - 9.7.1 Implementation Defined Options
  - 9.7.2 Ambiguous conditions
- 9.8 The optional Locals word set
  - 9.8.1 Implementation Defined Options
  - 9.8.2 Ambiguous conditions
- 9.9 The optional Memory-Allocation word set
  - 9.9.1 Implementation Defined Options
- 9.10 The optional Programming-Tools word set
  - 9.10.1 Implementation Defined Options
  - 9.10.2 Ambiguous conditions
- 9.11 The optional Search-Order word set
  - 9.11.1 Implementation Defined Options
  - 9.11.2 Ambiguous conditions
10 Should I use Gforth extensions?
11 Model
12 Integrating Gforth into C programs
- 12.1 Types
- 12.2 Variables
- 12.3 Functions
- 12.4 Signals
13 Emacs and Gforth
- 13.1 Installing gforth.el
- 13.2 Emacs Tags
- 13.3 Hilighting
- 13.4 Auto-Indentation
- 13.5 Blocks Files
14 Image Files
- 14.1 Image Licensing Issues
- 14.2 Image File Background
- 14.3 Non-Relocatable Image Files
- 14.4 Data-Relocatable Image Files
- 14.5 Fully Relocatable Image Files
  - 14.5.1 gforthmi
  - 14.5.2 cross.fs
- 14.6 Stack and Dictionary Sizes
- 14.7 Running Image Files
- 14.8 Modifying the Startup Sequence
15 Engine
- 15.1 Portability
- 15.2 Threading
- 15.3 Primitives
- 15.4 Performance
16 Cross Compiler
- 16.1 Using the Cross Compiler
- 16.2 How the Cross Compiler Works
17 MINOS2, a GUI library
- 17.1 MINOS2 object framework
  - 17.1.1 actor methods:
  - 17.1.2 widget methods:
- 17.2 MINOS2 tutorial
Appendix A Bugs
Appendix B Authors and Ancestors of Gforth
- B.1 Authors and Contributors
- B.2 Pedigree
Appendix C Other Forth-related information
Appendix D Licenses
- D.1 GNU Free Documentation License
  - D.1.1 ADDENDUM: How to use this License for your documents
- D.2 GNU GENERAL PUBLIC LICENSE
Word Index
Concept and Word Index

Gforth

This manual is for Gforth (version 0.7.9_20230126, January 26, 2023), a fast and portable implementation of the Standard Forth language. It serves as reference manual, but it also contains an introduction to Forth and a Forth tutorial.

Authors: Bernd Paysan, Anton Ertl, Gerald Wodni Copyright © 1995, 1996, 1997, 1998, 2000, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014,2015,2016,2017,2018,2019,2020,2021,2022 Free Software Foundation, Inc.

Gforth Manual

Table of Contents

Gforth