Gforth 1.0 NEWS
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 " in Gforth, or by clicking on the word in the word index.
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:
- Additional ways to write literals in source code: scaled notation for FP numbers (`6k5`, `23%`); strings (`"string"`), xts (``word`), nts (```word`), body addresses (`<word> <word+8>`). See Literals in source code;
- You can specify the vocabulary (or several) of a word, e.g., `forth:and` vs. `assembler:and`.
- Nonparsing syntax for dealing with value-flavoured and defer-flavoured words (`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`.
- Contents of environment variables: `${LANG}`
- You can extend the text interpreter with more **recognizers**: `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-found`
- IDE features:
- Show source code of a word (`locate browse`).
- show uses of a word (`where nw bw ww`).
- backtraces show source locations and can be browsed (`nt bt tt`);
- and use an editor if desired (`edit g gg whereg`);
- other words: `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:`
- Per-task values and defers: `uvalue udefer`
- 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:
- Modify the behaviour of words: `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:`
- User-defined `to` etc.: `to-table: n/a to-class: >uvalue set-to`
- Modify the implementation of words: `set-optimizer`
- For fans of non-postfix syntax: `compsem: intsem: opt:`
- Creating a word from a template: `create-from reveal reveal! noname-from`
- Apply `set-does>` etc. to a word defined earlier: `make-latest`
- Introspection: `.hm immediate?`
- Performance comparable to SwiftForth
- IP-update optimization speeds up loop-dominated programs by a factor of 2
- Literal stack allows constant folding and other optimizations
Many of these words are still in Gforth 1.0, but they may be removed in the future.
- You 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:
- Single precision: `umin umax`
- Explicitly floored, symmetric, or unsigned division words: `/s /f u/ mods modf umod /mods /modf u/mod du/mod */s */f u*/ */mods */modf u*/mod ud/mod`
- Two-stage division: `staged/-size /f-stage1m /f-stage2m modf-stage2m /modf-stage2m u/-stage1m u/-stage2m umod-stage2m u/mod-stage2m staged/-divisor`
- Bitwise operations: `mux arshift dlshift drshift darshift >pow2 log2 pow2? ctz wrol wror lrol lror rol ror drol dror`
- Pseudo-random numbers: `rnd random seed!`
- Floating-point: `f*+ s>f f>s fcopysign ftrunc v* faxpy infinity inf -infinity -inf nan`
- Stack Manipulation:
- Data stack: `third fourth`
- FP stack: `fthird ffourth f-rot`
- Return stack: `r'@ rpick n>r nr> f>r fr> fr@`
- 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:
- Generic: `*aligned *align`
- Cells: `!@ +!@ cell- cell/ th th@ th!`
- Words for accessing memory in 16-bit (w), 32-bit (l), and 64-bit (x, xd) units: `w@ w! l@ l! x@ x! xd@ xd!`
- for dealing with different byte orders: `wbe wle lbe lle xbe xle xdbe xdle`
- for sign-extending: `c>s w>s l>s x>s xd>s`
- for allocating: `w, l, x, xd,`
- for sizes: `/x`
- for alignment: `waligned walign laligned lalign xaligned xalign`
- for other sizes: `char- float/ sfloat/ dfloat/`
- Xchars: `xc@ xc@+? xc!+ xc-width xhold xc, invalid-char`
- 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`
- $t r i n g s \left(\right. S t r i n g r e p r e s e n t a t i o n w i t h a u t o m a t i c m e m o r y m a n a g e m e n t \left.\right) : ‘$! $@ $@len $!len $+!len $del $ins $+ ! c$+! $free $init $iter $over $exec $. $slurp $slurp-file $+slurp $+slurp-file $variable`
- $t r i n g a r r a y s : ‘$[] $[]! $[]+! $+[]! $[]@ $[]# $[]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`
- Counted strings: `place string,`
- Control flow
- Counted loops: `-[do u-[do array>mem mem+do mem-do i' delta-i`
- Generalize Eaker's `case` to loops: `next-case ?of contof`
- Low-level control flow words: `cs-drop`
- Exits: `?exit execute-exit`
- Exceptions and warnings: `fast-throw exceptions ?errno-throw ?ior catch-nobt warning" warnings`
- Defining words: `avariable buffer: aconstant`
- Forward declarations: `forward .unresolved`
- Values: `avalue 2value fvalue +to addressable: addr`.
- Inline definitions: `inline: ;inline`
- Quotations: `[: ;]`
- Deferred words: `:is preserve wrap-xt`
- Structures: `wfield: lfield: xfield: extend-structure`
- User-defined stacks: `stack stack: stack> >stack >back back> +after -stack set-stack get-stack`
- No-ops: `[noop] noop`
- Name tokens: `find-name-in latestnt xt>name traverse-wordlist name>interpret name>compile compile-only? obsolete? name>link`
- Literal compilers: `lit, aliteral 2lit, flit, slit,`
- 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`
- String to number conversion: `>float1 holds`
- Environmental queries: `max-xchar xchar-maxmem os-type`
- File inclusion: `\\\ .included`
- General file handling: `+fmode file-eof?`
- 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`
- Simple numeric output: `h. dec.r`
- Floating-point output: `fp. e. e.p e.exact`
- 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`
- Definitions in assembly language: `abi-code ;abi-code`
- 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.