Many of the words below are just mentioned, without much indication
what they do. You can find out more by klicking on the word in the Web version of this
document, by typing "help
This text mentions words that appear the first time in the documentation; some have been available earlier, but were not documented.
It is now documented which words are intended to be permanently supported, and which are not; see Stability Goals.
The text interpreter can recognize more things:
6k5, 23%); strings
("string"), xts ( `word), nts
( ``word), body addresses
(<word> <word+8>). See Literals
in source code;forth:and vs. assembler:and.v and d in the
following examples): ->v for to v;
+>v for +to v; 'v for
addr v; @>d for action-of d;
=>d for is d. See rec-to.${LANG}recs rec-name rec-local rec-scope rec-number .-is-dcell? rec-float rec-complex rec-string rec-to rec-dtick rec-tick rec-body rec-env rec-meta rec-forth rec-sequence: get-recs set-recs rec-none translate-name translate-cell translate-dcell translate-float translate-complex translate-string scan-translate-string translate-env translate-to rec-filter rec-forth-nt? translate: interpreting compiling postponing ?rec-foundIDE features:
locate browse).where nw bw ww).nt bt tt);edit g gg whereg);fancy-after-l xt-locate l n b before-locate after-locate ll short-where expand-where prepend-where unused-words"Smart .s: ... guesses what stack items
mean and displays them appropriately. .s itself stays
dumb.
A status line at the bottom of the terminal shows
BASE, stacks, and search order.
-status +status
Multi-Tasking on multiple cores or hardware threads:
newtask task newtask4 stacksize stacksize4 initiate execute-task kill-task kill stop stop-ns stop-dns thread-deadline halt sleep wake restart pause auser uallot up@ user' 's mutex lock unlock critical-section atomic!@ atomic+!@ atomic?!@ barrier
Message queues (similar to the actor model) provide a way to combine
communication with synchronization of the tasks:
send-event ?events event-loop
Cilk is useful for distributing work across tasks:
cores cilk-init spawn spawn1 spawn2 cilk-sync cilk-bye
C interface enhancements, includig callbacks:
c-value c-variable c-funptr c++-library-name c++-library add-libpath add-framework add-incdir add-cflags add-ldflags c-callback c-callback-thread callback#
The dictionary can now have more than one section, each with its
own dictionary pointer, which allows allocation without affecting other
sections, used, e.g., for nested definitions. See Sections. Words:
next-section previous-section extra-section .sections
Postpone multiple words with
]]...[[.
Value-flavoured and defer-flavoured fields:
value: cvalue: wvalue: lvalue: scvalue: swvalue: slvalue: 2value: fvalue: sfvalue: dfvalue: zvalue: $value: value[]: $value[]: defer:
Closures: Execution tokens for code with data:
free-closure [n:l [d:l [f:l [n:d [d:d [f:d [n:h [d:h [f:h [n:h1 [d:h1 [f:h1 [{: :}l :}d :}h :}h1 :}xt >addr <{: ;>
New word header layout, and based on that:
set-does> set-compsem set->int set->comp set-name>string set-name>link;
using a code addres instead of an xt: set-execute; new code
addresses for that: dovalue: dodoes: doabicode:to etc.:
to-table: n/a to-class: >uvalue set-toset-optimizercompsem: intsem: opt:create-from reveal reveal! noname-fromset-does> etc. to a word defined earlier:
make-latest.hm immediate?Performance comparable to SwiftForth
Many of these words are still in Gforth 1.0, but they may be removed in the future.
.name (use id.);does-handler! (implementation changed, use
set-does>);/does-handler (implementation changed, see Carnal
words);@local# f@local# laddr# lp+!# (replaced by
@localn f@localn lp+n lp+!);clear-libs (interface changed, use
c-library ... end-c-library)<interpretation interpretation> <compilation compilation> create-interpret/compile
(replaced by set->int set-compsem)naligned (use *aligned)name>comp name>int (use
name>compile name>interpret)path-allot (use dup , 0 , allot)sl@ sw@ ul@ uw@ (use l@ l>s;
w@ w>s; l@; w@).;s block-position cfalign cfaligned compile-lp+! empty-buffer name?int s>number? s>unumber? save-bufferYou can use the return stack interpretively (except for passing data into or out of INCLUDED, EVALUATE etc.)
help shows the documentation of words, or
documentation nodes. Other words providing information:
authors license.
Boolean flags: select
Arithmetic words:
umin umax/s /f u/ mods modf umod /mods /modf u/mod du/mod */s */f u*/ */mods */modf u*/mod ud/modstaged/-size /f-stage1m /f-stage2m modf-stage2m /modf-stage2m u/-stage1m u/-stage2m umod-stage2m u/mod-stage2m staged/-divisormux arshift dlshift drshift darshift >pow2 log2 pow2? ctz wrol wror lrol lror rol ror drol drorrnd random seed!s>f f>s fcopysign ftrunc v* faxpy infinity inf -infinity -inf nanStack Manipulation:
Dictionary allocation:
->here w, l, x, xd, a, mem, save-mem-dict
Heap allocation: save-mem extend-mem free-mem-var.
Growable buffers:
buffer% init-buffer adjust-buffer.
Memory access:
*aligned *align!@ +!@ cell- cell/ th th@ th!w@ w! l@ l! x@ x! xd@ xd!wbe wle lbe lle xbe xle xdbe xdlec>s w>s l>s x>s xd>sw, l, x, xd,/xwaligned walign laligned lalign xaligned xalignchar- float/ sfloat/ dfloat/String and character constants:
newline #tab #lf #cr #ff #bs #del #bell #esc #eof
Strings:
string-suffix? scan scan-back skip $split nosplit? safe/string insert delete cstring>sstring capscompare capsstring-prefix? capssearch s+ append
Redirect printing words to a string:
>string-execute $tmp
$trings (String representation with automatic memory management):
$! $@ $@len $!len $+!len $del $ins $+! c$+! $free $init $iter $over $exec $. $slurp $slurp-file $+slurp $+slurp-file $variable
$tring arrays:
$[] $[]! $[]+! $+[]! $[]@ $[]# $[]map $[]slurp $[]slurp-file $[]. $[]free $[]variable
Internationalization and localization:
l" locales native@ locale@ program default locale-csv-out locale-csv .locale-csv locale! locale:
Substitution in strings:
macros-wordlist replaces replacer: .substitute $substitute substitute unescape $unescape
Control flow
-[do u-[do array>mem mem+do mem-do i' delta-icase to loops:
next-case ?of contofcs-drop?exit execute-exitfast-throw exceptions ?errno-throw ?ior catch-nobt warning" warningsDefining words: avariable buffer: aconstant
forward .unresolvedavalue 2value fvalue +to addressable: addr.inline: ;inline[: ;]:is preserve wrap-xtwfield: lfield: xfield: extend-structurestack stack: stack> >stack >back back> +after -stack set-stack get-stackName tokens:
find-name-in latestnt xt>name traverse-wordlist name>interpret name>compile compile-only? obsolete? name>link
Word definition and text-interpreter status:
in-colon-def? state
Conditional and looping compilation:
[DEFINED] [UNDEFINED] [I] INT-[I]
Text interpreter hooks:
before-line before-word line-end-hook
Input stream: string-parse
Wordlists:
in-wordlist in cs-wordlist cs-vocabulary .voc wordlist-words mwords map-vocs
Environmental queries:
max-xchar xchar-maxmem os-type
Redirection: outfile-id infile-id
Directories:
basename dirname open-dir read-dir close-dir filename-match get-dir set-dir =mkdir mkdir-parents
Search paths:
absolute-file? .fpath file>fpath file>path
Terminal output, in particular colors:
at-deltaxy default-color error-color error-hl-inv error-hl-ul warning-color info-color success-color input-color status-color compile-color postpone-color light-mode dark-mode uncolored-mode magenta-input default-input
Single-key input:
key-ior xkey? ekey>xchar k-enter k-backspace k-tab k-winch k-pause k-mute k-volup k-voldown k-sel k-eof fkey. simple-fkey-string
CSV input:
read-csv csv-separator csv-quote .quoted-csv
Locals:
{: | :} z: z^ xt: @localn f@localn !localn lp+n lp+!
Mini-OOF2 (a little larger than Mini-OOF, but much smaller than
the others; Gforth-specific):
>o o> rec-moof2 :method
Regular Expressions:
(( )) charclass +char -char ..char +chars +class -class c? -c? \d \s .? -\d -\s \^ \$ str=? =" {** **} {++ ++} {* *} {+ +} // {{ || }} \( \) \0 s>> >> << <<" s// //s //o //g FORK JOIN ` `? -`
Examining compiled code:
xt-simple-see xt-see-code
Debugging words:
debug-fid once ~~bt ~~1bt ??? WTF?? !!FiXME!! replace-word ~~Variable ~~Value +ltrace -ltrace #loc
Code Coverage and Execution Frequency:
.coverage annotate-cov bw-cover color-cover save-cov load-cov nocov[ ]nocov cov+ ?cov+ cov% .cover-raw
Disassembler:
disasm2 intel-syntax at&t-syntax disasm disasm-gdb
Keeping track of Time:
ns >time&date&tz ntime
Image saving and startup:
'image process-option
MINOS2:
actor widget caller-w active-w act-name$ clicked scrolled touchdown touchup ukeyed ekeyed ?inside focus defocus entered left show hide get set show-you parent-w act name$ x y w h d gap baseline kerning raise border borderv bordert borderl w-color draw-init draw split lastfit hglue dglue vglue hglue@ dglue@ vglue@ xywh xywhd !resize !size dispose-widget .widget par-split resized >animate color: new-color: text-color: text-emoji-color: fade-color: text-emoji-fade-color: re-color re-text-color re-emoji-color re-fade-color re-text-emoji-fade-color vp-top vp-bottom vp-left vp-right vp-reslide vp-needed
Other words:
f.s-precision fclearstack sh-get synonym out
We have not done Gforth EC work since Gforth 0.7. We recommend using Gforth 0.7 for Gforth EC, but welcome bug or success reports for Gforth EC in our git head.
Requirements:
At run-time requires libtool and gcc (for the libcc C interface) and
gdb (for the disassembler (SEE)) on some platforms.
Installation:
support for DESTDIR, POST_INSTALL, INSTALL_SCRIPT
automatic performance tuning on building (--enable-force-reg unnecessary)
report performance and functionality problems at end of "make"
autogen.sh now exists
License:
Changed to GPLv3
Bug fixes
Now works with address-space randomization.
The single-step debugger works again in some engines.
Many others.
Ports:
AMD64, ARM, IA-64 (Itanium): better performance
PPC, PPC64: disassembler and assembler
Gforth EC: R8C, 4stack, misc, 8086 work
MacOS X: better support
Invocation:
New flags --ignore-async-signals, --vm-commit (default overcommit)
--print-sequences
Forth 200x:
X:extension-query: produce true for all implemented extensions
X:required REQUIRED etc. (not new)
X:defined: [DEFINED] and [UNDEFINED]
X:parse-name: PARSE-NAME (new name)
X:deferred: deferred words (new: DEFER@ DEFER! ACTION-OF)
X:structures: +FIELD FIELD: FFIELD: CFIELD: etc.
X:ekeys: new: EKEY>FKEY K-SHIFT-MASK K-CTRL-MASK K-ALT-MASK K-F1...K-F12
X:fp-stack (not new)
X:number-prefixes (partially new, see below)
Number prefixes:
0x is a hex prefix: 0xff and 0XfF now produces (decimal) 255
# is a decimal prefix: #10 now produces (decimal) 10
Signs after the number prefix are now accepted, e.g, #-50.
' now only handles a single (x)char: 'ab is no longer accepted,
'a' now produces (decimal) 97
Unicode support (currently supports only uniform encoding):
added xchars words for dealing with variable-width multi-byte characters
provide 8bit (ISO Latin 1) and UTF-8 support for xchars
New words:
\C C-FUNCTION C-LIBRARY END-C-LIBRARY C-LIBRARY-NAME (libcc C interface)
LIB-ERROR (complements OPEN-LIB)
OUTFILE-EXECUTE INFILE-EXECUTE BASE-EXECUTE (limited change of global state)
16-bit and 32-bit memory acces: UW@ UL@ SW@ SL@ W! L! W@ L@ /W /L
NEXT-ARG SHIFT-ARGS (OS command-line argument processing)
NOTHROW (for backtrace control)
FTRUNC FMOD (undocumented)
SEE-CODE SEE-CODE-RANGE (show generated dynamic native code)
Improvements/changes of existing words:
S\", .\" now support \l, \m, \z, and limits hex and octal character specs.
OPEN-FILE with W/O no longer creates or truncates files (no compat. file)
OPEN-LIB now understands ~ at the start, like OPEN-FILE.
TRY...ENDTRY changed significantly, compatibility files available (see docs).
The disassembler (DISCODE) can now use gdb to disassemble code
Uninitialized defered words now give a warning when executed
Division is floored (disable with "configure --enable-force-cdiv")
Gforth (not gforth-fast) reports division by zero and overflow on division
on all platforms.
Newly documented words:
S>NUMBER? S>UNUMBER?
EKEY keypress names: K-LEFT K-RIGHT K-UP K-DOWN K-HOME K-END K-PRIOR
K-NEXT K-INSERT K-DELETE
CLEARSTACKS
FORM
Environment variable GFORTHSYSTEMPREFIX (used by word SYSTEM and friends)
C interface:
exported symbols now start with "gforth_" (for referencing them from C code)
libcc C function call interface (requires libtool and gcc at run-time)
alternative: undocumented libffi-based interface
Libraries:
depth-changes.fs: report stack depth changes during interpretation
ans-report.fs now reports CfV extensions
fsl-util.4th: FSL support files (undocumented)
regexp.fs for regular expressions (undocumented)
complex.fs for complex numbers (undocumented)
fft.fs for Fast Fourier Transform (undocumented)
wf.fs, a Wiki implementation (undocumented)
httpd.fs, a web server (undocumented)
status.fs, show interpreter status in separate xterm (undocumented)
profile.fs for profiling (undocumented, incomplete)
endtry-iferror.fs, recover-endtry.fs to ease the TRY change transition
test/tester.fs: Now works with FP numbers (undocumented)
test/ttester.fs: Version of tester.fs with improved interface (T{...}T).
compat library:
compat/execute-parsing.fs
Speed improvements:
automatic performance tuning on building
static stack caching (good speedup on PPC)
mixed-precision division is now faster
support for int128 types on AMD64
workarounds for gcc performance bugs (in particular, PR 15242)
branch target alignment (good speedup on Alpha).
Bug fixes (in particular, gforth-0.6.2 compiles with gcc-3.3)
New words: LATEST, LATESTXT (LASTXT deprecated)
Operating environment: Added optional support for a C interface built
on the ffcall libraries (more portable and powerful than the old
one, but still not documented). To use it, the ffcall libraries
have to be installed before building Gforth (see INSTALL).
Miscellaneous: Gforth-fast now uses static superinstructions (some
speedup on some platforms); generally this is transparent (apart
from the speedup), but there are lots of command-line options for
controlling the static superinstruction generation.
Bug fixes (installation on big-endian machines sometimes did not work)
Changes in behaviour:
S": interpreted use now ALLOCATEs the string (they live until BYE).
Long word names (512MB on 32-bit systems) are now supported (change to
the header format).
New threaded code execution method: primitive-centric (allows the
following), hybrid direct/indirect threaded (easier portability),
with dynamic superinstructions (typical speedup on Athlon: factor
2). New engine gforth-itc for dealing with some potential
backwards-compatibility problems (see "Direct or Indirect Threaded?"
in the manual).
Operating environment:
Default dictionary size is now 4MB.
Large file support on OSs that support them (i.e., files with more
than 2GB on 32-bit machines).
Gforth can now deal well with broken pipes in most situations.
vi tags files can be built with tags.fs (usage like etags.fs).
gforth.el mostly rewritten.
New image file format.
New words:
Keyboard input: EDIT-LINE K-PRIOR K-NEXT K-DELETE
File input: SLURP-FILE SLURP-FID
Programming tools: ID. .ID WORDLIST-WORDS SIMPLE-SEE
Conditional execution: [DEFINED] [UNDEFINED]
Defining Words: CONST-DOES> ]]
Input stream: PARSE-WORD EXECUTE-PARSING EXECUTE-PARSING-FILE
String comparison: STR= STR< STRING-PREFIX?
String literals: S\" .\" \"-PARSE
Floating point output: F.RDP F>STR-RDP F>BUF-RDP
Miscellaneous:
Generalized prims2x.fs into Vmgen (see README.vmgen etc.); used the
new capabilities in prims (e.g., automatic handling of the return
stack and instruction stream).
Changes in behaviour:
There are now two engines: the fast engine (gforth-fast) is at least
as fast as gforth in earlier releases; the debugging engine (gforth)
supports precise backtracing for signals (e.g., illegal memory
access), but is slower by a factor of 1-2.
Block files now start at block 0 by default (instead of block 1). If
you have block files around, prepend 1024 bytes to convert them, or
do a "1 OFFSET !" to establish the old behaviour.
Gforth now does not translate newlines to LFs on reading. Instead,
READ-LINE now interprets LF, CR, and CRLF as newlines. Newlines on
output are in the OSs favourite format.
SEE now disassembles primitives (or hex-DUMPs the code if no
disassembler is available).
>HEAD (aka >NAME) now returns 0 (instead of the nt of ???) on failure.
Syntax of prim changed: stack effects are now surrounded by
parentheses, tabs are insignificant.
Operating environment:
Gforth now produces a backtrace when catching an exception.
On platforms supporting the Unix 98 SA_SIGINFO semantics, you get more
precise error reports for SIGSEGV and SIGFPE (e.g., "stack
underflow" instead of "Invalid memory address").
Gforth now produces exit code 1 if there is an error (i.e., an
uncaught THROW) in batch processing.
You can use "gforthmi --application ..." to build an image that
processes the whole command-line when invoked directly (instead of
through gforth -i).
Ports:
AIX.
20% speedup on 604e under powerpc-unknown-linux-gnu,
19%-29% speedup on Celeron with gcc-2.95.
New words:
Missing ANS Forth words: EKEY EKEY? EKEY>CHAR
Timing words: CPUTIME UTIME
Vector arithmetic: V* FAXPY
FP comparison: F~ABS F~REL
Deferred words: <IS> [IS]
Nested number output: <<# #>>
Exception handling: TRY RECOVER ENDTRY
Directory handling: OPEN-DIR READ-DIR CLOSE-DIR FILENAME-MATCH
Other: ]L PUSH-ORDER
Miscellaneous:
Significant extensions to the manual (added an introduction, among
other things), many of them due to a new team member: Neal Crook.
Added assemblers and disassemblers for 386, Alpha, MIPS (thanks to
contributions by Andrew McKewan, Bernd Thallner, and Christian
Pirker). Contributions of assemblers and disassemblers for other
architectures are welcome.
Operating environment:
Path handling: "." at the start of the path represents the directory
the nearest enclosing file resides in (if there is none: the working
directory). "~+" indicates the working directory. The default path
now has "." in front.
gforth and gforthmi is now more GNU standards compliant (wrt
command-line options).
New command-line-option: --die-on-signal
Errors are now directed to stderr.
Stdout is now unbuffered, if it is a tty.
User input device redirection (for filters) is now possible.
Ports:
Now runs on IRIX (and other MIPS-based systems without linker-flag -d).
Direct threading now works on PowerPC (20% speedup on 604e).
Better support for m68k (thanks to Andreas Schwab and Jorge Acereda).
It is possible to create executables that contain the image (for
non-OS systems).
Added a lot of embedded control (EC) stuff. Supported controllers and
small CPUs are Siemens C16x, 8086, 6502, Mixed-Mode's FPGA MISC, Bernd Paysan's
4stack processor. Not finished: ShBoom alias PSC1000, H8, AVR.
New, changed, and removed words:
Renamed F0 to FP0 (avoids unexpected behaviour in hex), added aliases
SP0, RP0, LP0 (recommended for future use) for S0, R0, L0.
Renamed PARSE-WORD into SWORD (PARSE-WORD is used with the meaning of
NAME in OpenBoot and dpans6 A.6.2.2008)
Added FPICK (suggested by Julian Noble).
Added EXCEPTION.
S" gforth" ENVIRONMENT? now produces the version-string.
Changed representation of types in struct package, and correspondingly
changed names.
Miscellaneous:
Plain text documentation is now available in doc/gforth.txt.
Documentation improvements.
Wordlist structure changed.
Added mini-oof.
Reorganized files: added directories and reorganized many files into
them; renamed files into 8.3 format to work with completely broken
systems (but there are again some files that won't work there).
Bug fixes.
Various changes without log information only known as mega-patches.
Cross compiler now also supports compilation only for undefined or forward
referenced words. Plugins to support some native code generation
(for PSC1000).
More files in the compat library.
Stack overflow detection by memory protection on most systems
(allocation with mmap).
gforth.fi is now fully relocatable.
fully relocatable images are now easier to create.
added primitives K and UNDER+.
Win32 support.
Improved support for embedded controllers and other deprived environments.
some bug fixes.
added concept index; other documentation improvements.
Bug fixes
Portability and Installation:
Support architectures with buggy long longs (alpha-dec-osf).
Better support for DOS and other non-Unix systems.
Size changes through the command line are passed to the image (and
saved with savesystem); the preamble specifies an interpreter and is
propagated by save-system.
Tools:
Improved etags support.
more.fs allows output paging.
Added compat/ directory containing ANS implementations of Gforth features.
Added tiny multitasker (tasker.fs).
Added two alternatives for object-oriented programming: oof.fs, objects.fs.
Added ans-report.fs (reports which words are used from which wordset).
New words:
Changed POPEN and PCLOSE to OPEN-PIPE and CLOSE-PIPE.
Added FORM, ROWS, and COLS.
added primitives EMIT-FILE, STDOUT, STDERR.
Added TABLEs (case-sensitive wordlists).
added POSTPONE,.
Added the ability to combine arbitrary interpretation and compilation
semantics (INTERPRET/COMPILE:); state-smart words were generally
rewritten to use that mechanism.
Changes to existing words:
EMIT and TYPE now work through file words (and are redirectable).
HEADER now stores the compilation wordlist in the header and REVEAL
reveals into that wordlist.
changed behaviour of SYSTEM (no longer returns wretval, but puts it in
$?) added (SYSTEM) ( c_addr u -- wretval wior ).
' and ['] now give an error for compile-only words.
Authors: Anton Ertl, Bernd Paysan
Copyright (C) 1995,1996,1997,1998,2000,2003,2006,2007,2008,2019,2022,2023,2024 Free Software Foundation, Inc.
This file is part of Gforth.
Gforth is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation, either version 3
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.#See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see http://www.gnu.org/licenses/.
% Local Variables:
% fill-prefix: " "