desmost 0.9.1 → 0.10.1

package/src/compiler/compiler.ts

@@ -0,0 +1,275 @@
+import dedent from "dedent";
+
+import { format_error, normalise_latex, prettify_latex } from "./format";
+
+import type { DesmostOptions } from "../options";
+import { DesmostError, type Fallible } from "../errors";
+import { DesmostParser, Ast } from "../parser";
+import { is_latex } from "../utils";
+
+
+/** Debug diagnostics returned from `compile()`. */
+export interface DesmostDebug
+{
+	duration: number;
+	num_blocks: number;
+	ast: Ast[];
+}
+
+
+export class DesmostCompiler
+{
+	private desmos: Desmos.Calculator
+
+	/** The source code to compile. */
+	private source: string
+
+	private options: DesmostOptions
+
+	private parser: DesmostParser
+
+	/** Accumulated errors awaiting evaluation. */
+	private errors: DesmostError[] = []
+
+	/**
+	 * Have we only seen blank lines so far?
+	 * 
+	 * This is used for excluding leading blanks.
+	 */
+	private seen_non_blank = false
+
+	/**
+	 * The number of pending blank expressions to add.
+	 * 
+	 * This is used to excluding trailing blanks.
+	 */
+	private pending_blanks: number = 0
+
+	private debug: DesmostDebug | null = null
+
+
+	/** Create a compiler for compiling `source` into `desmos`. */
+	constructor(
+		desmos: Desmos.Calculator,
+		source: string,
+		options: DesmostOptions,
+	)
+	{
+		this.desmos = desmos;
+		this.source = source;
+		this.options = options;
+		this.parser = new DesmostParser(this.source, this.options);
+	}
+
+
+	/**
+	 * Run the compiler to completion.
+	 */
+	public compile(): void | DesmostDebug
+	{
+		if (this.options.debug) {
+			this.debug = {
+				duration: performance.now(),
+				num_blocks: 0,
+				ast: [],
+			};
+		}
+
+		/* 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
+		}
+
+		/* 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. */
+		/* NOTE: It also doesn't sacrifice performance, since `.setExpressions()` internally just calls `.setExpression()` in a loop anyway. Benchmarks in the frontend produce similar times for both, so there's no performance improvement. */
+		try {
+			let done = false;
+
+			while (!done) {
+				done = this.compile_next();
+			}
+		}
+		catch (e) {
+			this.errors.push(e as Error);  // FIXME Should probably override as critical
+		}
+
+		if (this.options.keep_trailing_blanks) {
+			this.flush_pending_blanks();
+		}
+
+		/* NOTE: No need to check `options.place_errors`!
+
+			- If it's `start`, `id: deferred` will replace the placeholder at the start as required.
+			- If it's `end`, `id: deferred` won't exist so this expression will be appended as required.
+			- If it's `inline`, we shouldn't have any accumulated errors at all, but if we do, then the end is where they should be anyway.
+		*/
+		if (this.errors.length > 0) {
+			this.desmos.setExpression({
+				id: "deferred",
+				type: "text",
+				text: this.errors.map(err => format_error(err, this.options)).join("\n\n"),
+			});
+		} else {
+			this.desmos.removeExpression({ id: "deferred" });
+		}
+
+		if (this.options.debug) {
+			this.debug!.duration = performance.now() - this.debug!.duration;
+
+			return this.debug!;
+		}
+	}
+
+	/**
+	 * Compile only the next block, returning `true` if compilation has finished.
+	 */
+	compile_next(): Fallible<boolean>
+	{
+		let result = this.parser.parse_next();
+		if (result === undefined) return true;
+
+		let { blocks, errors } = result;
+
+		for (let block of blocks) {
+			this.compile_block(block);
+		}
+
+		for (let error of errors) {
+			this.evaluate_error(error);
+		}
+
+		return false;
+	}
+
+	compile_block(block: Ast): void
+	{
+		if (this.options.debug) {
+			this.debug!.num_blocks++;
+			this.debug!.ast.push(block);
+		}
+
+		switch (block.kind)
+		{
+			case Ast.Kind.INCANTATION_INVOCATION:
+				this.evaluate_global_incantation(block);
+				break;
+
+			case Ast.Kind.EXPRESSION:
+				// @ts-expect-error: check type-narrows
+				if (block.data.latex === " ") {
+					if (this.options.ignore_all_blanks) break;
+					if (!this.seen_non_blank && !this.options.keep_leading_blanks) break;
+
+					this.pending_blanks++;
+					break;
+				}
+				else {
+					this.flush_pending_blanks();
+					this.pending_blanks = 0;
+					this.seen_non_blank = true;
+
+					this.evaluate_expr(block);
+					break;
+				}
+		}
+	}
+
+
+	// == LOW-LEVEL == //
+
+	/**
+	 * Evaluate arguments (if any) to a global incantation `invocation`, then apply the incantation to `desmos`.
+	 */
+	evaluate_global_incantation(invocation: Ast.IncantationInvocation): Fallible<void>
+	{
+		let data = undefined;
+
+		if ("arg_raw" in invocation && invocation.arg_raw != undefined) {
+			try {
+				data = invocation.incantation.evaluate_arg(invocation.arg_raw, this.options);
+				invocation.incantation.apply(this.desmos, data);
+			}
+			catch (e) {
+				this.evaluate_error(e as Error);
+			}
+		}
+	}
+
+
+	/**
+	 * Evaluate local incantation invocations on `expr`, then add `expr` to `desmos`.
+	 */
+	evaluate_expr(expr: Ast.Expression): Fallible<void>
+	{
+		for (let invocation of expr.incantations) {
+			let data = undefined;
+
+			if ("arg_raw" in invocation && invocation.arg_raw != undefined) {
+				try {
+					data = invocation.incantation.evaluate_arg(invocation.arg_raw, this.options);
+				}
+				catch (e) {
+					this.evaluate_error(e as Error);
+					// if it needs the arg, then we can't press on
+					if (invocation.incantation.requires_arg) continue;
+				}
+			}
+
+			try {
+				invocation.incantation.apply(expr.data, data);
+			}
+			catch (e) {
+				this.evaluate_error(e as Error);
+			}
+		}
+
+		if (is_latex(expr.data)) {
+			expr.data.latex = normalise_latex(expr.data.latex!);
+
+			if (this.options.prettify) {
+				expr.data.latex = prettify_latex(expr.data.latex);
+			}
+		}
+		else if (expr.data.type === "text" && this.options.dedent_text) {
+			expr.data.text = dedent(expr.data.text ?? "");
+		}
+
+		this.desmos.setExpression(expr.data);
+	}
+
+	/**
+	 * Handle a `DesmostError`, respecting the user's options.
+	 */
+	evaluate_error(error: DesmostError): Fallible<void | string>
+	{
+		switch (this.options.errors) {
+			case "crash":
+				throw error;
+
+			case "suppress":
+				console.error(format_error(error, this.options));
+				break;
+
+			default: switch (this.options.place_errors) {
+				case "end":
+				case "start":
+					this.errors.push(error);
+					break;
+				
+				case "inline":
+					this.desmos.setExpression({
+						type: "text",
+						text: format_error(error, this.options),
+					});
+					break;
+			}
+		}
+	}
+
+	flush_pending_blanks(): void
+	{
+		for (let i = 0; i < this.pending_blanks; i++) {
+			this.desmos.setExpression({ latex: ` ` });
+		}
+	}
+}

package/src/compiler/format.ts

@@ -1,11 +1,11 @@
 import type { DesmostOptions } from "../options";
 
-import { UnrecoverableError } from "../errors";
+import { DesmostError } from "../errors";
 import { LINE } from "../utils";
 
 
 export function format_error(
-	e: UnrecoverableError,
+	e: DesmostError,
 	options: DesmostOptions,
 ): string
 {
@@ -15,12 +15,24 @@ export function format_error(
 	// 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.data == undefined) {
+		return display;
+	}
+
+	if (e.data.show != undefined) {
+		display += `\n${LINE}\n`;
+		display += e.data.show.text;
+
+		if (e.data.show.span != undefined) {
+			display += `\n`;
+			display += ' '.repeat(e.data.show.span.start);
+			display += '^'.repeat(e.data.show.span.length);
+		}
+	}
 
-		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}\``;
+	if (options.expand_errors) {
+		if (e.data.hint  != undefined) display += `\n${LINE}\nHint: ${e.data.hint}`;
+		if (e.data.note  != undefined) display += `\n${LINE}\nNote: ${e.data.note}`;
 	}
 
 	return display;

package/src/decompiler/decompile.ts

@@ -2,7 +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";
+import type { DesmostOptions } from "../options";
 
 
 export interface SemiStructuredAst

package/src/decompiler/extract.ts

@@ -1,7 +1,7 @@
 import { stringify_json5, prettify_source } from "./format";
 
 import { Ast } from "../parser";
-import { is_latex } from "../desmos";
+import { is_latex } from "../utils";
 
 import { DesmosIncantation, ViewportIncantation } from "../magic/global";
 
@@ -19,6 +19,7 @@ export function extract_settings(
    let arg_raw = stringify_json5(
       desmos.settings,
       (k, v) => (
+            // @ts-expect-error: weird
             v === defaults[k]
          || k === "__observers"
          || k === "guid"
@@ -50,6 +51,7 @@ export function extract_viewport(
 
    let arg_raw = stringify_json5(
       { left, right, bottom, top },
+      /// @ts-expect-error: weird
       (k, v) => v === defaults[k] ? undefined : v,
       "  ",
    );

package/src/errors.ts

@@ -1,3 +1,6 @@
+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");
 
@@ -10,51 +13,64 @@ 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 DesmostError extends Error
 {
-	info?: UnrecoverableError.Info;
+	data?: DesmostError.Data;
+
+	constructor(msg: string | undefined, name: string) {
+		super(msg);
+      this.name = name;
+	}
 }
 
-export namespace UnrecoverableError
+export namespace DesmostError
 {
-	export interface Info
+	export interface Data
 	{
-		hint?: string,
-		note?: string,
-		flagged_by?: string,
+		msg?:   string
+		while?: string
+		hint?:  string
+		note?:  string
+		debug?: string
+
+		show?: {
+			text:  string
+			span?: Range
+		}
 	}
 
-	/** The parser unexpectedly reached the end of its entire input source code. */
-	export class UnexpectedEnd extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Unexpected End"; }
+	/** The parser unexpectedly reached the end of its source. */
+	export class UnexpectedEnd extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Unexpected End of Source"); }
 	}
 
 	/** The parser did not receive input that it expected. */
-	export class MissingInput extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Missing Input"; }
+	export class MissingInput extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Missing Input"); }
 	}
 
 	/** The parser received input that did not match what it expected. */
-	export class UnexpectedInput extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Unexpected Input"; }
+	export class UnexpectedInput extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Unexpected Input"); }
 	}
 
 	/** The parser received excess input that it did not expect. */
-	export class ExcessInput extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Excess Input"; }
+	export class ExcessInput extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Excess Input"); }
 	}
 
 	/** An incantation can't be applied here. */
-	export class IllegalIncantation extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Illegal Incantation"; }
+	export class IllegalIncantation extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Illegal Incantation"); }
 	}
 
-	/** An incantation's argument couldn't be parsed. */
-	export class InvalidArgument extends UnrecoverableError {
-		constructor(msg: string, override info?: Info) { super(msg); this.name = "Invalid Argument"; }
+	/** An incantation's argument is invalid - could be a parsing, evaluation or validation failure. */
+	export class InvalidArgument extends DesmostError {
+		constructor(override data: Data) { super(data.msg, "Invalid Argument"); }
 	}
 }
 
-
-/** Indicates that a function may throw an `UnrecoverableError`. */
-export type Unrecoverable<Result> = Result | Result & { readonly __brand?: unique symbol };
+/** Indicates that a function may throw a `DesmostError`. */
+export type Fallible<Result>
+	= Result
+	| Result & { readonly __brand?: unique symbol };

package/src/index.internal.ts

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

package/src/magic/.template.ts

@@ -1,7 +1,7 @@
 // import { Incantation, ArgIncantation, type GLOBAL, type LOCAL, type EXPR } from "../incantation";
 
 // import type { DesmostOptions } from "../../options";
-// import { UnrecoverableError, type Unrecoverable } from "../../errors";
+// import { DesmostError, type Fallible } from "../../errors";
 
 
 // export class ?Incantation extends ArgIncantation<?>
@@ -18,7 +18,7 @@
 // 		// TODO
 // 	}
 
-// 	override evaluate_arg(raw: ?, options: DesmostOptions): Unrecoverable<?>
+// 	override evaluate_arg(raw: ?, options: DesmostOptions): Fallible<?>
 // 	{
 // 		let out = super.evaluate_arg(raw, options) as ?;
 

package/src/magic/global/desmos.ts

@@ -1,6 +1,6 @@
 import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
-import { UnrecoverableError, type Unrecoverable } from "../../errors";
+import { DesmostError, type Fallible } from "../../errors";
 import type { DesmostOptions } from "../../options";
 
 
@@ -26,19 +26,17 @@ export class DesmosIncantation extends ArgIncantation<GLOBAL>
 		}
 	}
 
-	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<DesmosSettings>
+	override evaluate_arg(raw: string, options: DesmostOptions): Fallible<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`,
-					}
-				);
+				throw new DesmostError.MissingInput({
+					msg:  `/desmos received empty settings`,
+					hint: `Provide settings like \`/desmos{expressionsCollapsed: true}\``,
+					note: `Use just /desmos (without \`{}\`) if you want it as an indicator`,
+				});
 			}
 		}
 		

package/src/magic/global/viewport.ts

@@ -1,6 +1,6 @@
 import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
-import { UnrecoverableError, type Unrecoverable } from "../../errors";
+import { DesmostError, type Fallible } from "../../errors";
 import type { DesmostOptions } from "../../options";
 
 
@@ -36,20 +36,17 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 		target.setMathBounds({ left, right, bottom, top });
 	}
 
-	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<ViewportBounds>
+	override evaluate_arg(raw: string, options: DesmostOptions): Fallible<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",
-					}
-				);
+				throw new DesmostError.InvalidArgument({
+					msg:  `/${this.identifier} received empty viewport bounds`,
+					hint: `Provide bounds like \`/viewport{left: -8, right: 8}\``,
+					note: `Missing bounds are kept as their defaults`,
+				});
 			}
 
 			let invalid_keys = Object.keys(out).filter(key => !VALID_KEYS.includes(key));
@@ -57,13 +54,10 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 			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",
-					}
-				);
+				throw new DesmostError.InvalidArgument({
+					msg:  `/${this.identifier} received invalid ${plural}: [${invalid_keys.join(", ")}]`,
+					hint: `Valid fields are: [${VALID_KEYS.join(", ")}]`,
+				});
 			}
 		}
 

package/src/magic/incantation.ts

@@ -2,7 +2,7 @@ import Json5 from "json5";
 import dedent from "dedent";
 
 import type { DesmostOptions } from "../options";
-import { UnrecoverableError, type Unrecoverable } from "../errors";
+import { DesmostError, type Fallible } from "../errors";
 
 
 /**
@@ -46,9 +46,11 @@ export abstract class Incantation<
 	{
 		if ((actual ?? "expression") !== required)
 		{
-			throw new UnrecoverableError.IllegalIncantation(
-				`/${this.identifier} can only applied to ${required === "expression" ? "latex" : required} blocks, but target block has type: ${actual}`
-			);
+			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}`,
+			});
 		}
 	}
 }
@@ -80,7 +82,7 @@ export abstract class ArgIncantation<
 	 * 
 	 * 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.
 	 */
-	evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<unknown>
+	evaluate_arg(raw: string, options: DesmostOptions): Fallible<unknown>
 	{
 		switch (this.arg_type) {
 			case Incantation.ArgType.LATEX:  return raw;
@@ -95,7 +97,7 @@ export abstract class ArgIncantation<
 				}
 				catch (e) {
 					// @ts-expect-error: fine
-					throw new UnrecoverableError.InvalidArgument(e.message);
+					throw new DesmostError.InvalidArgument({ msg: e.message });
 				}
 			}
 		}
@@ -103,34 +105,31 @@ export abstract class ArgIncantation<
 
 	protected require_nonempty(
 		arg: object,
-		msg?: string,
-		info?: UnrecoverableError.Info,
-	): Unrecoverable<void>
+		error_data?: DesmostError.Data,
+	): Fallible<void>
 	{
 		if (Object.entries(arg).length === 0) {
-			throw new UnrecoverableError.MissingInput(
-				msg ?? `/${this.identifier} received an empty argument {}`,
-				info,
-			);
+			throw new DesmostError.MissingInput({
+				msg: `/${this.identifier} received an empty argument {}`,
+				...error_data
+			});
 		}
 	}
 
 	protected require_known(
 		arg: object,
 		valid_fields: string[],
-		info?: UnrecoverableError.Info,
-	): Unrecoverable<void>
+		error_data?: DesmostError.Data,
+	): Fallible<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,
-					}
-				);
+				throw new DesmostError.InvalidArgument({
+					msg:  `/${this.identifier} received invalid field: ${field}`,
+					hint: `Valid fields are [${valid_fields.join(", ")}]`,
+					...error_data,
+				});
 			}
 		}
 	}