desmost 0.10.0 → 0.11.0

package/src/compiler/compiler.ts

@@ -77,7 +77,7 @@ export class DesmostCompiler
 
 		/* To aggregate errors at the start, we need a target to retroactively inject errors into */
 		if (this.options.place_errors === "start") {
-			this.desmos.setExpression({ id: "deferred", latex: " " });  // FIXME check if ` ` needed
+			this.desmos.setExpression({ id: "desmost-deferred", type: "text", text: "" });
 		}
 
 		/* The compiler is lazy, parsing and evaluating one block at a time (as opposed to first parsing the entire AST). We don't need the whole AST, so this saves memory. */
@@ -88,13 +88,13 @@ export class DesmostCompiler
 			while (!done) {
 				done = this.compile_next();
 			}
+
+			if (this.options.keep_trailing_blanks) {
+				this.flush_pending_blanks();
+			}
 		}
 		catch (e) {
-			this.errors.push(e as Error);  // FIXME Should probably override as critical
-		}
-
-		if (this.options.keep_trailing_blanks) {
-			this.flush_pending_blanks();
+			this.evaluate_error(e as Error);
 		}
 
 		/* NOTE: No need to check `options.place_errors`!
@@ -105,12 +105,12 @@ export class DesmostCompiler
 		*/
 		if (this.errors.length > 0) {
 			this.desmos.setExpression({
-				id: "deferred",
+				id: "desmost-deferred",
 				type: "text",
-				text: this.errors.map(err => format_error(err, this.options)).join("\n\n"),
+				text: this.errors.map(err => format_error(err, this.options)).join(`\n\n`),
 			});
 		} else {
-			this.desmos.removeExpression({ id: "deferred" });
+			this.desmos.removeExpression({ id: "desmost-deferred" });
 		}
 
 		if (this.options.debug) {
@@ -244,6 +244,7 @@ export class DesmostCompiler
 	{
 		switch (this.options.errors) {
 			case "crash":
+				this.desmos.setBlank();
 				throw error;
 
 			case "suppress":

package/src/compiler/format.ts

@@ -66,7 +66,7 @@ export function prettify_latex(latex: string): string
 	latex = latex.replaceAll(/(:|,)(?!\\ ) */g, "$1\\ ");
 
 	latex = latex.replaceAll(
-		/(?<=[^\w]|^)\\?(length|mean|median|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
+		/(?<=[^\w]|^)\\?(length|mean|median|min|max|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
 		"\\operatorname{$1}"
 	);
 

package/src/decompiler/decompile.ts

@@ -1,8 +1,9 @@
-import { emit_global_incantation, emit_expression } from "./emit";
-import { extract_settings, extract_viewport, extract_expression } from "./extract";
+import { emit_incantation, emit_expression } from "./emit";
+import { extract_expression } from "./extract";
 
+import { fill_defaults, type DesmostOptions } from "../options";
 import { Ast } from "../parser";
-import type { DesmostOptions } from "../options";
+import { GLOBAL_INCANTATIONS } from "../magic";
 
 
 export interface SemiStructuredAst
@@ -13,7 +14,9 @@ export interface SemiStructuredAst
 
 
 /**
- * Decompile Desmos into raw Desmost source code.
+ * Decompile Desmos into Desmost.
+ * 
+ * This extracts relevant state from the given `desmos` calculator instance, emitting the minimal raw source code that would reconstruct that calculator instance.
  * 
  * 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.
  */
@@ -30,23 +33,36 @@ export function decompile(
 	 */
 	blank?: Desmos.Calculator,
 
-	// TODO doc
+	/**
+	 * Decompilation options.
+	 * 
+	 * See {@linkcode DesmostOptions} for available options.
+	 */
 	options?: Partial<DesmostOptions>,
 ): string
 {
-	return ast_to_source(desmos_to_ast(desmos, blank ?? desmos));
+	let opts = fill_defaults(options);
+
+	let ast = desmos_to_ast(desmos, blank ?? desmos, opts);
+	let src = ast_to_source(ast, opts);
+
+	return src;
 }
 
 /**
  * Decompile `desmos` into a semi-structured AST.
  */
-export function desmos_to_ast(desmos: Desmos.Calculator, blank: Desmos.Calculator): SemiStructuredAst
+export function desmos_to_ast(
+	desmos: Desmos.Calculator,
+	blank: Desmos.Calculator,
+	options: DesmostOptions,
+): SemiStructuredAst
 {
 	return {
 		globals: [
-			extract_settings(desmos, blank),
-			extract_viewport(desmos, blank),
-		].filter(x => x != null),
+			GLOBAL_INCANTATIONS.desmos.extract(desmos, blank),
+			GLOBAL_INCANTATIONS.viewport.extract(desmos, blank),
+		].filter(x => x != undefined),
 		locals: desmos.getExpressions().map(extract_expression),
 	};
 }
@@ -54,11 +70,11 @@ export function desmos_to_ast(desmos: Desmos.Calculator, blank: Desmos.Calculato
 /**
  * Emit the Desmost source code representation of `ast`.
  */
-export function ast_to_source(ast: SemiStructuredAst): string
+export function ast_to_source(ast: SemiStructuredAst, options: DesmostOptions): string
 {
 	return (
-      ast.globals.map(emit_global_incantation).join("\n")
-      + "\n\n"
-      + ast.locals.map(emit_expression).join("\n")
+        ast.globals.map(inc => emit_incantation(inc, options, { expand: true })).join("\n")
+      + (options.keep_leading_blanks ? "\n" : "\n\n")
+      + ast.locals.map(expr => emit_expression(expr, options)).join("\n")
 	);
 }

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();