desmost 0.1.0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "desmost",
+  "author": "Sup#2.0",
+  "version": "0.1.0",
+  "license": "MIT",
+
+  "description": "A tiny DSL for compiling LaTeX to Desmos",
+  "keywords": [
+    "desmos", "latex", "desmost"
+  ],
+
+  "homepage": "https://github.com/Sup2point0/desmost",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sup2point0/desmost.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sup2point0/desmost/issues"
+  },
+  
+  "type": "module",
+  "files": [
+    "./src/",
+    "./dist/",
+    "package.json"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+
+  "scripts": {
+    "build":   "tsc -p ./tsconfig.build.json",
+
+    "test":    "vitest run",
+      "testw": "vitest",
+
+    "check":   "npx oxlint src"
+  },
+
+  "dependencies":
+  {
+    "json5": "^2.2"
+  },
+
+  "devDependencies":
+  {
+    "@eslint/js": "^10.0",
+    "@types/desmos": "1.11",
+    "@types/node": "^26.0",
+    "oxlint": "^1.78",
+    "oxlint-tsgolint": "^7.0",
+    "typescript": "^7.0",
+    "vitest": "^4.0"
+  }
+}

package/src/compiler/compile.ts

@@ -0,0 +1,127 @@
+import { type DesmostOptions, set_default_options } from "./options";
+import { evaluate_global_incantation, evaluate_expr, evaluate_error } from "./evaluate";
+
+import { DesmostParser, Ast } from "../parser";
+import { UnrecoverableError } from "../errors";
+
+
+/**
+ * Compile Desmost into Desmos.
+ * 
+ * This calls the Desmost compiler: parsing and evaluating `source`, then injecting the results into an existing `desmos` instance. Pass in `options` to customise compilation.
+ * 
+ * ## Example
+ * 
+ * ```ts
+ * let calc = Desmos.GraphingCalculator();
+ * 
+ * compile(calc, `/text{ sup world! }`);
+ * 
+ * compile(calc, `/slider{ error! } :: t = 0`, {
+ *   errors: "crash",
+ * });
+ * ```
+ */
+export function compile(
+  /** The Desmos calculator instance to compile into. */
+  desmos: Desmos.Calculator,
+
+  /** The Desmost source code to compile. */
+  source: string,
+
+  /** Compilation options. */
+  options?: DesmostOptions,
+): void | DesmostDebug
+{
+  if (desmos == undefined) {
+    console.error(`Desmost: No \`Desmos.Calculator\` instance provided, aborting compilation!`);
+    return;
+  }
+
+  if (source == undefined) {
+    console.error(`Desmost: No source code provided, aborting compilation!`);
+    return;
+  }
+
+  let t_init = performance.now();
+  let ast = [];
+
+  let opts = set_default_options(options);
+  let parser = new DesmostParser(source, opts);
+  
+  /* To aggregate errors at the start, we need a target to retroactively inject errors into */
+  if (opts.place_errors === "start") {
+    desmos.setExpression({ id: "deferred-start", latex: "" });
+  }
+
+  let errors = [];
+
+  try {
+    while (true) {
+      let r = parser.parse_next();
+      if (r === null) break;
+
+      if (opts.debug) {
+        ast.push(r);
+      }
+
+      let defer: string | void;
+      
+      switch (r.kind) {
+        case Ast.Kind.INCANTATION_INVOCATION:
+          defer = evaluate_global_incantation(r, desmos, opts);
+          break;
+
+        case Ast.Kind.EXPRESSION:
+          defer = evaluate_expr(r, desmos, opts);
+          break;
+
+        case Ast.Kind.INVALID_INCANTATION:
+          defer = evaluate_error(r.error, desmos, opts);
+          break;
+      }
+
+      if (defer !== undefined) {
+        errors.push(defer);
+      }
+    }
+  }
+  catch (e) {
+    if (e instanceof UnrecoverableError) {
+      errors = [e.message];
+    } else {
+      throw e;
+    }
+  }
+
+  if (errors.length > 0) {
+    let expr: Desmos.ExpressionState = {
+      type: "text",
+      text: errors.join("\n\n"),
+    };
+
+    switch (opts.place_errors) {
+      case "start":
+        desmos.setExpression({ ...expr, id: "deferred-start" });
+        break;
+      case "end":
+      case "inline":
+        desmos.setExpression(expr);
+        break;
+    }
+  }
+
+  if (opts.debug) {
+    return {
+      duration: performance.now() - t_init,
+      ast,
+    };
+  }
+}
+
+
+interface DesmostDebug
+{
+  duration: number;
+  ast: Ast[];
+}

package/src/compiler/evaluate.ts

@@ -0,0 +1,121 @@
+import type { DesmostOptions } from "./options";
+
+import { Ast } from "../parser";
+import { UnrecoverableError, type Unrecoverable } from "../errors";
+
+
+/**
+ * Evaluate arguments (if any) to a global incantation `invocation`, then apply the incantation to `desmos`.
+ */
+export function evaluate_global_incantation(
+  invocation: Ast.IncantationInvocation,
+  desmos: Desmos.Calculator,
+  options: Required<DesmostOptions>,
+): Unrecoverable<void | string>
+{
+  let data = undefined;
+
+  if ("arg_raw" in invocation && invocation.arg_raw != undefined) {
+    try {
+      data = invocation.incantation.evaluate_arg(invocation.arg_raw);
+    }
+    catch (e) {
+      let msg = evaluate_error(e as Error, desmos, options);
+      if (msg != undefined) {
+        return msg;
+      }
+    }
+  }
+
+  invocation.incantation.apply(desmos, data);
+}
+
+
+/**
+ * Evaluate arguments (if any) to local incantation invocations on `expr`, then add `expr` to `desmos`.
+ */
+export function evaluate_expr(
+  expr: Ast.Expression,
+  desmos: Desmos.Calculator,
+  options: Required<DesmostOptions>,
+): Unrecoverable<void | string>
+{
+  let errors: string[] = [];
+
+  for (let invocation of expr.incantations) {
+    if (invocation.kind === Ast.Kind.INVALID_INCANTATION) {
+      let msg = evaluate_error(invocation.error, desmos, { ...options, place_errors: "start" });
+      if (msg != undefined) {
+        errors.push(msg);
+      }
+      continue;
+    }
+
+    let data = undefined;
+
+    if ("arg_raw" in invocation && invocation.arg_raw != undefined) {
+      try {
+        data = invocation.incantation.evaluate_arg(invocation.arg_raw);
+      }
+      catch (e) {
+        errors.push(format_error(e as Error, options));
+        if (invocation.incantation.requires_arg) continue;
+      }
+    }
+
+    invocation.incantation.apply(expr.data, data);
+  }
+  
+  if (errors.length > 0) {
+    desmos.setExpression({ type: "text", text: errors.join("\n\n") });
+  }
+  desmos.setExpression(expr.data);
+}
+
+
+/**
+ * Handle an `InvalidInvocation`, respecting the user's preferences in `options`.
+ * 
+ * If the user set `place_errors: start` or `place_errors: end`, this returns the formatted error message for deferred aggregation.
+ */
+export function evaluate_error(
+  error: UnrecoverableError,
+  desmos: Desmos.Calculator,
+  options: Required<DesmostOptions>,
+): Unrecoverable<void | string>
+{
+  switch (options.errors) {
+    case "crash":
+      throw error;
+
+    case "suppress":
+      console.error(error);
+      break;
+
+    default: switch (options.place_errors) {
+      case "end":
+      case "start":
+        return format_error(error, options);
+      
+      default:
+        desmos.setExpression({
+          type: "text",
+          text: format_error(error, options),
+        });
+        break;
+    }
+  }
+}
+
+
+function format_error(
+  e: UnrecoverableError,
+  options: Required<DesmostOptions>,
+): string
+{
+  let prefix = options.error_prefix;
+  let sep = (prefix === "" || prefix.endsWith("\n")) ? "" : " ";
+
+  return `${prefix}${sep}${e.name}: ${e.message}`;
+  // TODO maybe include stack? (configurable?)
+}

package/src/compiler/index.ts

@@ -0,0 +1,2 @@
+export { compile } from "./compile";
+export type { DesmostOptions } from "./options";

package/src/compiler/options.ts

@@ -0,0 +1,77 @@
+/** Options to customise Desmost compilation. */
+export interface DesmostOptions
+{
+  /**
+   * How should errors be *surfaced*?
+   * 
+   * Errors will always be logged to console for the developer; this setting affects how they visually reach the end user.
+   * 
+   * - `surface` (default): Blocks that result in errors will become Desmos text expressions containing the error message, leaving other expressions unaffected.
+   * - `crash`: The entire compilation to Desmos will terminate with a single error message. This means you don't get any output at all, but errors are also immediately obvious.
+   * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine).
+   */
+  errors?: "surface" | "crash" | "suppress"
+
+  /**
+   * Where should errors be placed?
+   * 
+   * - `inline` (default): Alongside or in place of the expression that produced it.
+   * - `end`: All aggregated at the end of the Desmos expressions list.
+   * - `start`: All aggregated at the start of the Desmos expressions list.
+   */
+  place_errors?: "inline" | "end" | "start"
+
+  /**
+   * The prefix to prepend to error blocks. Defaults to `[DESMOST ERROR]\n`. Provide a blank string if you wish for no prefix to be added.
+   */
+  error_prefix?: string
+
+  /**
+   * Should comments be ignored, instead of turned into text expressions?
+   * 
+   * Defaults to `false`, meaning comments are kept.
+   */
+  ignore_comments?: boolean
+
+  /**
+   * Should all line breaks be ignored, instead of kept as blank expressions.
+   * 
+   * Defaults to `false`, meaning all blank lines are kept.
+   */
+  ignore_line_breaks?: boolean
+
+  /**
+   * Should trailing blank lines at the end of the source be ignored, instead of kept as blank expressions?
+   * 
+   * Defaults to `false`, meaning trailing blank lines are kept.
+   */
+  ignore_trailing_blanks?: boolean
+
+  /**
+   * Return debug diagnostics? This includes the unevaluated AST, and performance diagnostics.
+   * 
+   * Defaults to `false`.
+   */
+  debug?: boolean
+}
+
+
+/**
+ * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
+ */
+export function set_default_options(options: Partial<DesmostOptions> | undefined): Required<DesmostOptions>
+{
+  options ??= {};
+  
+  options.errors ??= "surface";
+  options.place_errors ??= "inline";
+  options.error_prefix ??= "[DESMOST ERROR]\n";
+  
+  options.ignore_comments ??= false;
+  options.ignore_line_breaks ??= false;
+  options.ignore_trailing_blanks ??= false;
+
+  options.debug ??= false;
+
+  return options as Required<DesmostOptions>;
+}

package/src/desmos.ts

@@ -0,0 +1,13 @@
+/**
+ * The Desmos API (currently) is browser-only, so we polyfill the API objects we need here for the server-side.
+ */
+
+export enum DesmosColour
+{
+  RED    = "#c74440",
+  BLUE   = "#2d70b3",
+  GREEN  = "#388c46",
+  PURPLE = "#6042a6",
+  ORANGE = "#fa7e19",
+  BLACK  = "#000000",
+}

package/src/errors.ts

@@ -0,0 +1,46 @@
+/**
+ * The compiler encountered a fatal unrecoverable error, which will reach the end user.
+ * 
+ * It's not *literally* unrecoverable in the sense that it will crash the compiler completely, but it means there are no further fallbacks to try.
+ */
+export class UnrecoverableError extends Error {}
+
+export namespace UnrecoverableError
+{
+  /** The parser unexpectedly reached the end of its entire input source code. */
+  export class UnexpectedEnd extends UnrecoverableError {}
+
+  /** The parser did not receive input that it expected. */
+  export class MissingInput extends UnrecoverableError {}
+
+  /** The parser received input that did not match what it expected. */
+  export class UnexpectedInput extends UnrecoverableError {}
+
+  /** The parser received excess input that it did not expect. */
+  export class ExcessInput extends UnrecoverableError {}
+
+
+  /** An incantation can't be applied here. */
+  export class IllegalIncantation extends UnrecoverableError {}
+
+  /** An incantation's argument couldn't be parsed. */
+  export class InvalidArgument extends UnrecoverableError {}
+}
+
+
+/** The compiler encountered a non-fatal recoverable failure (usually during speculative parsing), which only results in internal backtracking. */
+export class RecoverableFail {}
+
+
+/** Indicates that a function may throw a `RecoverableFail`. */
+export type Recoverable<Result> = Result | Result & { readonly __brand?: unique symbol };
+
+/** Indicates that a function may throw an `UnrecoverableError`. */
+export type Unrecoverable<Result> = Result | Result & { readonly __brand?: unique symbol };;
+
+/**
+ * Indicates that a function may throw either a `RecoverableFail` *or* an `UnrecoverableError`.
+ * 
+ * This is used in potentially ambiguous cases. For instance, the user might have invoked an unknown incantation, in which case we might want to `RecoverableFail` and fallback to parsing it as LaTeX; on the other hand, if they invoked a valid incantation, but did not supply the required argument, that's a definite `UnrecoverableError`.
+ */
+export type MaybeRecoverable<Result> = Recoverable<Result> | Unrecoverable<Result>;

package/src/index.ts

@@ -0,0 +1 @@
+export { compile, type DesmostOptions } from "./compiler";

package/src/magic/.template.ts

@@ -0,0 +1,22 @@
+// import { Incantation, ArgIncantation, type GLOBAL, type LOCAL, type EXPR } from "../incantation";
+
+
+// export class ?Incantation extends ArgIncantation<?>
+// {
+//   override readonly description
+//     = ""
+
+//   override readonly identifier   = ?
+//   override readonly requires_arg = ?
+//   override readonly arg_type     = Incantation.ArgType.?
+
+//   override apply(target: ?, data: ?)
+//   {
+//     // TODO
+//   }
+
+//   override evaluate_arg(raw: ?): ?
+//   {
+//     // TODO
+//   }
+// }

package/src/magic/expr/index.ts

@@ -0,0 +1,11 @@
+import { ArgIncantation, type EXPR } from "../incantation";
+
+import { LatexIncantation } from "./latex";
+import { TextIncantation } from "./text";
+
+
+export const EXPR_INCANTATIONS: ArgIncantation<EXPR>[] =
+[
+  new LatexIncantation(),
+  new TextIncantation(),
+];

package/src/magic/expr/latex.ts

@@ -0,0 +1,24 @@
+import { Incantation, ArgIncantation, type EXPR } from "../incantation";
+
+
+export class LatexIncantation extends ArgIncantation<EXPR>
+{
+  override readonly description
+    = "Produce a LaTeX expression. This allows the input to span multiple lines."
+  
+  override readonly identifier   = "latex"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.LATEX
+
+  apply(target: Desmos.ExpressionState, data: string): void
+  {
+    target.type = "expression";
+    // @ts-expect-error: outdated types
+    target.latex = data;
+  }
+
+  override evaluate_arg(data: string): string
+  {
+    return data;
+  }
+}

package/src/magic/expr/text.ts

@@ -0,0 +1,19 @@
+import { Incantation, ArgIncantation, type EXPR } from "../incantation";
+
+
+export class TextIncantation extends ArgIncantation<EXPR>
+{
+  override readonly description
+    = "Produce a text expression (“Add Note” in the Desmos GUI)."
+  
+  override readonly identifier   = "text"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.STRING
+
+  override apply(target: Desmos.ExpressionState, data: string)
+  {
+    target.type = "text";
+    // @ts-expect-error: outdated types
+    target.text = data;
+  }
+}

package/src/magic/global/dark-mode.ts

@@ -0,0 +1,17 @@
+import { Incantation, type GLOBAL } from "../incantation";
+
+
+export class DarkModeIncantation extends Incantation<GLOBAL>
+{
+  override readonly description
+    = "Enable dark mode for the calculator, which inverts all colours."
+  
+  override readonly identifier = "dark"
+
+  apply(target: Desmos.Calculator)
+  {
+    target.updateSettings({
+      invertedColors: true,
+    });
+  }
+}

package/src/magic/global/desmos.ts

@@ -0,0 +1,20 @@
+import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
+
+
+export class DesmosIncantation extends ArgIncantation<GLOBAL>
+{
+  override readonly description
+    = "Set the configuration of the calculator via `Calculator.updateSettings()`."
+  
+  override readonly identifier   = "desmos"
+  override readonly requires_arg = false
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  override apply(
+    target: Desmos.Calculator,
+    data: Desmos.GraphConfiguration & Desmos.GraphSettings,
+  ): void
+  {
+    target.updateSettings(data);
+  }
+}

package/src/magic/global/index.ts

@@ -0,0 +1,13 @@
+import { Incantation, type GLOBAL } from "../incantation";
+
+import { DesmosIncantation } from "./desmos";
+import { ViewportIncantation } from "./viewport";
+import { DarkModeIncantation } from "./dark-mode";
+
+
+export const GLOBAL_INCANTATIONS: Incantation<GLOBAL>[] =
+[
+  new DesmosIncantation(),
+  new ViewportIncantation(),
+  new DarkModeIncantation(),
+];

package/src/magic/global/viewport.ts

@@ -0,0 +1,25 @@
+import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
+
+
+interface ViewportBounds
+{
+  left:   number; right: number;
+  bottom: number; top:   number;
+}
+
+
+export class ViewportIncantation extends ArgIncantation<GLOBAL>
+{
+  override readonly description
+    = "Set the bounds of the viewport via `Calculator.setMathBounds()`."
+  
+  override readonly identifier   = "viewport"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  apply(target: Desmos.Calculator, data: ViewportBounds)
+  {
+    // TODO validate bounds
+    target.setMathBounds(data);
+  }
+}