TweetFollow Us on Twitter

Pocket Forth
Volume Number:5
Issue Number:4
Column Tag:Forth Forum

Pocket Forth

By örg Langowski, MacTutor Editorial Board

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

“Public Domain Pocket Forth”

Imagine: a compiler that creates applications or desk accessories from the same source code, with only a one or two line change. Impossible? Read on. That compiler will work interactively, so that you can create code as you go, typing in routine after routine and checking them out on the fly. The applications will be very small, they can be run in a 32K partition. And, of course, the code will be fast.

I’m not joking, such a development system does exist. Even more unbelievable, it’s free. It’s now been several months since I downloaded PocketForth from the GEnie Forth Roundtable, and had a lot of fun with it since then. Lately, we even received a letter requesting a review of PocketForth, so I thought this a good opportunity to introduce you to the public domain Forth for the Macintosh.

PocketForth has been written by Chris Heilman, and unfortunately all the author leaves in the documentation is his Compuserve address (70566,1474); no mail address, no phone number. Since I am not on Compuserve (can’t access from here), I wasn’t able to contact him. Therefore, Chris, when you read this: my apologies that we couldn’t warn you. I hope you’ll appreciate this review, and please contact us if you have any comments.

Although PocketForth is completely public domain - even the sources are available upon request - we’d like to have the author’s authorization before putting his system on the source code disk. We are working on it, but the Forth compiler might come on a later disk. Meanwhile, you can download the system from GEnie or Compuserve; the Stuffit file is about 150K long and contains ample documentation and examples.

PocketForth implementation

PocketForth is based on FIG-Forth and a Forth for the 68000 described in Dr. Dobb’s Journal (G. Y. Fletcher, DDJ no. 123, January 1987). It uses a 16-bit stack and base-relative addressing with 32K offset, therefore the total code size is restricted to 32K bytes. The implementation uses subroutine threading with JSRs relative to the base pointer, which is kept in A3. An example illustrates this. Our test routine simply adds 3 and 4, outputs the sum and a space:

: test 3 4 + . 32 emit ;

this compiles to

 move.w #3,-(a6) ; literal 3
 move.w #4,-(a6) ; literal 4
 jsr  $E94(a3) ; +
 jsr  $BF0(a3) ; .
 move.w #32,-(a6); literal 32 
 jsr  $9FA(a3) ; emit
 rts

As you see, the code is dependent on the correct setup of A3. PocketForth must therefore execute in a locked block of memory, which is allocated at startup. The initialization code makes all the standard calls (_MoreMasters, _InitGraf, _InitFonts, _InitWindows, _InitMenus, _InitDialogs, _TEInit, _FlushEvents, _InitCursor), gets the PocketForth main code from the resource DICT ID=257 and jumps to its beginning. DICT 257 is the PocketForth dictionary and contains the names and executable code of all the known Forth words (this is in contrast to Mach2, which creates headerless code and the names are kept in a separate vocabulary). The DICT resource is locked, so that the block won’t move while PocketForth is executing. The startup sequence sets A3 to point to the beginning of the DICT block, initializes stack pointers and other things, and enters the Forth interpreter.

The PocketForth Dictionary

PocketForth dictionary entries have a header consisting of a name field and a link field. The name field is 4 bytes long, the first byte containing the name length, and the next three bytes the first three characters of the name. This means that the words compile and compute will have the same dictionary entry (caution!). The upper bit of the name field’s first byte is the immediate bit; when set, it indicates an immediate execution word. The link field, after the name field, is 2 bytes long and points to the previous dictionary entry. The link field is followed by the definition’s executable code.

Applications vs. desk accessories

You might have already guessed why PocketForth separates the setup code and the DICT resource. This way, application and DA ‘shells’ can be made that set up the environment so that the Forth code in the dictionary can be executed without making big changes between the two versions.

The shell is a dumb terminal window with an Apple, File and Edit menu. The window will accept keyboard input, which is interpreted by the Forth system. Files can be loaded with the word -->, and they will be normal text files, no block file business here. Text pasted from the clipboard will be interpreted just like keyboard input.

The application and the DA look exactly the same, and behave almost exactly the same. Forth code that creates a turnkey application will, if done correctly, create a ‘turnkey DA’ with only minor changes. This is achieved by accessing PocketForth’s system variables through a table using the word +md, which adds the offset of a ‘Mac Data’ block to the top of stack. This block is located at different positions in the application and the DA, and using +md lets you access the system variables transparently.

Examples of the variables pointed to by +md are the main window pointer, vectors to activate, update and mousedown handlers, a vector to an idle routine which is run once on each pass through the event loop (for the APPL) or when the accRun message is received (for the DA). The +md data block also contains an event table, which is a jump table to the event handlers for event types 0 to 15 (APPL) or 0 to 8 (DA). To change default event handling one installs new vectors in this table.

The Example

I rewrote one example from Palo Alto Shipping’s source code disk in PocketForth (Listing 1) to show you some of the techniques used in this Forth implementation. First, we have to redefine a couple of useful Mach2 words which are not present in PocketForth. pick and roll, 16-bit versions of the corresponding Mach2 words, are implemented in 68000 code. PocketForth has no assembler, but can compile 16-bit hex constants inline using the word ,$.

Toolbox access is also done using inline code. Before calling the trap, we must set up the A7 stack; like Mach2, PocketForth uses A6 for the parameter stack and A7 for the return stack. The words >r, 2>r, r> and 2r> are provided for moving 16- and 32- bit quantities to and from the A7 stack. Addresses of PocketForth variables and words are always 16-bit relative to the start of the dictionary, before calling a trap they must be converted to 32-bit absolute addresses with >abs.

The central part of the example is pretty standard Forth; PocketForth has no local variables, so we have to dup swap drip flip flop a little more than usual.

The last part of the example sets up the PocketForth system to start up automatically with the example program, saves the changes to the dictionary and quits. Make sure you have made a backup before you execute the example, the changes are irreversible. The way we make PocketForth run our program on startup is through the activate handler. We install a new activate vector in the event table which will execute our program’s start sequence on the first activate event; thereafter activate events will be ignored. The start sequence calls the word reflect which installs a vector to an idle routine that does the graphical display, and disables keyboard input by storing the null event vector at the keydown position of the event table. In order to execute the idle routine, the DA has to have the accRun flag set in its header. The correct value for the drvrFlags is $6400; change with ResEdit if necessary.

Chris Heilman gives another method to patch the Forth system with an autostart vector. He patches a JMP instruction into the initialization code in the dictionary. However, I was not able to find the correct patch position for the desk accessory, so I used the method I just described, which works for APPL and DA in the same way.

Speed

No review is complete without the results of the Sieve benchmark (Listing 2), so I’ll give them to you: 3.3 seconds for ten iterations of the standard benchmark (1899 primes). MacForth Plus takes the same time, 3.3 seconds, while Mach2 takes 1.9 seconds; therefore PocketForth compares very well with the two major Macintosh Forth systems. Note in the code that the word to access the loop index is r, not i as in the other Forths.

Summary

PocketForth comes in a 150K Stuffit file that contains: the application, the desk accessory, a demo application that has been created under PocketForth, source code for that demo and various other examples, including a floating point package, a mini-paint program and the Sieve benchmark. A manual and a glossary of Forth words is also contained in the package.

PocketForth has been designed to create compact applications and DAs; the maximum code size is restricted to 32K, anyway. However, it is amazing what can be done in so little space, given the compactness of Forth code; each routine call requires only 4 bytes. The example application is only 9K long, including bundle, menu and window resources, and the corresponding desk accessory takes only 8K. You can decrease the application’s partition size in Multifinder down to 32k without any problems.

PocketForth has its limitations, of course: restricted maximum size, few utilities, no built-in editor (I used McSink when I wrote this). There is no assembler, and I used the Mach2 assembler to write the machine code words. Well, there must be something that makes it worth paying for Mach2 or MacForth, I guess if you have a major project in Forth, you have to get a full development system, of course. But for creating ‘instant’ desk accessories, or small applications, or for just fumbling around with the machine and producing interesting hacks (or bombs, for that matter), PocketForth is just the ideal system.

Listing 1: ‘Reflections’ demo rewritten for Pocket Forth

( Reflections demo from Mach2 demo disk; rewritten )
( for PocketForth v.3 )
( J. Langowski / MacTutor Feb. 1988 )

( Compile this demo with a COPY of Pocket Forth or the )
( Pocket Forth DA; the dictionary will be irreversibly )
( changed to create a turnkey application / DA. )

( Note that the change required to compile this example ) 
( with the DA version consists only of a 1 line deletion; )
( see at the bottom of the listing. )

forget task
: task ;

: pick ( n -- dup stack item n levels down )
        ,$ 301E ( move.w [a6]+,d0)
        ,$ E380 ( asl.l  #1,d0 )
        ,$ 3D36 ,$ 0 ( move.w [a6,d0.w],-[a6] )
;

: roll ( n -- move up stack item n levels down )
        ,$ 2F02  (     move.l d2,-[a7] )
        ,$ 301E  (     move.w [a6]+,d0 )
        ,$ 6F16  (     ble.s   @1 )
        ,$ 5380  (     subq.l  #1,d0 )
        ,$ 3200  (     move.w  d0,d1 )
        ,$ 3F1E  ( @2  move.w [a6]+,-[a7] )
        ,$ 51C8
        ,$ FFFC  (     dbf     d0,@2 )
        ,$ 341E  (     move.w  [a6]+,d2 )
        ,$ 3D1F  ( @3  move.w  [a7]+,-[a6] )
        ,$ 51C9
        ,$ FFFC  (     dbf     d1,@3 )
        ,$ 3D02  (     move.w  d2,-[a6] )
        ,$ 241F  (     move.l  [a7]+,d2 )
;                ( @1  rts )

: range ( value lo hi -- flag ) 
        2 pick <  rot rot < or 0=
;         

: 4dup ( n1 n2 n3 n4 - n1 n2 n3 n4 n1 n2 n3 n4 )
 3 pick 3 pick 3 pick 3 pick 
;

4 +md constant wrect ( Pocket Forth main window )

2variable myport
: getport >abs 2>r ,$ A874 ; ( _GetPort )
: setport 2@ 2>r ,$ A873 ; ( _SetPort )
: cls wrect >abs 2>r ,$ A8A3 ; ( _EraseRect )

( QuickDraw Equates )
hex
8      constant PatCopy
B      constant PatBic
10     constant PortRect
decimal

( Window Size Variables )
variable        WTop
variable        WLeft
variable        WBottom
variable        WRight
variable        WWidth
variable        WHeight

( Positions     Velocities )
variable xx1    variable xx1dot
variable yy1    variable yy1dot
variable xx2    variable xx2dot
variable yy2    variable yy2dot

: GetWCoords ( -- )
        wrect       @  WTop    !
        wrect 2+    @  WLeft   !
        wrect 4 +   @  WBottom !
        wrect 6 +   @  WRight  !

        ( Calculate the current window width and height. )
        WBottom @ WTop  @ - WHeight !
        WRight  @ WLeft @ - WWidth  !  
;

( Erase the window and set the initial pen positions and velocities. 
)
: SetupReflect (  -  )
        cls
        GetWCoords
        WWidth  @ 3 /    xx1 !   3 xx1dot !
        WHeight @        yy1 !  -4 yy1dot !
        WWidth  @ 3 / 2* xx2 !   4 xx2dot !
        WHeight @        yy2 !  -3 yy2dot ! ;

( Draws a newline and leaves coords on stack. )
: NewCoords ( -- xx1 yy1 xx2 yy2 )
        ( Increment the line position. )
        xx1dot @ xx1 +!
        yy1dot @ yy1 +!
        xx2dot @ xx2 +!
        yy2dot @ yy2 +!

        xx1 @ 1 WWidth @ range 0=
        if xx1dot @ negate xx1dot ! then

        yy1 @ 1 WHeight @ range 0=
        if yy1dot @ negate yy1dot ! then

        xx2 @ 1 WWidth @ range 0=
        if xx2dot @ negate xx2dot ! then

        yy2 @ 1 WHeight @ range 0=
        if yy2dot @ negate yy2dot ! then 

        xx1 @ yy1 @ xx2 @ yy2 @
;

( Leaves 40 coordinate pairs on the stack and draws the 1st ten lines. 
)
: First20Lines (  -  )
        20 0 do
                PatCopy >r ,$ A89C ( _PenMode )
                NewCoords 4dup
                !pen -to
        loop ;

20 +md constant idlevector
: LinesAdvance (  -  )
                PatCopy >r ,$ A89C ( _PenMode )
                NewCoords 4dup
                !pen -to

                83 roll 83 roll 83 roll 83 roll
                PatBic >r ,$ A89C ( _PenMode ) 
                        ( and white out the n-21st line)
                !pen -to
;

‘ LinesAdvance constant LAdv

12 +md constant actVect
actVect @ constant actDefault

24 +md constant nullevent
nullevent 6 + constant keyvector
nullevent @ constant rien

: Reflect (  -  )
        SetUpReflect
        First20Lines cls
        LAdv idlevector !
        rien keyvector !  ;

variable flag  1 flag !
: start drop ( act/deact flag) 
        cls
        flag @ if 
                reflect 0 flag !
                begin ?terminal drop again
                ( leave out in DA version )
        then  ;
‘ start actvect !   
 save   ( CAUTION: changes dictionary irreversibly )

: bye ,$ A9F4 ( _ExitToShell )  ; bye

Listing 2: Sieve benchmark for PocketForth

( © Chris Heilman )
( Sleeve of Erastothanes )
( optomized for Pocket Forth with inline machine code )
9000 room - grow  ( provide for 9000 dictionary bytes )
forget task : TASK ;  decimal

( timer )
: START ( -- d ) 362 0 dl@ ;  ( get ‘ticks’ )
: T. ( sec -- ) s>d <# # 46 hold #S #> type ;  ( print sec.tenths )
: STOP ( d -- ) start 2swap dnegate d+ drop  6 / t. .” Seconds” ;

8190 constant SIZE
variable FLAGS size allot

( compile these 2 byte words inline )
: [DUP] ( n -- n n ) [ ‘ dup @ literal ] , ; 
 IMMEDIATE  ( equal to:  dup )
: [DROP] ( n -- ) [ ‘ drop @ literal ] , ; 
 IMMEDIATE  ( equal to:  drop )
: [1+] ( n -- n+1 ) [ ‘ 1+ @ literal ] , ; 
 IMMEDIATE  ( equal to:  1+ )

( compile machine code inline routines )
: R+ ( n -- n+r ) 12311 , 53590 , ; 
 IMMEDIATE  ( equal to:  r + )
: 0RC! ( -- ) 12311 , 16947 , 0 , ; 
 IMMEDIATE  ( equal to:  0 r c! )

: PRIME  flags size 1 fill
    0 size 0 DO
      flags r+ c@ IF
        3 r+ r+ [dup] r+ size < IF
          size flags + over r+ flags +
          DO  0rc! [dup]  +LOOP
        THEN [drop] [1+]
      THEN
    LOOP . .” primes” cr ;

: SIEVE  page  .”        The Sieve of Erastothanes” decimal
    cr  start  10 0 DO prime LOOP  beep
    cr  stop  cr .” Not too shabby, eh?”  cr ;

sieve

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

BusyCal 3.7.2 - Powerful calendar app wi...
BusyCal is the powerful, flexible, reliable calendar app for macOS. It's packed with time-saving features and compatible with all leading cloud services including iCloud, Google, Exchange and more.... Read more
BusyContacts 1.4.2 - Fast, efficient con...
BusyContacts is a contact manager for OS X that makes creating, finding, and managing contacts faster and more efficient. It brings to contact management the same power, flexibility, and sharing... Read more
iShowU Instant 1.3.0 - Full-featured scr...
iShowU Instant gives you real-time screen recording like you've never seen before! It is the fastest, most feature-filled real-time screen capture tool from shinywhitebox yet. All of the features you... Read more
Capo 3.8 - Slow down and learn to play y...
Capo lets you slow down your favorite songs so you can hear the notes and learn how they are played. With Capo, you can quickly tab out your songs atop a highly-detailed OpenCL-powered spectrogram... Read more
Viber 11.7.0 - Send messages and make fr...
Viber lets you send free messages and make free calls to other Viber users, on any device and network, in any country! Viber syncs your contacts, messages and call history with your mobile device, so... Read more
Drive Genius 5.3.1 - $79.00
Drive Genius features a comprehensive Malware Scan. Automate your malware protection. Protect your investment from any threat. The Malware Scan is part of the automated DrivePulse utility. DrivePulse... Read more
CorelDRAW 21.2.0.708 - Graphic design so...
CorelDRAW - professional graphic design software for vector illustration, layout, and so much more. Get started quickly and easily with a wealth of intuitive tools, built-in learning materials,... Read more
Navicat Premium Essentials 12.1.27 - Pro...
Navicat Premium Essentials is a compact version of Navicat which provides basic and necessary features you will need to perform simple administration on a database. It supports the latest features... Read more
OmniFocus 3.4.3 - GTD task manager with...
OmniFocus is an organizer app. It uses projects to organize tasks naturally, and then add tags to organize across projects. Easily enter tasks when you’re on the go, and process them when you have... Read more
Microsoft OneNote 16.30 - Free digital n...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more

Latest Forum Discussions

See All

Upcoming mobile MMO TeeTINY Online’s sec...
TeeTINY Online is an upcoming anime-themed MMO which boasts striking visuals and an ambitious open world to explore. Following a successful CBT (closed beta test) on Android, developer TEENY.studio has now released a follow-up test which adds an... | Read more »
Breakout: Dark Prison is a fast-paced ac...
Breakout: Dark Prison is an action RPG from LaterSoft. Set in the aftermath of a deadly virus outbreak your daughter has been taken from you because she has an immunity to the illness in her DNA. Not being a fan of experimentation on children –... | Read more »
Apple Arcade in review
This weekend, Apple Arcade will officially be one month old. That means anyone who signed up for the free trial on day one has a decision to make: Stick with the service and shell out $5 a month, or cancel and go about your merry way. | Read more »
Alluris is a choose-your-own adventure g...
Alluris is an RPG that the developer's are calling a swipe-your-own adventure game. This is because the game incorporates a Reigns-style - swiping left or right - selection mechanic to make all the decisions you'd usually expect to make across... | Read more »
Hello Hero All Stars receives update wit...
The first Hello Hero game hit global platforms in 2013 and proved a huge success, with developer Fincon adding two more entries to this popular series of casual RPG games since. Released in June this year, Hello Hero All Stars brings many of the... | Read more »
Zombieland: Double Tapper, a cartoon idl...
Zombieland: Double Tapper is the idle RPG tie-in to the upcoming Zombieland: Double Tap. Oddly, it's one of two different Zombieland games launching today, with the other being the Switch title Zombieland: Double Tap - Road Trip. [Read more] | Read more »
Rusty Lake's The White Door launche...
Rusty Lake and Second Maze's intriguing point-and-click adventure game, The White Door, is now up for pre-order on the App Store. This one sees you playing as Robert Hill, a mental health patient who is suffering from severe memory loss. The game... | Read more »
Hellrule is an auto-runner inspired by G...
Hellrule is an upcoming auto-runner game from independent developer Pedrocorp where players will take control of a dapperly dressed gentlemen who comes equipped with a razor-sharp umbrella for slicing up his foes. The game will be available for... | Read more »
Grobo is a gravity bending puzzle platfo...
Grobo is a 2D puzzle platformer that marks the first release from developers Hot Chocolate Games. You'll find yourself manipulating gravity as you make your through this title that's available now for iOS and Android. [Read more] | Read more »
Adrenaline, Compulsive Entertainment’s h...
Compulsive Entertainment’s high-octane arcade racer, Adrenaline, has now made its way to the App Store following a successful launch on Google Play. It’s a ton of challenging, fast-paced fun, boasting easy-to-learn controls and a varied selection... | Read more »

Price Scanner via MacPrices.net

11″ WiFi iPad Pros on sale today for up to $2...
Amazon has new 2018 Apple 11″ WiFi iPad Pros in stock today and on sale for up to $250 off Apple’s MSRP. These are the same iPad Pros sold by Apple in its retail and online stores. Be sure to select... Read more
Apple offers clearance 2018 15″ 6-Core MacBoo...
Apple has clearance 2018 15″ 6-Core Touch Bar MacBook Pros, Certified Refurbished, available starting at only $1999. Each model features a new outer case, shipping is free, and an Apple 1-year... Read more
Apple continues to offer refurbished 2019 21″...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Verizon offers free iPhone 7 for customers wh...
Verizon is offering a free 32GB iPhone 7 for new or existing customers who open a new line of service, no trade-in required. Cost of the phone is credited to your account monthly for 24 months. The... Read more
13″ 2.4GHz 4-Core MacBook Pros remain availab...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
Lease one iPhone Xs, Xr, or X at Sprint and g...
Purchase an Apple iPhone X, Xr, Xs, or Xs Max at Sprint, and get a 64GB iPhone Xr for free. Requires 2 new lines or 1 upgrade-eligible line and 1 new line. The fine print: “iPhone Xs (64 GB) $37.50/... Read more
How to use your Apple Education discount to s...
Purchase a new MacBook Pro or MacBook Air using Apple’s Education discount, and take up to $200 off MSRP. All teachers, students, and staff of any educational institution with a .edu email address... Read more
Base 2019 13″ 1.4GHz 4-Core MacBook Pro on sa...
Amazon has the new 2019 13″ 1.4GHz/128GB 4-Core Space Gray Touch Bar MacBook Pro on sale for $100 off Apple’s MSRP. This is the same MacBook Pro sold by Apple in its retail and online stores: – 2019... Read more
Save up to $30 on Apple’s AirPods at these re...
Amazon is offering discounts on new 2019 Apple AirPods ranging up to $30 off MSRP. Shipping is free: – AirPods with Charging Case: $144 $15 off MSRP – AirPods with Wireless Charging Case: $169 $30... Read more
Save $15 on Apple Watch Series 5 models on Wa...
Walmart has new Apple Watch Series 5 models on sale for $15 off Apple’s MSRP on their online store. Choose free shipping or free local store pickup (if available). Sale prices for online orders only... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**734688BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Location Number:** 000297-Reston-Store **Job Description:** The Core Read more
Best Buy *Apple* Computing Master - Best Bu...
**738529BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Location Number:** 000258-Lewisville-Store **Job Description:** **What does a Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**741888BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Location Number:** 000870-N Scottsdale-Store **Job Description:** At Best Buy, Read more
*Apple* Mobile App Developer - eiWorkflow So...
…eiWorkflow Solutions, LLC is currently looking for a consultant for the following role. Apple Mobile App Developer Tasks the role will be performing: ? Mobile App Read more
Essbase Developer - *Apple* - Theorem, LLC...
Job Summary Apple is seeking an experienced, detail-minded Essbase developer to join our worldwide business development and strategy team. If you are someone who Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.