desmost 0.8.1 → 0.9.0

package/src/magic/local/label.ts

@@ -1,6 +1,8 @@
-import { UnrecoverableError } from "../../errors";
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
+import { UnrecoverableError } from "../../errors";
+import type { DesmostOptions } from "../../options";
+
 
 interface LabelOptions
 {
@@ -10,6 +12,13 @@ interface LabelOptions
 	pos?: keyof typeof Desmos.LabelOrientations;
 }
 
+const VALID_FIELDS = ["text", "show", "size", "pos"];
+
+const VALID_POSITIONS = [
+	"ABOVE", "BELOW", "LEFT", "RIGHT",
+	"ABOVE_LEFT", "ABOVE_RIGHT", "BELOW_LEFT", "BELOW_RIGHT",
+];
+
 
 export class LabelIncantation extends ArgIncantation<LOCAL>
 {
@@ -25,36 +34,56 @@ export class LabelIncantation extends ArgIncantation<LOCAL>
 		super.require_expr_type(target.type, "expression");
 		target.label = data.text;
 		target.showLabel = data.show ?? true;
-		// @ts-expect-error: outdated types TODO check
+		// @ts-expect-error: outdated types
 		if (data.size != undefined) target.labelSize = data.size;
 		if (data.pos  != undefined) target.labelOrientation = data.pos;
 	}
 
-	override evaluate_arg(raw: string): LabelOptions
+	override evaluate_arg(raw: string, options: DesmostOptions): LabelOptions
 	{
-		let out = super.evaluate_arg(raw) as LabelOptions;
+		let out = super.evaluate_arg(raw, options) as LabelOptions;
+
+		if (options.check_args) {
+			super.require_nonempty(out, `/label received empty argument`, {
+				hint: `You can provide [${VALID_FIELDS.join(", ")}]`,
+				flagged_by: "check_args",
+			});
 
-		if (!("text" in out)) {
-			throw new UnrecoverableError.InvalidArgument(
-				`/label requires a \`text\` argument, such as: \`/label{ text: "sup world!" }\``
-			);
+			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",
+					}
+				);
+			}
+
+			super.require_known(out, VALID_FIELDS);
 		}
 
 		if (typeof out.pos != "undefined") {
-			let pos = out.pos.trim().toUpperCase();
-
-			switch (pos) {
-				case "ABOVE":
-				case "BELOW":
-				case "LEFT":
-				case "RIGHT":
-					out.pos = pos;
-					break;
-				
-				default:
+			let pos = out.pos.trim().toUpperCase().replaceAll("-", "_");
+
+			if (VALID_POSITIONS.includes(pos)) {
+				// @ts-expect-error: validated
+				out.pos = pos;
+			}
+			else {
+				// @ts-expect-error: indexing
+				let orientation = Desmos.LabelOrientations[pos];
+
+				if (options.check_args && orientation == undefined) {
 					throw new UnrecoverableError.InvalidArgument(
-						`/label: Invalid label position: ${pos}`
+						`/label received invalid label position: ${pos}`,
+						{
+							hint: `Valid label positions are ${VALID_POSITIONS.join(", ")}`,
+							flagged_by: "check_args"
+						}
 					);
+				}
+				
+				out.pos = orientation;
 			}
 		}
 

package/src/magic/local/line.ts

@@ -1,13 +1,18 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
+import type { DesmostOptions } from "../../options";
+import { type Unrecoverable } from "../../errors";
+
 
 interface LineOptions
 {
-	style?:   keyof typeof Desmos.Styles;  // TODO allow raw enum
+	style?:   keyof typeof Desmos.Styles;
 	width?:   number;
 	opacity?: number;
 }
 
+const VALID_FIELDS = ["style", "width", "opacity"];
+
 
 export class LineIncantation extends ArgIncantation<LOCAL>
 {
@@ -22,8 +27,20 @@ export class LineIncantation extends ArgIncantation<LOCAL>
 	{
 		super.require_expr_type(target.type, "expression");
 		
-		if (data.style != undefined)   target.lineStyle   = data.style;
-		if (data.width != undefined)   target.lineWidth   = data.width;
+		if (data.style   != undefined) target.lineStyle   = data.style;
+		if (data.width   != undefined) target.lineWidth   = data.width;
 		if (data.opacity != undefined) target.lineOpacity = data.opacity;
 	}
+
+	override evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<LineOptions>
+	{
+		let out = super.evaluate_arg(raw, options) as LineOptions;
+
+		if (options.check_args) {
+			super.require_nonempty(out);
+			super.require_known(out, VALID_FIELDS);
+		}
+
+		return out;
+	}
 }

package/src/magic/local/slider.ts

@@ -3,8 +3,8 @@ import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
 interface SliderBounds
 {
-	min?:  number | string;
-	max?:  number | string;
+	min:   number | string;
+	max:   number | string;
 	step?: number | string;
 }
 
@@ -21,7 +21,6 @@ export class SliderIncantation extends ArgIncantation<LOCAL>
 	override apply(target: Desmos.ExpressionState, data: SliderBounds)
 	{
 		super.require_expr_type(target.type, "expression");
-		// @ts-expect-error: outdated types
 		target.sliderBounds = data;
 	}
 }

package/src/{compiler/options.ts → options.ts}

@@ -1,11 +1,30 @@
+import { LINE } from "./utils";
+import { compile } from "./compiler/compile";
+
+
 /**
  * Options to customise Desmost compilation.
  * 
- * To customise compilation, pass in a `DesmostOptions` object as the last argument to `compile()`:
+ * To customise compilation, pass in a `DesmostOptions` object as the last argument to {@linkcode compile()}:
  * 
  * ```ts
  * compile(calc, source, { errors: "crash" });
  * ```
+ * 
+ * ## Decompilation
+ * 
+ * The same options can also be applied to decompilation:
+ * 
+ * ```ts
+ * decompile(calc, blank, { prettify: false });
+ * ```
+ * 
+ * Here, this means “decompile into source code that would reproduce `calc`, *when compiled with these options*”. As an identity:
+ * 
+ * ```ts
+ * let options = { ... };
+ * compile(_, decompile(calc, _ options), options) == calc  // (value equality)
+ * ```
  */
 export interface DesmostOptions
 {
@@ -19,7 +38,7 @@ export interface DesmostOptions
 	 * 
 	 * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine).
 	 */
-	errors?: "surface" | "crash" | "suppress"
+	errors: "surface" | "crash" | "suppress"
 
 	/**
 	 * Where should errors be placed?
@@ -28,7 +47,7 @@ export interface DesmostOptions
 	 * - `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"
+	place_errors: "inline" | "end" | "start"
 
 	/**
 	 * The prefix to prepend to error blocks.
@@ -37,42 +56,69 @@ export interface DesmostOptions
 	 * 
 	 * Provide a `""` blank string if you wish for no prefix to be added.
 	 */
-	error_prefix?: string
+	error_prefix: string
+
+	/**
+	 * Show all the available diagnostics for errors, including hints and debug information?
+	 * 
+	 * Defaults to `true`, meaning all output is shown.
+	 */
+	expand_errors: boolean
+
+	/**
+	 * Error if an incantation receives a `{}` object argument with unknown fields?
+	 * 
+	 * 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.
+	 * 
+	 * 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.
+	 */
+	check_args: boolean
 
 	/**
 	 * Prettify LaTeX output so it renders nicely in the Desmos editor?
 	 * 
 	 * Defaults to `true`, meaning LaTeX is prettified.
 	 */
-	prettify?: boolean
+	prettify: boolean
+
+	/**
+	 * Strip common indentation from `/text{}` blocks?
+	 * 
+	 * Defaults to `true`, meaning text is dedented.
+	 */
+	dedent_text: boolean
 
 	/**
 	 * Should `%` LaTeX comments be ignored, instead of turned into text expressions (notes)?
 	 * 
 	 * Defaults to `false`, meaning comments are kept.
 	 */
-	ignore_comments?: boolean
+	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
+	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
+	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
+	keep_trailing_blanks: boolean
 
 	/**
 	 * Return debug diagnostics?
@@ -81,16 +127,19 @@ export interface DesmostOptions
 	 * 
 	 * Defaults to `false`, meaning `compile()` returns `void`.
 	 */
-	debug?: boolean
+	debug: boolean
 }
 
 
-export const DEFAULT_OPTIONS =
+export const DEFAULT_OPTIONS: DesmostOptions =
 {
    errors: "surface",
    place_errors: "inline",
-   error_prefix: "[DESMOST ERROR]\n",
+   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,
@@ -102,10 +151,10 @@ export const DEFAULT_OPTIONS =
 /**
  * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
  */
-export function fill_defaults(options: Partial<DesmostOptions> | undefined): Required<DesmostOptions>
+export function fill_defaults(options: Partial<DesmostOptions> | undefined): DesmostOptions
 {
    return {
       ...DEFAULT_OPTIONS,
       ...options,
-   } as Required<DesmostOptions>;
+   };
 }

package/src/parser/desmost-parser.ts

@@ -1,7 +1,7 @@
 import { GenericParser } from "./generic-parser";
 import { Ast } from "./ast";
 
-import type { DesmostOptions } from "../compiler";
+import type { DesmostOptions } from "../options";
 import { NO_MATCH, UnrecoverableError } from "../errors";
 import type { NoMatch, Unrecoverable } from "../errors";
 import * as utils from "../utils";
@@ -468,20 +468,26 @@ export class DesmostParser extends GenericParser
 		}
 
 		/* NOTE: Cut in by 1 on both sides to exclude {} braces */
-		let out = utils.chars(this.source, init + 1, this.i - 1);
+		let raw = utils.chars(this.source, init + 1, this.i - 1);
 		
 		for (let [i, j] of utils.reversing(utils.paired(indices_to_insert_quotes))) {
 			i -= init + 1;
 			j -= init + 1;
 
-			let value = out.slice(i, j).join("");
+			let value = raw.slice(i, j).join("");
 			if (["true", "false", "null", "undefined"].includes(value)) continue;
 			
-			out.splice(j, 0, `"`);
-			out.splice(i, 0, `"`);
+			raw.splice(j, 0, `"`);
+			raw.splice(i, 0, `"`);
 		}
 
-		return out.join("").trim();
+		let out = raw.join("");
+
+		if (arg_type !== Incantation.ArgType.STRING) {
+			out = out.trim();
+		}
+
+		return out;
 	}
 }
 

package/src/parser/generic-parser.ts

@@ -48,14 +48,6 @@ export class GenericParser
 		return this.source.at(this.i);
 	}
 
-	/**
-	 * Get the character *after* the current one that the parser points at.
-	 */
-	protected next(): string | undefined
-	{
-		return this.source.at(this.i + 1);
-	}
-
 	/**
 	 * Peek a snippet of the upcoming source text.
 	 * 
@@ -64,7 +56,11 @@ export class GenericParser
 	public preview(idx?: number): string
 	{
 		idx ??= this.i;
-		return this.source.slice(idx, idx + 20) + "...";
+
+		return (
+			this.source.slice(idx, idx + 20).replaceAll("\n", " ")
+			+ (idx + 20 >= this.length ? "⏎" : "...")
+		);
 	}
 
 	/**
@@ -140,7 +136,7 @@ export class GenericParser
 
 		while (this.current === raw[ii]) {
 			let r = this.try_advance();
-			if (r === NO_MATCH) return NO_MATCH;
+			if (r === NO_MATCH) return NO_MATCH;  // FIXME?
 
 			ii++;
 			if (ii === raw.length) return;
@@ -167,14 +163,18 @@ export class GenericParser
 	/**
 	 * Consume 0 or more whitespace characters.
 	 * 
-	 * Same as `.consume_spaces()`, but allows newlines.
+	 * Same as `.consume_spaces()`, but allows tabs and newlines.
 	 */
 	protected consume_whitespace(): void
 	{
 		/* NOTE: Callers should be able to assume this is safe to call even when at end of input, since it should just match 0 characters */
 		if (this.i >= this.length) return;
 
-		while (this.current === " " || this.current === "\n") {
+		while (
+			this.current === " "
+			|| this.current === "\n"
+			|| this.current === "\t"
+		) {
 			this.advance();
 		}
 	}

package/src/parser/readme.md

@@ -11,6 +11,8 @@ The parser is split into `DesmostParser` and `GenericParser`.
 
 The parser is stateful, tracking its current position in the source text with its `.i` field.
 
+`parse_next()` is the only method consumers need to be aware of, the rest is implementation detail. Would love to make them `private`, unfortunately we need them public for unit testing ;)
+
 
 ## Backtracking
 

package/src/utils.ts

@@ -1,3 +1,6 @@
+export const LINE = '—'.repeat(10);
+
+
 export function* reversing<T>(items: ArrayLike<T>): Generator<T>
 {
 	for (let i = items.length - 1; i >= 0; i--) {

package/svelte/desmost.svelte

@@ -141,9 +141,11 @@ onMount(() =>
       inject(el_desmos, source.textContent);
     }
     else {
-      let observer = new IntersectionObserver(() => {
-        inject(el_desmos, source.textContent);
-        observer.disconnect();
+      let observer = new IntersectionObserver(([entry]) => {
+        if (entry.isIntersecting) {
+          inject(el_desmos, source.textContent);
+          observer.disconnect();
+        }
       });
       observer.observe(el_desmos);
       lazy_observers.push(observer);

package/dist/compiler/options.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../src/compiler/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAE9B;;;;;;;;;OASG;IACH,MAAM,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;IAEzC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAA;IAEzC;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAA;IAEzB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAA;IAE3B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAA;IAE7B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAE9B;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAGD,eAAO,MAAM,eAAe;;;;;;;;;;CAW3B,CAAC;AAGF;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,GAAG,QAAQ,CAAC,cAAc,CAAC,CAMpG"}

package/dist/compiler/options.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../../src/compiler/options.ts"],"names":[],"mappings":"AAuFA,MAAM,CAAC,MAAM,eAAe,GAC5B;IACG,MAAM,EAAE,SAAS;IACjB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,mBAAmB;IACjC,QAAQ,EAAE,IAAI;IACd,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,KAAK;IACxB,mBAAmB,EAAE,KAAK;IAC1B,oBAAoB,EAAE,KAAK;IAC3B,KAAK,EAAE,KAAK;CACd,CAAC;AAGF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAA4C;IAEvE,OAAO;QACJ,GAAG,eAAe;QAClB,GAAG,OAAO;KACgB,CAAC;AACjC,CAAC"}