fsb is a preprocessor and converter of Forth source files. Its goal is to make it easy to edit and mantain Forth source files, in ordinary text format, for Forth systems that use blocks files.
Following some simple layout conventions, the source file can be edited without the lack of space imposed by blocks, thus making it possible to include detailed comments and arrange a clear layout.
fsb is written as a plugin for the Vim editor. It can be used to edit Forth sources with the Vim editor (thus using the included associated style and key mappings), or as a command line tool to convert Forth source files edited with any other editor.
fsb provides two main converters (to FB and FBS formats, as explained below); but a set of additional, more specific converters are included as shell files.
Project web page: http://programandala.net/en.program.fsb.html.
The Vim editor must be installed in the system. The GUI version (called gvim) is not required; the console version is enough.
Some converters have specific requirements. See their source code (the files with the ".sh" filename extension).
fsb can run on any system Vim can run on, and convert files from the FSB format to FS, FB or FBS formats (see below). But the other converters, provided only as shell files, run only on GNU/Linux or other flavours of Unix.
The filename extensions used by fsb are derived from ".fs" and ".fb", used by Gforth and other Forth systems.
| Extension | Description |
|---|---|
.fs |
Forth stream file. |
.fsb |
Forth stream file with blocks-like layout. |
.fb |
Forth blocks file. |
.fbs |
Forth blocks file with stream-like end-of-lines. |
FBS is the name fsb uses for a target format it can convert FSB sources to. FBS files are blocks files but with 63-chars lines and end of lines. This is the format used by the library of the lina Forth system.
fsb uses an ad-hoc simple format for Forth source, called FSB. The ".fsb" filename extension is used. FSB files are ordinary text files with only three simple layout conventions: block headers, metacomments and empty lines.
Block headers must be marked with a comment. There are three ways to do it:
-
A paren comment that starts at the first column of the line.
-
A slash comment that starts at the first columen of the line and ends with a second closing slash. This alternative is provided in order to include words with closing parens.
-
A dot-paren comment that starts at the first column of the line.
In all cases, more comments or Forth code can be included after the header comment.
Examples:
( Tools)
\ this is block 0
.( More tools) \ anything is allowed here
\ this is block 1
( MAIN-WORD ) page
\ this is block 2
\ (CORE) \
\ this is block 3
\ (MORE) \ by MEE on 2015-09-19
\ this is block 4
The only header comment that is not necessary is the first one, for block 0. When there is something (except metacomments, see below) at the top of the file, it’s suppossed to be the contents of the first block. Example:
\ This is block 0, \ even without an actual block header. : bla ( -- ) recurse ; ( More ) \ This is block 1.
Metacomments are comments that will be removed from the target file. They are backslash comments that are on their own line and have at least one space on the left.
( block header ) \ This comment will be preserved. variable range \ this comment will be preserved as well \ But all these comments \ will be removed \ from the target file.
fsb recognizes some directives, provided they are the first word of a backslash metacomment. Directive names start with a hash sign. Example:
forth code here \ #directive-name directive-parameters more forth code here
The #vim directive makes it possible to execute any Vim
command to preprocess the source.
\ #vim any-vim-ex-command
Executing the #vim directives is the first task done by fsb.
The directives are removed from the source before executing
them, and they are executed in the order they appear in the
source.
This example is extracted from the sources of the Tron 0xF game:
\ The following '#vim' directives, processed by fsb, \ translate the UTF-8 chars in this source file to \ ZX Spectrum's user defined graphics. \ Esperanto letters: \ #vim %substitute@Ĉ@\=nr2char(144)@g \ #vim %substitute@ĉ@\=nr2char(145)@g \ #vim %substitute@Ĝ@\=nr2char(146)@g \ #vim %substitute@ĝ@\=nr2char(147)@g \ #vim %substitute@Ĥ@\=nr2char(148)@g \ #vim %substitute@ĥ@\=nr2char(149)@g \ #vim %substitute@Ĵ@\=nr2char(150)@g \ #vim %substitute@ĵ@\=nr2char(151)@g \ #vim %substitute@Ŝ@\=nr2char(152)@g \ #vim %substitute@ŝ@\=nr2char(153)@g \ #vim %substitute@Ŭ@\=nr2char(154)@g \ #vim %substitute@ŭ@\=nr2char(155)@g
The #previm directive works the same way than #vim. The
only difference is #previm directives are executed first. This
makes it possible to modify the #vim directives with the
#previm directives.
Some key mappings are provided in order to help during the edition of FSB files with the Vim editor. All of them work in the normal mode of Vim.
| Shortcut | Action |
|---|---|
.fb |
Convert the current buffer to a FB file. |
.fbs |
Convert the current buffer to a FBS file. |
,s |
Toggle the FSB style (underline block headers and show a right column limit). |
,f |
Toggle the block format beetween the standard 16x64 and the alternative 32x32 (used by some 8-bit Forth systems). |
,g |
Go to the block specified as a prefix count (first block is 0). |
,G |
Go to the block specified as as prefix count, counting backwards from the end of the file (last block is 0). |
,b |
Go to the bottom of the current block. |
,t |
Go to the top of the current block. |
,p |
Go to the previous block. |
,n |
Go to the next block. |
,<Up> |
Move maximum number of valid lines up (usually 16). This is useful to calculate where a new block header is needed. |
,<Down> |
Move maximum number of valid lines down (usually 16). This is useful to calculate where a new block header is needed. |
,c |
Check the current block (their length and the length of their lines). |
,C |
Check all blocks (their lenght and the length of their lines). |
,L |
Check the length of all lines of the file. |
,# |
Show the number of the current block. Known issue: block 0 shows number 1. |
,i |
List an index of all blocks. |
Several converters are provided as shell files (with the ".sh" filename extension). They can be used from the command line, without starting a Vim session. Most of them are specific to ZX Spectrum Forth systems, but may be used as a model for other systems.
Some converters have special requirements. See their source file for more details.
- fsb-abersoft
-
ZX Spectrum TAP file for the original unfixed Abersoft Forth (one file called "DISC", with 11 1-KiB screens, but 11263 bytes instead of 11264).
- fsb-abersoft11k
-
ZX Spectrum TAP file for Abersoft Forth fixed by the Afera library (one file called "DISC", with 11 1-KiB screens, 11264 bytes).
- fsb-abersoft16k
-
ZX Spectrum TAP file for Abersoft Forth improved by the Afera library (one file called "DISC", with 16 1-KiB screens).
- fsb-fb
-
FB format: classic blocks file.
- fsb-fbs
-
FBS format: blocks file but with 63-character lines and ends of line (the format used by the lina Forth system).
- fsb-mgt
-
ZX Spectrum MGT file (disk image for GDOS, G+DOS, Beta DOS or Uni-DOS), with the Forth source saved on the sectors; used by Solo Forth.
- fsb-superforth
-
Sinclair QL SuperForth individual block files.
- fsb-tap
-
ZX Spectrum TAP file (tape), for any ZX Spectrum Forth.
As the two main conversions (fsb2fb and fsb2fbs) are done by the Vim plugin itself, they are associated to key shortcuts.
-
Edit <CONFIG.sh> and change the installation directories and the installation command, if you need. Several options are provided in commented out lines.
-
Run <INSTALL.sh>.
In order to uninstall fsb, run <UNINSTALL.sh>.
-
The ",#" key mapping shows number 1 for block 0. This is caused by the simple method used to count the block headers above the current cursor position.
-
The optional 32x32 block format has not been tested.
fsb has been used to develop two projects in Forth: Afera (Afera in GitHub) and Tron 0xF (Tron 0xF in GitHub). It worked great, but the development of Solo Forth, (Solo Forth in GitHub), with a library file of more than 400 hundreds blocks and growing, was too much for fsb on a Raspbery Pi 2… Then a faster and simpler version was developed in Forth. It’s called fsb2 (fsb2 in GitHub).
fsb and fsb2 do the same: they convert the same source format and provide the same target formats. But there are some differences:
-
fsb2 is much faster.
-
fsb2 does not provide directives.
-
fsb2 does not allow comments or code at the right of a backslash-format block header.
-
fsb2 supports TRD and DSK disk images as target format.
fsb and fsb2 can be installed at the same time.