Skip to content

25.Editing_Code

Jump to bottom
Matteo Vitturi edited this page Jan 8, 2024 · 9 revisions

Editing Forth code on the Sinclair ZX Spectrum Next

You have three options:

  1. Edit code using blocks/screens, e.g. using edit
  2. Edit code using files, e.g. using LED
  3. Edit code using PC then use it with vForth.

You don't need to select one method - you can mix and match.

Notice, that although the third option is sometimes nice, you lose a lot of the interactive development that you would by using the first two methods. That's not to say you can't do it sometimes!

The rest of this document will give some guidance of the three approaches, along with examples.

You can also review the vForth Core PDF manual. This has sections on editing code.

Blocks / Screens

This is a mechanism to allow you to enter code, edit it and reload. They work well in vForth.

Screen is 1 KByte so it can store text in 16 lines and 64 columns in that fixed format. All blocks/screens are stored in the file called !Blooks-64.bin.

Detail on how to use these are covered elsewhere:

Please see these locations for much more detail - but I'd seriously suggest trying them since they are fast, easy and good for quick prototypes.

Editing with Files

The LED editor is similar to 'Edit', the screen/block editor, but operates on files of up to 17568 lines long and 85 characters.

Since the LED editor is based on the screen/block editor, it shares many of the commands and look-and-feel. This is can be advantage because you can switch between editing blocks and editing files using the same system. This editor is covered in more detail in section 3.3 of the vForth PDF manual.

You also need to be aware that editing files presents some challenges on the Sinclair ZX Spectrum, and so you should be aware them:

  • The vForth LED editor is a work in progress, and has a few rough edges.
  • All file editing uses RAM - that is not the case with screens/blocks which have fixed reserved space.
  • Big files use a lot of RAM! Maybe make several more smaller files - and use need or include to load them.
  • Even if LED can load very large file, the loading itself takes great amount of time and paging down is a slow operation
    • better not to use LED if the file is greater than a few hundred rows.

Memory

To load a file the LED command uses 8K pages 48 to 223 to store the file. If you are using this memory for your application, then you need to be careful. (See section 3.3, 6.3 and 7 - vForth's heap uses 8Kpages #32-39 and #40-47 are reserved. Also see https://wiki.specnext.dev/Memory_map ).

A demonstration

After loading vForth, load the large file editor (LED) and dir support.

needs led
needs dir

Show the current directory enter: dir .

Depending on how you started it will probably affect the current directory. If you started with the basic launcher, you'll probably be in the vForth directory. The dot command might be in the present directory. To show the 'root' directory type:

dir \

This shows the list of directories at the top level of the SD card.

Creating a new file

Let's edit a new file at the top level of the SD card. First I want to create a empty file. LED doesn't create files, so we need to create one.

needs touch
touch \test1.f
dir \

During DIR printing, you can use [EDIT] to pause the output. DIR also understands [BREAK] which is 'stop immediately'.

Opening an existing file

led \test1.f

You can make some edits to this blank document. Specifically with an empty file you need to insert a few lines with [EDIT]-s to shift down.

Once you have finished type [EDIT]-Q to quit.

You need to save it:

led-save

You can also duplicate a file:

led-file \test2.f

You are now editing a copy that will be saved as test2.f.

led-save

Now you have a copy on SD card.

NOTE: Within LED you can use [EDIT]-W to write without needing to quit to Forth prompt.

Look at the file size:

dir \

If you want to view the file you've just created there is a utility called view:

needs view
view \test1.f
view \test2.f

Remove Files we don't want

You have to specify the drive "c:"

needs unlink
unlink c:\test2.f

Checking how much space we have

needs unused
unused .

Editor Commands Sumnmary

After the [Edit] key (Shift + 1 using standard PC keyboard) the Editor recognizes the following single or double key-stroke commands:

  • [Edit] + Q : Quit EDIT Utility
  • [Edit] + U : Undo, that is re-read current screen from disk ignoring any modification done since last FLUSH. This feature is quite important, since it does for a single Screen what EMPTY-BUFFERS does for all of them.
  • [Edit] + H : take (or Hold) current line content and keep it in PAD
  • [Edit] + R : Replace current line with the current PAD content.
  • [Edit] + S : make Space at current cursor position shifting lower lines down; last line will be lost.
  • [Edit] + D : Delete current line shifting up lowerline,but a copy is copied to PAD before deletion,like H.
  • [Edit] + I : Insert at current cursor line position the content of PAD: it does commands S and R.
  • [Edit] + N : go to Next screen
  • [Edit] + B : go Back to previous screen
  • [Edit] + P : accepts two hexadecimal digits representing a byte and Put it at cursor position. This way, non- printable characters, i.e. ASCII code between 0 and 31 ($00 - $1F), can be stored inside a Screen, but care must be paid to avoid corrupting the display because most of them are control characters and some of them are used. Characters with ASCII code between $80 and $FF can be stored in a Screen, but they are emitted to video translated to the corresponding codes between $00 and $7F.

Any other key has no meaning and returns the flashing cursor back to its position.

Other keys:

  • [Delete] (that is Caps-Shift + ZERO) removes a character at current cursor position, shifting left the rest of the line.
  • [Break] (that is Caps-Shift + SPACE) inserts a space at current cursor position, shifting right the rest of the line.
  • [Caps-Lock] (that is Caps-Shift + 2) accounts for a keystroke, but it is interpreted by the system to change the Caps-Lock state switching between enabled ( █ ) and disabled ( ▄ ).

Using a PC/Mac/Linux Box

Sometimes it's nice to use fully featured editors on modern PCs.

That's ok. This section explains different approaches to doing that.

You can save your text files using DOS/Windows line endings (CR LF, 13 10), with Unix/Linux/MacOS line endings (LF, 10), or Spectrum/Classic Mac line endings (CR, 13). You can use any file extension you like (.txt, .f, .fth, .fs, ...) as long as they are plain text.

It's suggested you don't make you files too big - because loading times are long. In practice, we suggest you make your files much shorter than LED supports.

It's also important to limit the line length to 85 or less. Some editors have a margin ruler you can set at, say, 80 characters that will show you when you are writing lines that are too long.

Transfering back to the Spectrum Next

When you've completed your changes, normaly you'd copy them to the Spectrum Next and test the words them one by one.

Remember the advantage of Forth is piecemeal 'incremental' development and debugging - which is best done on the target machine.

Method 1: Copy to the SD Card

This is by far the easiest option for transfering files. However, it's the slowest cycle time for development when debugging on a Spectrum Next. (Perhaps you want to edit on the Spectrum Next after you've copied your changes across?)

Usually, if you have a single SD card in your Spectrum Next, you would:

  • Invoke REMOUNT (from Forth or from BASIC), but leave your Spectrum Next wait for keypress
  • Remove the SD card and put it in your PC
  • Copy the files over to a suitable directory on the SD card
  • Eject the SD card from your PC and put it back into the Spectrum Next
  • Hit Y key to complete the remount cycle.

It's not necessary to power down the Spectrum Next as long as you are not using the SD card at the time.

To remount from Forth:

needs REMOUNT
remount

Hit Y to complete the remount.

Loading the new code

There are two ways of loading a specific file:

  • needs <name> where is the name of your file without the .f at the end. NOTE: needs looks in the inc and then lib directories for file.
  • include <filepath-and-filename> where refer to a full-path filename with explicit extension.

NOTE: NEEDS lookups up whether it's loaded in the dictionary first - so you don't get duplicate defintions. If you are using needs then you will need to use forget or markers to make the dictionary forget.

Include will include it everytime - but you will get duplicate defintions, which is not a big problem but you might run out of memory since it does'nt erase the old versions.

Method 2: Transfer electronically

Theoretically it's possible to transfer the files via Wi-Fi or other methods.

Options:

There are also SD cards that can accept a remote connection - but reports are that these are hard to come by and they don't always work well. I would not suggest this option.

WARNINGS:

  • Only copy what you need
  • Don't copy giant files.
    • e.g. You should not copy the 16 Mbyte '!Blocks-64.bin' file.

sync

https://solhsa.com/specnext.html

Get Next Sync release. Currently this is v1.2. https://github.com/Threetwosevensixseven/specnext/releases/

Instructions are provided with Sync in the file nextsync.txt. You should install on your PC/Mac and Next in /dot/ directory as described in that text file.

  1. run python nextsync.py as explained in the text file.
  2. Run vForth from the BASIC loader (currently Forth17_load.bas)
  3. Type bye
  4. Press a key then type .sync on a new line from inside the basic program
  5. Type run to take you back to the Forth environment
  6. Now load your program, say with include dev\myfile.f`

When you want to reload you program, forget previous definitions (or use marker words) and then repeat from 3 to sync the changes from your machine.

zxnftp

See https://github.com/varmfskii/zxnext_tools - links to https://github.com/varmfskii/zxnftp

(Info to be added)

Serial - DeZog

This might be useful - but is not usually used with vForth development.

DeZog usage documentation has the basic guidance https://github.com/maziac/DeZog/blob/main/documentation/Usage.md

You can use this with either a real Spectrum Next or an emulator such as ZEsarUX and CSpect.

The details on hardware are here: https://github.com/maziac/DeZog/blob/main/documentation/Usage.md#zx-next--serial-interface

vForth-Next - a Sinclair ZX Spectrum Next Forth

Clone this wiki locally