desmost 0.8.1 → 0.9.0

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,11 +48,18 @@ 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(
-		/(?<=[^\w]|^)\\?(mean|median|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
+		/(?<=[^\w]|^)\\?(length|mean|median|count|total|repeat|join|sort|shuffle|unique|mod|ceil|floor|round|sign) ?(?=\(|\\left\()/g,
+		"\\operatorname{$1}"
+	);
+
+	latex = latex.replaceAll(
+		/\s(and|or)\s/g,
 		"\\operatorname{$1}"
 	);
 

package/src/compiler/index.ts

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

package/src/decompiler/decompile.ts

@@ -1,7 +1,9 @@
 import { emit_global_incantation, emit_expression } from "./emit";
 import { extract_settings, extract_viewport, extract_expression } from "./extract";
 
+import { fill_defaults } from "../options";
 import { Ast } from "../parser";
+import type { DesmostOptions } from "../options";
 
 
 export interface SemiStructuredAst
@@ -16,15 +18,35 @@ 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));
+	let opts = fill_defaults(options);
+	return ast_to_source(desmos_to_ast(desmos, blank ?? desmos));
 }
 
 /**
  * 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: [

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()
@@ -15,6 +15,7 @@ export const stringify_json5: (typeof JSON.stringify) = (
 export function prettify_source(source: string): string
 {
    source = source.replaceAll(/(?<=[^ ])=(?=[^ ])/g, " = ");
+   source = source.replaceAll(/\}\\/g, "} \\")
 
    return source;
 }

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;
+	}
 }

package/src/magic/incantation.ts

@@ -1,5 +1,7 @@
 import Json5 from "json5";
+import dedent from "dedent";
 
+import type { DesmostOptions } from "../options";
 import { UnrecoverableError, type Unrecoverable } from "../errors";
 
 
@@ -21,17 +23,17 @@ export abstract class Incantation<
 >
 {
 	/** Short user-facing description of what the incantation does. */
-	public abstract readonly description: string
+	abstract readonly description: string
 
 	/** The raw text sequence that matches this incantation, such as `viewport` or `hidden`. */
-	public abstract readonly identifier: string
+	abstract readonly identifier: string
 
 	/** An alternative `.identifier`, strictly for localisation purposes only. */
-	public readonly alias?: string
+	readonly alias?: string
 
 
 	/** Apply this incantation's effect to `target`, using the provided `data` if required. */
-	public abstract apply(
+	abstract apply(
 		target: Effect extends GLOBAL ? Desmos.Calculator : Desmos.ExpressionState,
 		data?: unknown,
 	): void
@@ -45,7 +47,7 @@ export abstract class Incantation<
 		if ((actual ?? "expression") !== required)
 		{
 			throw new UnrecoverableError.IllegalIncantation(
-				`/${this.identifier} can only applied to ${required === "expression" ? "latex" : required} expressions, but target block has type: ${actual}`
+				`/${this.identifier} can only applied to ${required === "expression" ? "latex" : required} blocks, but target block has type: ${actual}`
 			);
 		}
 	}
@@ -61,10 +63,10 @@ export abstract class ArgIncantation<
 	extends Incantation<Effect>
 {
 	/** Does this incantation always require an argument to be passed? */
-	public readonly requires_arg: boolean = true
+	readonly requires_arg: boolean = true
 
 	/** What type of argument does this incantation accept? */
-	public abstract readonly arg_type: Incantation.ArgType
+	abstract readonly arg_type: Incantation.ArgType
 
 
 	/**
@@ -75,14 +77,18 @@ export abstract class ArgIncantation<
 	 * ## Notes
 	 * 
 	 * Child incantation classes should override this method, though the defaults should cover most cases (except `ArgType.ENUM`).
+	 * 
+	 * Validity checks for missing or invalid values, incorrect types, and unknown fields should be performed here, so that `.apply()` can assume the data it receives is guaranteed to be valid.
 	 */
-	public evaluate_arg(raw: string): Unrecoverable<unknown>
+	evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<unknown>
 	{
 		switch (this.arg_type) {
-			case Incantation.ArgType.STRING: return raw;
 			case Incantation.ArgType.LATEX:  return raw;
 			case Incantation.ArgType.ENUM:   return raw;
 			
+			case Incantation.ArgType.STRING:
+				return (options.dedent_text) ? dedent(raw): raw.trim();
+			
 			case Incantation.ArgType.OBJECT: {
 				try {
 					return Json5.parse(`{${raw}}`);
@@ -94,9 +100,53 @@ export abstract class ArgIncantation<
 			}
 		}
 	}
+
+	protected require_nonempty(
+		arg: object,
+		msg?: string,
+		info?: UnrecoverableError.Info,
+	): Unrecoverable<void>
+	{
+		if (Object.entries(arg).length === 0) {
+			throw new UnrecoverableError.MissingInput(
+				msg ?? `/${this.identifier} received an empty argument {}`,
+				info,
+			);
+		}
+	}
+
+	protected require_known(
+		arg: object,
+		valid_fields: string[],
+		info?: UnrecoverableError.Info,
+	): Unrecoverable<void>
+	{
+		// TODO accumulate
+		for (let field of Object.keys(arg)) {
+			if (!valid_fields.includes(field)) {
+				throw new UnrecoverableError.InvalidArgument(
+					`/${this.identifier} received invalid field: ${field}`,
+					{
+						hint: `Valid fields are [${valid_fields.join(", ")}]`,
+						...info,
+					}
+				);
+			}
+		}
+	}
 }
 
 
+/** An incantation that affects the entire Desmos calculator state, like `/desmos` or `/viewport`. */
+export type GLOBAL = Incantation.Effect.GLOBAL;
+
+/** An incantation that affects only the expression immediately following it, like `/hide` or `/slider`. */
+export type LOCAL = Incantation.Effect.LOCAL;
+
+/** An incantation that produces an expression, like `/latex` or `/text`. */
+export type EXPR = Incantation.Effect.EXPR;
+
+
 export namespace Incantation
 {
 	/** The kind of effect an incantation produces - it either modifies only one block, or modifies the calculator as a whole. */
@@ -128,16 +178,3 @@ export namespace Incantation
 		OBJECT = "Object",
 	}
 }
-
-
-// == ALIASES == //
-
-/** An incantation that affects the entire Desmos calculator state, like `/desmos` or `/viewport`. */
-export type GLOBAL = Incantation.Effect.GLOBAL;
-
-/** An incantation that affects only the expression immediately following it, like `/hide` or `/slider`. */
-export type LOCAL = Incantation.Effect.LOCAL;
-
-/** An incantation that produces an expression, like `/latex` or `/text`. */
-export type EXPR = Incantation.Effect.EXPR;
-

package/src/magic/local/anim.ts

@@ -11,7 +11,6 @@ export class AnimIncantation extends Incantation<LOCAL>
 	override apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
-		// @ts-expect-error: outdated types
 		target.playing = true;
 	}
 }

package/src/magic/local/colour.ts

@@ -1,13 +1,14 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
-import { UnrecoverableError } from "../../errors";
 
 import { DesmosColour } from "../../desmos";
+import { UnrecoverableError } from "../../errors";
+import type { DesmostOptions } from "../../options";
 
 
 export class ColourIncantation extends ArgIncantation<LOCAL>
 {
 	override readonly description
-		= ""
+		= "Change the colour of a rendered expression, such as a line, region, polygon, etc."
 
 	override readonly identifier   = "color"
 	override readonly alias        = "colour"
@@ -20,7 +21,7 @@ export class ColourIncantation extends ArgIncantation<LOCAL>
 		target.color = data;
 	}
 
-	override evaluate_arg(data: string): DesmosColour
+	override evaluate_arg(data: string, options: DesmostOptions): DesmosColour
 	{
 		switch (data.trim().toUpperCase()) {
 			case "RED":    return DesmosColour.RED;