desmost 0.10.1 → 0.11.0

package/src/decompiler/emit.ts

@@ -1,56 +1,88 @@
+import { prettify_source } from "./format";
+
+import { DEFAULT_OPTIONS, type DesmostOptions } from "../options";
+import { Incantation } from "../magic";
 import type { Ast } from "../parser";
 
 
 /**
  * Emit the source code for a global incantation `invocation`.
  */
-export function emit_global_incantation(invocation?: Ast.IncantationInvocation): string
+export function emit_incantation(
+   invocation: Ast.IncantationInvocation,
+   options: DesmostOptions,
+   _?: { expand: boolean },
+): string
 {
 	if (invocation == undefined) return "";
 
    let ident = invocation.incantation.identifier;
-   let arg_raw = invocation.arg_raw;
-	
-   return `/${ident}{\n  ${arg_raw}\n}`;
+
+   if ("arg_raw" in invocation) {
+      let arg_raw = invocation.arg_raw;
+
+      if (_?.expand && invocation.incantation.arg_type === Incantation.ArgType.OBJECT) {
+         return `/${ident}{\n  ${arg_raw}\n}`;
+      } else {
+         return `/${ident}{${arg_raw}}`;
+      }
+   } else {
+      return `/${ident}`
+   }
 }
 
 
 /**
  * Emit the source code for an `expr`.
  */
-export function emit_expression(expr?: Ast.Expression): string
+export function emit_expression(
+   expr: Ast.Expression,
+   options: DesmostOptions,
+): string
 {
 	if (expr == undefined) return "";
-
-	// TODO
-   let locals: string[] = [];
-
-   let sep = expr.incantations.length > 0 ? " :: " : "";
    
-   let content;
-
    switch (expr.data.type) {
       case "text":
-         expr.data.text ??= "";
-
-         if (expr.data.text.includes("\n")) {
-            content = `/text{\n${expr.data.text}\n}`;
-         } else {
-            content = `% ${expr.data.text}`;
+         if (expr.data.text?.startsWith(DEFAULT_OPTIONS.error_prefix)) {
+            var content = `% [invalid]`;
+         }
+         else if (expr.data.text?.includes("\n")) {
+            if (options.prettify) {
+               let indented = (
+                  expr.data.text
+                  .split("\n")
+                  .map(line => `  ${line}`)
+                  .join("\n")
+               );
+               var content = `/text{\n${indented}\n}`;
+            }
+            else {
+               var content = `/text{\n${expr.data.text}\n}`
+            }
+         }
+         else {
+            var content = `% ${expr.data.text ?? ""}`;
          }
          break;
       
       case "table":
-         content = "[tables are currently unsupported]";
+         var content = "% [tables are currently unsupported]";
          break;
       
       default:
-         if (expr.data.latex?.trim() !== "") {
-            content = expr.data.latex ?? "[unsupported]";
-         } else {
-            content = "";
-         }
+         var content = (
+              expr.data.latex?.trim() === "" ? ""
+            : expr.data.latex == undefined   ? "% [unsupported]"
+            : options.prettify               ? prettify_source(expr.data.latex)
+            :                                  expr.data.latex
+         );
    }
 
-   return `${locals.join(" ")}${sep}${content}`;
+   let locals = expr.incantations.map(inc => emit_incantation(inc, options));
+
+   let sep = (locals.length > 0) ? " :: " : "";
+   let space = (locals.length >= 3  ) ? '\n' : ' ';
+
+   return `${locals.join(space)}${sep}${content}`;
 }

package/src/decompiler/extract.ts

@@ -1,103 +1,44 @@
-import { stringify_json5, prettify_source } from "./format";
-
 import { Ast } from "../parser";
-import { is_latex } from "../utils";
-
-import { DesmosIncantation, ViewportIncantation } from "../magic/global";
+import { LOCAL_INCANTATIONS } from "../magic";
+import type { LOCAL } from "../magic";
 
 
-/**
- * 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) => (
-            // @ts-expect-error: weird
-            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 },
-      /// @ts-expect-error: weird
-      (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
+export function extract_expression(expr: Desmos.ExpressionState): Ast.Expression
 {
-   let data;
-
-   // @ts-expect-error: check type-narrows
-   if (expression.latex?.trim() === "") {
-      data = { latex: ` ` };
-   } else {
-      data = Object.fromEntries(
-         Object.entries(expression)
-         .filter(([key, value]) => !is_insignificant(key, value))
-      );
-   }
-
-   if (is_latex(expression)) {
-      data.latex = prettify_source(data.latex);
-   }
-
 	return {
 		kind: Ast.Kind.EXPRESSION,
-		data,
-		incantations: [],  // TODO
+		data: (
+         expr.latex?.trim() === "" ? { latex: ` ` }
+         : {
+            type:  expr.type,
+            latex: expr.latex,
+            text:  expr.text,
+         } as Desmos.ExpressionState
+      ),
+		incantations: extract_locals(expr),
 	};
 }
 
-
-function is_insignificant(key: string, value: any): boolean
+function extract_locals(expr: Desmos.ExpressionState): Ast.IncantationInvocation<LOCAL>[]
 {
-   return (
-         value === ""
-      || typeof value === "object" && Object.values(value).every(v => v === "")
-   );
+   /* NOTE: Currently only LaTeX expressions can have local incantations applied to them, this will change in future */
+   switch (expr.type)
+   {
+      case "text":  return [];
+      case "table": return [];
+      default:
+         if (expr.latex?.trim() === "") {
+            return [];
+         }
+         else {
+            return (
+               Object.values(LOCAL_INCANTATIONS)
+               .map(inc => inc.extract(expr))
+               .filter(each => each != undefined)
+            );
+         }
+   }
 }

package/src/decompiler/format.ts

@@ -1,20 +1,9 @@
-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, " = ");
+   source = source.replaceAll(/\\left\s*(\(|\[|\\\{)/g, "$1");
+   source = source.replaceAll(/\\right\s*(\)|\]|\\\})/g, "$1");
+	source = source.replaceAll(/(:|,)\\ /g, "$1 ");
 
    return source;
 }

package/src/decompiler/readme.md

@@ -21,7 +21,7 @@ The first 2 stages are closely intertwined, so they're merged into one `desmos_t
 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
+- We can diff the AST instead of the source when doing incremental decompilation in future
 
 
 ## Extracting the AST
@@ -37,6 +37,6 @@ The main challenge here is removing unnecessary noise - we need to pick up on fi
 ## 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.
+The main concern here is ensuring the emitted source code looks like something the user would write, which means nice formatting, line breaks, spaces, indentation, 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/errors.ts

@@ -1,12 +1,14 @@
 import type { Range } from "./utils";
 
 
-/** 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 };
-
+/**
+ * Multiple aggregated errors.
+ * 
+ * Since the compiler does its best to recover from errors, it often needs to aggregate errors to report later, instead of immediately throwing.
+ */
+export class DesmostErrors {
+	constructor(public errors: DesmostError[] = []) {}
+}
 
 /**
  * The compiler encountered a fatal unrecoverable error, which will reach the end user.
@@ -28,7 +30,6 @@ export namespace DesmostError
 	export interface Data
 	{
 		msg?:   string
-		while?: string
 		hint?:  string
 		note?:  string
 		debug?: string
@@ -59,6 +60,11 @@ export namespace DesmostError
 		constructor(override data: Data) { super(data.msg, "Excess Input"); }
 	}
 
+	/** No incantation with this identifier exists. */
+	export class UnknownIncantation extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Unknown Incantation"); }
+	}
+
 	/** An incantation can't be applied here. */
 	export class IllegalIncantation extends DesmostError {
 		constructor(override data: Data) { super(data.msg, "Illegal Incantation"); }

package/src/magic/.template.ts

@@ -2,6 +2,7 @@
 
 // import type { DesmostOptions } from "../../options";
 // import { DesmostError, type Fallible } from "../../errors";
+// import { Ast } from "../../parser";
 
 
 // export class ?Incantation extends ArgIncantation<?>
@@ -28,4 +29,11 @@
 
 // 		return out;
 // 	}
+
+// 	override extract(target: ?): Ast.IncantationInvocation<?> | undefined
+// 	{
+// 		// TODO
+// 	}
 // }
+
+// export const ? = new ?Incantation();

package/src/magic/expr/index.ts

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

package/src/magic/expr/latex.ts

@@ -1,14 +1,14 @@
 import { Incantation, ArgIncantation, type EXPR } from "../incantation";
 
 
-export class LatexIncantation extends ArgIncantation<EXPR>
+class LatexIncantation extends ArgIncantation<EXPR>
 {
-	override readonly description
-		= "Produce a LaTeX expression. This allows the input to span multiple lines."
-	
+	override readonly effect       = Incantation.Effect.EXPR
 	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."
 
 	apply(target: Desmos.ExpressionState, data: string): asserts target is Desmos.Expression
 	{
@@ -16,4 +16,8 @@ export class LatexIncantation extends ArgIncantation<EXPR>
 		// @ts-expect-error: previous assignment type-narrows
 		target.latex = data === "" ? " " : data;
 	}
+
+	// TODO extract
 }
+
+export const latex = new LatexIncantation();

package/src/magic/expr/text.ts

@@ -1,15 +1,15 @@
 import { Incantation, ArgIncantation, type EXPR } from "../incantation";
 
 
-export class TextIncantation extends ArgIncantation<EXPR>
+class TextIncantation extends ArgIncantation<EXPR>
 {
-	override readonly description
-		= "Produce a text expression (“Add Note” in the Desmos GUI)."
-	
+	override readonly effect       = Incantation.Effect.EXPR
 	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 apply(target: Desmos.ExpressionState, data: string): asserts target is Desmos.Note
 	{
@@ -17,4 +17,8 @@ export class TextIncantation extends ArgIncantation<EXPR>
 		// @ts-expect-error: previous assignment type-narrows
 		target.text = data;
 	}
+
+	// TODO extract
 }
+
+export const text = new TextIncantation();

package/src/magic/global/dark.ts

@@ -0,0 +1,29 @@
+import { Incantation, type GLOBAL } from "../incantation";
+
+import { Ast } from "../../parser";
+
+
+export class DarkModeIncantation extends Incantation<GLOBAL>
+{
+	override readonly effect     = Incantation.Effect.GLOBAL
+	override readonly identifier = "dark"
+	override readonly description
+		= "Enable dark mode for the calculator, which inverts all colours."
+
+	apply(target: Desmos.Calculator)
+	{
+		target.updateSettings({ invertedColors: true });
+	}
+
+	override extract(target: Desmos.Calculator): Ast.IncantationInvocation<Incantation.Effect.GLOBAL> | void
+	{
+		if (target.settings.invertedColors) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: dark,
+			};
+		}
+	}
+}
+
+export const dark = new DarkModeIncantation();

package/src/magic/global/desmos.ts

@@ -1,7 +1,8 @@
 import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
-import { DesmostError, type Fallible } from "../../errors";
 import type { DesmostOptions } from "../../options";
+import { DesmostError, type Fallible } from "../../errors";
+import { Ast } from "../../parser";
 
 
 type DesmosSettings = Desmos.GraphConfiguration & Desmos.GraphSettings
@@ -16,10 +17,7 @@ export class DesmosIncantation extends ArgIncantation<GLOBAL>
 	override readonly requires_arg = false
 	override readonly arg_type     = Incantation.ArgType.OBJECT
 
-	override apply(
-		target: Desmos.Calculator,
-		data?: DesmosSettings,
-	): void
+	override apply(target: Desmos.Calculator, data?: DesmosSettings): void
 	{
 		if (data != undefined) {
 			target.updateSettings(data);
@@ -42,4 +40,36 @@ export class DesmosIncantation extends ArgIncantation<GLOBAL>
 		
 		return out;
 	}
+
+	override extract(
+		target: Desmos.Calculator,
+		blank: Desmos.Calculator,
+	): Ast.IncantationInvocation<Incantation.Effect.GLOBAL> | void
+	{
+		let settings = { ...target.settings };
+		let defaults = blank.settings;
+
+		for (let [key, val] of Object.entries(settings)) {
+			if (
+					val === defaults[key]
+				|| key === "__observers"
+				|| key === "guid"
+				|| key === "randomSeed"
+				|| key === "colors"
+			) {
+				delete settings[key];
+			}
+		}
+
+		let arg_raw = super.emit_object_arg(settings);
+		if (arg_raw.trim() === "") return;
+
+		return {
+			kind: Ast.Kind.INCANTATION_INVOCATION,
+			incantation: desmos,
+			arg_raw,
+		};
+	}
 }
+
+export const desmos = new DesmosIncantation();

package/src/magic/global/index.ts

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

package/src/magic/global/viewport.ts

@@ -2,6 +2,7 @@ import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
 import { DesmostError, type Fallible } from "../../errors";
 import type { DesmostOptions } from "../../options";
+import { Ast } from "../../parser";
 
 
 interface ViewportBounds
@@ -63,4 +64,32 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 
 		return out;
 	}
+
+	override extract(
+		target: Desmos.Calculator,
+		blank: Desmos.Calculator,
+	): Ast.IncantationInvocation<Incantation.Effect.GLOBAL> | void
+	{
+		let { left, right, bottom, top } = target.graphpaperBounds.mathCoordinates;
+		let bounds = { left, right, bottom, top };
+		
+		let defaults = blank.graphpaperBounds.mathCoordinates;
+
+		for (let [key, val] of Object.entries(bounds)) {
+			if (Math.abs(val - defaults[key]) < 0.001) {
+				delete bounds[key];
+			}
+		}
+
+		let arg_raw = super.emit_object_arg(bounds);
+		if (arg_raw.trim() === "") return;
+
+		return {
+			kind: Ast.Kind.INCANTATION_INVOCATION,
+			incantation: viewport,
+			arg_raw,
+		};
+	}
 }
+
+export const viewport = new ViewportIncantation();

package/src/magic/incantation.ts

@@ -2,6 +2,7 @@ import Json5 from "json5";
 import dedent from "dedent";
 
 import type { DesmostOptions } from "../options";
+import type { Ast } from "../parser";
 import { DesmostError, type Fallible } from "../errors";
 
 
@@ -18,12 +19,10 @@ import { DesmostError, type Fallible } from "../errors";
  * 
  * Incantations that accept an argument derive from `ArgIncantation`.
  */
-export abstract class Incantation<
-	Effect extends Incantation.Effect = Incantation.Effect
->
+export abstract class Incantation<Effect extends Incantation.Effect = Incantation.Effect>
 {
-	/** Short user-facing description of what the incantation does. */
-	abstract readonly description: string
+	/** Whether the incantation is a global, local or expression incantation. */
+	abstract readonly effect: Effect
 
 	/** The raw text sequence that matches this incantation, such as `viewport` or `hidden`. */
 	abstract readonly identifier: string
@@ -31,6 +30,9 @@ export abstract class Incantation<
 	/** An alternative `.identifier`, strictly for localisation purposes only. */
 	readonly alias?: string
 
+	/** Short user-facing description of what the incantation does. */
+	abstract readonly description: string
+
 
 	/** Apply this incantation's effect to `target`, using the provided `data` if required. */
 	abstract apply(
@@ -49,10 +51,20 @@ export abstract class Incantation<
 			let req = required === "expression" ? "latex" : required;
 
 			throw new DesmostError.IllegalIncantation({
-				msg: `/${this.identifier} can only applied to ${req} blocks, but target block has type: ${actual}`,
+				msg: `/${this.identifier} can only applied to \`${req}\` blocks, but target block has type: \`${actual}\``,
 			});
 		}
 	}
+
+	/**
+	 * Extract the AST representation of this incantation from `target`.
+	 * 
+	 * (The opposite of {@linkcode apply()}.)
+	*/
+	abstract extract(
+		target: Effect extends GLOBAL ? Desmos.Calculator : Desmos.ExpressionState,
+		blank?: Effect extends GLOBAL ? Desmos.Calculator : never,
+	): Ast.IncantationInvocation<Effect> | void
 }
 
 
@@ -133,6 +145,16 @@ export abstract class ArgIncantation<
 			}
 		}
 	}
+
+	/**
+	 * Stringify an object argument to its raw source text.
+	 */
+	protected emit_object_arg(data: object): string
+	{
+		let defined = Object.fromEntries(Object.entries(data).filter((k, v) => Boolean(v)));
+		
+		return Json5.stringify(defined).slice(1, -1);
+	}
 }