console-toolkit 1.2.8 → 1.2.10

package/src/turtle/index.d.ts

@@ -0,0 +1,21 @@
+import Turtle from './turtle.js';
+import {draw} from './draw-unicode.js';
+import Box from '../box.js';
+
+declare module './turtle.js' {
+  interface Turtle {
+    /** Draws the turtle's path as a Box using Unicode box-drawing characters.
+     * @param options - Draw options.
+     * @returns A Box containing the drawn path.
+     */
+    toBox(options?: {ignore?: string; useArcs?: boolean}): Box;
+    /** Draws the turtle's path as a string array using Unicode box-drawing characters.
+     * @param options - Draw options.
+     * @returns Array of strings.
+     */
+    toStrings(options?: {ignore?: string; useArcs?: boolean}): string[];
+  }
+}
+
+export {Turtle, draw};
+export default Turtle;

package/src/turtle/index.js

@@ -1,9 +1,17 @@
 import Turtle from './turtle.js';
 import draw from './draw-unicode.js';
 
+/** Draws the turtle's path as a Box using Unicode box-drawing characters.
+ * @param {object} [options] - Draw options.
+ * @returns {import('../box.js').default}
+ */
 Turtle.prototype.toBox = function (options) {
   return draw(this, options);
 };
+/** Draws the turtle's path as a string array using Unicode box-drawing characters.
+ * @param {object} [options] - Draw options.
+ * @returns {string[]}
+ */
 Turtle.prototype.toStrings = function (options) {
   return this.toBox(options).toStrings();
 };

package/src/turtle/turtle.d.ts

@@ -0,0 +1,269 @@
+/** Turtle graphics on a grid with directional movement and line drawing.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Module:-turtle}
+ */
+export class Turtle {
+  /** Direction constant: right (0). */
+  static RIGHT: 0;
+  /** Direction constant: down (1). */
+  static DOWN: 1;
+  /** Direction constant: left (2). */
+  static LEFT: 2;
+  /** Direction constant: up (3). */
+  static UP: 3;
+
+  /** Direction constant: east (0). */
+  static EAST: 0;
+  /** Direction constant: south (1). */
+  static SOUTH: 1;
+  /** Direction constant: west (2). */
+  static WEST: 2;
+  /** Direction constant: north (3). */
+  static NORTH: 3;
+
+  /** The 2D grid of cells with directional line weights. */
+  cells: ({u?: number; d?: number; l?: number; r?: number} | null)[][];
+  /** Grid width. */
+  width: number;
+  /** Grid height. */
+  height: number;
+  /** Current direction (0=right, 1=down, 2=left, 3=up). */
+  direction: number;
+  /** Current position. */
+  position: {x: number; y: number};
+  /** Current line theme/weight. */
+  theme: number;
+  /** Saved state stack. */
+  stack: [number, number, number, number][];
+
+  /**
+   * @param width - Grid width.
+   * @param height - Grid height.
+   * @param theme - Initial line theme (default: 1).
+   */
+  constructor(width: number, height: number, theme?: number);
+
+  /** Resets the turtle position to (0, 0).
+   * @returns This Turtle.
+   */
+  reset(): this;
+  /** Alias for `reset`. */
+  home: Turtle['reset'];
+
+  /** Sets the turtle position.
+   * @param x - X coordinate.
+   * @param y - Y coordinate.
+   * @returns This Turtle.
+   */
+  set(x: number, y: number): this;
+  /** Alias for `set`. */
+  goto: Turtle['set'];
+  /** Alias for `set`. */
+  setPos: Turtle['set'];
+  /** Alias for `set`. */
+  setPosition: Turtle['set'];
+
+  /** Sets the X coordinate.
+   * @param x - X coordinate.
+   * @returns This Turtle.
+   */
+  setX(x: number): this;
+  /** Sets the Y coordinate.
+   * @param y - Y coordinate.
+   * @returns This Turtle.
+   */
+  setY(y: number): this;
+
+  /** Moves the turtle by a relative offset without drawing.
+   * @param dx - X offset.
+   * @param dy - Y offset.
+   * @returns This Turtle.
+   */
+  add(dx: number, dy: number): this;
+  /** Alias for `add`. */
+  advance: Turtle['add'];
+
+  /** Adds to the X coordinate.
+   * @param dx - X offset.
+   * @returns This Turtle.
+   */
+  addX(dx: number): this;
+  /** Adds to the Y coordinate.
+   * @param dy - Y offset.
+   * @returns This Turtle.
+   */
+  addY(dy: number): this;
+
+  /** Sets the line theme/weight.
+   * @param theme - Theme number.
+   * @returns This Turtle.
+   */
+  setTheme(theme: number): this;
+  /** Alias for `setTheme`. */
+  setPen: Turtle['setTheme'];
+  /** Alias for `setTheme`. */
+  setWidth: Turtle['setTheme'];
+
+  /** Sets the direction.
+   * @param direction - Direction (0-3).
+   * @returns This Turtle.
+   */
+  setDirection(direction: number): this;
+  /** Alias for `setDirection`. */
+  setDir: Turtle['setDirection'];
+
+  /** Sets direction to up.
+   * @returns This Turtle.
+   */
+  setUp(): this;
+  /** Alias for `setUp`. */
+  setNorth: Turtle['setUp'];
+
+  /** Sets direction to down.
+   * @returns This Turtle.
+   */
+  setDown(): this;
+  /** Alias for `setDown`. */
+  setSouth: Turtle['setDown'];
+
+  /** Sets direction to left.
+   * @returns This Turtle.
+   */
+  setLeft(): this;
+  /** Alias for `setLeft`. */
+  setWest: Turtle['setLeft'];
+
+  /** Sets direction to right.
+   * @returns This Turtle.
+   */
+  setRight(): this;
+  /** Alias for `setRight`. */
+  setEast: Turtle['setRight'];
+
+  /** Turns the turtle 90° left.
+   * @returns This Turtle.
+   */
+  left(): this;
+  /** Alias for `left`. */
+  lt: Turtle['left'];
+
+  /** Turns the turtle 90° right.
+   * @returns This Turtle.
+   */
+  right(): this;
+  /** Alias for `right`. */
+  rt: Turtle['right'];
+
+  /** Saves the current state onto the stack.
+   * @returns This Turtle.
+   */
+  save(): this;
+  /** Restores the last saved state from the stack.
+   * @returns This Turtle.
+   */
+  restore(): this;
+
+  /** Moves up by distance, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  moveUp(distance: number): this;
+  /** Alias for `moveUp`. */
+  moveNorth: Turtle['moveUp'];
+
+  /** Moves down by distance, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  moveDown(distance: number): this;
+  /** Alias for `moveDown`. */
+  moveSouth: Turtle['moveDown'];
+
+  /** Moves left by distance, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  moveLeft(distance: number): this;
+  /** Alias for `moveLeft`. */
+  moveWest: Turtle['moveLeft'];
+
+  /** Moves right by distance, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  moveRight(distance: number): this;
+  /** Alias for `moveRight`. */
+  moveEast: Turtle['moveRight'];
+
+  /** Moves in a direction, drawing a line.
+   * @param direction - Direction (0-3).
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  move(direction: number, distance: number): this;
+
+  /** Moves the turtle forward, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  forward(distance: number): this;
+  /** Alias for `forward`. */
+  fd: Turtle['forward'];
+  /** Alias for `forward`. */
+  fwd: Turtle['forward'];
+
+  /** Moves the turtle backward, drawing a line.
+   * @param distance - Steps.
+   * @returns This Turtle.
+   */
+  backward(distance: number): this;
+  /** Alias for `backward`. */
+  bk: Turtle['backward'];
+  /** Alias for `backward`. */
+  back: Turtle['backward'];
+  /** Alias for `backward`. */
+  bwd: Turtle['backward'];
+
+  /** Marks a half-step line in the given direction.
+   * @param direction - Direction (0-3).
+   * @returns This Turtle.
+   */
+  markHalf(direction: number): this;
+  /** Marks a half-step line forward.
+   * @returns This Turtle.
+   */
+  markHalfForward(): this;
+  /** Marks a half-step line backward.
+   * @returns This Turtle.
+   */
+  markHalfBackward(): this;
+
+  /** Marks a half-step line up.
+   * @returns This Turtle.
+   */
+  markHalfUp(): this;
+  /** Alias for `markHalfUp`. */
+  markHalfNorth: Turtle['markHalfUp'];
+
+  /** Marks a half-step line down.
+   * @returns This Turtle.
+   */
+  markHalfDown(): this;
+  /** Alias for `markHalfDown`. */
+  markHalfSouth: Turtle['markHalfDown'];
+
+  /** Marks a half-step line left.
+   * @returns This Turtle.
+   */
+  markHalfLeft(): this;
+  /** Alias for `markHalfLeft`. */
+  markHalfWest: Turtle['markHalfLeft'];
+
+  /** Marks a half-step line right.
+   * @returns This Turtle.
+   */
+  markHalfRight(): this;
+  /** Alias for `markHalfRight`. */
+  markHalfEast: Turtle['markHalfRight'];
+}
+
+export default Turtle;

package/src/turtle/turtle.js

@@ -1,5 +1,8 @@
 import {addAliases} from '../meta.js';
 
+/** Turtle graphics on a grid. Supports directional movement, line drawing, state save/restore, and various aliases.
+ * @see {@link https://github.com/uhop/console-toolkit/wiki/Package:-turtle}
+ */
 export class Turtle {
   static RIGHT = 0;
   static DOWN = 1;
@@ -11,6 +14,11 @@ export class Turtle {
   static WEST = 2;
   static NORTH = 3;
 
+  /** Creates a new Turtle on a grid of the given size.
+   * @param {number} width - Grid width.
+   * @param {number} height - Grid height.
+   * @param {number} [theme=1] - The line theme/pen width.
+   */
   constructor(width, height, theme = 1) {
     this.cells = new Array(height);
     for (let i = 0; i < height; ++i) {
@@ -25,71 +33,136 @@ export class Turtle {
     this.stack = [];
   }
 
+  /** Resets the turtle position to (0, 0).
+   * @returns {this}
+   */
   reset() {
     this.position.x = this.position.y = 0;
     return this;
   }
+  /** Sets the turtle position (clamped to grid bounds).
+   * @param {number} x
+   * @param {number} y
+   * @returns {this}
+   */
   set(x, y) {
     this.position.x = Math.max(0, Math.min(this.width - 1, x));
     this.position.y = Math.max(0, Math.min(this.height - 1, y));
     return this;
   }
+  /** Sets the X coordinate.
+   * @param {number} x
+   * @returns {this}
+   */
   setX(x) {
     this.position.x = Math.max(0, Math.min(this.width - 1, x));
     return this;
   }
+  /** Sets the Y coordinate.
+   * @param {number} y
+   * @returns {this}
+   */
   setY(y) {
     this.position.y = Math.max(0, Math.min(this.height - 1, y));
     return this;
   }
+  /** Moves the turtle by a relative offset without drawing.
+   * @param {number} dx - X offset.
+   * @param {number} dy - Y offset.
+   * @returns {this}
+   */
   add(dx, dy) {
-    return this.set(x + dx, y + dy);
+    return this.set(this.position.x + dx, this.position.y + dy);
   }
+  /** Adds to the X coordinate.
+   * @param {number} dx - X offset.
+   * @returns {this}
+   */
   addX(dx) {
-    return this.setX(x + dx);
+    return this.setX(this.position.x + dx);
   }
+  /** Adds to the Y coordinate.
+   * @param {number} dy - Y offset.
+   * @returns {this}
+   */
   addY(dy) {
-    return this.setY(y + dy);
+    return this.setY(this.position.y + dy);
   }
 
+  /** Sets the line theme/pen width.
+   * @param {number} theme
+   * @returns {this}
+   */
   setTheme(theme) {
     this.theme = theme;
     return this;
   }
 
+  /** Sets the turtle direction (0=right, 1=down, 2=left, 3=up).
+   * @param {number} direction
+   * @returns {this}
+   */
   setDirection(direction) {
     this.direction = direction % 4;
     return this;
   }
+  /** Sets direction to up.
+   * @returns {this}
+   */
   setUp() {
     return this.setDirection(Turtle.UP);
   }
+  /** Sets direction to down.
+   * @returns {this}
+   */
   setDown() {
     return this.setDirection(Turtle.DOWN);
   }
+  /** Sets direction to left.
+   * @returns {this}
+   */
   setLeft() {
     return this.setDirection(Turtle.LEFT);
   }
+  /** Sets direction to right.
+   * @returns {this}
+   */
   setRight() {
     return this.setDirection(Turtle.RIGHT);
   }
+  /** Turns the turtle 90° to the left.
+   * @returns {this}
+   */
   left() {
     return this.setDirection((this.direction + 3) % 4);
   }
+  /** Turns the turtle 90° to the right.
+   * @returns {this}
+   */
   right() {
     return this.setDirection((this.direction + 1) % 4);
   }
 
+  /** Saves the current position, direction, and theme onto the stack.
+   * @returns {this}
+   */
   save() {
     this.stack.push([this.position.x, this.position.y, this.direction, this.theme]);
     return this;
   }
+  /** Restores the position, direction, and theme from the stack.
+   * @returns {this}
+   */
   restore() {
-    if (!this.stack) throw new ReferenceError('Unmatched restore');
+    if (!this.stack.length) throw new ReferenceError('Unmatched restore');
     [this.position.x, this.position.y, this.direction, this.theme] = this.stack.pop();
     return this;
   }
 
+  /** Moves the turtle up, drawing a line.
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   moveUp(distance) {
     if (!distance) return this;
     if (distance < 0) return this.moveDown(-distance);
@@ -116,6 +189,10 @@ export class Turtle {
     this.position.y = last;
     return this;
   }
+  /** Moves the turtle down, drawing a line.
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   moveDown(distance) {
     if (!distance) return this;
     if (distance < 0) return this.moveUp(-distance);
@@ -142,6 +219,10 @@ export class Turtle {
     this.position.y = last;
     return this;
   }
+  /** Moves the turtle left, drawing a line.
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   moveLeft(distance) {
     if (!distance) return this;
     if (distance < 0) return this.moveRight(-distance);
@@ -168,6 +249,10 @@ export class Turtle {
     this.position.x = last;
     return this;
   }
+  /** Moves the turtle right, drawing a line.
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   moveRight(distance) {
     if (!distance) return this;
     if (distance < 0) return this.moveLeft(-distance);
@@ -194,6 +279,11 @@ export class Turtle {
     this.position.x = last;
     return this;
   }
+  /** Moves the turtle in the given direction, drawing a line.
+   * @param {number} direction - Direction (0=right, 1=down, 2=left, 3=up).
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   move(direction, distance) {
     switch (direction) {
       case Turtle.UP:
@@ -207,13 +297,25 @@ export class Turtle {
     }
     return this;
   }
+  /** Moves the turtle forward in its current direction.
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   forward(distance) {
     return this.move(this.direction, distance);
   }
+  /** Moves the turtle backward (opposite of current direction).
+   * @param {number} distance - Number of cells to move.
+   * @returns {this}
+   */
   backward(distance) {
     return this.move((this.direction + 2) % 4, distance);
   }
 
+  /** Marks a half-line from the center of the current cell in the given direction.
+   * @param {number} direction - Direction (0=right, 1=down, 2=left, 3=up).
+   * @returns {this}
+   */
   markHalf(direction) {
     let cell = this.cells[this.position.y][this.position.x];
     if (!cell) cell = this.cells[this.position.y][this.position.x] = {};
@@ -233,21 +335,39 @@ export class Turtle {
     }
     return this;
   }
+  /** Marks a half-step line forward.
+   * @returns {this}
+   */
   markHalfForward() {
     return this.markHalf(this.direction);
   }
+  /** Marks a half-step line backward.
+   * @returns {this}
+   */
   markHalfBackward() {
     return this.markHalf((this.direction + 2) % 4);
   }
+  /** Marks a half-step line up.
+   * @returns {this}
+   */
   markHalfUp() {
     return this.markHalf(Turtle.UP);
   }
+  /** Marks a half-step line down.
+   * @returns {this}
+   */
   markHalfDown() {
     return this.markHalf(Turtle.DOWN);
   }
+  /** Marks a half-step line left.
+   * @returns {this}
+   */
   markHalfLeft() {
     return this.markHalf(Turtle.LEFT);
   }
+  /** Marks a half-step line right.
+   * @returns {this}
+   */
   markHalfRight() {
     return this.markHalf(Turtle.RIGHT);
   }