desmost 0.8.2 → 0.9.1

package/src/compiler/compile.ts

@@ -1,6 +1,6 @@
-import { type DesmostOptions, fill_defaults } from "./options";
 import { evaluate_global_incantation, evaluate_expr, evaluate_error } from "./evaluate";
 
+import { type DesmostOptions, fill_defaults } from "../options";
 import { DesmostParser, Ast } from "../parser";
 
 
@@ -37,8 +37,12 @@ export function compile(
 	/** The Desmost source code to compile. */
 	source: string,
 
-	/** Compilation options. */
-	options?: DesmostOptions,
+	/**
+	 * Compilation options.
+	 * 
+	 * See {@linkcode DesmostOptions} for the options available.
+	*/
+	options?: Partial<DesmostOptions>,
 ): void | DesmostDebug
 {
 	if (desmos == undefined) {
@@ -95,7 +99,7 @@ export function compile(
 					break;
 
 				case Ast.Kind.EXPRESSION:
-					// @ts-expect-error: outdated types
+					// @ts-expect-error: check type-narrows
 					if (r.data.latex === " ") {
 						if (opts.ignore_all_blanks) break;
 						if (!seen_non_blank && !opts.keep_leading_blanks) break;

package/src/compiler/evaluate.ts

@@ -1,8 +1,11 @@
+import dedent from "dedent";
+
 import { format_error, normalise_latex, prettify_latex } from "./format";
-import type { DesmostOptions } from "./options";
+import type { DesmostOptions } from "../options";
 
 import { Ast } from "../parser";
 import { UnrecoverableError, type Unrecoverable } from "../errors";
+import { is_latex } from "../desmos";
 
 
 /**
@@ -11,14 +14,14 @@ import { UnrecoverableError, type Unrecoverable } from "../errors";
 export function evaluate_global_incantation(
 	invocation: Ast.IncantationInvocation,
 	desmos: Desmos.Calculator,
-	options: Required<DesmostOptions>,
+	options: 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);
+			data = invocation.incantation.evaluate_arg(invocation.arg_raw, options);
 		}
 		catch (e) {
 			let msg = evaluate_error(e as Error, desmos, options);
@@ -31,12 +34,12 @@ export function evaluate_global_incantation(
 
 
 /**
- * Evaluate arguments (if any) to local incantation invocations on `expr`, then add `expr` to `desmos`.
+ * Evaluate local incantation invocations on `expr`, then add `expr` to `desmos`.
  */
 export function evaluate_expr(
 	expr: Ast.Expression,
 	desmos: Desmos.Calculator,
-	options: Required<DesmostOptions>,
+	options: DesmostOptions,
 ): Unrecoverable<void | string>
 {
 	let errors: string[] = [];
@@ -54,31 +57,37 @@ export function evaluate_expr(
 
 		if ("arg_raw" in invocation && invocation.arg_raw != undefined) {
 			try {
-				data = invocation.incantation.evaluate_arg(invocation.arg_raw);
+				data = invocation.incantation.evaluate_arg(invocation.arg_raw, options);
 			}
 			catch (e) {
 				errors.push(format_error(e as Error, options));
+				// if it needs the arg, then we can't press on
 				if (invocation.incantation.requires_arg) continue;
 			}
 		}
 
-		invocation.incantation.apply(expr.data, data);
+		try {
+			invocation.incantation.apply(expr.data, data);
+		}
+		catch (e) {
+			errors.push(format_error(e as Error, options));
+		}
 	}
 	
 	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 (is_latex(expr.data)) {
+		expr.data.latex = normalise_latex(expr.data.latex!);
 
 		if (options.prettify) {
-			// @ts-expect-error: outdated types
 			expr.data.latex = prettify_latex(expr.data.latex);
 		}
 	}
+	else if (expr.data.type === "text" && options.dedent_text) {
+		expr.data.text = dedent(expr.data.text ?? "");
+	}
 
 	desmos.setExpression(expr.data);
 }
@@ -92,7 +101,7 @@ export function evaluate_expr(
 export function evaluate_error(
 	error: UnrecoverableError,
 	desmos: Desmos.Calculator,
-	options: Required<DesmostOptions>,
+	options: DesmostOptions,
 ): Unrecoverable<void | string>
 {
 	switch (options.errors) {

package/src/compiler/format.ts

@@ -1,18 +1,29 @@
-import type { DesmostOptions } from "./options";
+import type { DesmostOptions } from "../options";
 
 import { UnrecoverableError } from "../errors";
+import { LINE } from "../utils";
 
 
 export function format_error(
 	e: UnrecoverableError,
-	options: Required<DesmostOptions>,
+	options: 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?)
+	let display = `${prefix}${sep}${e.name}: ${e.message}`;
+
+	if (e.info != undefined && options.expand_errors) {
+		display += `\n${LINE}`;
+
+		if (e.info.hint != undefined)       display += `\nHint: ${e.info.hint}`;
+		if (e.info.note != undefined)       display += `\n${LINE}\nNote: ${e.info.note}`;
+		if (e.info.flagged_by != undefined) display += `\n${LINE}\nFlagged by: \`${e.info.flagged_by}\``;
+	}
+
+	return display;
 }
 
 
@@ -37,7 +48,9 @@ export function normalise_latex(latex: string): string
 export function prettify_latex(latex: string): string
 {
 	latex = latex.replaceAll(/(?<!\\left)(\(|\[|\\\{)/g, "\\left$1");
+	latex = latex.replaceAll(/(?:\\left\s?)+/g, "\\left");
 	latex = latex.replaceAll(/(?<!\\right)(\)|\]|\\\})/g, "\\right$1");
+	latex = latex.replaceAll(/(?:\\right\s?)+/g, "\\right");
 	latex = latex.replaceAll(/(:|,)(?!\\ ) */g, "$1\\ ");
 
 	latex = latex.replaceAll(

package/src/compiler/index.ts

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

package/src/decompiler/decompile.ts

@@ -2,6 +2,7 @@ import { emit_global_incantation, emit_expression } from "./emit";
 import { extract_settings, extract_viewport, extract_expression } from "./extract";
 
 import { Ast } from "../parser";
+import type { DesmostOptions } from "../compiler";
 
 
 export interface SemiStructuredAst
@@ -16,9 +17,24 @@ export interface SemiStructuredAst
  * 
  * 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
+export function decompile(
+	/** The Desmos calculator instance to decompile. */
+	desmos: Desmos.Calculator,
+
+	/**
+	 * The default blank Desmos calculator instance to use as a baseline.
+	 * 
+	 * It is **highly recommended** to include this, otherwise your decompiled source will have a bunch of unnecessary incantations!
+	 * 
+	 * This is used in deciding what settings are noise that can be omitted. For instance, most of your calculator settings are probably set to their default values, so there's no need to include *every single one of them* in `/desmos{}`.
+	 */
+	blank?: Desmos.Calculator,
+
+	// TODO doc
+	options?: Partial<DesmostOptions>,
+): string
 {
-	return ast_to_source(desmos_to_ast(desmos, blank));
+	return ast_to_source(desmos_to_ast(desmos, blank ?? desmos));
 }
 
 /**

package/src/decompiler/emit.ts

@@ -31,15 +31,24 @@ export function emit_expression(expr?: Ast.Expression): string
 
    switch (expr.data.type) {
       case "text":
-         content = `/text{ ${expr.data.text} }`;
+         expr.data.text ??= "";
+
+         if (expr.data.text.includes("\n")) {
+            content = `/text{\n${expr.data.text}\n}`;
+         } else {
+            content = `% ${expr.data.text}`;
+         }
          break;
+      
+      case "table":
+         content = "[tables are currently unsupported]";
+         break;
+      
       default:
-         // @ts-expect-error: outdated types
-         if (expr.data.latex?.trim() === "") {
-            content = "";
+         if (expr.data.latex?.trim() !== "") {
+            content = expr.data.latex ?? "[unsupported]";
          } else {
-            // @ts-expect-error: outdated types
-            content = expr.data.latex ?? "?";
+            content = "";
          }
    }
 

package/src/decompiler/extract.ts

@@ -1,6 +1,7 @@
 import { stringify_json5, prettify_source } from "./format";
 
 import { Ast } from "../parser";
+import { is_latex } from "../desmos";
 
 import { DesmosIncantation, ViewportIncantation } from "../magic/global";
 
@@ -69,7 +70,7 @@ export function extract_expression(expression: Desmos.ExpressionState): Ast.Expr
 {
    let data;
 
-   // @ts-expect-error: outdated types
+   // @ts-expect-error: check type-narrows
    if (expression.latex?.trim() === "") {
       data = { latex: ` ` };
    } else {
@@ -79,7 +80,7 @@ export function extract_expression(expression: Desmos.ExpressionState): Ast.Expr
       );
    }
 
-   if ("latex" in data) {
+   if (is_latex(expression)) {
       data.latex = prettify_source(data.latex);
    }
 

package/src/decompiler/format.ts

@@ -3,7 +3,7 @@ export const stringify_json5: (typeof JSON.stringify) = (
 ) =>
 {
    return (
-      /// @ts-expect-error: random `null`??
+      // @ts-expect-error: random `null`??
       JSON.stringify(data, replacer, space)
       .slice(1, -1)  // strip surrounding {}
       .trim()

package/src/decompiler/readme.md

@@ -2,7 +2,15 @@
 
 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:
+This decompiles a `Desmos.Calculator` instance into the *minimal* raw Desmost source code that could *completely* reproduce the calculator state. In other words, we want this to hold:[^equality]
+
+[^equality]: Using value equality of ‘calculator state’.
+
+```ts
+compile(decompile(calc)) == calc
+```
+
+Decompilation happens through several lowering stages:
 
 ```hs
 Desmos.Calculator -> object[] -> Ast[] -> string

package/src/desmos.ts

@@ -11,3 +11,12 @@ export enum DesmosColour
 	ORANGE = "#fa7e19",
 	BLACK  = "#000000",
 }
+
+
+/**
+ * Is `expr` a Desmos LaTeX expression (as opposed to a note or table)?
+ */
+export function is_latex(expr: Desmos.ExpressionState): expr is Desmos.Expression
+{
+	return (expr.type === undefined || expr.type === "expression");
+}

package/src/errors.ts

@@ -10,28 +10,49 @@ export type NoMatch = typeof NO_MATCH & { readonly __brand?: unique symbol };
  * 
  * 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 class UnrecoverableError extends Error
+{
+	info?: UnrecoverableError.Info;
+}
 
 export namespace UnrecoverableError
 {
+	export interface Info
+	{
+		hint?: string,
+		note?: string,
+		flagged_by?: string,
+	}
+
 	/** The parser unexpectedly reached the end of its entire input source code. */
-	export class UnexpectedEnd extends UnrecoverableError {}
+	export class UnexpectedEnd extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Unexpected End"; }
+	}
 
 	/** The parser did not receive input that it expected. */
-	export class MissingInput extends UnrecoverableError {}
+	export class MissingInput extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Missing Input"; }
+	}
 
 	/** The parser received input that did not match what it expected. */
-	export class UnexpectedInput extends UnrecoverableError {}
+	export class UnexpectedInput extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Unexpected Input"; }
+	}
 
 	/** The parser received excess input that it did not expect. */
-	export class ExcessInput extends UnrecoverableError {}
-
+	export class ExcessInput extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Excess Input"; }
+	}
 
 	/** An incantation can't be applied here. */
-	export class IllegalIncantation extends UnrecoverableError {}
+	export class IllegalIncantation extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Illegal Incantation"; }
+	}
 
 	/** An incantation's argument couldn't be parsed. */
-	export class InvalidArgument extends UnrecoverableError {}
+	export class InvalidArgument extends UnrecoverableError {
+		constructor(msg: string, override info?: Info) { super(msg); this.name = "Invalid Argument"; }
+	}
 }
 
 

package/src/index.internal.ts

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

package/src/index.ts

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

package/src/magic/.template.ts

@@ -1,22 +1,31 @@
 // import { Incantation, ArgIncantation, type GLOBAL, type LOCAL, type EXPR } from "../incantation";
 
+// import type { DesmostOptions } from "../../options";
+// import { UnrecoverableError, type Unrecoverable } from "../../errors";
+
 
 // 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
-//   }
+// 	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: ?, options: DesmostOptions): Unrecoverable<?>
+// 	{
+// 		let out = super.evaluate_arg(raw, options) as ?;
+
+// 		if (options.check_args) {
+// 			// TODO
+// 		}
+
+// 		return out;
+// 	}
 // }

package/src/magic/expr/latex.ts

@@ -10,15 +10,10 @@ export class LatexIncantation extends ArgIncantation<EXPR>
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.LATEX
 
-	apply(target: Desmos.ExpressionState, data: string): void
+	apply(target: Desmos.ExpressionState, data: string): asserts target is Desmos.Expression
 	{
 		target.type = "expression";
-		// @ts-expect-error: outdated types
+		// @ts-expect-error: previous assignment type-narrows
 		target.latex = data === "" ? " " : data;
 	}
-
-	override evaluate_arg(data: string): string
-	{
-		return data;
-	}
 }

package/src/magic/expr/text.ts

@@ -11,10 +11,10 @@ export class TextIncantation extends ArgIncantation<EXPR>
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.STRING
 
-	override apply(target: Desmos.ExpressionState, data: string)
+	override apply(target: Desmos.ExpressionState, data: string): asserts target is Desmos.Note
 	{
 		target.type = "text";
-		// @ts-expect-error: outdated types
+		// @ts-expect-error: previous assignment type-narrows
 		target.text = data;
 	}
 }

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

@@ -10,8 +10,6 @@ export class DarkModeIncantation extends Incantation<GLOBAL>
 
 	apply(target: Desmos.Calculator)
 	{
-		target.updateSettings({
-			invertedColors: true,
-		});
+		target.updateSettings({ invertedColors: true });
 	}
 }

package/src/magic/global/desmos.ts

@@ -1,5 +1,8 @@
 import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
+import { UnrecoverableError, type Unrecoverable } from "../../errors";
+import type { DesmostOptions } from "../../options";
+
 
 type DesmosSettings = Desmos.GraphConfiguration & Desmos.GraphSettings
 
@@ -7,7 +10,7 @@ type DesmosSettings = Desmos.GraphConfiguration & Desmos.GraphSettings
 export class DesmosIncantation extends ArgIncantation<GLOBAL>
 {
 	override readonly description
-		= "Set the configuration of the calculator via `Calculator.updateSettings()`."
+		= "Tweak calculator settings via `Calculator.updateSettings()`."
 	
 	override readonly identifier   = "desmos"
 	override readonly requires_arg = false
@@ -22,4 +25,23 @@ export class DesmosIncantation extends ArgIncantation<GLOBAL>
 			target.updateSettings(data);
 		}
 	}
+
+	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<DesmosSettings>
+	{
+		let out = super.evaluate_arg(raw, options) as DesmosSettings;
+
+		if (options.check_args) {
+			if (Object.keys(out).length === 0) {
+				throw new UnrecoverableError.MissingInput(
+					`/${this.identifier} received empty settings`,
+					{
+						hint: `Provide settings like \`/desmos{expressionsCollapsed: true}\``,
+						note: `Use just /desmos (without \`{}\`) if you want it as an indicator`,
+					}
+				);
+			}
+		}
+		
+		return out;
+	}
 }

package/src/magic/global/viewport.ts

@@ -1,5 +1,8 @@
 import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
+import { UnrecoverableError, type Unrecoverable } from "../../errors";
+import type { DesmostOptions } from "../../options";
+
 
 interface ViewportBounds
 {
@@ -7,6 +10,8 @@ interface ViewportBounds
 	bottom?: number; top?:   number;
 }
 
+const VALID_KEYS = ["left", "right", "bottom", "top"];
+
 
 export class ViewportIncantation extends ArgIncantation<GLOBAL>
 {
@@ -17,7 +22,7 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
 
-	apply(target: Desmos.Calculator, data: ViewportBounds)
+	override apply(target: Desmos.Calculator, data: ViewportBounds)
 	{
 		let existing = target.graphpaperBounds.mathCoordinates;
 
@@ -30,4 +35,38 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 
 		target.setMathBounds({ left, right, bottom, top });
 	}
+
+	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<ViewportBounds>
+	{
+		let out = super.evaluate_arg(raw, options) as ViewportBounds;
+
+		if (options.check_args) {
+			if (Object.keys(out).length === 0) {
+				throw new UnrecoverableError.InvalidArgument(
+					`/${this.identifier} received empty viewport bounds`,
+					{
+						hint: `Provide bounds like \`/viewport{left: -8, right: 8}\``,
+						note: `Missing bounds are kept as their defaults`,
+						flagged_by: "check_args",
+					}
+				);
+			}
+
+			let invalid_keys = Object.keys(out).filter(key => !VALID_KEYS.includes(key));
+
+			if (invalid_keys.length > 0) {
+				let plural = invalid_keys.length > 1 ? "fields" : "field";
+
+				throw new UnrecoverableError.InvalidArgument(
+					`/${this.identifier} received invalid ${plural}: [${invalid_keys.join(", ")}]`,
+					{
+						hint: `Valid fields are: [${VALID_KEYS.join(", ")}]`,
+						flagged_by: "check_args",
+					}
+				);
+			}
+		}
+
+		return out;
+	}
 }