desmost 0.10.1 → 0.11.0

package/src/magic/local/anim.ts

@@ -1,16 +1,29 @@
 import { Incantation, type LOCAL } from "../incantation";
+import { Ast } from "../../parser";
 
 
 export class AnimIncantation extends Incantation<LOCAL>
 {
-	override readonly description
-		= "Animate the slider of a block."
-	
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier = "anim"
+	override readonly description
+		= `Animate the slider of a block.`
 
 	override apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.playing = true;
 	}
+
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.playing) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: anim,
+			};
+		}
+	}
 }
+
+export const anim = new AnimIncantation();

package/src/magic/local/colour.ts

@@ -1,7 +1,8 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
-import { DesmostError } from "../../errors";
 import type { DesmostOptions } from "../../options";
+import { DesmostError } from "../../errors";
+import { Ast } from "../../parser";
 
 
 type DesmosColourName = keyof typeof Desmos.Colors;
@@ -12,13 +13,13 @@ const VALID_COLOURS = ["RED", "BLUE", "GREEN", "PURPLE", "ORANGE", "BLACK"];
 
 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"
+	override readonly effect       = Incantation.Effect.LOCAL
+	override readonly identifier   = "colour"
+	override readonly alias        = "color"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.ENUM
+	override readonly description
+		= "Change the colour of a rendered expression, such as a line, region, polygon, etc."
 
 	override apply(target: Desmos.ExpressionState, data: DesmosColour)
 	{
@@ -46,4 +47,15 @@ export class ColourIncantation extends ArgIncantation<LOCAL>
 			return internal;
 		}
 	}
+	
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL>
+	{
+		return {
+			kind: Ast.Kind.INCANTATION_INVOCATION,
+			incantation: colour,
+			arg_raw: target.color,  // FIXME use name
+		};
+	}
 }
+
+export const colour = new ColourIncantation();

package/src/magic/local/dashed.ts

@@ -1,16 +1,30 @@
 import { Incantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 export class DashedIncantation extends Incantation<LOCAL>
 {
+	override readonly effect       = Incantation.Effect.LOCAL
+	override readonly identifier = "dashed"
 	override readonly description
 		= "Render a block as a dashed line."
-	
-	override readonly identifier = "dashed"
 
 	override apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.lineStyle = Desmos.Styles.DASHED;
 	}
+	
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.lineStyle === Desmos.Styles.DASHED) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: dashed,
+			};
+		}
+	}
 }
+
+export const dashed = new DashedIncantation();

package/src/magic/local/fill.ts

@@ -1,5 +1,7 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 interface FillOptions
 {
@@ -9,16 +11,31 @@ interface FillOptions
 
 export class FillIncantation extends ArgIncantation<LOCAL>
 {
-	override readonly description
-		= "Change fill styles for a rendered block."
-	
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier   = "fill"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
+	override readonly description
+		= "Change fill styles for a rendered block."
 
 	override apply(target: Desmos.ExpressionState, data: FillOptions)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.fillOpacity = data.opacity;
 	}
+
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.fillOpacity) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: fill,
+				arg_raw: super.emit_object_arg({
+					opacity: target.fillOpacity,
+				}),
+			};
+		}
+	}
 }
+
+export const fill = new FillIncantation();

package/src/magic/local/hide.ts

@@ -1,16 +1,30 @@
 import { Incantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 export class HideIncantation extends Incantation<LOCAL>
 {
+	override readonly effect       = Incantation.Effect.LOCAL
+	override readonly identifier = "hide"
 	override readonly description
 		= "Hide rendering for a block. This includes graphs, points, polygons, etc."
-	
-	override readonly identifier = "hide"
 
 	apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.hidden = true;
 	}
+		
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.hidden) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: hide,
+			};
+		}
+	}
 }
+
+export const hide = new HideIncantation();

package/src/magic/local/index.ts

@@ -1,29 +1,28 @@
 import { Incantation, type LOCAL } from "../incantation";
-import { AnimIncantation } from "./anim";
 
-import { ColourIncantation } from "./colour";
-import { DashedIncantation } from "./dashed";
-import { FillIncantation   } from "./fill";
-import { HideIncantation   } from "./hide";
-import { LabelIncantation  } from "./label";
-import { LineIncantation   } from "./line";
-import { NoLineIncantation } from "./no-line";
-import { PointIncantation  } from "./point";
-import { SecretIncantation } from "./secret";
-import { SliderIncantation } from "./slider";
+import { anim    } from "./anim";
+import { colour  } from "./colour";
+import { dashed  } from "./dashed";
+import { fill    } from "./fill";
+import { hide    } from "./hide";
+import { label   } from "./label";
+import { line    } from "./line";
+import { no_line } from "./no-line";
+import { point   } from "./point";
+import { secret  } from "./secret";
+import { slider  } from "./slider";
 
 
-export const LOCAL_INCANTATIONS: Incantation<LOCAL>[] =
-[
-	new AnimIncantation(),
-	new ColourIncantation(),
-	new DashedIncantation(),
-	new FillIncantation(),
-	new HideIncantation(),
-	new LabelIncantation(),
-	new LineIncantation(),
-	new NoLineIncantation(),
-	new PointIncantation(),
-	new SecretIncantation(),
-	new SliderIncantation(),
-];
+export const LOCAL_INCANTATIONS = {
+	anim,
+	colour,
+	dashed,
+	fill,
+	hide,
+	label,
+	line,
+	no_line,
+	point,
+	secret,
+	slider,
+} satisfies Record<string, Incantation<LOCAL>>;

package/src/magic/local/label.ts

@@ -1,20 +1,25 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
-import { DesmostError } from "../../errors";
 import type { DesmostOptions } from "../../options";
+import { DesmostError } from "../../errors";
+import { Ast } from "../../parser";
 
 
 interface LabelOptions
 {
-	text: string;
-	show?: boolean;
-	size?: number;
-	pos?: "ABOVE" | "BELOW" | "LEFT" | "RIGHT" | "ABOVE_LEFT" | "ABOVE_RIGHT" | "BELOW_LEFT" | "BELOW_RIGHT";
+	text:  string
+	show?: boolean
+	size?: number
+	pos?:
+		| "DEFAULT"
+		| "ABOVE" | "BELOW" | "LEFT" | "RIGHT"
+		| "ABOVE_LEFT" | "ABOVE_RIGHT" | "BELOW_LEFT" | "BELOW_RIGHT"
 }
 
 const VALID_FIELDS = ["text", "show", "size", "pos"];
 
 const VALID_POSITIONS = [
+	"DEFAULT",
 	"ABOVE", "BELOW", "LEFT", "RIGHT",
 	"ABOVE_LEFT", "ABOVE_RIGHT", "BELOW_LEFT", "BELOW_RIGHT",
 ];
@@ -22,12 +27,12 @@ const VALID_POSITIONS = [
 
 export class LabelIncantation extends ArgIncantation<LOCAL>
 {
-	override readonly description
-		= "Label a block that evaluates to a point(s)."
-
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier   = "label"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
+	override readonly description
+		= "Label a block that evaluates to a point(s)."
 
 	override apply(target: Desmos.ExpressionState, data: LabelOptions)
 	{
@@ -84,4 +89,22 @@ export class LabelIncantation extends ArgIncantation<LOCAL>
 
 		return out;
 	}
+		
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.label || target.showLabel) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: label,
+				arg_raw: super.emit_object_arg({
+					text: target.label,
+					show: target.showLabel,
+					size: target.labelSize,
+					pos:  target.labelOrientation,
+				}),
+			};
+		}
+	}
 }
+
+export const label = new LabelIncantation();

package/src/magic/local/line.ts

@@ -2,6 +2,7 @@ import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
 import type { DesmostOptions } from "../../options";
 import type { Fallible } from "../../errors";
+import { Ast } from "../../parser";
 
 
 interface LineOptions
@@ -16,12 +17,12 @@ const VALID_FIELDS = ["style", "width", "opacity"];
 
 export class LineIncantation extends ArgIncantation<LOCAL>
 {
-	override readonly description
-		= "Change line styles for a rendered block."
-
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier   = "line"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
+	override readonly description
+		= "Change line styles for a rendered block."
 
 	override apply(target: Desmos.ExpressionState, data: LineOptions)
 	{
@@ -43,4 +44,25 @@ export class LineIncantation extends ArgIncantation<LOCAL>
 
 		return out;
 	}
+	
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (
+				target.lineStyle !== Desmos.Styles.SOLID
+			|| target.lineWidth
+			|| target.lineOpacity
+		) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: line,
+				arg_raw: super.emit_object_arg({
+					style:   target.lineStyle,
+					width:   target.lineWidth,
+					opacity: target.lineOpacity,
+				}),
+			};
+		}
+	}
 }
+
+export const line = new LineIncantation();

package/src/magic/local/no-line.ts

@@ -1,16 +1,30 @@
 import { Incantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 export class NoLineIncantation extends Incantation<LOCAL>
 {
+	override readonly effect       = Incantation.Effect.LOCAL
+	override readonly identifier = "no-line"
 	override readonly description
 		= "Disable rendering lines for a block."
-	
-	override readonly identifier = "no-line"
 
 	override apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.lines = false;
 	}
+		
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.lines === false) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: no_line,
+			};
+		}
+	}
 }
+
+export const no_line = new NoLineIncantation();

package/src/magic/local/point.ts

@@ -1,5 +1,7 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 interface PointStyles
 {
@@ -11,12 +13,12 @@ interface PointStyles
 
 export class PointIncantation extends ArgIncantation<LOCAL>
 {
-	override readonly description
-		= ""
-	
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier   = "point"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
+	override readonly description
+		= ""
 
 	override apply(target: Desmos.ExpressionState, data: Partial<PointStyles>)
 	{
@@ -26,4 +28,26 @@ export class PointIncantation extends ArgIncantation<LOCAL>
 		if (data.size    != undefined)  target.pointSize    = data.size;
 		if (data.opacity != undefined)  target.pointOpacity = data.opacity;
 	}
+
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (
+				target.pointStyle && target.pointStyle !== Desmos.Styles.POINT
+			|| target.pointSize
+			|| target.pointOpacity
+		)
+		{
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: point,
+				arg_raw: super.emit_object_arg({
+					style:   target.pointStyle,
+					size:    target.pointSize,
+					opacity: target.pointOpacity,
+				}),
+			};
+		}
+	}
 }
+
+export const point = new PointIncantation();

package/src/magic/local/secret.ts

@@ -1,16 +1,30 @@
 import { Incantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 export class SecretIncantation extends Incantation<LOCAL>
 {
+	override readonly effect       = Incantation.Effect.LOCAL
+	override readonly identifier = "secret"
 	override readonly description
 		= "Turn a block into a secret expression, which is hidden from the end user."
-	
-	override readonly identifier = "secret"
 
 	override apply(target: Desmos.ExpressionState)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.secret = true;
 	}
+		
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.secret) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: secret,
+			};
+		}
+	}
 }
+
+export const secret = new SecretIncantation();

package/src/magic/local/slider.ts

@@ -1,5 +1,7 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
 
+import { Ast } from "../../parser";
+
 
 interface SliderBounds
 {
@@ -11,16 +13,29 @@ interface SliderBounds
 
 export class SliderIncantation extends ArgIncantation<LOCAL>
 {
-	override readonly description
-		= "Set the bounds of the slider for a variable."
-	
+	override readonly effect       = Incantation.Effect.LOCAL
 	override readonly identifier   = "slider"
 	override readonly requires_arg = true
 	override readonly arg_type     = Incantation.ArgType.OBJECT
+	override readonly description
+		= "Set the bounds of the slider for a variable."
 
 	override apply(target: Desmos.ExpressionState, data: SliderBounds)
 	{
 		super.require_expr_type(target.type, "expression");
 		target.sliderBounds = data;
 	}
+		
+	override extract(target: Desmos.Expression): Ast.IncantationInvocation<LOCAL> | void
+	{
+		if (target.sliderBounds != undefined) {
+			return {
+				kind: Ast.Kind.INCANTATION_INVOCATION,
+				incantation: slider,
+				arg_raw: super.emit_object_arg(target.sliderBounds),
+			};
+		}
+	}
 }
+
+export const slider = new SliderIncantation();

package/src/parser/ast.ts

@@ -3,15 +3,17 @@ import { Incantation, ArgIncantation } from "../magic";
 
 export namespace Ast
 {
-	/** What kind of AST node this is. */
-	export enum Kind
-	{
+	/**
+	 * What kind of AST node this is.
+	 */
+	export enum Kind {
 		EXPRESSION             = "Expression",
 		INCANTATION_INVOCATION = "Incantation-Invocation",
 	}
-
 	
-	/** A Desmos expression to add to the calculator. */
+	/**
+	 * A Desmos expression to add to the calculator.
+	 */
 	export interface Expression
 	{
 		kind: Kind.EXPRESSION
@@ -19,8 +21,9 @@ export namespace Ast
 		incantations: IncantationInvocation<Incantation.Effect.LOCAL>[]
 	}
 
-
-	/** A pending incantation invocation that requires applying its argument (if any), then applying its effect. */
+	/**
+	 * A pending incantation invocation that requires applying its argument (if any), then applying its effect.
+	 */
 	export type IncantationInvocation<Effect extends Incantation.Effect = Incantation.Effect> =
 		| {
 			kind: Kind.INCANTATION_INVOCATION

package/src/parser/desmost-parser.ts

@@ -1,9 +1,10 @@
 import { GenericParser } from "./generic-parser";
 import { Ast } from "./ast";
+import { NO_MATCH, INVALID_PARSE } from "./errors";
+import type { NoMatch, InvalidParse } from "./errors";
 
 import type { DesmostOptions } from "../options";
-import { NO_MATCH, DesmostError } from "../errors";
-import type { NoMatch, Fallible } from "../errors";
+import { DesmostError, type Fallible } from "../errors";
 import * as utils from "../utils";
 
 import {
@@ -116,7 +117,7 @@ export class DesmostParser extends GenericParser
 	{
 		// 1 global incantation
 		try {
-			let r = this.try_parse_incantation(GLOBAL_INCANTATIONS);
+			let r = this.try_parse_incantation(Object.values(GLOBAL_INCANTATIONS));
 
 			if (r !== NO_MATCH) {
 				this.eat_whitespace();
@@ -133,7 +134,7 @@ export class DesmostParser extends GenericParser
 
 		while (this.current === "/") {
 			try {
-				var invocation = this.try_parse_incantation(LOCAL_INCANTATIONS);
+				var invocation = this.try_parse_incantation(Object.values(LOCAL_INCANTATIONS));
 			}
 			catch (e) {
 				this.errors.push(e as Error);
@@ -310,14 +311,17 @@ export class DesmostParser extends GenericParser
 			return NO_MATCH;
 		}
 
-		let incantation = EXPR_INCANTATIONS.find(inc => inc.identifier === ident || inc.alias === ident);
+		let incantation =	
+			Object.values(EXPR_INCANTATIONS)
+			.find(inc => inc.identifier === ident || inc.alias === ident);
+		
 		if (incantation == undefined) {
 			this.i = init;
 			return NO_MATCH;
 		}
 
 		/* NOTE: All expression incantations currently require arguments, and all for the foreseeable future will too */
-		let arg_raw = this.parse_incantation_arg((incantation as ArgIncantation<EXPR>).arg_type);
+		let arg_raw = this.parse_incantation_arg(incantation.arg_type);
 
 		let data = {};
 		incantation.apply(data, arg_raw);

package/src/parser/errors.ts

@@ -0,0 +1,10 @@
+/** The parser failed to parse something (usually during speculative parsing), which only results in internal backtracking. */
+export const NO_MATCH = Symbol("no-match");
+
+/** The compiler encountered a non-fatal recoverable failure (usually during speculative parsing), which only results in internal backtracking. */
+export type NoMatch = typeof NO_MATCH & { readonly __brand?: unique symbol };
+
+
+export const INVALID_PARSE = Symbol("invalid-parse");
+
+export type InvalidParse = typeof INVALID_PARSE & { readonly __brand?: unique symbol };

package/src/parser/generic-parser.ts

@@ -1,5 +1,7 @@
-import { NO_MATCH, DesmostError } from "../errors";
-import type { NoMatch, Fallible } from "../errors";
+import { NO_MATCH, INVALID_PARSE } from "./errors";
+import type { NoMatch, InvalidParse } from "./errors";
+
+import { DesmostError, type Fallible } from "../errors";
 
 
 const IGNORED_CHARACTERS = new Set([
@@ -189,28 +191,24 @@ export class GenericParser
 	}
 
 	/**
-	 * Consume 0 or more space or tab characters.
+	 * Consume 0 or more space or tab characters (but not newlines).
+	 * 
+	 * This is always safe to call, and will match 0 characters if the parser is out of bounds.
 	 */
 	protected eat_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.out_of_bounds()) return;
-
 		while (this.current === ' ' || this.current === '\t') {
 			this.advance();
 		}
 	}
 
 	/**
-	 * Consume 0 or more whitespace characters.
+	 * Consume 0 or more whitespace characters (including newlines).
 	 * 
-	 * Same as `.consume_spaces()`, but allows tabs and newlines.
+	 * This is always safe to call, and will match 0 characters if the parser is out of bounds.
 	 */
 	protected eat_newlines(): 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'