desmost 0.3.2 → 0.4.1

package/src/parser/desmost-parser.ts

@@ -1,8 +1,10 @@
 import { GenericParser } from "./generic-parser";
 import { Ast } from "./ast";
 
+import type { DesmostOptions } from "../compiler";
 import { FAIL, UnrecoverableError } from "../errors";
 import type { RecoverableFail, Unrecoverable, MaybeRecoverable } from "../errors";
+import * as utils from "../utils";
 
 import {
   Incantation, ArgIncantation,
@@ -10,8 +12,6 @@ import {
 } from "../magic";
 import type { GLOBAL, LOCAL, EXPR } from "../magic";
 
-import type { DesmostOptions } from "../compiler";
-
 
 /**
  * A stateful lazy parser for Desmost.
@@ -318,24 +318,31 @@ export class DesmostParser extends GenericParser
    *             ^^^^^^^
    * ```
    * 
+   * Returns the raw text without `{}`.
+   * 
+   * ```ts
+   * /incantation{ arg }
+   *               ^^^
+   * ```
+   * 
    * ## Notes
    * 
    * We don't actually care for what type the argument is since we won't be evaluating it, we just want to find the closing `}`.
    * 
-   * However, the argument itself might be *meant* to contain a `}`. So we need a way to accurately identify the actual closing brace:
+   * However, the argument itself might contain one or many `}`! So we need a way to accurately identify the actual closing brace:
    * 
    * ```ts
    * /incantation{ field: { value: 1 } }
    *                                 ^ ^
    * ```
    * 
-   * A well-formed argument always has matching pairs of `{}`, so we'll keep a stack. It starts with the opening `{`. When the stack is depleted, we must've reached the end of the argument.
+   * In our context, we have the guarantee that any well-formed argument always has matching pairs of `{}`. So we'll keep track of a context stack that starts with the opening `{`, and when the stack is depleted, we must've reached the end of the argument.
    * 
    * However, there's still more edge cases:
    * 
    * ```ts
    * /label{ text: "This }s weird" }
-   *              ^
+   *                     ^
    * ```
    * 
    * `{` and `}` can appear in strings, and they won't necessarily be matched, so we'll ignore them by also tracking string contexts.
@@ -345,9 +352,18 @@ export class DesmostParser extends GenericParser
    *          ^
    * ```
    * 
-   * `{` and `}` in LaTeX can be escaped with `\{` or `\}`, and these won't necessarily be matched, so we'll ignore them by also tracking backslash escapes.
+   * `{` and `}` in LaTeX can be escaped with `\{` or `\}`, and these won't necessarily be matched, so we'll ignore them by also tracking escapes.
    * 
    * If the user truly mismatches `{}`, then, well ...parsing will fail catastrophically!
+   * 
+   * This method also handles parsing raw enum literals by converting them to strings. So this:
+   * 
+   * ```ts
+   * /line{ style: DOTTED }
+   *               ^^^^^^
+   * ```
+   * 
+   * Produces `style: "DOTTED"` (instead of `style: DOTTED`, which would fail to later parse as JSON).
    */
   parse_incantation_arg(
     /**
@@ -367,68 +383,62 @@ export class DesmostParser extends GenericParser
       `Expected \`{\` to start incantation argument, but found: \`${this.preview()}\``
     );
 
-    enum Ctx {
-      BLOCK  = Char.L_BRACE,
-      STR_1  = Char.QUOTE_SINGLE,
-      STR_2  = Char.QUOTE_DOUBLE,
-      STR_F  = Char.BACKTICK,
-      ESCAPE = Char.BACKSLASH,
-    }
+    /** The context stack to keep track of when the closing `}` is encountered. */
+    let stack = new ContextStack();
 
-    let stack: Ctx[] = [Ctx.BLOCK];
-
-    /**
-     * Pop `ctx` if it is the currently active context, returning `true` if successful.
-    */
-    function try_pop(ctx: Ctx): boolean
-    {
-      if (stack.at(-1) === ctx) {
-        stack.pop();
-        return true;
-      }
-
-      return false;
-    }
+    /** Indices at which to later insert `"` quotes. */
+    let indices_to_insert_quotes: number[] = [];
 
     while (stack.length > 0) {
-      if (try_pop(Ctx.ESCAPE)) {
+      // If the last character was an escape, we don't care at all what the next character is!
+      // This handles \\ double escape perfectly fine, since the first negates the second
+      if (stack.try_pop(Ctx.ESCAPE)) {
         this.advance(
-          `Unexpected end of input while parsing incantation argument, stack: ${JSON.stringify(stack)}`
+          `Unexpected end of input while parsing incantation argument, stack: ${stack.debug()}`
         );
       }
       
-      let top = stack.at(-1)!;
-
-      switch (this.current) {
-        case Ctx.ESCAPE: stack.push(Ctx.ESCAPE); break;
+      let top = stack.top!;
 
-        case Char.L_BRACE:
-          /* NOTE: *Currently* `{}` should be ignored in all contexts except `Ctx.BLOCK`. This might change if more contexts are added in future! */
-          if (top !== Ctx.BLOCK) break;
-          stack.push(Ctx.BLOCK); break;
+      switch (this.current)
+      {
+        case Char.BACKSLASH: stack.push(Ctx.ESCAPE); break;
 
-        case Char.R_BRACE:
-          try_pop(Ctx.BLOCK); break;
+        case "{":  stack.push(     Ctx.BLOCK, { unless: [Ctx.STR_1, Ctx.STR_2, Ctx.STR_F] }); break;
+        case "}":  stack.force_pop(Ctx.BLOCK, { unless: [Ctx.STR_1, Ctx.STR_2, Ctx.STR_F] }); break;
       }
 
-      if (arg_type === Incantation.ArgType.OBJECT) {
-        switch (this.current) {
-          case Ctx.STR_1:
-            if (top === Ctx.STR_2) break;
-            if (top === Ctx.STR_F) break;
-            try_pop(Ctx.STR_1) || stack.push(Ctx.STR_1);
+      if (arg_type === Incantation.ArgType.OBJECT)
+      {
+        if (top === Ctx.VALUE && this.current?.match(/[a-zA-Z]/)) {
+          stack.push(Ctx.ENUM);
+          indices_to_insert_quotes.push(this.i);
+        }
+        else if (top === Ctx.ENUM && this.current?.match(/[^a-zA-Z]/)) {
+          stack.pop();
+          indices_to_insert_quotes.push(this.i);
+
+          if (indices_to_insert_quotes.length % 2 != 0) {
+            console.error(`Desmost [INTERNAL]: Logic error in \`parse_incantation_arg()\`: Mismatched inserted quotes`);
+          }
+        }
+
+        switch (this.current)
+        {
+          case ":": stack.push(Ctx.VALUE, { when: [Ctx.BLOCK] }); break;
+          case ",": stack.try_pop(Ctx.VALUE); break;
+
+          case Char.QUOTE_1:
+            stack.pop_or_push(Ctx.STR_1, { unless: [Ctx.STR_2, Ctx.STR_F] });
+            stack.try_pop(Ctx.VALUE);
             break;
-            
-          case Ctx.STR_2:
-            if (top === Ctx.STR_1) break;
-            if (top === Ctx.STR_F) break;
-            try_pop(Ctx.STR_2) || stack.push(Ctx.STR_2);
+          case Char.QUOTE_2:
+            stack.pop_or_push(Ctx.STR_2, { unless: [Ctx.STR_1, Ctx.STR_F] });
+            stack.try_pop(Ctx.VALUE);
             break;
-
-          case Ctx.STR_F:
-            if (top === Ctx.STR_1) break;
-            if (top === Ctx.STR_2) break;
-            try_pop(Ctx.STR_F) || stack.push(Ctx.STR_F);
+          case Char.BACKTICK:
+            stack.pop_or_push(Ctx.STR_F, { unless: [Ctx.STR_1, Ctx.STR_2] });
+            stack.try_pop(Ctx.VALUE);
             break;
         }
       }
@@ -439,18 +449,119 @@ export class DesmostParser extends GenericParser
     }
 
     /* NOTE: Cut in by 1 on both sides to exclude {} braces */
-    return this.source.slice(init + 1, this.i - 1).trim();
+    let out = 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("");
+      if (["true", "false", "null", "undefined"].includes(value)) continue;
+      
+      out.splice(j, 0, `"`);
+      out.splice(i, 0, `"`);
+    }
+
+    return out.join("").trim();
   }
+}
 
+
+class ContextStack
+{
+  #data: Ctx[] = [Ctx.BLOCK]
+
+  get length(): number {
+    return this.#data.length;
+  }
+
+  /** The currently active context. */
+  get top(): Ctx {
+    return this.#data.at(-1)!;
+  }
+
+  push(ctx: Ctx, options?: StackOperationOptions): boolean
+  {
+    if (this.#should_skip(options)) return false;
+
+    this.#data.push(ctx);
+    return true;
+  }
+
+  pop(): void
+  {
+    this.#data.pop();
+  }
+
+  /** Pop `ctx` if it is the currently active context, returning `true` if so. */
+  try_pop(ctx: Ctx): boolean
+  {
+    if (this.top === ctx) {
+      this.#data.pop();
+      return true;
+    } else {
+      return false;
+    }
+  }
+
+  /** Backtrack until `ctx` is popped. */
+  force_pop(ctx: Ctx, options?: StackOperationOptions): boolean
+  {
+    if (this.#should_skip(options)) return false;
+
+    let idx = this.#data.lastIndexOf(ctx);
+    if (idx === -1) return false;
+
+    /* NOTE: We could report errors for unterminated contexts, but we'll leave that for the actual evaluation - in case we get something wrong ;) */
+    this.#data.splice(idx);
+    return true;
+  }
+
+  /** Pop `ctx` if it is the current context, else push it onto the stack. */
+  pop_or_push(ctx: Ctx, options?: StackOperationOptions): boolean
+  {
+    if (this.#should_skip(options)) return false;
+
+    this.try_pop(ctx) || this.push(ctx);
+    return true;
+  }
+
+  debug(): string {
+    return JSON.stringify(this.#data);
+  }
+
+  #should_skip(options: StackOperationOptions | undefined): boolean
+  {
+    return Boolean(
+        options?.when != undefined && !options?.when?.includes(this.top)
+      || options?.unless?.includes(this.top)
+    );
+  }
 }
 
+interface StackOperationOptions
+{
+  /** Only perform this operation if the current context is any of these. */
+  when?: Ctx[];
+
+  /** Don't perform this operation if the current context is any of these. */
+  unless?: Ctx[];
+}
 
 enum Char
 {
-  L_BRACE      = "{",
-  R_BRACE      = "}",
-  QUOTE_SINGLE = `'`,
-  QUOTE_DOUBLE = `"`,
-  BACKTICK     = "`",
-  BACKSLASH    = "\\",
+  BACKSLASH = "\\",
+  QUOTE_1   = `'`,
+  QUOTE_2   = `"`,
+  BACKTICK  = "`",
+}
+
+enum Ctx {
+  BLOCK  = "{",
+  VALUE  = ":",
+  ENUM   = "<enum literal>",
+  STR_1  = Char.QUOTE_1,
+  STR_2  = Char.QUOTE_2,
+  STR_F  = Char.BACKTICK,
+  ESCAPE = Char.BACKSLASH,
 }

package/src/parser/generic-parser.ts

@@ -8,9 +8,9 @@ const IGNORED_CHARACTERS = new Set([
 
 
 /**
- * A stateful lazy parser, providing core methods for parsing.
+ * A stateful lazy parser, providing core (non-Desmost-specific) methods for parsing.
  * 
- * Many methods come in `<verb>` and `try_<verb>` pairs. On parsing failure, the former throws an `UnrecoverableError`, but the latter instead backtracks and only throws a `RecoverableFail`.
+ * Many methods come in `<verb>` and `try_<verb>` pairs. On parsing failure, the former throws an `UnrecoverableError`, but the latter instead backtracks and only returns a `RecoverableFail`. The former is for expected parses, while the latter is for speculative parsing.
  */
 export class GenericParser
 {
@@ -57,7 +57,7 @@ export class GenericParser
   }
 
   /**
-   * Peek a snippet of the upcoming source text (for error messages).
+   * Peek a snippet of the upcoming source text.
    * 
    * Optionally start from the given `idx`.
    */

package/src/parser/index.ts

@@ -1,7 +1,5 @@
 /**
  * Implements `DesmostParser`, the Desmost parsing engine.
- * 
- * The parsing engine makes heavy use of exceptions for backtracking, which is *very unperformant*, but makes for *much more readable code*. Desmost isn't expecting to parse huge documents of source code, so I decided this is an acceptable trade-off.
  */
 
 export { DesmostParser } from "./desmost-parser";

package/src/utils.ts

@@ -0,0 +1,54 @@
+export function* reversing<T>(items: ArrayLike<T>): Generator<T>
+{
+  for (let i = items.length - 1; i >= 0; i--) {
+    yield items[i];
+  }
+}
+
+export function paired<T>(items: Iterable<T>): Array<[left: T, right: T]>
+{
+  return pairing(items).toArray();
+}
+
+export function* pairing<T>(items: Iterable<T>): Generator<[left: T, right: T]>
+{
+  let previous = null;
+
+  for (let item of items) {
+    if (previous === null) {
+      previous = item;
+      continue;
+    }
+    else {
+      yield [previous, item];
+      previous = null;
+    }
+  }
+
+  if (previous !== null) {
+    return previous;
+  }
+}
+
+
+export function chars(s: string, start?: number, stop?: number): string[]
+{
+  return new Range(start ?? 0, stop ?? s.length).map(i => s[i]).toArray();
+}
+
+
+export class Range
+{
+  constructor(
+    protected start: number, 
+    protected stop: number,
+  )
+  {}
+
+  *map<T>(callback: (n: number) => T): Generator<T>
+  {
+    for (let n = this.start; n < this.stop; n++) {
+      yield callback(n);
+    }
+  }
+}