desmost 0.7.3 → 0.8.1

package/src/compiler/options.ts

@@ -9,97 +9,103 @@
  */
 export interface DesmostOptions
 {
-  /**
-   * How should errors be *surfaced* to 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"
+	/**
+	 * How should errors be *surfaced* to 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.
+	 *    - Note that this will *clear all expressions* in the calculator instance.
+	 * 
+	 * - `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"
+	/**
+	 * 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
+	/**
+	 * 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
 
-  /**
-   * Prettify LaTeX output so it renders nicely in the Desmos editor?
-   * 
-   * Defaults to `true`, meaning LaTeX is prettified.
-   */
-  prettify?: boolean
+	/**
+	 * Prettify LaTeX output so it renders nicely in the Desmos editor?
+	 * 
+	 * Defaults to `true`, meaning LaTeX is prettified.
+	 */
+	prettify?: boolean
 
-  /**
-   * Should `%` LaTeX comments be ignored, instead of turned into text expressions (notes)?
-   * 
-   * Defaults to `false`, meaning comments are kept.
-   */
-  ignore_comments?: boolean
+	/**
+	 * Should `%` LaTeX comments be ignored, instead of turned into text expressions (notes)?
+	 * 
+	 * 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_all_blanks?: boolean
+	/**
+	 * Should all line breaks be ignored, instead of kept as blank expressions?
+	 * 
+	 * Defaults to `false`, meaning all blank lines are kept.
+	 */
+	ignore_all_blanks?: boolean
 
-  /**
-   * Should trailing blank lines at the start of the source be kept as blank expressions?
-   * 
-   * Defaults to `false`, meaning leading blank lines are ignored.
-   */
-  keep_leading_blanks?: boolean
+	/**
+	 * Should trailing blank lines at the start of the source be kept as blank expressions?
+	 * 
+	 * Defaults to `false`, meaning leading blank lines are ignored.
+	 */
+	keep_leading_blanks?: boolean
 
-  /**
-   * Should trailing blank lines at the end of the source be kept as blank expressions?
-   * 
-   * Defaults to `false`, meaning trailing blank lines are ignored.
-   */
-  keep_trailing_blanks?: boolean
+	/**
+	 * Should trailing blank lines at the end of the source be kept as blank expressions?
+	 * 
+	 * Defaults to `false`, meaning trailing blank lines are ignored.
+	 */
+	keep_trailing_blanks?: boolean
 
-  /**
-   * Return debug diagnostics?
-   * 
-   * This includes the unevaluated AST and performance diagnostics.
-   * 
-   * Defaults to `false`, meaning `compile()` returns `void`.
-   */
-  debug?: boolean
+	/**
+	 * Return debug diagnostics?
+	 * 
+	 * This includes the unevaluated AST and performance diagnostics.
+	 * 
+	 * Defaults to `false`, meaning `compile()` returns `void`.
+	 */
+	debug?: boolean
 }
 
 
+export const DEFAULT_OPTIONS =
+{
+   errors: "surface",
+   place_errors: "inline",
+   error_prefix: "[DESMOST ERROR]\n",
+   prettify: true,
+   ignore_comments: false,
+   ignore_all_blanks: false,
+   keep_leading_blanks: false,
+   keep_trailing_blanks: false,
+   debug: false,
+};
+
+
 /**
  * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
  */
 export function fill_defaults(options: Partial<DesmostOptions> | undefined): Required<DesmostOptions>
 {
-  let out = Object.assign({}, options);
-  
-  out.errors ??= "surface";
-  out.place_errors ??= "inline";
-  out.error_prefix ??= "[DESMOST ERROR]\n";
-
-  out.prettify ??= true;
-  
-  out.ignore_comments ??= false;
-  out.ignore_all_blanks ??= false;
-  out.keep_leading_blanks ??= false;
-  out.keep_trailing_blanks ??= false;
-  out.debug ??= false;
-
-  return out as Required<DesmostOptions>;
+   return {
+      ...DEFAULT_OPTIONS,
+      ...options,
+   } as Required<DesmostOptions>;
 }

package/src/compiler/readme.md

@@ -0,0 +1,5 @@
+# Compiler
+
+This module implements the top-level logic of the Desmost -> Desmos compiler.
+
+The compiler is lazy, parsing and evaluating one block at a time (instead of constructing the entire AST and then evaluating).

package/src/decompiler/decompile.ts

@@ -0,0 +1,48 @@
+import { emit_global_incantation, emit_expression } from "./emit";
+import { extract_settings, extract_viewport, extract_expression } from "./extract";
+
+import { Ast } from "../parser";
+
+
+export interface SemiStructuredAst
+{
+   globals: Ast.IncantationInvocation[];
+	locals: Ast.Expression[];
+}
+
+
+/**
+ * Decompile Desmos into raw Desmost source code.
+ * 
+ * The caller must also supply a `blank` calculator instance. This is used as a reference for default field values, so that emitted incantations like `/desmos{}` don't get filled with a huge amount of noise.
+ */
+export function decompile(desmos: Desmos.Calculator, blank: Desmos.Calculator): string
+{
+	return ast_to_source(desmos_to_ast(desmos, blank));
+}
+
+/**
+ * Decompile `desmos` into a semi-structured AST.
+ */
+export function desmos_to_ast(desmos: Desmos.Calculator, blank: Desmos.Calculator): SemiStructuredAst
+{
+	return {
+		globals: [
+			extract_settings(desmos, blank),
+			extract_viewport(desmos, blank),
+		].filter(x => x != null),
+		locals: desmos.getExpressions().map(extract_expression),
+	};
+}
+
+/**
+ * Emit the Desmost source code representation of `ast`.
+ */
+export function ast_to_source(ast: SemiStructuredAst): string
+{
+	return (
+      ast.globals.map(emit_global_incantation).join("\n")
+      + "\n\n"
+      + ast.locals.map(emit_expression).join("\n")
+	);
+}

package/src/decompiler/emit.ts

@@ -0,0 +1,47 @@
+import type { Ast } from "../parser";
+
+
+/**
+ * Emit the source code for a global incantation `invocation`.
+ */
+export function emit_global_incantation(invocation?: Ast.IncantationInvocation): string
+{
+	if (invocation == undefined) return "";
+
+   let ident = invocation.incantation.identifier;
+   let arg_raw = invocation.arg_raw;
+	
+   return `/${ident}{\n  ${arg_raw}\n}`;
+}
+
+
+/**
+ * Emit the source code for an `expr`.
+ */
+export function emit_expression(expr?: Ast.Expression): string
+{
+	if (expr == undefined) return "";
+
+	// TODO
+   let locals: string[] = [];
+
+   let sep = expr.incantations.length > 0 ? " :: " : "";
+   
+   let content;
+
+   switch (expr.data.type) {
+      case "text":
+         content = `/text{ ${expr.data.text} }`;
+         break;
+      default:
+         // @ts-expect-error: outdated types
+         if (expr.data.latex?.trim() === "") {
+            content = "";
+         } else {
+            // @ts-expect-error: outdated types
+            content = expr.data.latex ?? "?";
+         }
+   }
+
+   return `${locals.join(" ")}${sep}${content}`;
+}

package/src/decompiler/extract.ts

@@ -0,0 +1,100 @@
+import { stringify_json5, prettify_source } from "./format";
+
+import { Ast } from "../parser";
+
+import { DesmosIncantation, ViewportIncantation } from "../magic/global";
+
+
+/**
+ * Extract a `/desmos` incantation from the settings of `desmos`.
+ */
+export function extract_settings(
+   desmos: Desmos.Calculator,
+   blank: Desmos.Calculator,
+): Ast.IncantationInvocation | null
+{
+   let defaults = blank.settings;
+
+   let arg_raw = stringify_json5(
+      desmos.settings,
+      (k, v) => (
+            v === defaults[k]
+         || k === "__observers"
+         || k === "guid"
+         || k === "randomSeed"
+         || k === "colors"
+      ) ? undefined : v,
+      "  ",
+   );
+
+   if (arg_raw.trim() === "") return null;
+
+	return {
+		kind: Ast.Kind.INCANTATION_INVOCATION,
+		incantation: new DesmosIncantation(),
+		arg_raw,
+	};
+}
+
+/**
+ * Extract a `/viewport` incantation from the viewport bounds of `desmos`.
+ */
+export function extract_viewport(
+   desmos: Desmos.Calculator,
+   blank: Desmos.Calculator,
+): Ast.IncantationInvocation | null
+{
+   let defaults = blank.graphpaperBounds.mathCoordinates;
+	let { left, right, bottom, top } = desmos.graphpaperBounds.mathCoordinates;
+
+   let arg_raw = stringify_json5(
+      { left, right, bottom, top },
+      (k, v) => v === defaults[k] ? undefined : v,
+      "  ",
+   );
+
+   if (arg_raw.trim() === "") return null;
+
+	return {
+		kind: Ast.Kind.INCANTATION_INVOCATION,
+		incantation: new ViewportIncantation(),
+		arg_raw,
+	};
+}
+
+/**
+ * Extract an expression and the local incantations that reproduce its state.
+ */
+export function extract_expression(expression: Desmos.ExpressionState): Ast.Expression
+{
+   let data;
+
+   // @ts-expect-error: outdated types
+   if (expression.latex?.trim() === "") {
+      data = { latex: ` ` };
+   } else {
+      data = Object.fromEntries(
+         Object.entries(expression)
+         .filter(([key, value]) => !is_insignificant(key, value))
+      );
+   }
+
+   if ("latex" in data) {
+      data.latex = prettify_source(data.latex);
+   }
+
+	return {
+		kind: Ast.Kind.EXPRESSION,
+		data,
+		incantations: [],  // TODO
+	};
+}
+
+
+function is_insignificant(key: string, value: any): boolean
+{
+   return (
+         value === ""
+      || typeof value === "object" && Object.values(value).every(v => v === "")
+   );
+}

package/src/decompiler/format.ts

@@ -0,0 +1,20 @@
+export const stringify_json5: (typeof JSON.stringify) = (
+   data, replacer, space
+) =>
+{
+   return (
+      /// @ts-expect-error: random `null`??
+      JSON.stringify(data, replacer, space)
+      .slice(1, -1)  // strip surrounding {}
+      .trim()
+      .replaceAll(/"([^"]+)":/g, "$1:")  // "key": <value> -> key: <value>
+   );
+}
+
+
+export function prettify_source(source: string): string
+{
+   source = source.replaceAll(/(?<=[^ ])=(?=[^ ])/g, " = ");
+
+   return source;
+}

package/src/decompiler/index.ts

@@ -0,0 +1 @@
+export { decompile } from "./decompile";

package/src/decompiler/readme.md

@@ -0,0 +1,34 @@
+# Decompiler
+
+This module implements the Desmos -> Desmost decompiler.
+
+This decompiles a `Desmos.Calculator` instance into the *minimal* raw Desmost source code that could *completely* reproduce the calculator state. Decompilation happens through several lowering stages:
+
+```hs
+Desmos.Calculator -> object[] -> Ast[] -> string
+```
+
+The first 2 stages are closely intertwined, so they're merged into one `desmos_to_ast()` function.
+
+Technically it'd be more performant to directly emit instead of constructing the intermediate AST, but doing it this way means:
+
+- We can access the AST for debug information (in Playground)
+- We can diff the AST instead of the source when doing incremenetal decompilation in future
+
+
+## Extracting the AST
+`Desmos.Calculator -> object[] -> Ast[]`
+
+We need to not only extract the expressions in the editor with `.getExpressions()`, but also other global calculator state like `.graphpaperBounds`.
+
+We then transform those raw objects into `Ast` nodes.
+
+The main challenge here is removing unnecessary noise - we need to pick up on fields that *wouldn't* be covered by defaults and include them as incantations, but ignore everything else to avoid producing humongous `/desmos{ p, q, r, s, t }` slop.
+
+
+## Emitting the Source
+`Ast[] -> string`
+
+The main concern here is ensuring the emitted source code looks like something the user would write, which means nice formatting, line breaks, spaces, indentatino, etc.
+
+Once we try implementing incremental decompilation, this will be the hardest part because we need to reconcile changes with the user's existing source code, respecting where their formatting deviates from the autogenerated output (currently their entire source code may be shuffled around when decompiling, which is terrible UX).

package/src/desmos.ts

@@ -4,10 +4,10 @@
 
 export enum DesmosColour
 {
-  RED    = "#c74440",
-  BLUE   = "#2d70b3",
-  GREEN  = "#388c46",
-  PURPLE = "#6042a6",
-  ORANGE = "#fa7e19",
-  BLACK  = "#000000",
+	RED    = "#c74440",
+	BLUE   = "#2d70b3",
+	GREEN  = "#388c46",
+	PURPLE = "#6042a6",
+	ORANGE = "#fa7e19",
+	BLACK  = "#000000",
 }

package/src/errors.ts

@@ -1,3 +1,10 @@
+/** The parser failed to parse something (usually during speculative parsing), which only results in internal backtracking. */
+export const NO_MATCH = Symbol("no-match");
+
+/** The compiler encountered a non-fatal recoverable failure (usually during speculative parsing), which only results in internal backtracking. */
+export type NoMatch = typeof NO_MATCH & { readonly __brand?: unique symbol };
+
+
 /**
  * The compiler encountered a fatal unrecoverable error, which will reach the end user.
  * 
@@ -7,33 +14,26 @@ 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 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 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 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 {}
+	/** 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 can't be applied here. */
+	export class IllegalIncantation extends UnrecoverableError {}
 
-  /** An incantation's argument couldn't be parsed. */
-  export class InvalidArgument extends UnrecoverableError {}
+	/** An incantation's argument couldn't be parsed. */
+	export class InvalidArgument extends UnrecoverableError {}
 }
 
 
-/** The parser failed to parse something (usually during speculative parsing), which only results in internal backtracking. */
-export const NO_MATCH = Symbol("no-match");
-
-/** The compiler encountered a non-fatal recoverable failure (usually during speculative parsing), which only results in internal backtracking. */
-export type NoMatch = typeof NO_MATCH & { readonly __brand?: unique symbol };
-
-
 /** Indicates that a function may throw an `UnrecoverableError`. */
 export type Unrecoverable<Result> = Result | Result & { readonly __brand?: unique symbol };

package/src/index.internal.ts

@@ -1,4 +1,6 @@
-export { fill_defaults } from "./compiler/options";
+export { fill_defaults, DEFAULT_OPTIONS } from "./compiler/options";
 export type { DesmostDebug } from "./compiler/compile";
 
 export { Ast } from "./parser";
+
+export { desmos_to_ast, ast_to_source } from "./decompiler/decompile";

package/src/index.ts

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

package/src/magic/expr/index.ts

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

package/src/magic/expr/latex.ts

@@ -3,22 +3,22 @@ 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
+	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 === "" ? " " : data;
-  }
+	apply(target: Desmos.ExpressionState, data: string): void
+	{
+		target.type = "expression";
+		// @ts-expect-error: outdated types
+		target.latex = data === "" ? " " : data;
+	}
 
-  override evaluate_arg(data: string): string
-  {
-    return data;
-  }
+	override evaluate_arg(data: string): string
+	{
+		return data;
+	}
 }

package/src/magic/expr/text.ts

@@ -3,18 +3,18 @@ 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 alias        = "note"
-  override readonly requires_arg = true
-  override readonly arg_type     = Incantation.ArgType.STRING
+	override readonly description
+		= "Produce a text expression (“Add Note” in the Desmos GUI)."
+	
+	override readonly identifier   = "text"
+	override readonly alias        = "note"
+	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;
-  }
+	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

@@ -3,15 +3,15 @@ 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"
+	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,
-    });
-  }
+	apply(target: Desmos.Calculator)
+	{
+		target.updateSettings({
+			invertedColors: true,
+		});
+	}
 }