Skip to content
slaxorPublic

About

A terminal that accomodates forth systems

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

fterm

A serial terminal for Forth targets (built against Mecrisp-Stellaris). It works like tio, plus:

  • uploads that send line by line and wait for the target's ok. before the next line, stopping at the first error with file:line
  • #include / #require resolved on the host
  • macros and config written in Forth, running on the host
  • a control socket so neovim or another tmux pane can push files into the open session

Run

nix run .            # or: just run
fterm -p /dev/ttyACM0 -b 115200
fterm send dcf77.fs  # through the running session, or directly if none runs
fterm eval 'flash'   # run host Forth in the running session

fterm send exits non-zero on error and prints file:line: message to stderr, so it works as a neovim makeprg:

set makeprg=fterm\ send\ %
set errorformat=%f:%l:\ %m

Install with home-manager

# flake inputs
fterm.url = "https://github.com/slaxor/fterm.git";

# home configuration
imports = [ inputs.fterm.homeManagerModules.default ];
programs.fterm = {
  enable = true;
  init = ''
    2 timestamps
    : reboot  s" reset" run  2000 delay ;
    ' reboot bind F6
  '';
};

init is written to ~/.config/fterm/init.fs. It is used when there's no project .fterm.fs, or when a project config says include-global. The package is built against your own pkgs, and overlays.default provides pkgs.fterm. For the serial port your user needs to be in the dialout group (users.users.<you>.extraGroups on NixOS).

Input

Lines are edited locally, readline style, and sent with Enter:

Key Action
up/down, ctrl-p/ctrl-n history
ctrl-r reverse history search (ctrl-r again for older, Enter runs, Esc cancels)
ctrl-a/ctrl-e, home/end line start / end
ctrl-b/ctrl-f, left/right char back / forward
alt-b/alt-f, ctrl-left/ctrl-right word back / forward
ctrl-w, ctrl-u, ctrl-k, ctrl-y kill word / to start / to end, yank
ctrl-c discard the line

After Enter, keys go raw to the target until it prompts with ok. (or reports an error), so words that loop until a keypress (log, decode) keep working. History is shared by target lines, # directives and host Forth. It is saved to $XDG_STATE_HOME/fterm/history (~/.local/state/fterm/history), or to the file you give history in .fterm.fs.

Keys

Key Action
ctrl-t q quit
ctrl-t : host Forth prompt
ctrl-t u upload a file (prompt); Tab there opens the file picker
ctrl-t r repeat last upload
ctrl-t e edit the last error location (or last upload)
ctrl-t c forget the #require list (after a target reset)
ctrl-t l toggle raw passthrough (no local editing)
ctrl-t h help
ctrl-t ctrl-t send a literal ctrl-t
ctrl-t <c>, F1..F12 macros bound with bind
ctrl-c, Esc abort a running upload or macro; while the target runs a line they are forwarded, and if no ok. follows within 0.5 s you get the line editor back

A single-line paste goes into the line editor. A multi-line paste goes through the upload path, with flow control.

Line directives

Lines starting with # are handled by fterm itself:

Directive Action
#i file, #include file upload
#r file, #require file upload once per session
#e [file] $VISUAL/$EDITOR (fallback nvim) at +LINE; with no argument it opens the last error
#f forth run host Forth

Tab after #i, #r or #e opens the file picker and fills in the argument.

File picker

A full-screen list of the Forth sources (.fs .fth .4th .f .forth) below the working directory and the path directories, skipping hidden dirs, target/ and result. Typing filters fuzzily (word starts and consecutive letters rank first), up/down/Tab/ctrl-n/ctrl-p move, PgUp/PgDn page, ctrl-u clears, Enter chooses and Esc cancels. Terminals at least 100 columns wide get a preview of the selected file. From the upload prompt the choice is uploaded right away and recorded in history as #i file. Target output that arrives while the picker is open is held back and shown when it closes.

Any other # line (#s, # 42) goes to the target unchanged.

The same #include / #require lines work inside uploaded files. They are resolved relative to the including file, then the path directories.

Config: .fterm.fs

fterm loads the file given with -c, or else the nearest .fterm.fs found upwards from the working directory. Only if there is none does it load ~/.config/fterm/init.fs ($XDG_CONFIG_HOME). A project config pulls the global one in with include-global, usually as its first line. Relative paths in it resolve against its directory. See example.fterm.fs.

Host words on top of a small core Forth (stack, arithmetic, if else then, begin until/again/while repeat, do loop i j, variable constant create , @ !, s" ." ' execute recurse, words see list):

Word Stack
port ( a u -- ) serial device
baud ( n -- )
timeout ( ms -- ) per-line prompt timeout, default 3000
eol ( c -- ) 13 CR (default), 10 LF, 0 CRLF
prompt ( a u -- ) success suffix, default ok.
error / no-errors ( a u -- ) / ( -- ) add an error pattern / clear the defaults
path ( a u -- ) add an include search directory
history ( a u -- ) history file, relative to the config; empty string: none
send ( a u -- ) send a line, wait for ok., throw on error
run ( a u -- ) send a line, don't wait (for words that loop)
raw ( a u -- ) send bytes as they are
dtr / rts ( f -- ) set a modem line, e.g. a hard reset if RUN is wired to DTR: : kill 0 dtr 100 delay -1 dtr ;
upload ( a u -- ) upload a file
upload? ( a u -- ) upload a file if it exists, otherwise do nothing
exists ( a u -- f ) true if the file exists (working dir, then config dir)
expect ( a u ms -- f ) wait for text in the output (includes the reply to the last send)
delay ( ms -- ) wait, showing output
bind ( xt "key" -- ) ' w bind F5, ' w bind p (ctrl-t p)
include ( "file" -- ) load more host Forth (~/ expands)
included ( a u -- ) same, taking a string
include-global ( -- ) load ~/.config/fterm/init.fs, if it exists
forget-required ( -- ) clear the #require list
see ( "name" -- ) decompile a host word
list ( "name" -- ) show a colon definition's source with file:line
bye ( -- ) quit

If you define on-connect, it runs after every (re)connect, e.g. : on-connect s" autoexec.fs" upload? ;.

Default error patterns (Mecrisp-Stellaris): not found., Stack underflow, Stack not balanced, Structures don't match, Jump too far.

Layout

  • lib/: core library and public API (source preprocessing, line protocol, host Forth, session, control socket)
  • cli/: thin binary that only uses lib's public API

Dev shell

nix develop

Build & test

just build
just test
just lint
just doc   # cargo doc --open

License

GPLv3, see LICENSE.

About

A terminal that accomodates forth systems

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages