@wdprlib/parser 3.1.1 → 3.2.0

package/src/parser/rules/inline/bold.ts

@@ -0,0 +1,86 @@
+/**
+ *
+ * Parses the Wikidot bold formatting syntax: `**text**`.
+ *
+ * Bold text is delimited by double asterisks. The opening and closing
+ * markers must appear on the same line; if no closing `**` is found
+ * before a newline, the opening marker is emitted as literal text.
+ *
+ * Wikidot behavior for empty bold (`****`): the markers and their
+ * (empty) content are discarded entirely, producing no output.
+ *
+ * Bold may nest other inline formatting (italic, underline, etc.)
+ * within its body.
+ *
+ * Produces a `"container"` AST element with `type: "bold"`.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken, hasClosingMarkerBeforeNewline } from "../types";
+import { parseInlineUntil } from "./utils";
+
+/**
+ * Inline rule for parsing `**bold**` formatting.
+ *
+ * Triggered by a `BOLD_MARKER` token (`**`). The rule checks for a
+ * matching closing marker on the same line, then recursively parses
+ * inline content between the markers.
+ *
+ * When no closing marker is found, the opening `**` is treated as
+ * literal text rather than causing a parse failure, preserving
+ * Wikidot's graceful-degradation behavior.
+ */
+export const boldRule: InlineRule = {
+  name: "bold",
+  startTokens: ["BOLD_MARKER"],
+
+  /**
+   * Attempts to parse bold formatting at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result containing either a `"container"` element
+   *          with `type: "bold"`, an empty array (for `****`), or a text
+   *          fallback for unmatched markers
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const startToken = currentToken(ctx);
+
+    // Check if closing marker exists
+    if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: ctx.pos + 1 }, "BOLD_MARKER")) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: startToken.value }],
+        consumed: 1,
+      };
+    }
+
+    // Parse content between markers
+    const result = parseInlineUntil({ ...ctx, pos: ctx.pos + 1 }, "BOLD_MARKER");
+
+    // Empty bold (****) is discarded entirely in Wikidot
+    if (result.elements.length === 0) {
+      return {
+        success: true,
+        elements: [],
+        consumed: 1 + result.consumed + 1,
+      };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "bold",
+            attributes: {},
+            elements: result.elements,
+          },
+        },
+      ],
+      consumed: 1 + result.consumed + 1, // open + content + close
+    };
+  },
+};

package/src/parser/rules/inline/color.ts

@@ -0,0 +1,140 @@
+/**
+ *
+ * Parses the Wikidot inline color syntax: `##color|text##`.
+ *
+ * This syntax applies a CSS color to inline text. The color specifier
+ * and the text content are separated by a pipe (`|`). Both parts are
+ * required; an empty color or empty content causes the parse to fail.
+ *
+ * Supported color formats:
+ * - 3-digit hex (e.g. `c00`) -- automatically prefixed with `#`
+ * - 6-digit hex (e.g. `cc0000`) -- automatically prefixed with `#`
+ * - Named CSS colors (e.g. `blue`, `red`)
+ * - CSS color functions (e.g. `rgb(255,0,0)`)
+ *
+ * Wikidot syntax examples:
+ * - `##c00|Apple##` -- red text reading "Apple"
+ * - `##blue|Ocean##` -- blue text reading "Ocean"
+ * - `##rgb(0,128,0)|Green text##` -- CSS function color
+ *
+ * Produces a `"color"` AST element with the resolved color value and
+ * nested inline elements.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { hasClosingMarkerBeforeNewline } from "../types";
+import { parseInlineUntil } from "./utils";
+
+/**
+ * Inline rule for parsing `##color|text##` color formatting.
+ *
+ * Triggered by a `COLOR_MARKER` token (`##`). The rule collects the
+ * color specifier until a `PIPE` token, then recursively parses inline
+ * content until the closing `##`.
+ *
+ * Fails if:
+ * - No closing `##` is found on the same line
+ * - No pipe separator is present
+ * - The color specifier or content is empty
+ */
+export const colorRule: InlineRule = {
+  name: "color",
+  startTokens: ["COLOR_MARKER"],
+
+  /**
+   * Attempts to parse color formatting at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"color"` element, or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    // Check if closing marker exists
+    if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: ctx.pos + 1 }, "COLOR_MARKER")) {
+      return { success: false };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1; // ##
+
+    // Collect color specification until PIPE
+    let colorSpec = "";
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (
+        !token ||
+        token.type === "PIPE" ||
+        token.type === "COLOR_MARKER" ||
+        token.type === "NEWLINE" ||
+        token.type === "EOF"
+      ) {
+        break;
+      }
+      colorSpec += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Must have a PIPE separator
+    if (ctx.tokens[pos]?.type !== "PIPE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Parse inline content until closing ##
+    const contentResult = parseInlineUntil({ ...ctx, pos }, "COLOR_MARKER");
+    pos += contentResult.consumed;
+    consumed += contentResult.consumed;
+
+    // Consume closing ##
+    if (ctx.tokens[pos]?.type === "COLOR_MARKER") {
+      pos++;
+      consumed++;
+    } else {
+      return { success: false };
+    }
+
+    const textChildren = contentResult.elements;
+
+    const trimmedColor = colorSpec.trim();
+
+    // Wikidot requires non-empty color spec and non-empty content
+    if (trimmedColor === "" || textChildren.length === 0) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "color",
+          data: {
+            color: hexifyColor(trimmedColor),
+            elements: textChildren,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};
+
+/**
+ * Normalizes shorthand hex color values by prepending a `#` sign.
+ *
+ * Wikidot allows users to write hex colors without the `#` prefix
+ * (e.g. `c00` or `ff0000`). This function detects 3- or 6-character
+ * hex strings and adds the prefix. Non-hex color values (named colors,
+ * CSS functions) are returned unchanged.
+ *
+ * @param color - The trimmed color string from the markup
+ * @returns The color string, with `#` prepended if it was a bare hex value
+ */
+function hexifyColor(color: string): string {
+  if (/^[a-fA-F0-9]{3}$/.test(color) || /^[a-fA-F0-9]{6}$/.test(color)) {
+    return `#${color}`;
+  }
+  return color;
+}

package/src/parser/rules/inline/comment.ts

@@ -0,0 +1,90 @@
+/**
+ *
+ * Parses the Wikidot comment syntax: `[!-- text --]`.
+ *
+ * Comments are completely removed from the rendered output. Any content
+ * between the opening `[!--` and closing `--]` markers is consumed and
+ * discarded. Comments may contain arbitrary text, including markup
+ * characters that would otherwise be interpreted.
+ *
+ * If the closing `--]` is never found (unterminated comment), the rule
+ * fails and the opening `[!--` falls through to other rules or the
+ * text fallback.
+ *
+ * Unlike HTML comments (`<!-- -->`), Wikidot comments use square
+ * brackets with exclamation marks.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Inline rule for parsing `[!-- comment --]` syntax.
+ *
+ * Triggered by a `COMMENT_OPEN` token (`[!--`). Consumes all tokens
+ * until a `COMMENT_CLOSE` (`--]`) token is found, then returns an
+ * empty elements array (discarding the comment content).
+ *
+ * Comments may span across newlines. However, if an EOF is reached
+ * before the closing marker, the parse fails.
+ */
+export const commentRule: InlineRule = {
+  name: "comment",
+  startTokens: ["COMMENT_OPEN"],
+
+  /**
+   * Attempts to parse a comment at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with an empty elements array (comment discarded),
+   *          or `{ success: false }` if the comment is unterminated
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    let pos = ctx.pos + 1; // skip [!--
+    let consumed = 1;
+
+    // Consume all tokens until we find --]
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token) {
+        break;
+      }
+
+      if (token.type === "COMMENT_CLOSE") {
+        consumed++;
+        pos++;
+        // Return empty result - comment is discarded
+        return {
+          success: true,
+          elements: [],
+          consumed,
+        };
+      }
+
+      if (token.type === "EOF") {
+        // Unterminated comment - fail
+        ctx.diagnostics.push({
+          severity: "warning",
+          code: "unclosed-comment",
+          message: "Unterminated comment: missing closing --]",
+          position: openToken.position,
+        });
+        return { success: false };
+      }
+
+      pos++;
+      consumed++;
+    }
+
+    ctx.diagnostics.push({
+      severity: "warning",
+      code: "unclosed-comment",
+      message: "Unterminated comment: missing closing --]",
+      position: openToken.position,
+    });
+    return { success: false };
+  },
+};

package/src/parser/rules/inline/equation-ref.ts

@@ -0,0 +1,115 @@
+/**
+ *
+ * Parses the Wikidot equation reference syntax: `[[eref name]]`.
+ *
+ * An equation reference creates a clickable link that points to a
+ * named equation block defined elsewhere on the page (via
+ * `[[equation name]]` block syntax in the block-level parser). The
+ * reference is rendered as the equation's assigned number.
+ *
+ * Only the short form `eref` is recognized as a valid keyword.
+ * The long form `[[equation name]]` is NOT supported by Wikidot for
+ * inline references and is rendered as plain text.
+ *
+ * Produces an `"equation-reference"` AST element whose `data` field
+ * contains the reference name string.
+ *
+ * Wikidot syntax example:
+ * - `[[eref myEquation]]` -- references equation named "myEquation"
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseBlockName } from "../utils";
+
+/**
+ * Inline rule for parsing `[[eref name]]` equation references.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. The rule verifies the
+ * block name is `eref` (case-insensitive), then collects the
+ * reference name until the closing `]]`.
+ *
+ * Fails if the block name is not `eref`, the reference name is empty,
+ * or `]]` is not found.
+ */
+export const equationRefRule: InlineRule = {
+  name: "equation-ref",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse an `[[eref name]]` reference at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with an `"equation-reference"` element,
+   *          or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+
+    // Parse block name
+    const nameResult = parseBlockName(ctx, pos);
+    if (!nameResult) {
+      return { success: false };
+    }
+
+    const blockName = nameResult.name.toLowerCase();
+    // Only "eref" is supported in Wikidot
+    if (blockName !== "eref") {
+      return { success: false };
+    }
+
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Parse reference name
+    let refName = "";
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "BLOCK_CLOSE" || token.type === "NEWLINE") {
+        break;
+      }
+      refName += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    refName = refName.trim();
+
+    // Empty reference is invalid
+    if (!refName) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "equation-reference",
+          data: refName,
+        },
+      ],
+      consumed,
+    };
+  },
+};