desmost 0.9.0 → 0.10.0

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

package/src/magic/local/colour.ts

@@ -1,10 +1,15 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
-import { DesmosColour } from "../../desmos";
-import { UnrecoverableError } from "../../errors";
+import { DesmostError } from "../../errors";
 import type { DesmostOptions } from "../../options";
 
 
+type DesmosColourName = keyof typeof Desmos.Colors;
+type DesmosColour = (typeof Desmos.Colors)[DesmosColourName];
+
+const VALID_COLOURS = ["RED", "BLUE", "GREEN", "PURPLE", "ORANGE", "BLACK"];
+
+
 export class ColourIncantation extends ArgIncantation<LOCAL>
 {
 	override readonly description
@@ -23,17 +28,22 @@ export class ColourIncantation extends ArgIncantation<LOCAL>
 
 	override evaluate_arg(data: string, options: DesmostOptions): DesmosColour
 	{
-		switch (data.trim().toUpperCase()) {
-			case "RED":    return DesmosColour.RED;
-			case "BLUE":   return DesmosColour.BLUE;
-			case "GREEN":  return DesmosColour.GREEN;
-			case "PURPLE": return DesmosColour.PURPLE;
-			case "ORANGE": return DesmosColour.ORANGE;
-			case "BLACK":  return DesmosColour.BLACK;
-			default:
-				throw new UnrecoverableError(
-					`Invalid colour: \`${data}\``
-				);
+		let colour = data.trim().toUpperCase();
+
+		if (VALID_COLOURS.includes(colour)) {
+			return Desmos.Colors[colour as DesmosColourName];
+		}
+		else {
+			let internal = Desmos.Colors[colour as DesmosColourName];
+
+			if (options.check_args && internal == undefined) {
+				throw new DesmostError.InvalidArgument({
+					msg:  `/colour received invalid colour: \`${data}\``,
+					hint: `Valid colours are ${VALID_COLOURS.join(", ")}`,
+				});
+			}
+
+			return internal;
 		}
 	}
 }

package/src/magic/local/label.ts

@@ -1,6 +1,6 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
-import { UnrecoverableError } from "../../errors";
+import { DesmostError } from "../../errors";
 import type { DesmostOptions } from "../../options";
 
 
@@ -8,8 +8,8 @@ interface LabelOptions
 {
 	text: string;
 	show?: boolean;
-	size?: number | keyof typeof Desmos.LabelSizes;
-	pos?: keyof typeof Desmos.LabelOrientations;
+	size?: number;
+	pos?: "ABOVE" | "BELOW" | "LEFT" | "RIGHT" | "ABOVE_LEFT" | "ABOVE_RIGHT" | "BELOW_LEFT" | "BELOW_RIGHT";
 }
 
 const VALID_FIELDS = ["text", "show", "size", "pos"];
@@ -36,6 +36,7 @@ export class LabelIncantation extends ArgIncantation<LOCAL>
 		target.showLabel = data.show ?? true;
 		// @ts-expect-error: outdated types
 		if (data.size != undefined) target.labelSize = data.size;
+		// @ts-expect-error: outdated types
 		if (data.pos  != undefined) target.labelOrientation = data.pos;
 	}
 
@@ -44,19 +45,16 @@ export class LabelIncantation extends ArgIncantation<LOCAL>
 		let out = super.evaluate_arg(raw, options) as LabelOptions;
 
 		if (options.check_args) {
-			super.require_nonempty(out, `/label received empty argument`, {
+			super.require_nonempty(out, {
+				msg:  `/label received empty argument`,
 				hint: `You can provide [${VALID_FIELDS.join(", ")}]`,
-				flagged_by: "check_args",
 			});
 
 			if (!("text" in out)) {
-				throw new UnrecoverableError.MissingInput(
-					`/label is missing label text`,
-					{
-						hint: `Provide text for the label: \`/label{text: "sup world!"}\``,
-						flagged_by: "check_args",
-					}
-				);
+				throw new DesmostError.MissingInput({
+					msg:  `/label is missing label text`,
+					hint: `Provide text for the label: \`/label{text: "sup world!"}\``,
+				});
 			}
 
 			super.require_known(out, VALID_FIELDS);
@@ -74,13 +72,10 @@ export class LabelIncantation extends ArgIncantation<LOCAL>
 				let orientation = Desmos.LabelOrientations[pos];
 
 				if (options.check_args && orientation == undefined) {
-					throw new UnrecoverableError.InvalidArgument(
-						`/label received invalid label position: ${pos}`,
-						{
-							hint: `Valid label positions are ${VALID_POSITIONS.join(", ")}`,
-							flagged_by: "check_args"
-						}
-					);
+					throw new DesmostError.InvalidArgument({
+						msg:  `/label received invalid label position: ${pos}`,
+						hint: `Valid label positions are ${VALID_POSITIONS.join(", ")}`,
+					});
 				}
 				
 				out.pos = orientation;

package/src/magic/local/line.ts

@@ -1,7 +1,7 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
 import type { DesmostOptions } from "../../options";
-import { type Unrecoverable } from "../../errors";
+import type { Fallible } from "../../errors";
 
 
 interface LineOptions
@@ -32,7 +32,7 @@ export class LineIncantation extends ArgIncantation<LOCAL>
 		if (data.opacity != undefined) target.lineOpacity = data.opacity;
 	}
 
-	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<LineOptions>
+	override evaluate_arg(raw: string, options: DesmostOptions): Fallible<LineOptions>
 	{
 		let out = super.evaluate_arg(raw, options) as LineOptions;
 

package/src/options.ts

@@ -2,6 +2,36 @@ import { LINE } from "./utils";
 import { compile } from "./compiler/compile";
 
 
+/** Default options that Desmost uses for `compile()` and `decompile()`. */
+export const DEFAULT_OPTIONS: DesmostOptions =
+{
+   errors: "surface",
+   place_errors: "inline",
+   error_prefix: `[DESMOST ERROR]\n${LINE}\n`,
+	expand_errors: true,
+	check_args: true,
+   prettify: true,
+	dedent_text: true,
+   ignore_comments: false,
+   ignore_all_blanks: false,
+   keep_leading_blanks: false,
+   keep_trailing_blanks: false,
+   debug: false,
+};
+
+
+/**
+ * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
+ */
+export function fill_defaults(options: Partial<DesmostOptions> | undefined): DesmostOptions
+{
+   return {
+      ...DEFAULT_OPTIONS,
+      ...options,
+   };
+}
+
+
 /**
  * Options to customise Desmost compilation.
  * 
@@ -29,14 +59,15 @@ import { compile } from "./compiler/compile";
 export interface DesmostOptions
 {
 	/**
-	 * How should errors be *surfaced* to the end user?
+	 * How should errors be displayed?
 	 * 
-	 * - `surface` (default): Blocks that result in errors will become Desmos text expressions containing the error message, leaving other expressions unaffected.
+	 * - `surface` (default): Blocks that result in errors will become Desmos text blocks 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.
+	 * - `crash`: The entire compilation to Desmos will terminate with a single error message in a text block.
+	 *   - This means you don't get any Desmos rendering at all, but errors are also immediately obvious.
+	 *    - Note that this will *clear all expressions* in the calculator instance. If you pass in a non-blank `Desmos.Calculator` to `compile()`, it could get cleared.
 	 * 
-	 * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine).
+	 * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine!).
 	 */
 	errors: "surface" | "crash" | "suppress"
 
@@ -52,7 +83,7 @@ export interface DesmostOptions
 	/**
 	 * The prefix to prepend to error blocks.
 	 * 
-	 * Defaults to `[DESMOST ERROR]\n`.
+	 * Defaults to `"[DESMOST ERROR]"`.
 	 * 
 	 * Provide a `""` blank string if you wish for no prefix to be added.
 	 */
@@ -61,100 +92,101 @@ export interface DesmostOptions
 	/**
 	 * Show all the available diagnostics for errors, including hints and debug information?
 	 * 
-	 * Defaults to `true`, meaning all output is shown.
+	 * Defaults to `true` – all output is shown.
 	 */
 	expand_errors: boolean
 
 	/**
-	 * Error if an incantation receives a `{}` object argument with unknown fields?
+	 * Error if an incantation receives a `{}` object argument with unknown fields, or no fields at all?
 	 * 
-	 * This also errors if an incantation receives an empty `{}` object.
-	 * 
-	 * For instance, `/label{position: LEFT}` is invalid; it should be `/label{pos: LEFT}`. With `check_args: false`, this silently no-ops; with `check_args: true`, it flags an error.
+	 * For instance, `/label{position: LEFT}` is invalid; it should be `/label{pos: LEFT}`. With `check_args: false`, this silently no-ops.
 	 * 
 	 * Desmost doesn’t remove unknown fields, it just passes them directly to the Desmos API. If you know what you’re doing and a field you know exists isn’t supported by Desmos, you can disable this to avoid erroring.
 	 * 
-	 * Defaults to `true`, meaning arguments are checked.
+	 * Defaults to `true` – arguments are checked. The Desmos API happily accepts and ignores invalid fields, so Desmost provides a safety net for you ;)
 	 */
 	check_args: boolean
 
 	/**
 	 * Prettify LaTeX output so it renders nicely in the Desmos editor?
 	 * 
-	 * Defaults to `true`, meaning LaTeX is prettified.
+	 * This means you can keep your source code much neater. It handles stuff like converting `()` –> `\left(\right)`, `x, y` –> `x,\ y`, `min(x, y)` –> `\operatorname{min}\left(x,\ y\right)`, and more!
+	 * 
+	 * Defaults to `true` – LaTeX is prettified.
 	 */
 	prettify: boolean
 
 	/**
 	 * Strip common indentation from `/text{}` blocks?
 	 * 
-	 * Defaults to `true`, meaning text is dedented.
+	 * This allows you to indent content for readability:
+	 * 
+	 * ```hs
+	 * /text{
+	 *   Now I have
+	 *   a lovely indent
+	 * }
+	 * ```
+	 * 
+	 * Defaults to `true` – text is dedented.
 	 */
 	dedent_text: boolean
 
 	/**
-	 * Should `%` LaTeX comments be ignored, instead of turned into text expressions (notes)?
+	 * Should `%` LaTeX comments be ignored, instead of turned into text blocks (notes)?
 	 * 
-	 * Defaults to `false`, meaning comments are kept.
+	 * ```hs
+	 * % Do I become a text expression?
+	 * y = x
+	 * ```
+	 * 
+	 * Defaults to `false` – 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.
+	 * ```hs
+	 * % Should there be a blank block after this?
+	 * 
+	 * % Should there be a blank block before this?
+	 * ```
+	 * 
+	 * This takes precedence over `keep_leading_blanks` and `keep_trailing_blanks`.
+	 * 
+	 * Defaults to `false` – blank lines are recognised.
 	 */
 	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.
+	 * This is disabled by default so line breaks after global incantations don’t mess things up:
+	 * 
+	 * ```hs
+	 * /viewport{left: -8, right: 8}
+	 * 
+	 * % I don’t have a blank block above me, yay
+	 * ```
+	 * 
+	 * Defaults to `false` – 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.
+	 * Defaults to `false` – trailing blank lines are ignored.
 	 */
 	keep_trailing_blanks: boolean
 
 	/**
-	 * Return debug diagnostics?
+	 * Return debug diagnostics from `compile()`?
 	 * 
-	 * This includes the unevaluated AST and performance diagnostics.
+	 * This includes the unevaluated AST and performance diagnostics. Relevant types are exposed from `desmost/internal`, but beware that these are implementation details and unstable.
 	 * 
-	 * Defaults to `false`, meaning `compile()` returns `void`.
+	 * Defaults to `false` – `compile()` returns `void`.
 	 */
 	debug: boolean
 }
-
-
-export const DEFAULT_OPTIONS: DesmostOptions =
-{
-   errors: "surface",
-   place_errors: "inline",
-   error_prefix: `[DESMOST ERROR]\n${LINE}\n`,
-	expand_errors: true,
-   prettify: true,
-	dedent_text: true,
-	check_args: false,
-   ignore_comments: false,
-   ignore_all_blanks: false,
-   keep_leading_blanks: false,
-   keep_trailing_blanks: false,
-   debug: false,
-};
-
-
-/**
- * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
- */
-export function fill_defaults(options: Partial<DesmostOptions> | undefined): DesmostOptions
-{
-   return {
-      ...DEFAULT_OPTIONS,
-      ...options,
-   };
-}

package/src/parser/ast.ts

@@ -1,4 +1,3 @@
-import { UnrecoverableError } from "../errors";
 import { Incantation, ArgIncantation } from "../magic";
 
 
@@ -9,7 +8,6 @@ export namespace Ast
 	{
 		EXPRESSION             = "Expression",
 		INCANTATION_INVOCATION = "Incantation-Invocation",
-		INVALID_INCANTATION    = "Invalid-Incantation",
 	}
 
 	
@@ -18,10 +16,7 @@ export namespace Ast
 	{
 		kind: Kind.EXPRESSION
 		data: Desmos.ExpressionState
-		incantations: Array<
-			| IncantationInvocation<Incantation.Effect.LOCAL>
-			| InvalidInvocation
-			>
+		incantations: IncantationInvocation<Incantation.Effect.LOCAL>[]
 	}
 
 
@@ -30,31 +25,16 @@ export namespace Ast
 		| {
 			kind: Kind.INCANTATION_INVOCATION
 			incantation: Incantation<Effect>
-			arg_raw: undefined
 		}
 		| {
 			kind: Kind.INCANTATION_INVOCATION
 			incantation: ArgIncantation<Effect>
 			arg_raw: string | undefined
 		};
-
-	/**
-	 * An invalid invantation invocation that raised an error when parsed.
-	 * 
-	 * This will be propogated to the user as an extra Desmos text expression (unless they have `errors: "suppress"` configured).
-	 */
-	export interface InvalidInvocation
-	{
-		kind: Kind.INVALID_INCANTATION
-		incantation: Incantation
-		arg_raw?: string
-		error: UnrecoverableError
-	}
 }
 
 /** An abstract object produced by the parser. */
 export type Ast =
 	| Ast.Expression
 	| Ast.IncantationInvocation
-	| Ast.InvalidInvocation
 ;