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

Vivaldi 1.0.118.19 - Lightweight browser...
Vivaldi browser. In 1994, two programmers started working on a web browser. Our idea was to make a really fast browser, capable of running on limited hardware, keeping in mind that users are... Read more
Stacks 2.6.11 - New way to create pages...
Stacks is a new way to create pages in RapidWeaver. It's a plugin designed to combine drag-and-drop simplicity with the power of fluid layout. Features: Fluid Layout: Stacks lets you build pages... Read more
xScope 4.1.3 - Onscreen graphic measurem...
xScope is powerful set of tools that are ideal for measuring, inspecting, and testing on-screen graphics and layouts. Its tools float above your desktop windows and can be accessed via a toolbar,... Read more
Cyberduck 4.7 - FTP and SFTP browser. (F...
Cyberduck is a robust FTP/FTP-TLS/SFTP browser for the Mac whose lack of visual clutter and cleverly intuitive features make it easy to use. Support for external editors and system technologies such... Read more
Labels & Addresses 1.7 - Powerful la...
Labels & Addresses is a home and office tool for printing all sorts of labels, envelopes, inventory labels, and price tags. Merge-printing capability makes the program a great tool for holiday... Read more
teleport 1.2.1 - Use one mouse/keyboard...
teleport is a simple utility to let you use one single mouse and keyboard to control several of your Macs. Simply reach the edge of your screen, and your mouse teleports to your other Mac! The... Read more
Apple iMovie 10.0.8 - Edit personal vide...
With an all-new design, Apple iMovie lets you enjoy your videos like never before. Browse your clips more easily, instantly share your favorite moments, and create beautiful HD movies and Hollywood-... Read more
Box Sync 4.0.6233 - 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
Fantastical 2.0.3 - Create calendar even...
Fantastical 2 is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
The Hit List 1.1.14 - Advanced reminder...
The Hit List manages the daily chaos of your modern life. It's easy to learn - it's as easy as making lists. And it's powerful enough to let you plan, then forget, then act when the time is right.... Read more

SoundHound + LiveLyrics is Making its De...
SoundHound Inc. has announced that SoundHound + LiveLyrics, will be one of the first third-party apps to hit the Apple Watch. With  SoundHound you'll be able to tap on your watch and have the app recognize the music you are listening to, then have... | Read more »
Adobe Joins the Apple Watch Lineup With...
A whole tidal wave of apps are headed for the Apple Watch, and Adobe has joined in with 3 new ways to enhance your creativity and collaborate with others. The watch apps pair with iPad/iPhone apps to give you total control over your Adobe projects... | Read more »
Z Steel Soldiers, Sequel to Kavcom'...
Kavcom has released Z Steel Soldiers, which continues the story of the comedic RTS originally created by the Bitmap Brothers. [Read more] | Read more »
Seene Lets You Create 3D Images With You...
Seene, by Obvious Engineering, is a 3D capture app that's meant to allow you to create visually stunning 3D images with a tap of your finger, and then share them as a 3D photo, video or gif. [Read more] | Read more »
Lost Within - Tips, Tricks, and Strategi...
Have you just downloaded Lost Within and are you in need of a guiding hand? While it’s not the toughest of games out there you might still want some helpful tips to get you started. [Read more] | Read more »
Entertain Your Pet With Your Watch With...
The Petcube Camera is a device that lets you use live video to check in on your pet, talk to them, and play with them using a laser pointer - all while you're away. And the Petcube app is coming to the Apple Watch, so you'll be able to hang out with... | Read more »
Now You Can Manage Your Line2 Calls With...
You'll be able to get your Line2 cloud phone service on the Apple Watch very soon. The watch app can send and receive messages using hands-free voice dictation, or by selecting from a list of provided responses. [Read more] | Read more »
R.B.I. Baseball 15 (Games)
R.B.I. Baseball 15 1.01 Device: iOS Universal Category: Games Price: $4.99, Version: 1.01 (iTunes) Description: The legendary Major League Baseball franchise returns to the diamond. Make History. ** ALL iPOD Touch, the iPad 2 and the... | Read more »
Here's How You Can Tell if an App W...
The Apple Watch is pretty much here, and that means a whole lot of compatible apps and games are going to be updated or released onto the App Store. That's okay though, beacause Apple has quietly updated their app description pages to make things... | Read more »
Forgotten Memories : Alternate Realities...
Forgotten Memories : Alternate Realities 1.0.1 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0.1 (iTunes) Description: + REDUCED PRICE ONLY THE LAUNCHING WEEK + "The most exciting horror game of 2015." - AppSpy... | Read more »

Price Scanner via MacPrices.net

Intel Compute Stick: A New Mini-Computing For...
The Intel Compute Stick, a new pocket-sized computer based on a quad-core Intel Atom processor running Windows 8.1 with Bing, is available now through Intel Authorized Dealers across much of the... Read more
Heal to Launch First One-Touch House Call Doc...
Santa Monica, California based Heal, a pioneer in on-demand personal health care services — will offer the first one-touch, on-demand house call doctor app for the Apple Watch. Heal’s Watch app,... Read more
Mac Notebooks: Avoiding MagSafe Power Adapter...
Apple Support says proper usage, care, and maintenance of Your Mac notebook’s MagSafe power adapter can substantially increase the the adapter’s service life. Of course, MagSafe itself is an Apple... Read more
12″ Retina MacBook In Shootout With Air And P...
BareFeats’ rob-ART morgan has posted another comparison of the 12″ MacBook with other Mac laptops, noting that the general goodness of all Mac laptops can make which one to purchase a tough decision... Read more
FileMaker Go for iPad and iPhone: Over 1.5 Mi...
FileMaker has announced that its FileMaker Go for iPad and iPhone app has surpassed 1.5 million downloads from the iTunes App Store. The milestone confirms the continued popularity of the FileMaker... Read more
Sale! 13-inch 2.7GHz Retina MacBook Pro for $...
 Best Buy has the new 2015 13″ 2.7GHz/128GB Retina MacBook Pro on sale for $1099 – $200 off MSRP. Choose free shipping or free local store pickup (if available). Price for online orders only, in-... Read more
Minimalist MacBook Confirms Death of Steve Jo...
ReadWrite’s Adriana Lee has posted a eulogy for the “Digital Hub” concept Steve Jobs first proposed back in 2001, declaring the new 12-inch MacBook with its single, over-subscribed USB-C port to be... Read more
13-inch 2.7GHz Retina MacBook Pro for $1234 w...
Adorama has the 13″ 2.7GHz/128GB Retina MacBook Pro in stock for $1234.99 ($65 off MSRP) including free shipping plus a free LG external DVD/CD optical drive. Adorama charges sales tax in NY & NJ... Read more
13-inch 2.5GHz MacBook Pro available for $999...
 Adorama has the 13-inch 2.5GHz MacBook Pro on sale for $999 including free shipping plus NY & NJ sales tax only. Their price is $100 off MSRP. Read more
Save up to $600 with Apple refurbished Mac Pr...
The Apple Store is offering Apple Certified Refurbished Mac Pros for up to $600 off the cost of new models. An Apple one-year warranty is included with each Mac Pro, and shipping is free. The... Read more

Jobs Board

*Apple* Retail - Multiple Positions (US) - A...
Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Watch SW Application Project Manager...
**Job Summary** The Apple Watch software team is looking for an Application Engineering Project Manager to work on new projects for Apple . The successful candidate Read more
Map Services Frameworks Manager - *Apple* M...
Job Description: Apple 's Maps Evaluation Organization is seeking a Senior Manager to lead the Map services assertions and performance frameworks group. Key Read more
Shuttle Driver - APPLE EAST, APPLE EAST (Unit...
HERE WE GROW AGAIN!! We are adding to our team! Red Lion Chevrolet of Apple Automotive is growing and we are looking for a PART TIME SHUTTLE DRIVER/ PORTER FOR SERVICE Read more
*Apple* Retail - Multiple Positions (US) - A...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.