# Tittle

Turtles in [Scittle](https://babashka.org/scittle/).

See [Papert, S: Mindstorms](https://www.worldofbooks.com/en-gb/products/mindstorms-book-seymour-papert-9780745016047).

## State of Play

![Polygons generated with Tittle](polygons.svg)

As a proof of concept, this proves the concept. There's a lot more to do.

I have not (yet) managed to get a scittle REPL running.

Clojure (and thus Scittle) is a fairly pure functional language. It's not good at imperative things, although of course it can do them. Turtle Graphics is by its nature imperative: you're commanding the turtle. So this is not a very idiomatic use of Scittle, and it's not very efficient; it invites you to write recursive functions (and of course I wish to encourage you to write recursive functions), but recursive functions in Scittle are not fast.

## Usage

At this stage, edit `index.html`

### Functions

Generally speaking, functions whose names end in exclamation points are imperative functions: they change the state of things by side-effect, and the return value may not be particularly relevant. I would normally consider imperative functions bad practice in Clojure.

#### (cos *angle*)

Return the cosine of this `angle`, considered to be expressed in degrees.

#### (degrees->radians *angle*)

Return the equivalent, in radians, of this `angle` espressed in degrees.

#### (draw-polygon! *sides* *side-length*)

Draw a regular polygon, with this number of `sides`, each of this `side-length`.

#### (draw-tree *length* *left-branch* *right-branch* *curvature* *branch-fraction* *trunk-fraction* *depth*)

Draw a tree. This is a fairly crude tree-drawing algorithm; there's lots of ways it can be improved, consider it a plac to start. Parameters (all numeric) as follows:
                 
* `length`: the length of the current segment of the tree;
* `left-branch`: the amount to turn left, with respect to the parent segment, to draw a left branch, in degrees;
* `right-branch`: the amount to turn right, with respect to the parent segment, to draw a right branch, in degrees;
* `curvature`: the amount to turn to draw the next segment of the current stem, in degrees;
* `branch-fraction`: the length of a branch segment, as a proportion of the length of its parent segment;
* `trunk-fraction`: the length of the next segment of a stem, as a proportion of the length of its parent segment;
* `depth`: the maximum depth of recursion to allow.

#### (log-turtle!)

Prints the state of the turtle to the browser console.

#### (move! *distance*)

Move the turtle forward on its current heading by `distance` units.

**NOTE THAT** this function invokes `move-to!`, q.v., which will create a
line element if the pen is down.

#### (move-to! *x* *y*)

Move the turtle absolutely to the coordinates `x`, `y`. If the pen is down, create a line element.
                 
**NOTE THAT** this is the only function which creates new graphical elements.

#### (number-or-error! *n*)

If `n` is a number, return it, else throw an exception.

#### (pen-down!)

Put the turtle's pen down (i.e., cause line segments to be created).

#### (pen-down?)

Return `true` if the turtle's pen is down, else `false`.

#### (pen-up!)

Lift the turtle's pen up (line segments will not be created).

#### (pen-up?)

Return `true` if the turtle's pen is not down, else `false`.

#### (radians->degrees *angle*)

Return the equivalent, in degrees, of this `angle` espressed in radians.

#### (sanitise-angle *angle*)

Take this `angle`, and return a number between 0 and 360 that represents it as an angular measurement.

#### (set-ink! *colour*)

Set the ink with which the turtle draws to this `colour`, which should be a string representation of a colour known to CSS.

#### (set-nib! *n*)

Set the nib (width) of the pen to this `n`, which should be a number.

#### (sin *angle*)

Return the sine of this `angle`, considered to be expressed in degrees.

#### (turn! *angle*)

Turn the turtle clockwise by this `angle`, expressed in degrees with respect to the X axis. If `angle` is not a number, throw an exception.

#### (turn-to! *angle*)

Turn the turtle to face `angle`, expressed in degrees with respect to the X axis. If `angle` is not a number, throw an exception.
                
**TODO**: Note that 180° is currently straight up; this is not intended, it is intended that 0° should be straight up, and this change will be made 
                before version 1.0.

## Licence

Copyright © Simon Brooke 2025

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.