Gforth 1.0 NEWS

User-visible changes between Gforth 0.7.x and 1.0: 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. Stability It is now documented which words are intended to be permanently supported, and which are not; see Stability Goals. Headline features 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 No longer documented words 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@). Internal and therefore no longer documented: ;s block-position cfalign cfaligned compile-lp+! empty-buffer name?int s>number? s>unumber? save-buffer Other additional features 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 trings(Stringrepresentationwithautomaticmemorymanagement):‘trings (String representation with automatic memory management): `! $@ $@len $!len $+!len $del $ins +!c+!

c+!

$free $init $iter $over $exec $. $slurp $slurp-file $+slurp $+slurp-file $variable` tringarrays:‘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 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.