Gforth Manual

Table of Contents

• Gforth
• Goals of Gforth
• Gforth Environment
  • Invoking Gforth
  • Leaving Gforth
  • Command-line editing
  • Environment variables
  • Gforth files
  • Gforth in pipes
  • Startup speed
• Forth Tutorial
  • Starting Gforth
  • Syntax
  • Crash Course
  • Stack
  • Arithmetics
  • Stack Manipulation
  • Using files for Forth code
  • Comments
  • Colon Definitions
  • Decompilation
  • Stack-Effect Comments
  • Types
  • Factoring
  • Designing the stack effect
  • Local Variables
  • Conditional execution
  • Flags and Comparisons
  • General Loops
  • Counted loops
  • Recursion
  • Leaving definitions or loops
  • Return Stack
  • Memory
  • Characters and Strings
  • Alignment
  • Files
    • Open file for input
    • Create file for output
    • Scan file for a particular line
    • Copy input to output
    • Close files
  • Interpretation and Compilation Semantics and Immediacy
  • Execution Tokens
  • Exceptions
  • Defining Words
  • Arrays and Records
  • POSTPONE
  • Literal
  • Advanced macros
  • Compilation Tokens
  • Wordlists and Search Order
• An Introduction to ANS Forth
  • Introducing the Text Interpreter
  • Stacks, postfix notation and parameter passing
  • Your first Forth definition
  • How does that work?
  • Forth is written in Forth
  • Review - elements of a Forth system
  • Where To Go Next
  • Exercises
• Forth Words
  • Notation
  • Case insensitivity
  • Comments
  • Boolean Flags
  • Arithmetic
    • Single precision
    • Double precision
    • Bitwise operations
    • Numeric comparison
    • Mixed precision
    • Floating Point
  • Stack Manipulation
    • Data stack
    • Floating point stack
    • Return stack
    • Locals stack
    • Stack pointer manipulation
  • Memory
    • ANS Forth and Gforth memory models
    • Dictionary allocation
    • Heap allocation
    • Memory Access
    • Address arithmetic
    • Memory Blocks
  • Control Structures
    • Selection
    • Simple Loops
    • Counted Loops
    • Arbitrary control structures
      • Programming Style
    • Calls and returns
    • Exception Handling
  • Defining Words
    • CREATE
    • Variables
    • Constants
    • Values
    • Colon Definitions
    • Anonymous Definitions
    • Supplying the name of a defined word
    • User-defined Defining Words
      • Applications of CREATE..DOES>
      • The gory details of CREATE..DOES>
      • Advanced does> usage example
      • Const-does>
    • Deferred words
    • Aliases
  • Interpretation and Compilation Semantics
    • Combined Words
  • Tokens for Words
    • Execution token
    • Compilation token
    • Name token
  • Compiling words
    • Literals
    • Macros
  • The Text Interpreter
    • Input Sources
    • Number Conversion
    • Interpret/Compile states
    • Interpreter Directives
  • The Input Stream
  • Word Lists
    • Vocabularies
    • Why use word lists?
    • Word list example
  • Environmental Queries
  • Files
    • Forth source files
    • General files
    • Search Paths
      • Source Search Paths
      • General Search Paths
  • Blocks
  • Other I/O
    • Simple numeric output
    • Formatted numeric output
    • String Formats
    • Displaying characters and strings
    • Input
    • Pipes
  • Locals
    • Gforth locals
      • Where are locals visible by name?
      • How long do locals live?
      • Locals programming style
      • Locals implementation
    • ANS Forth locals
  • Structures
    • Why explicit structure support?
    • Structure Usage
    • Structure Naming Convention
    • Structure Implementation
    • Structure Glossary
  • Object-oriented Forth
    • Why object-oriented programming?
    • Object-Oriented Terminology
    • The objects.fs model
      • Properties of the objects.fs model
      • Basic objects.fs Usage
      • The object.fs base class
      • Creating objects
      • Object-Oriented Programming Style
      • Class Binding
      • Method conveniences
      • Classes and Scoping
      • Dividing classes
      • Object Interfaces
      • objects.fs Implementation
      • objects.fs Glossary
    • The oof.fs model
      • Properties of the oof.fs model
      • Basic oof.fs Usage
      • The oof.fs base class
      • Class Declaration
      • Class Implementation
    • The mini-oof.fs model
      • Basic mini-oof.fs Usage
      • Mini-OOF Example
      • mini-oof.fs Implementation
    • Comparison with other object models
  • Programming Tools
    • Examining data and code
    • Forgetting words
    • Debugging
    • Assertions
    • Singlestep Debugger
  • Assembler and Code Words
    • Code and ;code
    • Common Assembler
    • Common Disassembler
    • 386 Assembler
    • Alpha Assembler
    • MIPS assembler
    • Other assemblers
  • Threading Words
  • Passing Commands to the Operating System
  • Keeping track of Time
  • Miscellaneous Words
• Error messages
• Tools
  • ans-report.fs: Report the words used, sorted by wordset
    • Caveats
• ANS conformance
  • The Core Words
    • Implementation Defined Options
    • Ambiguous conditions
    • Other system documentation
  • The optional Block word set
    • Implementation Defined Options
    • Ambiguous conditions
    • Other system documentation
  • The optional Double Number word set
    • Ambiguous conditions
  • The optional Exception word set
    • Implementation Defined Options
  • The optional Facility word set
    • Implementation Defined Options
    • Ambiguous conditions
  • The optional File-Access word set
    • Implementation Defined Options
    • Ambiguous conditions
  • The optional Floating-Point word set
    • Implementation Defined Options
    • Ambiguous conditions
  • The optional Locals word set
    • Implementation Defined Options
    • Ambiguous conditions
  • The optional Memory-Allocation word set
    • Implementation Defined Options
  • The optional Programming-Tools word set
    • Implementation Defined Options
    • Ambiguous conditions
  • The optional Search-Order word set
    • Implementation Defined Options
    • Ambiguous conditions
• Should I use Gforth extensions?
• Model
• Integrating Gforth into C programs
• Emacs and Gforth
  • Installing gforth.el
  • Emacs Tags
  • Hilighting
  • Auto-Indentation
  • Blocks Files
• Image Files
  • Image Licensing Issues
  • Image File Background
  • Non-Relocatable Image Files
  • Data-Relocatable Image Files
  • Fully Relocatable Image Files
    • gforthmi
    • cross.fs
  • Stack and Dictionary Sizes
  • Running Image Files
  • Modifying the Startup Sequence
• Engine
  • Portability
  • Threading
    • Scheduling
    • Direct or Indirect Threaded?
    • Dynamic Superinstructions
    • DOES>
  • Primitives
    • Automatic Generation
    • TOS Optimization
    • Produced code
  • Performance
• Cross Compiler
  • Using the Cross Compiler
  • How the Cross Compiler Works
• Bugs
• Authors and Ancestors of Gforth
  • Authors and Contributors
  • Pedigree
• Other Forth-related information
• Licenses
  • GNU Free Documentation License
    • ADDENDUM: How to use this License for your documents
  • GNU GENERAL PUBLIC LICENSE
  • Preamble
  • How to Apply These Terms to Your New Programs
• Word Index
• Concept and Word Index

Node:Top, Next:Goals, Previous:(dir), Up:(dir)

Gforth

Copyright © 1995, 1996, 1997, 1998, 2000, 2003 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License."

(a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."

• Goals: About the Gforth Project
• Gforth Environment: Starting (and exiting) Gforth
• Tutorial: Hands-on Forth Tutorial
• Introduction: An introduction to ANS Forth
• Words: Forth words available in Gforth
• Error messages: How to interpret them
• Tools: Programming tools
• ANS conformance: Implementation-defined options etc.
• Standard vs Extensions: Should I use extensions?
• Model: The abstract machine of Gforth
• Integrating Gforth: Forth as scripting language for applications
• Emacs and Gforth: The Gforth Mode
• Image Files: .fi files contain compiled code
• Engine: The inner interpreter and the primitives
• Cross Compiler: The Cross Compiler
• Bugs: How to report them
• Origin: Authors and ancestors of Gforth
• Forth-related information: Books and places to look on the WWW
• Licenses:
• Word Index: An item for each Forth word
• Concept Index: A menu covering many topics

  --- The Detailed Node Listing ---

  Gforth Environment

• Invoking Gforth: Getting in
• Leaving Gforth: Getting out
• Command-line editing:
• Environment variables: that affect how Gforth starts up
• Gforth Files: What gets installed and where
• Gforth in pipes:
• Startup speed: When 35ms is not fast enough ...

  Forth Tutorial

• Starting Gforth Tutorial:
• Syntax Tutorial:
• Crash Course Tutorial:
• Stack Tutorial:
• Arithmetics Tutorial:
• Stack Manipulation Tutorial:
• Using files for Forth code Tutorial:
• Comments Tutorial:
• Colon Definitions Tutorial:
• Decompilation Tutorial:
• Stack-Effect Comments Tutorial:
• Types Tutorial:
• Factoring Tutorial:
• Designing the stack effect Tutorial:
• Local Variables Tutorial:
• Conditional execution Tutorial:
• Flags and Comparisons Tutorial:
• General Loops Tutorial:
• Counted loops Tutorial:
• Recursion Tutorial:
• Leaving definitions or loops Tutorial:
• Return Stack Tutorial:
• Memory Tutorial:
• Characters and Strings Tutorial:
• Alignment Tutorial:
• Files Tutorial:
• Interpretation and Compilation Semantics and Immediacy Tutorial:
• Execution Tokens Tutorial:
• Exceptions Tutorial:
• Defining Words Tutorial:
• Arrays and Records Tutorial:
• POSTPONE Tutorial:
• Literal Tutorial:
• Advanced macros Tutorial:
• Compilation Tokens Tutorial:
• Wordlists and Search Order Tutorial:

  An Introduction to ANS Forth

• Introducing the Text Interpreter:
• Stacks and Postfix notation:
• Your first definition:
• How does that work?:
• Forth is written in Forth:
• Review - elements of a Forth system:
• Where to go next:
• Exercises:

  Forth Words

• Notation:
• Case insensitivity:
• Comments:
• Boolean Flags:
• Arithmetic:
• Stack Manipulation:
• Memory:
• Control Structures:
• Defining Words:
• Interpretation and Compilation Semantics:
• Tokens for Words:
• Compiling words:
• The Text Interpreter:
• The Input Stream:
• Word Lists:
• Environmental Queries:
• Files:
• Blocks:
• Other I/O:
• Locals:
• Structures:
• Object-oriented Forth:
• Programming Tools:
• Assembler and Code Words:
• Threading Words:
• Passing Commands to the OS:
• Keeping track of Time:
• Miscellaneous Words:

  Arithmetic

• Single precision:
• Double precision: Double-cell integer arithmetic
• Bitwise operations:
• Numeric comparison:
• Mixed precision: Operations with single and double-cell integers
• Floating Point:

  Stack Manipulation

• Data stack:
• Floating point stack:
• Return stack:
• Locals stack:
• Stack pointer manipulation:

  Memory

• Memory model:
• Dictionary allocation:
• Heap Allocation:
• Memory Access:
• Address arithmetic:
• Memory Blocks:

  Control Structures

• Selection: IF ... ELSE ... ENDIF
• Simple Loops: BEGIN ...
• Counted Loops: DO
• Arbitrary control structures:
• Calls and returns:
• Exception Handling:

  Defining Words

• CREATE:
• Variables: Variables and user variables
• Constants:
• Values: Initialised variables
• Colon Definitions:
• Anonymous Definitions: Definitions without names
• Supplying names: Passing definition names as strings
• User-defined Defining Words:
• Deferred words: Allow forward references
• Aliases:

  User-defined Defining Words

• CREATE..DOES> applications:
• CREATE..DOES> details:
• Advanced does> usage example:
• Const-does>:

  Interpretation and Compilation Semantics

• Combined words:

  Tokens for Words

• Execution token: represents execution/interpretation semantics
• Compilation token: represents compilation semantics
• Name token: represents named words

  Compiling words

• Literals: Compiling data values
• Macros: Compiling words

  The Text Interpreter

• Input Sources:
• Number Conversion:
• Interpret/Compile states:
• Interpreter Directives:

  Word Lists

• Vocabularies:
• Why use word lists?:
• Word list example:

  Files

• Forth source files:
• General files:
• Search Paths:

  Search Paths

• Source Search Paths:
• General Search Paths:

  Other I/O

• Simple numeric output: Predefined formats
• Formatted numeric output: Formatted (pictured) output
• String Formats: How Forth stores strings in memory
• Displaying characters and strings: Other stuff
• Input: Input
• Pipes: How to create your own pipes

  Locals

• Gforth locals:
• ANS Forth locals:

  Gforth locals

• Where are locals visible by name?:
• How long do locals live?:
• Locals programming style:
• Locals implementation:

  Structures

• Why explicit structure support?:
• Structure Usage:
• Structure Naming Convention:
• Structure Implementation:
• Structure Glossary:

  Object-oriented Forth

• Why object-oriented programming?:
• Object-Oriented Terminology:
• Objects:
• OOF:
• Mini-OOF:
• Comparison with other object models:

  The objects.fs model

• Properties of the Objects model:
• Basic Objects Usage:
• The Objects base class:
• Creating objects:
• Object-Oriented Programming Style:
• Class Binding:
• Method conveniences:
• Classes and Scoping:
• Dividing classes:
• Object Interfaces:
• Objects Implementation:
• Objects Glossary:

  The oof.fs model

• Properties of the OOF model:
• Basic OOF Usage:
• The OOF base class:
• Class Declaration:
• Class Implementation:

  The mini-oof.fs model

• Basic Mini-OOF Usage:
• Mini-OOF Example:
• Mini-OOF Implementation:

  Programming Tools

• Examining:
• Forgetting words:
• Debugging: Simple and quick.
• Assertions: Making your programs self-checking.
• Singlestep Debugger: Executing your program word by word.

  Assembler and Code Words

• Code and ;code:
• Common Assembler: Assembler Syntax
• Common Disassembler:
• 386 Assembler: Deviations and special cases
• Alpha Assembler: Deviations and special cases
• MIPS assembler: Deviations and special cases
• Other assemblers: How to write them

  Tools

• ANS Report: Report the words used, sorted by wordset.

  ANS conformance

• The Core Words:
• The optional Block word set:
• The optional Double Number word set:
• The optional Exception word set:
• The optional Facility word set:
• The optional File-Access word set:
• The optional Floating-Point word set:
• The optional Locals word set:
• The optional Memory-Allocation word set:
• The optional Programming-Tools word set:
• The optional Search-Order word set:

  The Core Words

• core-idef: Implementation Defined Options
• core-ambcond: Ambiguous Conditions
• core-other: Other System Documentation

  The optional Block word set

• block-idef: Implementation Defined Options
• block-ambcond: Ambiguous Conditions
• block-other: Other System Documentation

  The optional Double Number word set

• double-ambcond: Ambiguous Conditions

  The optional Exception word set

• exception-idef: Implementation Defined Options

  The optional Facility word set

• facility-idef: Implementation Defined Options
• facility-ambcond: Ambiguous Conditions

  The optional File-Access word set

• file-idef: Implementation Defined Options
• file-ambcond: Ambiguous Conditions

  The optional Floating-Point word set

• floating-idef: Implementation Defined Options
• floating-ambcond: Ambiguous Conditions

  The optional Locals word set

• locals-idef: Implementation Defined Options
• locals-ambcond: Ambiguous Conditions

  The optional Memory-Allocation word set

• memory-idef: Implementation Defined Options

  The optional Programming-Tools word set

• programming-idef: Implementation Defined Options
• programming-ambcond: Ambiguous Conditions

  The optional Search-Order word set

• search-idef: Implementation Defined Options
• search-ambcond: Ambiguous Conditions

  Emacs and Gforth

• Installing gforth.el: Making Emacs aware of Forth.
• Emacs Tags: Viewing the source of a word in Emacs.
• Hilighting: Making Forth code look prettier.
• Auto-Indentation: Customizing auto-indentation.
• Blocks Files: Reading and writing blocks files.

  Image Files

• Image Licensing Issues: Distribution terms for images.
• Image File Background: Why have image files?
• Non-Relocatable Image Files: don't always work.
• Data-Relocatable Image Files: are better.
• Fully Relocatable Image Files: better yet.
• Stack and Dictionary Sizes: Setting the default sizes for an image.
• Running Image Files: gforth -i file or file.
• Modifying the Startup Sequence: and turnkey applications.

  Fully Relocatable Image Files

• gforthmi: The normal way
• cross.fs: The hard way

  Engine

• Portability:
• Threading:
• Primitives:
• Performance:

  Threading

• Scheduling:
• Direct or Indirect Threaded?:
• Dynamic Superinstructions:
• DOES>:

  Primitives

• Automatic Generation:
• TOS Optimization:
• Produced code:

  Cross Compiler

• Using the Cross Compiler:
• How the Cross Compiler Works:

  Licenses

• GNU Free Documentation License: License for copying this manual.
• Copying: GPL (for copying this software).