kei-lisp-plugin-graphics 1.0.1 → 2.0.0

package/dist/index.d.ts

@@ -5,17 +5,23 @@ import { Cons, InterpretedSymbol, KeiLispPlugin, LispValue, PluginContext } from
  * @class
  * @classdesc Canvas2D drawing plugin for the kei-lisp interpreter. Implements
  *            the `KeiLispPlugin` contract (`name` / `has` / `apply`) and
- *            exposes 43 `g…` Lisp functions that proxy to a 2D rendering
+ *            exposes 45 `g…` Lisp functions that proxy to a 2D rendering
  *            context.
  * @author Keisuke Ikeda
  * @this {GraphicsPlugin}
  */
 declare class GraphicsPlugin extends Object implements KeiLispPlugin {
+  #private;
   /**
    * Dispatch map from a Lisp function name (InterpretedSymbol) to the name of
    * the GraphicsPlugin method that implements it.
    */
   static readonly buildInFunctions: Map<InterpretedSymbol, string>;
+  /**
+   * Builds the dispatch table.
+   * @return the dispatch table
+   */
+  static setup(): Map<InterpretedSymbol, string>;
   /**
    * Plugin identifier, used for diagnostics.
    */
@@ -38,18 +44,18 @@ declare class GraphicsPlugin extends Object implements KeiLispPlugin {
   /**
    * Dispatches the given symbol to the matching `g…` method.
    * @param aSymbol - the call symbol
-   * @param args - the evaluated argument list
-   * @param _ctx - the interpreter context (unused by this plugin)
+   * @param arguments_ - the evaluated argument list
+   * @param _context - the interpreter context (unused by this plugin)
    * @return the method's result, or `Cons.nil` if dispatch fails
    */
-  apply(aSymbol: InterpretedSymbol, args: Cons, _ctx: PluginContext): LispValue;
+  apply(aSymbol: InterpretedSymbol, arguments_: Cons, _context: PluginContext): LispValue;
   /**
    * Resolves the procedure name and invokes the matching method.
    * @param procedure - the Lisp symbol
-   * @param args - the evaluated argument list
+   * @param arguments_ - the evaluated argument list
    * @return the method's result, or `Cons.nil` if not registered
    */
-  selectProcedure(procedure: InterpretedSymbol, args: Cons): LispValue;
+  selectProcedure(procedure: InterpretedSymbol, arguments_: Cons): LispValue;
   /**
    * Looks up and invokes the JS method that implements the given Lisp symbol.
    * Throws `TypeError` when the dispatch table points to a method that does
@@ -57,10 +63,10 @@ declare class GraphicsPlugin extends Object implements KeiLispPlugin {
    * Ramda `R.invoker(1, methodName)(args, this)` call would surface the same
    * error by attempting to call `undefined`.
    * @param procedure - the Lisp symbol
-   * @param args - the evaluated argument list
+   * @param arguments_ - the evaluated argument list
    * @return the method's result
    */
-  buildInFunction(procedure: InterpretedSymbol, args: Cons): LispValue;
+  buildInFunction(procedure: InterpretedSymbol, arguments_: Cons): LispValue;
   /**
    * Checks whether the canvas exposes a usable 2D context, and narrows
    * `this.ctx` to non-null for the caller when it returns true.
@@ -69,72 +75,82 @@ declare class GraphicsPlugin extends Object implements KeiLispPlugin {
   checkSupport(): this is GraphicsPlugin & {
     ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
   };
-  /**
-   * Writes a diagnostic line directly to `process.stderr`, matching the
-   * convention used by kei-lisp itself (`Applier.format` writes to
-   * `process.stdout`). In a Node runtime this hits the real stderr; in a
-   * browser kei-lisp host (e.g. kei-lisp-web) the host typically swaps
-   * `process.stderr.write` for a sink that routes to the REPL output panel,
-   * so the same call reaches the user via the host's normal output channel.
-   * @param line - the line to write
-   */
-  _print(line: string): void;
-  gAlpha(args: Cons): LispValue;
-  gArc(args: Cons): LispValue;
-  gArcTo(args: Cons): LispValue;
-  gBezCurveTo(args: Cons): LispValue;
+  gAlpha(arguments_: Cons): LispValue;
+  gArc(arguments_: Cons): LispValue;
+  gArcTo(arguments_: Cons): LispValue;
+  gBezCurveTo(arguments_: Cons): LispValue;
   gClear(): LispValue;
   gClose(): LispValue;
-  gColor(args: Cons): LispValue;
+  gColor(arguments_: Cons): LispValue;
   gFill(): LispValue;
-  gFillColor(args: Cons): LispValue;
-  gFillRect(args: Cons): LispValue;
-  gFillText(args: Cons): LispValue;
-  gFillTri(args: Cons): LispValue;
+  gFillColor(arguments_: Cons): LispValue;
+  gFillRect(arguments_: Cons): LispValue;
+  gFillText(arguments_: Cons): LispValue;
+  gFillTri(arguments_: Cons): LispValue;
   gFinishPath(): LispValue;
-  gImage(args: Cons): LispValue;
-  gLineTo(args: Cons): LispValue;
-  gLineCap(args: Cons): LispValue;
-  gLineJoin(args: Cons): LispValue;
-  gLineWidth(args: Cons): LispValue;
-  gMoveTo(args: Cons): LispValue;
+  gImage(arguments_: Cons): LispValue;
+  gLineTo(arguments_: Cons): LispValue;
+  gLineCap(arguments_: Cons): LispValue;
+  gLineJoin(arguments_: Cons): LispValue;
+  gLineWidth(arguments_: Cons): LispValue;
+  gMoveTo(arguments_: Cons): LispValue;
   gOpen(): LispValue;
-  gPattern(args: Cons): LispValue;
-  gQuadCurveTo(args: Cons): LispValue;
-  gSaveJpeg(): LispValue;
-  gSavePng(): LispValue;
-  gScale(args: Cons): LispValue;
-  gShadowBlur(args: Cons): LispValue;
-  gShadowColor(args: Cons): LispValue;
-  gShadowOffsetX(args: Cons): LispValue;
-  gShadowOffsetY(args: Cons): LispValue;
-  gSleep(args: Cons): LispValue;
+  gPattern(arguments_: Cons): LispValue;
+  gQuadCurveTo(arguments_: Cons): LispValue;
+  gSaveJpeg(arguments_: Cons): LispValue;
+  gSavePng(arguments_: Cons): LispValue;
+  /**
+   * Shared implementation of `gsave-jpeg` / `gsave-png`. With no argument it
+   * triggers a browser download; with a single string argument it writes the
+   * encoded image to that file path on Node.js.
+   * @param arguments_ - the evaluated argument list (empty, or one path string)
+   * @param mimeType - the image MIME type to encode
+   * @param label - the format name used in diagnostics ("jpeg" / "png")
+   * @return `t` on success, `Cons.nil` otherwise
+   */
+  saveCanvas(arguments_: Cons, mimeType: string, label: string): LispValue;
+  gScale(arguments_: Cons): LispValue;
+  gShadowBlur(arguments_: Cons): LispValue;
+  gShadowColor(arguments_: Cons): LispValue;
+  gShadowOffsetX(arguments_: Cons): LispValue;
+  gShadowOffsetY(arguments_: Cons): LispValue;
+  gSleep(arguments_: Cons): LispValue;
   gStartPath(): LispValue;
   gStroke(): LispValue;
-  gStrokeColor(args: Cons): LispValue;
-  gStrokeRect(args: Cons): LispValue;
-  gStrokeText(args: Cons): LispValue;
-  gStrokeTri(args: Cons): LispValue;
-  gTextAlign(args: Cons): LispValue;
-  gTextBaseline(args: Cons): LispValue;
-  gTextDirection(args: Cons): LispValue;
-  gTextFont(args: Cons): LispValue;
-  gTranslate(args: Cons): LispValue;
-  gRect(args: Cons): LispValue;
-  gRotate(args: Cons): LispValue;
+  gStrokeColor(arguments_: Cons): LispValue;
+  gStrokeRect(arguments_: Cons): LispValue;
+  gStrokeText(arguments_: Cons): LispValue;
+  gStrokeTri(arguments_: Cons): LispValue;
+  gTextAlign(arguments_: Cons): LispValue;
+  gTextBaseline(arguments_: Cons): LispValue;
+  gTextDirection(arguments_: Cons): LispValue;
+  gTextFont(arguments_: Cons): LispValue;
+  gTranslate(arguments_: Cons): LispValue;
+  gRect(arguments_: Cons): LispValue;
+  gRotate(arguments_: Cons): LispValue;
+  /**
+   * Pushes the current drawing state (styles, transform, clip) onto the
+   * context's state stack. Pairs with `gRestore` to let Lisp callers manage
+   * state explicitly. Replaces the legacy per-method `ctx.save()` calls, which
+   * pushed state on every draw with no matching `restore()` and grew the stack
+   * unbounded.
+   * @return `t` on success, `Cons.nil` otherwise
+   */
+  gSave(): LispValue;
+  /**
+   * Pops the most recently saved drawing state off the context's state stack.
+   * Pairs with `gSave`. Popping an empty stack is a no-op per the Canvas spec.
+   * @return `t` on success, `Cons.nil` otherwise
+   */
+  gRestore(): LispValue;
   /**
    * Parses a color spec from the head of the argument Cons. Accepts
    * (1 string), (3 numbers — rgb), or (4 numbers — rgba); falls back to
    * `'black'` on anything else (legacy behavior).
-   * @param args - the argument Cons to parse
+   * @param arguments_ - the argument Cons to parse
    * @return CSS color string
    */
-  selectColor(args: Cons): string;
-  /**
-   * Builds the dispatch table.
-   * @return the dispatch table
-   */
-  static setup(): Map<InterpretedSymbol, string>;
+  selectColor(arguments_: Cons): string;
 }
 //#endregion
 //#region src/index.d.ts