desmost 0.7.2 → 0.8.0

package/src/compiler/evaluate.ts

@@ -1,4 +1,4 @@
-import { format_error } from "./format";
+import { format_error, normalise_latex, prettify_latex } from "./format";
 import type { DesmostOptions } from "./options";
 
 import { Ast } from "../parser";
@@ -9,26 +9,24 @@ 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>,
+	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);
+	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);
+			return msg;
+		}
+	}
+
+	invocation.incantation.apply(desmos, data);
 }
 
 
@@ -36,53 +34,53 @@ export function evaluate_global_incantation(
  * 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>,
+	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") });
-  }
-
-  // @ts-expect-error: outdated types
-  if (expr.data.latex != undefined) {
-    // @ts-expect-error: outdated types
-    expr.data.latex = normalise_latex(expr.data.latex);
-
-    if (options.prettify) {
-      // @ts-expect-error: outdated types
-      expr.data.latex = prettify_latex(expr.data.latex);
-    }
-  }
-
-  desmos.setExpression(expr.data);
+	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") });
+	}
+
+	// @ts-expect-error: outdated types
+	if (expr.data.latex != undefined) {
+		// @ts-expect-error: outdated types
+		expr.data.latex = normalise_latex(expr.data.latex);
+
+		if (options.prettify) {
+			// @ts-expect-error: outdated types
+			expr.data.latex = prettify_latex(expr.data.latex);
+		}
+	}
+
+	desmos.setExpression(expr.data);
 }
 
 
@@ -92,62 +90,30 @@ export function evaluate_expr(
  * 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>,
+	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;
-    }
-  }
-}
-
-
-/**
- * Remove line breaks from `latex` so Desmos can properly consume it.
- */
-function normalise_latex(latex: string): string
-{
-  latex = latex.replaceAll(/\s+/g, " ");
-  return latex;
-}
-
-
-/**
- * Prettify `latex` to render nicely in Desmos, reflecting how you would type directly into Desmos.
- * 
- * This includes:
- * 
- * - Replace `()`, `[]`, etc. with `\left(\right)`
- * - Replace `min()`, `max()`, etc. with `\operatorname{min}()`
- */
-function prettify_latex(latex: string): string
-{
-  latex = latex.replaceAll(/(?<!\\left)(\(|\[|\\\{)/g, "\\left$1");
-  latex = latex.replaceAll(/(?<!\\right)(\)|\]|\\\})/g, "\\right$1");
-
-  latex = latex.replaceAll(
-    /(?<=[^\w]|^)\\?(mean|median|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
-    "\\operatorname{$1}"
-  );
-
-  return latex;
+	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;
+		}
+	}
 }

package/src/compiler/format.ts

@@ -4,13 +4,46 @@ import { UnrecoverableError } from "../errors";
 
 
 export function format_error(
-  e: UnrecoverableError,
-  options: Required<DesmostOptions>,
+	e: UnrecoverableError,
+	options: Required<DesmostOptions>,
 ): string
 {
-  let prefix = options.error_prefix;
-  let sep = (prefix === "" || prefix.endsWith("\n")) ? "" : " ";
+	let prefix = options.error_prefix;
+	let sep = (prefix === "" || prefix.endsWith("\n")) ? "" : " ";
 
-  return `${prefix}${sep}${e.name}: ${e.message}`;
-  // TODO maybe include stack? (configurable?)
+	return `${prefix}${sep}${e.name}: ${e.message}`;
+	// TODO maybe include stack? (configurable?)
+}
+
+
+/**
+ * Remove line breaks from `latex` so Desmos can properly consume it.
+ */
+export function normalise_latex(latex: string): string
+{
+	latex = latex.replaceAll(/\s+/g, " ");
+	return latex;
+}
+
+
+/**
+ * Prettify `latex` to render nicely in Desmos, reflecting how you would type directly into Desmos.
+ * 
+ * This includes:
+ * 
+ * - Replace `()`, `[]`, etc. with `\left(\right)`
+ * - Replace `min()`, `max()`, etc. with `\operatorname{min}()`
+ */
+export function prettify_latex(latex: string): string
+{
+	latex = latex.replaceAll(/(?<!\\left)(\(|\[|\\\{)/g, "\\left$1");
+	latex = latex.replaceAll(/(?<!\\right)(\)|\]|\\\})/g, "\\right$1");
+	latex = latex.replaceAll(/(:|,)(?!\\ ) */g, "$1\\ ");
+
+	latex = latex.replaceAll(
+		/(?<=[^\w]|^)\\?(mean|median|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
+		"\\operatorname{$1}"
+	);
+
+	return latex;
 }

package/src/compiler/options.ts

@@ -9,76 +9,79 @@
  */
 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
 }
 
 
@@ -87,19 +90,19 @@ export interface DesmostOptions
  */
 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";
+	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;
+	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 out as Required<DesmostOptions>;
 }

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";