Package: turtle - uhop/console-toolkit GitHub Wiki

The turtle package implements the venerable Turtle graphics. It is used to generate an arbitrary line-based vector images.

`turtle/index.js` AKA `turtle`

This is the main user-facing module: turtle/index.js. It exposes other modules:

turtle/turtle.js defines the Turtle class, which is exposed by name and as the default export.
turtle/draw-unicode.js defines the draw() function, which is exposed by name.
- The Turtle class is augmented with toBox() and toStrings() methods based on the draw() function.

See the corresponding objects below for more details.

`turtle/turtle.js`

The turtle/turtle.js defines the main class.

Class `Turtle`

This is the class that is responsible for drawing.

The following static members are used to specify a direction:

Name	Alias	Value
`RIGHT`	`EAST`	0
`DOWN`	`SOUTH`	1
`LEFT`	`WEST`	2
`UP`	`NORTH`	3

These values are used in the Turtle methods.

The class defines the following properties:

Name	Type	Description
`width`	number	The width of the canvas.
`height`	number	The height of the canvas.
`direction`	number	The current direction.
`position`	`{x: number, y: number}`	The current position.
`theme`	number or string	The current sub-theme for a line.
`stack`	array	The stack used by `save()` and `restore()`. Stores `direction`, `position` and `theme`.

See the definition of a theme with sub-themes in Package: themes.

The Turtle class defines the following methods:

Name	Return	Description
`constructor(width, height, theme = 1)`	`Turtle`	Creates a new `Turtle` of given width and height with empty cells.
`reset()`	`this`	Resets the `position` to `{x: 0, y: 0}`.
`set(x, y)`	`this`	Sets the `position` to `{x, y}`.
`setX(x)`	`this`	Sets the `x` coordinate of the `position`.
`setY(y)`	`this`	Sets the `y` coordinate of the `position`.
`add(dx, dy)`	`this`	Adds `dx` and `dy` to the `position`.
`addX(dx)`	`this`	Adds `dx` to the `x` coordinate of the `position`.
`addY(dy)`	`this`	Adds `dy` to the `y` coordinate of the `position`.
`setTheme(theme)`	`this`	Sets the `theme`.
`setDirection(direction)`	`this`	Sets the `direction`.
`setUp()`	`this`	Sets the `direction` to `Turtle.UP`.
`setDown()`	`this`	Sets the `direction` to `Turtle.DOWN`.
`setLeft()`	`this`	Sets the `direction` to `Turtle.LEFT`.
`setRight()`	`this`	Sets the `direction` to `Turtle.RIGHT`.
`left()`	`this`	Turns left by 90 degrees.
`right()`	`this`	Turns right by 90 degrees.
`save()`	`this`	Saves the current `direction`, `position` and `theme` in the `stack`.
`restore()`	`this`	Restores the last `direction`, `position` and `theme` from the `stack`.
`move(direction, distance)`	`this`	Moves from the current `position` in the given `direction` by `distance` drawing a line.
`moveUp(distance)`	`this`	Moves from the current `position` up by `distance` drawing a line.
`moveDown(distance)`	`this`	Moves from the current `position` down by `distance` drawing a line.
`moveLeft(distance)`	`this`	Moves form the current `position` left by `distance` drawing a line.
`moveRight(distance)`	`this`	Moves from the current `position` right by `distance` drawing a line.
`forward(distance)`	`this`	Moves from the `position` in the current `direction` by `distance` drawing a line.
`backward(distance)`	`this`	Moves from the `position` in the direction opposite to the current `direction` by `distance` drawing a line.
`markHalf(direction)`	`this`	Draws a half-line in the current `position` in the given `direction`.
`markHalfUp()`	`this`	Draws a half-line in the current `position` up.
`markHalfDown()`	`this`	Draws a half-line in the current `position` down.
`markHalfLeft()`	`this`	Draws a half-line in the current `position` left.
`markHalfRight()`	`this`	Draws a half-line in the current `position` right.
`markHalfForward()`	`this`	Draws a half-line in the current `position` in the current `direction`.
`markHalfBackward()`	`this`	Draws a half-line in the current `position` in the direction opposite to the current `direction`.

The class defines the following aliases to accommodate various programming styles:

Name	Alias of
`home()`	`reset()`
`goto()`	`set()`
`setPos()`	`set()`
`setPosition()`	`set()`
`advance()`	`add()`
`lt()`	`left()`
`rt()`	`right()`
`fd()`	`forward()`
`fwd()`	`forward()`
`bk()`	`backward()`
`bwd()`	`backward()`
`back()`	`backward()`
`setPen()`	`setTheme()`
`setWidth()`	`setTheme()`
`setDir()`	`setDirection()`
`setNorth()`	`setUp()`
`setSouth()`	`setDown()`
`setWest()`	`setLeft()`
`setEast()`	`setRight()`
`moveNorth()`	`moveUp()`
`moveSouth()`	`moveDown()`
`moveWest()`	`moveLeft()`
`moveEast()`	`moveRight()`
`markHalfNorth()`	`markHalfUp()`
`markHalfSouth()`	`markHalfDown()`
`markHalfWest()`	`markHalfLeft()`
`markHalfEast()`	`markHalfRight()`

Notes on methods

Turtle works on a canvas defined by constructor(). Internally, each "pixel" is represented by a cell, which can be null to represent an empty cell or {t, r, b, l} to represent a cell with a theme. Cell's properties represent top, right, bottom, left respectively. If a property is not falsy, it means that a line passes through the middle of the cell's wall: top, right, bottom or left. The value of a property is a sub-theme id to use, usually 1 or 2.

constructor() creates an empty canvas and positions the turtle at the origin {x: 0, y: 0}.

Some implementations of the turtle graphics use methods like penUp() and penDown() to control when the turtle is allowed to draw. This implementation separates them into setXXX() and moveXXX() methods: the former methods update the turtle's position but do not draw and the latter methods draw a line and update the turtle's position.

The distance argument is inclusive and can be positive or negative.

markHalfXXX() draws a half-line in the current position in the given direction.

For example, the following code:

// excerpt from tests/manual/test_turtle-1.js:
const turtle = new Turtle(5, 1).markHalfDown().forward(2).markHalfUp().forward(2).markHalfDown(),
  branch = drawLineArt(turtle, lineTheme),
  panel = new Panel(7, 5)
    .put(2, 1, branch)
    .put(4, 0, '2')
    .put(2, 2, '4')
    .put(6, 2, '5')
    .put(0, 3, branch)
    .put(0, 4, '1')
    .put(4, 4, '3');
draw(panel);

It produces this output:

    2
  ╭─┴─╮
  4   5
╭─┴─╮
1   3

Exports

The Turtle class is exposed by name and as the default export.

`turtle/draw-line-art.js`

The turtle/draw-line-art.js defines a function that takes a turtle object and a line theme and draws a picture in a box.

Function `draw()`

draw(turtle, lineTheme, {ignore = ' '}) renders the turtle drawing using a line theme. Empty cells and impossible configurations will be drawn as ignore.

The function returns a box that contains the turtle drawing. It will have the same size as the turtle's canvas. See Box for details.

Exports

The draw() function is exposed by name and as the default export.

`turtle/draw-unicode.js`

The turtle/draw-unicode.js defines a function that takes a turtle object and produces a picture using Unicode line characters. Unlike the draw() function in turtle/draw-line-art.js above, this module does not support line themes but can render "impossible" configurations for table drawings.

Function `draw()`

draw(turtle, {ignore = ' ', useArcs = false}) renders the turtle drawing using Unicode line characters. Theme value 1 uses thin lines and 2 uses thick lines. Empty cells are rendered as ignore.

If useArcs are truthy, the function replaces 90 degree sharp angles with arcs. This option works only for thin lines (1). See the example above.

The function returns a box that contains the turtle drawing. It will have the same size as the turtle's canvas. See Box for details.

Exports

The draw() function is exposed by name and as the default export.

Package: turtle - uhop/console-toolkit GitHub Wiki

turtle/index.js AKA turtle

turtle/turtle.js

Class Turtle

Notes on methods

Exports

turtle/draw-line-art.js

Function draw()

Exports

turtle/draw-unicode.js

Function draw()

Exports

`turtle/index.js` AKA `turtle`

`turtle/turtle.js`

Class `Turtle`

`turtle/draw-line-art.js`

Function `draw()`

`turtle/draw-unicode.js`

Function `draw()`