# LispKit Draw Turtle

Library `(lispkit draw turtle)` defines a simple “turtle graphics” API. The API provides functionality for creating turtles and for moving turtles on a plane generating drawings as a side-effect. A drawing is a data structure defined by library `(lispkit draw)`.

A turtle is defined in terms of the following components:

- A position (x, y) defining the coordinates where the turtle is currently located within a coordinate system defined by parameters used to create the turtle via `make-turtle`
- A heading angle which defines the direction in degrees into which the turtle is moving
- A boolean flag pen down which, if set to `#t`, will make the turtle draw lines on the graphics plane when moving.
- A line width defining the width of lines drawn by the turtle
- A color defining the color of lines drawn by the turtle
- A drawing which records the moves of the turtle while the pen is down.

Turtles are mutable objects created via `make-turtle`. The functions listed below change the state of a turtle. In particular, they generate a drawing as a side-effect which can be accessed via `turtle-drawing`. For most functions, the turtle is an optional argument. If it is not provided, the function applies to the turtle provided by the `current-turtle` parammeter object.

current-turtle [parameter object]

Defines the current turtle, which is used as a default by all functions for which the turtle argument is optional. If there is no current turtle, this parameter is set to `#f`.

(turtle? obj) [procedure]

Returns `#t` if obj is a turtle. Otherwise, it returns `#f`.

(make-turtle x y scale) [procedure]

Returns a new turtle object. x and y determine the “home point” of the turtle. This is equivalent to the zero point of the coordinate system in which the turtle navigates. scale is a scaling factor.

(turtle-drawing turtle) [procedure]

Returns the drawing associated with the given turtle.

(turtle-x turtle) [procedure]

Returns the x coordinate of the position of the given turtle.

(turtle-y turtle) [procedure]

Returns the y coordinate of the position of the given turtle.

(turtle-angle turtle) [procedure]

Returns the current angle of the given turtle.

(turtle-angle turtle) [procedure]

Returns the current angle of the given turtle.

(turtle-pen-down? turtle) [procedure]

Returns `#t` if the given turtle has its pen down; otherwise `#f` is returned.

(pen-up) [procedure]
(pen-up turtle)

Lifts turtle from the plane. If turtle is not provided, the turtle defined by `current-turtle` is used. Subsequent `forward` and `backward` operations don’t lead to lines being drawn. Only the current coordinates are getting updated.

(pen-down) [procedure]
(pen-down turtle)

Drops turtle onto the plane. If turtle is not provided, the turtle defined by `current-turtle` is used. Subsequent `forward` and `backward` operations will lead to lines being drawn.

(pen-color color) [procedure]
(pen-color color turtle)

Sets the drawing color of turtle to color. If turtle is not provided, the turtle defined by `current-turtle` is used. color is a color object as defined by library `(lispkit draw)`.

(pen-size size) [procedure]
(pen-size size turtle)

Sets the pen size of turtle to size. If turtle is not provided, the turtle defined by `current-turtle` is used. The pen size corresponds to the width of lines drawn by `forward` and `backward`.

(home) [procedure]
(home turtle)

Moves turtle to its home position. If turtle is not provided, the turtle defined by `current-turtle` is used.

(move x y) [procedure]
(move x y turtle)

Moves turtle to the position described by the coordinates x and y. If turtle is not provided, the turtle defined by `current-turtle` is used.

(heading angle) [procedure]
(heading angle turtle)

Sets the heading of turtle to angle. If turtle is not provided, the turtle defined by `current-turtle` is used. angle is expressed in terms of degrees.

(turn angle) [procedure]
(turn angle turtle)

Adjusts the heading of turtle by angle degrees. If turtle is not provided, the turtle defined by `current-turtle` is used.

(right angle) [procedure]
(right angle turtle)

Adjusts the heading of turtle by angle degrees. If turtle is not provided, the turtle defined by `current-turtle` is used.

(left angle) [procedure]
(left angle turtle)

Adjusts the heading of turtle by -angle degrees. If turtle is not provided, the turtle defined by `current-turtle` is used.

(forward distance) [procedure]
(forward distance turtle)

Moves turtle forward by distance units drawing a line if the pen is down. If turtle is not provided, the turtle defined by `current-turtle` is used.

(backward distance) [procedure]
(backward distance turtle)

Moves turtle backward by distance units drawing a line if the pen is down. If turtle is not provided, the turtle defined by `current-turtle` is used.

(arc angle radius) [procedure]
(arc angle radius turtle)

Turns the turtle by the given angle (in radians) and draws an arc with radius around the current turtle position if the pen is down. If turtle is not provided, the turtle defined by `current-turtle` is used.