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

Latest Forum Discussions

See All

Whitethorn Games combines two completely...
If you have ever gone fishing then you know that it is a lesson in patience, sitting around waiting for a bite that may never come. Well, that's because you have been doing it wrong, since as Whitehorn Games now demonstrates in new release Skate... | Read more »
Call of Duty Warzone is a Waiting Simula...
It's always fun when a splashy multiplayer game comes to mobile because they are few and far between, so I was excited to see the notification about Call of Duty: Warzone Mobile (finally) launching last week and wanted to try it out. As someone who... | Read more »
Albion Online introduces some massive ne...
Sandbox Interactive has announced an upcoming update to its flagship MMORPG Albion Online, containing massive updates to its existing guild Vs guild systems. Someone clearly rewatched the Helms Deep battle in Lord of the Rings and spent the next... | Read more »
Chucklefish announces launch date of the...
Chucklefish, the indie London-based team we probably all know from developing Terraria or their stint publishing Stardew Valley, has revealed the mobile release date for roguelike deck-builder Wildfrost. Developed by Gaziter and Deadpan Games, the... | Read more »
Netmarble opens pre-registration for act...
It has been close to three years since Netmarble announced they would be adapting the smash series Solo Leveling into a video game, and at last, they have announced the opening of pre-orders for Solo Leveling: Arise. [Read more] | Read more »
PUBG Mobile celebrates sixth anniversary...
For the past six years, PUBG Mobile has been one of the most popular shooters you can play in the palm of your hand, and Krafton is celebrating this milestone and many years of ups by teaming up with hit music man JVKE to create a special song for... | Read more »
ASTRA: Knights of Veda refuse to pump th...
In perhaps the most recent example of being incredibly eager, ASTRA: Knights of Veda has dropped its second collaboration with South Korean boyband Seventeen, named so as it consists of exactly thirteen members and a video collaboration with Lee... | Read more »
Collect all your cats and caterpillars a...
If you are growing tired of trying to build a town with your phone by using it as a tiny, ineffectual shover then fear no longer, as Independent Arts Software has announced the upcoming release of Construction Simulator 4, from the critically... | Read more »
Backbone complete its lineup of 2nd Gene...
With all the ports of big AAA games that have been coming to mobile, it is becoming more convenient than ever to own a good controller, and to help with this Backbone has announced the completion of their 2nd generation product lineup with their... | Read more »
Zenless Zone Zero opens entries for its...
miHoYo, aka HoYoverse, has become such a big name in mobile gaming that it's hard to believe that arguably their flagship title, Genshin Impact, is only three and a half years old. Now, they continue the road to the next title in their world, with... | Read more »

Price Scanner via MacPrices.net

B&H has Apple’s 13-inch M2 MacBook Airs o...
B&H Photo has 13″ MacBook Airs with M2 CPUs and 256GB of storage in stock and on sale for up to $150 off Apple’s new MSRP, starting at only $849. Free 1-2 day delivery is available to most US... Read more
M2 Mac minis on sale for $100-$200 off MSRP,...
B&H Photo has Apple’s M2-powered Mac minis back in stock and on sale today for $100-$200 off MSRP. Free 1-2 day shipping is available for most US addresses: – Mac mini M2/256GB SSD: $499, save $... Read more
Mac Studios with M2 Max and M2 Ultra CPUs on...
B&H Photo has standard-configuration Mac Studios with Apple’s M2 Max & Ultra CPUs in stock today and on Easter sale for $200 off MSRP. Their prices are the lowest available for these models... Read more
Deal Alert! B&H Photo has Apple’s 14-inch...
B&H Photo has new Gray and Black 14″ M3, M3 Pro, and M3 Max MacBook Pros on sale for $200-$300 off MSRP, starting at only $1399. B&H offers free 1-2 day delivery to most US addresses: – 14″ 8... Read more
Department Of Justice Sets Sights On Apple In...
NEWS – The ball has finally dropped on the big Apple. The ball (metaphorically speaking) — an antitrust lawsuit filed in the U.S. on March 21 by the Department of Justice (DOJ) — came down following... Read more
New 13-inch M3 MacBook Air on sale for $999,...
Amazon has Apple’s new 13″ M3 MacBook Air on sale for $100 off MSRP for the first time, now just $999 shipped. Shipping is free: – 13″ MacBook Air (8GB RAM/256GB SSD/Space Gray): $999 $100 off MSRP... Read more
Amazon has Apple’s 9th-generation WiFi iPads...
Amazon has Apple’s 9th generation 10.2″ WiFi iPads on sale for $80-$100 off MSRP, starting only $249. Their prices are the lowest available for new iPads anywhere: – 10″ 64GB WiFi iPad (Space Gray or... Read more
Discounted 14-inch M3 MacBook Pros with 16GB...
Apple retailer Expercom has 14″ MacBook Pros with M3 CPUs and 16GB of standard memory discounted by up to $120 off Apple’s MSRP: – 14″ M3 MacBook Pro (16GB RAM/256GB SSD): $1691.06 $108 off MSRP – 14... Read more
Clearance 15-inch M2 MacBook Airs on sale for...
B&H Photo has Apple’s 15″ MacBook Airs with M2 CPUs (8GB RAM/256GB SSD) in stock today and on clearance sale for $999 in all four colors. Free 1-2 delivery is available to most US addresses.... Read more
Clearance 13-inch M1 MacBook Airs drop to onl...
B&H has Apple’s base 13″ M1 MacBook Air (Space Gray, Silver, & Gold) in stock and on clearance sale today for $300 off MSRP, only $699. Free 1-2 day shipping is available to most addresses in... Read more

Jobs Board

Medical Assistant - Surgical Oncology- *Apple...
Medical Assistant - Surgical Oncology- Apple Hill Location: WellSpan Medical Group, York, PA Schedule: Full Time Sign-On Bonus Eligible Remote/Hybrid Regular Apply Read more
Omnichannel Associate - *Apple* Blossom Mal...
Omnichannel Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Cashier - *Apple* Blossom Mall - JCPenney (...
Cashier - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Blossom Mall Read more
Operations Associate - *Apple* Blossom Mall...
Operations Associate - Apple Blossom Mall Location:Winchester, VA, United States (https://jobs.jcp.com/jobs/location/191170/winchester-va-united-states) - Apple Read more
Business Analyst | *Apple* Pay - Banco Popu...
Business Analyst | Apple PayApply now " Apply now + Apply Now + Start applying with LinkedIn Start + Please wait Date:Mar 19, 2024 Location: San Juan-Cupey, PR Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.