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

A Better Finder Rename 10.00b1 - File, p...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
CrossOver 14.1.6 - Run Windows apps on y...
CrossOver can get your Windows productivity applications and PC games up and running on your Mac quickly and easily. CrossOver runs the Windows software that you need on Mac at home, in the office,... Read more
Printopia 2.1.14 - Share Mac printers wi...
Run Printopia on your Mac to share its printers to any capable iPhone, iPad or iPod Touch. Printopia will also add virtual printers, allowing you to save print-outs to your Mac and send to apps.... Read more
Google Drive 1.24 - File backup and shar...
Google Drive is a place where you can create, share, collaborate, and keep all of your stuff. Whether you're working with a friend on a joint research project, planning a wedding with your fiancé, or... Read more
Chromium 45.0.2454.85 - Fast and stable...
Chromium is an open-source browser project that aims to build a safer, faster, and more stable way for all Internet users to experience the web. Version 45.0.2454.85: Note: Does not contain the "... Read more
OmniFocus 2.2.5 - GTD task manager with...
OmniFocus helps you manage your tasks the way that you want, freeing you to focus your attention on the things that matter to you most. Capturing tasks and ideas is always a keyboard shortcut away in... Read more
iFFmpeg 5.7.1 - Convert multimedia files...
iFFmpeg is a graphical front-end for FFmpeg, a command-line tool used to convert multimedia files between formats. The command line instructions can be very hard to master/understand, so iFFmpeg does... Read more
VOX 2.6 - Music player that supports man...
VOX is a beautiful music player that supports many filetypes. The beauty is in its simplicity, yet behind the minimal exterior lies a powerful music player with a ton of features and support for all... Read more
Box Sync 4.0.6567 - Online synchronizati...
Box Sync gives you a hard-drive in the Cloud for online storage. Note: You must first sign up to use Box. What if the files you need are on your laptop -- but you're on the road with your iPhone? No... Read more
Carbon Copy Cloner 4.1.4 - Easy-to-use b...
Carbon Copy Cloner backups are better than ordinary backups. Suppose the unthinkable happens while you're under deadline to finish a project: your Mac is unresponsive and all you hear is an ominous,... Read more

You Can Play Madfinger Games' Unkil...
Madfinger Games - probably best known for the Dead Trigger series - has officially launched their newest zombie shooter (that isn't called Dead Trigger), named Unkilled. [Read more] | Read more »
KORG iELECTRIBE for iPhone (Music)
KORG iELECTRIBE for iPhone 1.0.1 Device: iOS iPhone Category: Music Price: $9.99, Version: 1.0.1 (iTunes) Description: ** 50% OFF Special Launch Sale - For a Limited Time **The ELECTRIBE reborn in an even smaller form A full-fledged... | Read more »
I am Bread (Games)
I am Bread 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ‘I am Bread’ is the latest quirky adventure from the creators of 'Surgeon Simulator', Bossa Studios. This isn't the best thing... | Read more »
Rock(s) Rider - HD Edition (Games)
Rock(s) Rider - HD Edition 1.0.0 Device: iOS Universal Category: Games Price: $2.99, Version: 1.0.0 (iTunes) Description: *** PLEASE NOTE: Compatible with iPhone 4s, iPad 2, iPad mini, iPod touch (5th generation) or newer *** Do you... | Read more »
Rebuild 3: Gangs of Deadsville (Games)
Rebuild 3: Gangs of Deadsville 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: It's been a few years since the zombpocalypse turned the world's cities into graveyards and sent the few... | Read more »
Power Ping Pong (Games)
Power Ping Pong 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Do you wield your bat with zen-like focus or do your balls of fury give you a killer spin? Table tennis goes mobile with a... | Read more »
Z.O.N.A Project X (Games)
Z.O.N.A Project X 1.00 Device: iOS Universal Category: Games Price: $1.99, Version: 1.00 (iTunes) Description: Z.O.N.A Project X - shooter in the post-apocalyptic world. | Read more »
Trick Shot (Games)
Trick Shot 1.0.6 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.6 (iTunes) Description: A game where all you have to do is throw a ball into a box, simple? Trick Shot is a minimalist physics puzzler with 90 levels... | Read more »
VoxelCity (Games)
VoxelCity 1.0.2 Device: iOS Universal Category: Games Price: $1.99, Version: 1.0.2 (iTunes) Description: Looking for a new city builder? Tired of social media anti-games with no strategy? Look no further! NO IAP EVER! VoxelCity is a... | Read more »
Goat Simulator MMO Simulator (Games)
Goat Simulator MMO Simulator 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: ** IMPORTANT - SUPPORTED DEVICESiPhone 4S, iPad 2, iPod Touch 5 or better.** Coffee Stain Studios brings next-gen... | Read more »

Price Scanner via MacPrices.net

Near-Office Input Functionality Virtually Any...
Today Logitech introduced the Logitech K380 Multi-Device Bluetooth Keyboard and the Logitech M535 Bluetooth Mouse, giving users the freedom to work on any device, most anywhere. According to... Read more
College Student Deals: Additional $100 off Ma...
Take an additional $100 off all MacBooks and iMacs at Best Buy Online with their College Students Deals Savings, valid through September 4, 2015. Anyone with a valid .EDU email address can take... Read more
Will You Buy An iPad Pro? – The ‘Book Mystiqu...
It looks like we may not have to wait much longer to see what finally materializes as a new, larger-panel iPad (Pro/Plus?) Usually reliable Apple product prognosticator KGI Securities analyst Ming-... Read more
eFileCabinet Announces SMB Document Managemen...
Electronic document management (EDM) eFileCabinet, Inc., a hosted solutions provider for small to medium businesses, has announced that its SecureDrawer and eFileCabinet Online services will be... Read more
WaterField Designs Unveils American-Made, All...
San Francisco’s WaterField Designs today unveiled their all-leather Cozmo 2.0 — an elegant attach laptop bag with carefully-designed features to suit any business environment. The Cozmo 2.0 is... Read more
Apple’s 2015 Back to School promotion: Free B...
Purchase a new Mac or iPad at The Apple Store for Education and take up to $300 off MSRP. All teachers, students, and staff of any educational institution qualify for the discount. Shipping is free,... Read more
128GB MacBook Airs on sale for $100 off MSRP,...
B&H Photo has 11″ & 13″ MacBook Airs with 128GB SSDs on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 11″ 1.6GHz/128GB MacBook Air: $799.99, $100 off MSRP... Read more
13-inch 2.5GHz MacBook Pro (refurbished) avai...
The Apple Store has Apple Certified Refurbished 13″ 2.5GHz MacBook Pros available for $829, or $270 off the cost of new models. Apple’s one-year warranty is standard, and shipping is free: - 13″ 2.... Read more
27-inch 3.2GHz iMac on sale for $1679, save $...
B&H Photo has the 27″ 3.2GHz iMac on sale for $1679.99 including free shipping plus NY sales tax only. Their price is $120 off MSRP. Read more
Apple and Cisco Partner to Deliver Fast-Lane...
Apple and Cisco have announced a partnership to create a “fast lane” for iOS business users by optimizing Cisco networks for iOS devices and apps. The alliance integrates iPhone with Cisco enterprise... Read more

Jobs Board

*Apple* Desktop Analyst - KDS Staffing (Unit...
…field and consistent professional recruiting achievement. Job Description: Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Read more
Simply Mac *Apple* Specialist- Repair Techn...
Simply Mac is the greatest premier retailer of Apple products expertise in North America. We're looking for dedicated individuals to provide personalized service and Read more
Simply Mac *Apple* Specialist- Service Repa...
Simply Mac is the greatest premier retailer of Apple products expertise in North America. We're looking for dedicated individuals to provide personalized service and Read more
*Apple* Desktop Analyst - KDS Staffing (Unit...
…field and consistent professional recruiting achievement. Job Description: Title: Apple Desktop AnalystPosition Type: Full-time PermanentLocation: White Plains, NYHot Read more
Simply Mac- *Apple* Specialist- Store Manag...
Simply Mac is the largest premier retailer for Apple products and solutions. We're looking for dedicated individuals with a passion to simplify and enhance the Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.