TURTLE.md

Turtles App API (Application Programming Interface)

Basics

• At the beginning, only one turtle whose name is :trinity (don't omit : (colon), it is a Clojure keyword) will show up at the home position (center). This turtle, :trinity, can move forward/backward, change head angle clockwise/counterclockwise.

• More turtles can be added, each with its own name.

• Each turtle can move independently giving a command with its name. If only :trinity is there, you don't need to give the name to commands.

Movement

A turtle can move in response to commands. When a turtle moves, it leaves a trail. You can move turtles, change their colors, and get neat drawings this way.

All parameters to forward, backward, right, and left commands are relative to the current position or angle. The command may be given the name of the turtle. Without the name they would refer to the only turtle on the canvas.

command	description
(forward length) (forward name length)	moves the turtle forward by length.
(backward length) (backward name length)	moves the turtle backward by length.
(right angle) (right name angle)	changes the turtle head by degrees clockwise.
(left angle) (left name angle)	changes the turtle head by degrees counterclockwise.
(set-color color) (set-color name color)	changes the color of the turtle to a color, such as :red or :orange. This only works for colors that are already defined, see the list below
(set-color r g b) (set-color name r g b)	changes the color of the turtle to any combination of red, green, blue color components.
(undo) (undo name)	undoes the last line and back the turtle.
(home) (home name)	moves the turtle back to the home position.
(home-all)	moves all turtles back to the home position.

usage examples

(forward 30)         ;; :trinity moves forward by 30 pixels when only :trinity is there
(forward :neo 40)    ;; :neo moves

(backward 35)        ;; :trinity moves backward by 35 pixels when only  :trinity is there
(backward :neo 100)  ;; :neo moves

(right 45)           ;; :trinity turns 45 degrees clockwise when only :trinity is there
(right :neo 90)      ;; :neo turns 90 degrees clockwise

(left 30)            ;; :trinity turns 30 degrees counterclockwise when only  :trinity is there
(left :neo 135)      ;; :neo turns 135 degrees counterclockwise

(set-color :red)  ;; :trinity is now red when only :trinity is there
(set-color :neo :green) ;; :neo is now green

(set-color 255 0 0)  ;; :trinity is now red when only :trinity is there
(set-color :neo 0 255 0) ;; :neo is now green

(undo)               ;; :trinity's last line will be removed when only :trinity is there
(undo :neo)          ;; :neo's last line will be removed

(home)               ;; moves :trinity back to the home position, center  when only :trinity is there
(home :neo)          ;; moves :neo back to the home position, center

(home-all)           ;; moves all turtles back to the home position

Colors

You can use the following color names:

:lime :orange :white :yellow :navy :green :cyan :gold :red :blue 
:maroon :pink :teal :magenta :purple :silver :grey :brown :black

You can also specify your own colors by providing their RGB (Red, Green, Blue) encoding. For instance, 0 245 255 is a turquoise color. We discuss colors more in the turtles lesson.

Turtle

command	description
(add-turtle name)	adds a turtle with its name.
(turtle-names)	returns all turtle names.
(state) (state name)	returns a current state of the turtle.
(state-all)	returns current states of all turtles.

Turtle's state includes its current coordinates (x,y), the angle it's pointing at, its color, and its name: {:x 0, :y 0, :angle 135, :color :purple, :name :trinity}

usage examples

(add-turtle :neo)    ;; adds a turtle whose name is :neo

(turtle-names)       ;; returns all turtle names

(state)              ;; returns :trinity's current state when only :trinity is there.

(state :neo)         ;; returns :neo's current state

(state-all)          ;; returns all turtles' current states

The state functions show the absolute coordinates on the canvas.

For example, the starting state of :trinity is {:x 0, :y 0, :angle 90, :color :purple, :name :trinity}.

Absolute dimensions and angles are set up as shown below:

x and y in absolute values

position	x and y values
home	both x and y are zero. (x, y) = (0, 0)
rightmost	x is 240, y is any. (x, y) = (240, y)
leftmost	x is -240, y is any. (x, y) = (-240, y)
top	x is any, y is 150. (x, y) = (x, 150)
bottom	x is any, y is -150. (x, y) = (x, -150)

angle in absolute degrees

head	angle
right	0
up	90
left	180
down	270

Clean up

command	description
(clean) (clean name)	cleans all lines belong to the turtle.
(clean-all)	cleans all lines of all turtles.

usage examples

(clean)              ;; cleans all of :trinity's lines only when :trinity is there
(clean :neo)         ;; cleans all of :neo's lines

(clean-all)          ;; cleans all turtles all lines

Initialize

command	description
(init)	sets the canvas back to the staring state.

usage examples

(init)               ;; sets the canvas back to the starting state, only :trinity is in home position

Samples

How to Walk Turtles has more examples as well as function study materials.

License

ClojureBridge Curriculum by ClojureBridge is licensed under a Creative Commons Attribution 4.0 International License.