Will Snook.com


TurtleForth is a dialect of Forth for interactively creating technical drawings and geometric designs using turtle graphics. You can edit this sample code and your changes will be rendered as you type.

TurtleForth Language Intro

TurtleForth is based on two main concepts, turtle graphics and Forth stack computers. The idea of turtle graphics is that instead of using cartesian coordinates to define shapes, you just give directions to a pen-carrying turtle that knows how to go forward, turn left, and turn right. If you ever had the opportunity to use Logo in school, this should be familiar.

Forth is many things to many people, but in the case of turtleForth, Forth means basic RPN calculator functionality, the ability to define "words" representing re-usable shapes, unit conversions, etc., and the ability to fit very concise code next to a live preview image. My goal in creating this was to draw floorplan from many accurate measurements, but it also turned out to be fun for drawing fractals and geometric patterns.

TurtleForth is case sensitive, and it uses postfix notation with a stack. As with other Forth dialects, things like :, 3.14, +, penDown, ;, and draw-window are "words". Words must be separated by spaces. Comments start with \ and continue until the end of the line. Word definitions look like : word ... ;. To add 1 and 1, you say 1 1 +. To go 2 units forward, you could say 2 F, 1 1 + F, or : two 1 1 + ; two F.

The following table shows turtleForth's built-in words with a short explanation for each. Some words, like traceOn, don't change the stack. Other words pop 1 or 2 operands off of the stack, and some also push 1 or 2 results back onto the stack. In the descriptions for words which pop operands, T is the number which was on top of the stack, and S is the number which was second on the stack.

\ The rest of the line is a comment
: Start defining the word whose name follows ":"
; Stop defining a word
+ Add T to S (pop 2, push 1)
- Subtract T from S (pop 2, push 1)
* Multiply T by S (pop 2, push 1)
dup Duplicate T (push 1)
drop Discard T (pop 1)
swap Swap T with S (pop 2, push 2)
over Push a copy of S (push 1)
F Move turtle forward T units (pop 1)
L Turn turtle left T degrees (pop 1)
R Turn turtle right T degrees (pop 1)
arcL Draw a circular arc with radius S units and length T degrees, curving to the left (pop 2)
arcR Draw a circular arc with radius S units and length T degrees, curving to the right (pop 2)
mark Remember the turtle's position as position number T (pop 1)
gotoMark Take turtle back to position T (pop 1)
markTemp Remember the turtle's position as temp
gotoTemp Take turtle back to the temp position
home Move turtle to its home position
penUp Lift the turtle's pen to move without making lines
penDown Lower the turtle's pen to move and make lines
scale Set canvas scaling factor to T (pop 1)
stroke Set width of the pen stroke to T (pop 1)
traceOn Start debug tracing to the console log
traceOff Stop debug tracing
NOP Do nothing, can be useful while tracing the stack

TurtleForth is intentionally not Turing Complete. It omits memory allocation, pointers, and control flow features because those things aren't necessary for making drawings. Also, keeping the language super-simple allows quick and reliable interactive rendering.

Related Reading

Turtle Forth draws inspiration from Seymour Papert's Logo, Chuck Moore's Forth stack computers, and the Hewlett Packard Company's excellent graphing calculators.

TurtleForth Source on GitHub

The source is on GitHub under the MIT license at github.com/wsnook/turtleForth.

Turtle Graphics


There are many dialects of Forth, and the modern ones tend to comply with the ANS Forth specification. ANS Forth is quite complicated, and turtleForth doesn't make any attempt to implement it. Sources which are related to Chuck Moore's versions of Forth would probably be more helpful. MicroProcessor Engineering Limited has an interesting books page, and Stephen Pelc's "Programming Forth" (available in pdf) is good.

HP Calculators

The Hewlett Packard Company's programmable calculators are great! They use Reverse Polish Notation (RPN) with a stack, as opposed to infix notation with lots of parentheses. There is a learning curve, but once you understand how RPN works, it allows you to do calculations with a minimum of keystrokes, and less potential for confusion, compared to expressions with parentheses.

The Museum of HP Calculators has a good What is RPN? page with an explanation of how to do RPN calculations on HP calculators. The concepts are similar to Forth, especially if you mentally substitute a space in Forth when an HP calculator would use the enter key.