desmost 0.10.0 → 0.11.0

package/src/magic/global/index.ts

@@ -1,18 +1,12 @@
-export { DesmosIncantation } from "./desmos";
-export { ViewportIncantation } from "./viewport";
-export { DarkModeIncantation } from "./dark-mode";
-
-
 import { Incantation, type GLOBAL } from "../incantation";
 
-import { DesmosIncantation } from "./desmos";
-import { ViewportIncantation } from "./viewport";
-import { DarkModeIncantation } from "./dark-mode";
+import { desmos   } from "./desmos";
+import { viewport } from "./viewport";
+import { dark     } from "./dark";
 
 
-export const GLOBAL_INCANTATIONS: Incantation<GLOBAL>[] =
-[
-	new DesmosIncantation(),
-	new ViewportIncantation(),
-	new DarkModeIncantation(),
-];
+export const GLOBAL_INCANTATIONS = {
+	desmos,
+	viewport,
+	dark,
+} satisfies Record<string, Incantation<GLOBAL>>;

package/src/magic/global/viewport.ts

@@ -2,6 +2,7 @@ import { Incantation, ArgIncantation, type GLOBAL } from "../incantation";
 
 import { DesmostError, type Fallible } from "../../errors";
 import type { DesmostOptions } from "../../options";
+import { Ast } from "../../parser";
 
 
 interface ViewportBounds
@@ -63,4 +64,32 @@ export class ViewportIncantation extends ArgIncantation<GLOBAL>
 
 		return out;
 	}
+
+	override extract(
+		target: Desmos.Calculator,
+		blank: Desmos.Calculator,
+	): Ast.IncantationInvocation<Incantation.Effect.GLOBAL> | void
+	{
+		let { left, right, bottom, top } = target.graphpaperBounds.mathCoordinates;
+		let bounds = { left, right, bottom, top };
+		
+		let defaults = blank.graphpaperBounds.mathCoordinates;
+
+		for (let [key, val] of Object.entries(bounds)) {
+			if (Math.abs(val - defaults[key]) < 0.001) {
+				delete bounds[key];
+			}
+		}
+
+		let arg_raw = super.emit_object_arg(bounds);
+		if (arg_raw.trim() === "") return;
+
+		return {
+			kind: Ast.Kind.INCANTATION_INVOCATION,
+			incantation: viewport,
+			arg_raw,
+		};
+	}
 }
+
+export const viewport = new ViewportIncantation();

package/src/magic/incantation.ts

@@ -2,6 +2,7 @@ import Json5 from "json5";
 import dedent from "dedent";
 
 import type { DesmostOptions } from "../options";
+import type { Ast } from "../parser";
 import { DesmostError, type Fallible } from "../errors";
 
 
@@ -18,12 +19,10 @@ import { DesmostError, type Fallible } from "../errors";
  * 
  * Incantations that accept an argument derive from `ArgIncantation`.
  */
-export abstract class Incantation<
-	Effect extends Incantation.Effect = Incantation.Effect
->
+export abstract class Incantation<Effect extends Incantation.Effect = Incantation.Effect>
 {
-	/** Short user-facing description of what the incantation does. */
-	abstract readonly description: string
+	/** Whether the incantation is a global, local or expression incantation. */
+	abstract readonly effect: Effect
 
 	/** The raw text sequence that matches this incantation, such as `viewport` or `hidden`. */
 	abstract readonly identifier: string
@@ -31,6 +30,9 @@ export abstract class Incantation<
 	/** An alternative `.identifier`, strictly for localisation purposes only. */
 	readonly alias?: string
 
+	/** Short user-facing description of what the incantation does. */
+	abstract readonly description: string
+
 
 	/** Apply this incantation's effect to `target`, using the provided `data` if required. */
 	abstract apply(
@@ -49,10 +51,20 @@ export abstract class Incantation<
 			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}`,
+				msg: `/${this.identifier} can only applied to \`${req}\` blocks, but target block has type: \`${actual}\``,
 			});
 		}
 	}
+
+	/**
+	 * Extract the AST representation of this incantation from `target`.
+	 * 
+	 * (The opposite of {@linkcode apply()}.)
+	*/
+	abstract extract(
+		target: Effect extends GLOBAL ? Desmos.Calculator : Desmos.ExpressionState,
+		blank?: Effect extends GLOBAL ? Desmos.Calculator : never,
+	): Ast.IncantationInvocation<Effect> | void
 }
 
 
@@ -133,6 +145,16 @@ export abstract class ArgIncantation<
 			}
 		}
 	}
+
+	/**
+	 * Stringify an object argument to its raw source text.
+	 */
+	protected emit_object_arg(data: object): string
+	{
+		let defined = Object.fromEntries(Object.entries(data).filter((k, v) => Boolean(v)));
+		
+		return Json5.stringify(defined).slice(1, -1);
+	}
 }
 
 

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();