desmost 0.1.0

package/src/magic/incantation.ts

@@ -0,0 +1,142 @@
+import Json5 from "json5";
+
+import { UnrecoverableError, type Unrecoverable } from "../errors";
+
+
+/**
+ * An *Incantation* is like a slash command that tells Desmost to do something - like changing the properties of an expression, or applying some settings to the calculator as a whole.
+ * 
+ * Incantations must be prefixed by a `/`. They look like this:
+ * 
+ * ```math
+ * /viewport{ left: -1, right: 1 }
+ * /hidden :: x = 69
+ * /text :: Never gonna give you up
+ * ```
+ * 
+ * Incantations that accept an argument derive from `ArgIncantation`.
+ */
+export abstract class Incantation<
+  Effect extends Incantation.Effect = Incantation.Effect
+>
+{
+  /** Short user-facing description of what the incantation does. */
+  public abstract readonly description: string
+
+  /** The raw text sequence that matches this incantation, such as `viewport` or `hidden`. */
+  public abstract readonly identifier: string
+
+  /** An alternative `.identifier`, strictly for localisation purposes only. */
+  public readonly alias?: string
+
+
+  /** Apply this incantation's effect to `target`, using the provided `data` if required. */
+  public abstract apply(
+    target: Effect extends GLOBAL ? Desmos.Calculator : Desmos.ExpressionState,
+    data?: unknown,
+  ): void
+
+  /** Error if the `actual` type of the given expression is not `required`. */
+  protected require_expr_type<T extends Desmos.ExpressionState["type"]>(
+    actual: unknown,
+    required: T,
+  ): asserts actual is T
+  {
+    if ((actual ?? "expression") !== required)
+    {
+      throw new UnrecoverableError.IllegalIncantation(
+        `/${this.identifier} can only applied to ${required === "expression" ? "latex" : required} expressions, but target block has type: ${actual}`
+      );
+    }
+  }
+}
+
+
+/**
+ * An incantation that accepts an argument.
+ */
+export abstract class ArgIncantation<
+  Effect extends Incantation.Effect = Incantation.Effect
+>
+  extends Incantation<Effect>
+{
+  /** Does this incantation always require an argument to be passed? */
+  public readonly requires_arg: boolean = true
+
+  /** What type of argument does this incantation accept? */
+  public abstract readonly arg_type: Incantation.ArgType
+
+
+  /**
+   * Evaluate the argument provided to this incantation, throwing if an error is encountered.
+   * 
+   * For instance, for `/viewport{ left: -1, right: 1 }`, this returns the POJO `{ left: -1, right: 1 }`.
+   * 
+   * ## Notes
+   * 
+   * Child incantation classes should override this method, though the defaults should cover most cases (except `ArgType.ENUM`).
+   */
+  public evaluate_arg(raw: string): Unrecoverable<unknown>
+  {
+    switch (this.arg_type) {
+      case Incantation.ArgType.STRING: return raw;
+      case Incantation.ArgType.LATEX:  return raw;
+      case Incantation.ArgType.ENUM:   return raw;
+      
+      case Incantation.ArgType.OBJECT:
+        try {
+          return Json5.parse(`{${raw}}`);
+        }
+        catch (e) {
+          // @ts-expect-error: fine
+          throw new UnrecoverableError.InvalidArgument(e.message);
+        }
+    }
+  }
+}
+
+
+export namespace Incantation
+{
+  /** The kind of effect an incantation produces - it either modifies only one block, or modifies the calculator as a whole. */
+  export enum Effect
+  {
+    /** An incantation that affects the entire Desmos calculator state, like `/desmos` or `/viewport`. */
+    GLOBAL,
+
+    /** An incantation that affects only the expression immediately following it, like `/hide` or `/slider`. */
+    LOCAL,
+    
+    /** An incantation that produces an expression, like `/latex` or `/text`. */
+    EXPR,
+  }
+
+  /** The type of argument an incantation accepts, which affects how it is parsed. */
+  export enum ArgType
+  {
+    /** Any arbitrary user text content, where characters like `"` and `'` don't have semantic meaning and can be ignored. */
+    STRING = "String",
+
+    /** LaTeX, which should have balanced `{}` braces. */
+    LATEX = "LaTeX",
+
+    /** Specific value from an allowed set of values, which will map to an enum value in the Desmos API. */
+    ENUM = "Enum",
+
+    /** JavaScript object fields, where characters like `{}` and `"` all have semantic meaning, and must be balanced. */
+    OBJECT = "Object",
+  }
+}
+
+
+// == ALIASES == //
+
+/** An incantation that affects the entire Desmos calculator state, like `/desmos` or `/viewport`. */
+export type GLOBAL = Incantation.Effect.GLOBAL;
+
+/** An incantation that affects only the expression immediately following it, like `/hide` or `/slider`. */
+export type LOCAL = Incantation.Effect.LOCAL;
+
+/** An incantation that produces an expression, like `/latex` or `/text`. */
+export type EXPR = Incantation.Effect.EXPR;
+

package/src/magic/index.ts

@@ -0,0 +1,6 @@
+export { Incantation, ArgIncantation } from "./incantation";
+export type { GLOBAL, LOCAL, EXPR } from "./incantation";
+
+export { GLOBAL_INCANTATIONS } from "./global";
+export { LOCAL_INCANTATIONS } from "./local";
+export { EXPR_INCANTATIONS } from "./expr";

package/src/magic/local/anim.ts

@@ -0,0 +1,17 @@
+import { Incantation, type LOCAL } from "../incantation";
+
+
+export class AnimIncantation extends Incantation<LOCAL>
+{
+  override readonly description
+    = "Animates the slider of a block."
+  
+  override readonly identifier = "anim"
+
+  override apply(target: Desmos.ExpressionState)
+  {
+    super.require_expr_type(target.type, "expression");
+    // @ts-expect-error: outdated types
+    target.playing = true;
+  }
+}

package/src/magic/local/colour.ts

@@ -0,0 +1,38 @@
+import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
+import { UnrecoverableError } from "../../errors";
+
+import { DesmosColour } from "../../desmos";
+
+
+export class ColourIncantation extends ArgIncantation<LOCAL>
+{
+  override readonly description
+    = ""
+
+  override readonly identifier   = "color"
+  override readonly alias        = "colour"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.ENUM
+
+  override apply(target: Desmos.ExpressionState, data: DesmosColour)
+  {
+    super.require_expr_type(target.type, "expression");
+    target.color = data;
+  }
+
+  override evaluate_arg(data: string): DesmosColour
+  {
+    switch (data.trim()) {
+      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}\``
+        );
+    }
+  }
+}

package/src/magic/local/dashed.ts

@@ -0,0 +1,16 @@
+import { Incantation, type LOCAL } from "../incantation";
+
+
+export class DashedIncantation extends Incantation<LOCAL>
+{
+  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;
+  }
+}

package/src/magic/local/fill.ts

@@ -0,0 +1,24 @@
+import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
+
+
+interface FillOptions
+{
+  opacity: number;
+}
+
+
+export class FillIncantation extends ArgIncantation<LOCAL>
+{
+  override readonly description
+    = "Change fill styles for a rendered block."
+  
+  override readonly identifier   = "fill"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  override apply(target: Desmos.ExpressionState, data: FillOptions)
+  {
+    super.require_expr_type(target.type, "expression");
+    target.fillOpacity = data.opacity;
+  }
+}

package/src/magic/local/hide.ts

@@ -0,0 +1,16 @@
+import { Incantation, type LOCAL } from "../incantation";
+
+
+export class HideIncantation extends Incantation<LOCAL>
+{
+  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;
+  }
+}

package/src/magic/local/index.ts

@@ -0,0 +1,27 @@
+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 { LineIncantation } from "./line";
+import { NoLineIncantation } from "./no-line";
+import { PointIncantation } from "./point";
+import { SecretIncantation } from "./secret";
+import { SliderIncantation } from "./slider";
+
+
+export const LOCAL_INCANTATIONS: Incantation<LOCAL>[] =
+[
+  new AnimIncantation(),
+  new ColourIncantation(),
+  new DashedIncantation(),
+  new FillIncantation(),
+  new HideIncantation(),
+  new LineIncantation(),
+  new NoLineIncantation(),
+  new PointIncantation(),
+  new SecretIncantation(),
+  new SliderIncantation(),
+];

package/src/magic/local/line.ts

@@ -0,0 +1,29 @@
+import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
+
+
+interface LineOptions
+{
+  style?:   keyof typeof Desmos.Styles;  // TODO allow raw enum
+  width?:   number;
+  opacity?: number;
+}
+
+
+export class LineIncantation extends ArgIncantation<LOCAL>
+{
+  override readonly description
+    = "Change line styles for a rendered block."
+
+  override readonly identifier   = "line"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  override apply(target: Desmos.ExpressionState, data: LineOptions)
+  {
+    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.opacity != undefined) target.lineOpacity = data.opacity;
+  }
+}

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

@@ -0,0 +1,16 @@
+import { Incantation, type LOCAL } from "../incantation";
+
+
+export class NoLineIncantation extends Incantation<LOCAL>
+{
+  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;
+  }
+}

package/src/magic/local/point.ts

@@ -0,0 +1,29 @@
+import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
+
+
+interface PointStyles
+{
+  style?:   keyof typeof Desmos.Styles;
+  size?:    number;
+  opacity?: number;
+}
+
+
+export class PointIncantation extends ArgIncantation<LOCAL>
+{
+  override readonly description
+    = ""
+  
+  override readonly identifier   = "point"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  override apply(target: Desmos.ExpressionState, data: Partial<PointStyles>)
+  {
+    super.require_expr_type(target.type, "expression");
+
+    if (data.style   != undefined)  target.pointStyle   = data.style;
+    if (data.size    != undefined)  target.pointSize    = data.size;
+    if (data.opacity != undefined)  target.pointOpacity = data.opacity;
+  }
+}

package/src/magic/local/secret.ts

@@ -0,0 +1,16 @@
+import { Incantation, type LOCAL } from "../incantation";
+
+
+export class SecretIncantation extends Incantation<LOCAL>
+{
+  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;
+  }
+}

package/src/magic/local/slider.ts

@@ -0,0 +1,27 @@
+import { Incantation, ArgIncantation, type LOCAL } from "../incantation";
+
+
+interface SliderBounds
+{
+  min?:  number | string;
+  max?:  number | string;
+  step?: number | string;
+}
+
+
+export class SliderIncantation extends ArgIncantation<LOCAL>
+{
+  override readonly description
+    = "Set the bounds of the slider for a variable."
+  
+  override readonly identifier   = "slider"
+  override readonly requires_arg = true
+  override readonly arg_type     = Incantation.ArgType.OBJECT
+
+  override apply(target: Desmos.ExpressionState, data: SliderBounds)
+  {
+    super.require_expr_type(target.type, "expression");
+    // @ts-expect-error: outdated types
+    target.sliderBounds = data;
+  }
+}

package/src/parser/ast.ts

@@ -0,0 +1,60 @@
+import { UnrecoverableError } from "../errors";
+import { Incantation, ArgIncantation } from "../magic";
+
+
+export namespace Ast
+{
+  /** What kind of parse result this is. */
+  export enum Kind
+  {
+    EXPRESSION             = "Expression",
+    INCANTATION_INVOCATION = "Incantation-Invocation",
+    INVALID_INCANTATION    = "Invalid-Incantation",
+  }
+
+  
+  /** A Desmos expression to add to the calculator. */
+  export interface Expression
+  {
+    kind: Kind.EXPRESSION
+    data: Desmos.ExpressionState
+    incantations: Array<
+      | IncantationInvocation<Incantation.Effect.LOCAL>
+      | InvalidInvocation
+      >
+  }
+
+
+  /** 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
+      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: false` configured).
+   */
+  export interface InvalidInvocation
+  {
+    kind: Kind.INVALID_INCANTATION
+    incantation: Incantation
+    arg_raw?: string
+    error: UnrecoverableError
+  }
+}
+
+/** An abstract object produced by parsing a block of source code. */
+export type Ast =
+  | Ast.Expression
+  | Ast.IncantationInvocation
+  | Ast.InvalidInvocation
+;