-
Notifications
You must be signed in to change notification settings - Fork 1
02.QuickStart
This is a quick introduction to the vForth environment. The official PDF for vForth (see the link at the bottom) goes into a great amount of detail. Here we skip the details and get you going really quickly - and give you a taste of the power of vForth.
This introduction doesn’t teach you the Forth programming language - but you do not need to know Forth to use this quick-start guide. All the commands will be shown for you to type in and use. There is a link at the end to learn more about Forth itself.
See https://github.com/mattsteeldue/vforth-next/wiki/00.Home
Summary: You need to copy two directories from vForth project to Next's SD card:
- the whole "vForth" directory to C:/tools/vForth
- the dot command into C:/dot
There are also instructions for ZEsarUX emulator: https://github.com/mattsteeldue/vforth-next/wiki/05.How-to-install-vForth-Next-on-ZEsarUX-for-the-Spectrum-Next
load vForth17_loader.bas using the Spectrum Next ‘Browser’. You could also use .vforth from the Command Line - but let’s do it using the BASIC loader.
Select Y when it asks you whether to load screen #11 - this will load some extra things we need.
The spaces in the program are very important to Forth - that’s how it knows where words start and stop. Words are made up of any combination of letters, symbols and numbers. Forth uses spaces (and newlines) to separate Forth words.
There are some words which appear deceiving at first glance. An example is the word ." (‘dot-double-quote’) - which prints the text that follows - needs a space afterwards. The last double quote " at the end of the text is just a delimiter and doesn’t need a space before - but it will need one after, before the next word (if there is one).
You can use more than one line - but you cannot split the name of a word over two lines.
Here is a word that prints two stars:
: star [CHAR] * dup emit emit ;
Enter this into vForth then try running it by typing the word star on a new line.
star
This is another way to do that:
: star2 ." **" ;
Again try entering this line, then typing star2 on a new line.
star2
You load the graphics library like this:
needs graphics
That loads various graphics primitives that are interesting.
Let’s try to draw something:
100 100 50 circle
This should draw a circle on the screen - maybe over the text before on the screen.
Let’s try something else:
00 layer! key 12 layer!
When you run this the screen will change to standard Sinclair ZX Spectrum ULA mode. It will look very strange. Press a key to return back to vForth’s normal mode (Layer1,2 Timex HiRes (Enhanced ULA) mode, 512 w x 192 h pixels).
NOTE: there will be key code on the stack. Type a dot (.) to find out what key you pressed:
.
For me, I pressed enter (return), so code 13 is displayed.
. 13 ok
You can also type:
forget graphics
Which gets rid of all the graphics definitions.
Type BYE to return to BASIC. There will be a message about how to get back to vForth.
Let’s try that in BASIC - and have a warm start.
RUN
Code you type into vForth is either run immediately, or used to define a word or variable. If you define new words, they can be run by typing their name. However you will need to take extra steps to save it over a power down of your Spectrum Next.
Additionally typing definitions again and again into the computer is very annoying. Having a system to edit and reload into vForth is very important.
The three options to keep programs after power-down:
- blocks - these are 16 x 64 sized files and are stored in a special file. Blocks are fast and convenient on the Spectrum Next when doing development. Blocks can be loaded when you needed to recall a bunch of Forth code.
- files - on the Spectrum Next you can use files - and edit them on another PC. Longer term, this is a good option, but isn’t really a fast option for quickly making a Forth program.
- zap is a word that saves the entire state - you can use this when you distribute your program, application or game without needing people to load vForth first.
Theoretically you can keep your code during development in files or blocks. Editing and reloading from a block or a file is much quicker than typing the entire code in again.
Blocks are quite convenient on the Spectrum Next - and faster since the blocks file is already open.
We will use blocks in this quick-start guide.
This will show you the first line of the first 13 screens. A Screen has two Blocks.
0 13 index
Notice the numbers go BEFORE the word (in this case 'index') in Forth. (This is called reverse polish notation (RNP) or postfix notation - see https://en.wikipedia.org/wiki/Reverse_Polish_notation)
1 list will show you an introduction about Blocks and Screens.
1 list
1 is the Screen number.
Usually Screens after 11 (i.e 12) and before 100 are kept empty for your use.
Try:
12 list
The block should be blank (line numbers don't count as anything).
You need to load the block editor - this will have already been loaded if you loaded Screen 11. (You were asked at the start). If not you can type:
needs edit
We are going to write some code … let’s start at Screen 12.
Let's check it's empty first:
12 list
If you've already used block 12, then choose another empty block. You will need to replace the number 12 in the following examples with whatever you choose.
Now edit the block:
12 edit
On the first line we are going to put a description. Both parenthesis (round brackets) like ( this ) and
backslash \ like this can be used to make a comment - this tells vForth to ignore it. Remember
since ( and \ are words they need a space afterwards to work properly.
Let's put a title on the first line:
\ Make Patterns with stars
Now on the second line let's make a very simple definition. This makes one star.
: star [char] * emit ;
Now we should quit the editor using [Edit] + Q
Now list the block:
12 list
Now load the block:
12 load
Hopefully you won't have any errors. If you do please edit the block again
and check carefully. Remember spaces are very important to Forth! You need
at least one space between words. You can have more then one space - but
you require at least one space.
When you have no errors, you can try the following:
star
Our new word star, prints a star (or asterisk) on it's own.
star *ok
Now try:
cr star star star cr
This should print three stars on their own line.
The built in word cr prints on a new line. It's also called carriage return or line feed.
Blocks are edited using some buffer area, so it's a good idea to give
flush
every so often to effectively write back any modified block to SD.
Since the block is saved to the SD card in the blocks file, it will still be there after you restart the computer, or cold start vForth.
Then you can 12 load at any point to get it back.
12 load
Let's make some code to put into the block after the star word definition. Rather than type everything in, you can do each word definition (between and including the : and the ;) one at a time, and test it as we did above with star - you can use the examples below.
: stars ( n -- ) dup 0 > if 0 do star loop then ;
: starline ( n -- ) star
2 - dup 0 > if spaces else drop then
star ;
: starbox ( width height -- )
over cr stars
0 do dup cr starline loop
cr stars
;
Each time you can test it using the examples below. Remember you will need to exit from the editor using [EDIT]+Q and do a 12 load for Forth to load these definition so they are usable.
The ( n -- ) in stars and starline tells us (the humans) we need pass a number into the word, and it returns no number back. Since it's in round brackets this is a comment that vForth ignores. It's just a reminder to you what parameters it takes.
10 stars
10 starline
You must supply both of these words with a number - the size in this case - although that can be from another part of the program rather than a directly entered number.
The word starbox takes two parameters - width and height.
20 5 starbox
This draws a starbox 20 wide and 5 high.
NOTE: Starbox itself calls stars and starline to do its work.
You might have seen the warning that star, stars, starline and starbox are already defined.
New definitions of words hide older definitions - but older uses of these words still use the old versions. They do not replace the old versions.
You can forget definitions. These forget the named definition plus all later ones.
forget star
This will forget star, stars, starline, starbox. When you load you won't get the warning again ... unless you have older definitions with these names - because you've loaded the block more than once. If so you will need to forget star more than once.
12 load
You can also put a marker at the top of your block above star, stars, starline, starbox.
marker forget-stars
When you use forget-stars it restores the dictionary (where all the words are stored) to the
status before forget-stars was created. This removes forget-stars itself and all subsequent definitions. This definition allows forgetting across vocabularies since it keeps track of VOC-LINK, CURRENT, CONTEXT values.
You can use .s to check if any numbers are left over after testing a word.
.s
If you type:
1 2 3 .s
This will print
1 2 3 ok
If you type +
+
Then type .s
.s
Then it will print
1 5 ok
This is because + adds together the top two numbers on the stack - which are 2 and 3. You can call + again and see the result with .s (dot-S which actually means print stack).
The dot (or full stop) meaning print is just a convention in Forth to mean print stuff - hence . (print number), .s (print stack) and ." (print string). It's just a convention because Forth itself doesn't actually care what symbols, letters and numbers are used in the name of a word. Hence - and + are just words as well - and so is 1+ and several other strange looking words.
We haven't explained how stars, starline and starbox work. But then this quickstart quide would become a Forth introduction. The entire point was to give you a place to start with vForth so you could learn Forth and write cool Sinclair ZX Spectrum programs.
If you want to go further, you can checkout the resources below and also try the tutorial on the vForth wiki called 'Making a Classic Spectrum game'.
Each group of letters, symbols and numbers are a word. Spaces cannot be part of a word - they separate words. Numbers themselves are checked after checking for words in the dictionary.
Words themselves are defined by starting with a colon : and finishing the word with a semicolon ; where the name of the new word is after the colon. Notice: there is a space after colon, and a space before the semicolon.
Words are like functions, procedures, methods or subroutines in other programming languages. They are like a small bit of program code that runs when you use its name. Often you will define words and they will call other words - some built into vForth, others that you’ve defined yourself. This way you build your program up one word at a time, like bricks of a wall, making a building.
It’s important that you try to make these words small so you can get them working and test them properly. This is different from some other programming languages. The idea is that they are easy to test and fix (‘debug’) when they don’t work. You should test each word as you go. Sometimes you will have a word that is getting big and the data is getting hard to manage - this is a sign you need to refactor the word into multiple smaller words.
Most of this information is in the PDF document ‘vForth1.7-core-en-xxxxxx.pdf’ - find it here https://github.com/mattsteeldue/vforth-next/tree/master/doc. This is a really good introduction and reference. Coupled with the information inside https://github.com/mattsteeldue/vforth-next/wiki you have a great set of information.
You are going to need to learn Forth.
Something like https://www.forth.com/wp-content/uploads/2018/01/Starting-FORTH.pdf can teach you the beginning of Forth.
You can also get some idea from Wikipedia https://en.wikipedia.org/wiki/Forth_(programming_language)
There are lots of books on Forth. There is a collection of freely available ones here https://www.forth2020.org/books-on-forth
There is plenty of example code included in vForth itself - both in blocks, but also in the demo directory. Just read the code in there - either from your PC or from the Spectrum Next. For instance you should definitely take a look at chomp-chomp.f
Try to work out what it's going one line at a time.
Another great place to read code is in the vforth/doc/txt/!Blocks-64.bin_xxxxx.txt which contains the default code in the blocks file.
Written by Rob Probin and Matteo Vitturi, Nov 2023.
vForth-Next - a Sinclair ZX Spectrum Next Forth