@wdprlib/parser 3.1.2 → 3.2.0

package/src/parser/rules/inline/link-star.ts

@@ -0,0 +1,134 @@
+/**
+ *
+ * Parses the Wikidot star-link syntax: `[*url label]`.
+ *
+ * A star link is a convenience syntax for creating links that open
+ * in a new tab/window. The `[*` opening delimiter is tokenized as
+ * `BRACKET_STAR` by the lexer.
+ *
+ * Unlike the regular single-bracket link, the star link does not
+ * require a specific URL scheme -- any non-empty URL is accepted.
+ * If no label text is provided, the URL itself is used as the display text.
+ *
+ * The link always has `target: "new-tab"` regardless of the URL content.
+ *
+ * Wikidot syntax examples:
+ * - `[*https://example.com/ Visit Example]` -- with label
+ * - `[*https://example.com/]` -- URL used as label
+ *
+ * Produces a `"link"` AST element with `type: "direct"` and
+ * `target: "new-tab"`.
+ *
+ * @module
+ */
+import type { Element, LinkLabel } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { hasClosingMarkerBeforeNewline } from "../types";
+
+/**
+ * Inline rule for parsing `[*url label]` star links.
+ *
+ * Triggered by a `BRACKET_STAR` (`[*`) token. Collects the URL
+ * (until whitespace) and the optional label text (until `]`).
+ * When no label is provided, the URL serves as display text.
+ *
+ * Fails if:
+ * - No closing `]` is found on the same line
+ * - The URL is empty
+ */
+export const linkStarRule: InlineRule = {
+  name: "linkStar",
+  startTokens: ["BRACKET_STAR"],
+
+  /**
+   * Attempts to parse a star link at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"link"` element, or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    // Check if closing bracket exists
+    if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: ctx.pos + 1 }, "BRACKET_CLOSE")) {
+      return { success: false };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1; // [*
+
+    // Collect URL (until whitespace)
+    let url = "";
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (
+        !token ||
+        token.type === "WHITESPACE" ||
+        token.type === "BRACKET_CLOSE" ||
+        token.type === "NEWLINE" ||
+        token.type === "EOF"
+      ) {
+        break;
+      }
+      url += token.value;
+      pos++;
+      consumed++;
+    }
+
+    const trimmedUrl = url.trim();
+    if (!trimmedUrl) {
+      return { success: false };
+    }
+
+    // Skip whitespace between URL and label
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Collect label (until closing bracket)
+    let label = "";
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (
+        !token ||
+        token.type === "BRACKET_CLOSE" ||
+        token.type === "NEWLINE" ||
+        token.type === "EOF"
+      ) {
+        break;
+      }
+      label += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Consume closing bracket
+    if (ctx.tokens[pos]?.type === "BRACKET_CLOSE") {
+      pos++;
+      consumed++;
+    } else {
+      return { success: false };
+    }
+
+    const trimmedLabel = label.trim();
+    // If no label, use URL as label
+    const displayLabel = trimmedLabel || trimmedUrl;
+    const linkLabel: LinkLabel = { text: displayLabel };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: "direct",
+            link: trimmedUrl,
+            extra: null,
+            label: linkLabel,
+            target: "new-tab",
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/inline/link-triple.ts

@@ -0,0 +1,267 @@
+/**
+ *
+ * Parses the Wikidot triple-bracket link syntax: `[[[target | label]]]`.
+ *
+ * Triple-bracket links are Wikidot's primary page-linking mechanism.
+ * They support several target formats:
+ *
+ * - Page links: `[[[page-name]]]` or `[[[page-name | Label]]]`
+ * - Category pages: `[[[category:page-name]]]` (display shows text after colon)
+ * - Anchor links: `[[[#anchor-name]]]`
+ * - External URLs: `[[[https://example.com | Label]]]`
+ * - Interwiki links: `[[[wikipedia:Article]]]` (for known prefixes)
+ *
+ * Special syntax:
+ * - `[[[*target]]]` -- `*` prefix is stripped from target; for external URLs,
+ *   adds `target="_blank"` (new tab)
+ * - `[[[*|label]]]` -- links to root `/` with the given label
+ * - `[[[page|]]]` -- empty label after pipe defaults to the page name
+ *
+ * Multi-line support: a single newline within the link is converted to
+ * a space (in both target and label portions), but a double newline
+ * (paragraph break) or a newline directly before `]]]` invalidates the link.
+ *
+ * When the opening `[[[` has no valid closing `]]]`, it falls through
+ * as literal text rather than failing.
+ *
+ * Produces a `"link"` AST element with an appropriate `type` field
+ * (`"page"`, `"anchor"`, `"direct"`, or `"interwiki"`).
+ *
+ * @module
+ */
+import type { Element, LinkType, LinkLocation, LinkLabel } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Scans ahead to check whether a valid `LINK_CLOSE` (`]]]`) token
+ * exists, respecting Wikidot's multiline link rules.
+ *
+ * Allows at most one newline within the link content (typically after
+ * the pipe separator). Rejects the link if:
+ * - A double newline (paragraph break) is found
+ * - A newline appears directly before the closing `]]]`
+ * - EOF is reached without finding `]]]`
+ *
+ * @param ctx - The current parse context
+ * @param startPos - Token index at which to begin scanning (after `[[[`)
+ * @returns `true` if a valid closing `]]]` is found
+ */
+function hasClosingLinkMarker(ctx: ParseContext, startPos: number): boolean {
+  let pos = startPos;
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      return false;
+    }
+    if (token.type === "LINK_CLOSE") {
+      return true;
+    }
+    // Allow at most one newline, but not directly before LINK_CLOSE
+    if (token.type === "NEWLINE") {
+      const next = ctx.tokens[pos + 1];
+      if (next?.type === "NEWLINE") {
+        return false; // Double newline = paragraph break
+      }
+      // Newline directly before close = invalid
+      if (next?.type === "LINK_CLOSE") {
+        return false;
+      }
+    }
+    pos++;
+  }
+  return false;
+}
+
+/**
+ * Inline rule for parsing `[[[target | label]]]` triple-bracket links.
+ *
+ * Triggered by a `LINK_OPEN` (`[[[`) token. Collects the target string
+ * and optional pipe-separated label, then determines the link type
+ * (page, anchor, direct URL, or interwiki) based on the target format.
+ *
+ * When no valid closing `]]]` is found, the opening `[[[` is emitted
+ * as literal text.
+ *
+ * Edge cases handled:
+ * - Empty target with pipe (`[[[|text]]]`) is invalid
+ * - Multiple consecutive `#` in the target (`[[[page##anchor]]]`) is invalid
+ * - `[[[*|label]]]` links to root `/`
+ * - `[[[*target]]]` strips `*`; adds `target="_blank"` for external URLs
+ * - Category pages show only the text after the colon when no label is given
+ */
+export const linkTripleRule: InlineRule = {
+  name: "linkTriple",
+  startTokens: ["LINK_OPEN"],
+
+  /**
+   * Attempts to parse a triple-bracket link at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"link"` element, or a text
+   *          fallback when the syntax is invalid
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const startToken = currentToken(ctx);
+
+    if (!hasClosingLinkMarker(ctx, ctx.pos + 1)) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: startToken.value }],
+        consumed: 1,
+      };
+    }
+
+    // Collect tokens until LINK_CLOSE (newlines converted to spaces)
+    let target = "";
+    let labelText = "";
+    let foundPipe = false;
+    let consumed = 1; // opening [[[
+    let pos = ctx.pos + 1;
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "LINK_CLOSE" || token.type === "EOF") {
+        break;
+      }
+
+      // Convert newlines to spaces in link content (Wikidot allows single newlines)
+      if (token.type === "NEWLINE") {
+        if (foundPipe) {
+          labelText += " ";
+        } else {
+          target += " ";
+        }
+        consumed++;
+        pos++;
+        continue;
+      }
+
+      if (token.type === "PIPE" && !foundPipe) {
+        foundPipe = true;
+      } else if (foundPipe) {
+        labelText += token.value;
+      } else {
+        target += token.value;
+      }
+
+      consumed++;
+      pos++;
+    }
+
+    // Consume closing ]]]
+    if (ctx.tokens[pos]?.type === "LINK_CLOSE") {
+      consumed++;
+    }
+
+    const trimmedTarget = target.trim();
+
+    // Invalid: empty target with pipe (e.g., [[[|some-page]]])
+    if (trimmedTarget === "" && foundPipe) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: startToken.value }],
+        consumed: 1,
+      };
+    }
+
+    // Invalid: multiple consecutive # in target (e.g., [[[home###|Home]]], [[[page##anchor]]])
+    // Wikidot rejects these as invalid link syntax
+    if (/#{2,}/.test(trimmedTarget)) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: startToken.value }],
+        consumed: 1,
+      };
+    }
+
+    // `*` prefix: stripped from target; sets target="_blank" for external URLs
+    let finalTarget = trimmedTarget;
+    let hasStar = false;
+    if (trimmedTarget.startsWith("*")) {
+      hasStar = true;
+      finalTarget = trimmedTarget.slice(1);
+    }
+
+    const { linkType, link } = determineLinkTypeAndLocation(finalTarget);
+    const trimmedLabel = labelText.trim();
+
+    // Determine display text
+    let displayText: string;
+    if (foundPipe) {
+      // If label is empty (e.g., [[[page|]]]), use page name
+      displayText = trimmedLabel || finalTarget;
+    } else {
+      // For category pages (system:Recent Changes), use only the part after colon
+      // Use trimmedTarget (preserves * prefix) for display when no pipe
+      const colonIdx = trimmedTarget.indexOf(":");
+      if (colonIdx !== -1 && !trimmedTarget.startsWith("http") && !trimmedTarget.startsWith("*")) {
+        displayText = trimmedTarget.slice(colonIdx + 1).trim();
+      } else {
+        displayText = trimmedTarget;
+      }
+    }
+
+    const label: LinkLabel = { text: displayText };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: linkType,
+            link,
+            extra: null,
+            label,
+            target: hasStar && linkType === "direct" ? "new-tab" : null,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};
+
+/**
+ * Known interwiki prefixes recognized by Wikidot.
+ *
+ * Links whose target starts with one of these prefixes followed by a colon
+ * (e.g. `wikipedia:Article`) are classified as interwiki links rather than
+ * category page links.
+ */
+const INTERWIKI_PREFIXES = new Set(["wikipedia", "google", "dictionary", "wikidot"]);
+
+/**
+ * Determines the link type and structured location data from a raw
+ * triple-bracket link target string.
+ *
+ * Classification order:
+ * 1. Targets starting with `#` are anchor links
+ * 2. Targets starting with `http://` or `https://` are direct (external) links
+ * 3. Targets with a colon and a known interwiki prefix (without slashes)
+ *    are interwiki links
+ * 4. Everything else is a page link (including category pages like
+ *    `system:Recent Changes`)
+ *
+ * @param target - The trimmed, processed link target string
+ * @returns An object with `linkType` and `link` (the structured location data)
+ */
+function determineLinkTypeAndLocation(target: string): { linkType: LinkType; link: LinkLocation } {
+  if (target.startsWith("#")) {
+    return { linkType: "anchor", link: target };
+  }
+  if (target.startsWith("http://") || target.startsWith("https://")) {
+    return { linkType: "direct", link: target };
+  }
+  // Check for interwiki links (only known prefixes)
+  const colonIdx = target.indexOf(":");
+  if (colonIdx > 0 && !target.includes("/")) {
+    const prefix = target.slice(0, colonIdx).toLowerCase();
+    if (INTERWIKI_PREFIXES.has(prefix)) {
+      return { linkType: "interwiki", link: target };
+    }
+  }
+  // Page link (includes category pages like "system:Recent Changes")
+  return { linkType: "page", link: { site: null, page: target } };
+}

package/src/parser/rules/inline/math-inline.ts

@@ -0,0 +1,126 @@
+/**
+ *
+ * Parses the Wikidot inline math syntax: `[[$ LaTeX $]]`.
+ *
+ * Inline math renders a LaTeX expression inline with the surrounding
+ * text (as opposed to the block-level `[[math]]` which produces a
+ * display-mode equation).
+ *
+ * The LaTeX source is captured as-is between the `$` delimiters and
+ * stored in the AST for later rendering by a LaTeX engine (e.g. KaTeX
+ * or MathJax).
+ *
+ * Newlines are NOT allowed within inline math; if a `NEWLINE` token is
+ * encountered before the closing `$]]`, the parse fails.
+ *
+ * Wikidot syntax: `[[$ E = mc^2 $]]`
+ *
+ * Produces a `"math-inline"` AST element with `data["latex-source"]`
+ * containing the trimmed LaTeX string.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+
+/**
+ * Inline rule for parsing `[[$ LaTeX $]]` inline math.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. Looks for a `$` text
+ * token immediately after, collects the LaTeX source until the closing
+ * `$]]` sequence, and produces a math-inline element.
+ *
+ * Fails if:
+ * - No `$` follows the `[[`
+ * - A newline is encountered within the LaTeX source
+ * - The closing `$]]` sequence is not found
+ */
+export const mathInlineRule: InlineRule = {
+  name: "math-inline",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse inline math at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"math-inline"` 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;
+
+    // Expect $
+    if (ctx.tokens[pos]?.type !== "TEXT" || ctx.tokens[pos]?.value !== "$") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Skip whitespace
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+
+    // Collect LaTeX content until $]]
+    let latexSource = "";
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token) break;
+
+      // No newlines allowed in inline math
+      if (token.type === "NEWLINE") {
+        return { success: false };
+      }
+
+      // Check for closing $]]
+      if (
+        token.type === "TEXT" &&
+        token.value === "$" &&
+        ctx.tokens[pos + 1]?.type === "BLOCK_CLOSE"
+      ) {
+        break;
+      }
+
+      latexSource += token.value;
+      pos++;
+      consumed++;
+    }
+
+    // Expect $]]
+    if (ctx.tokens[pos]?.type !== "TEXT" || ctx.tokens[pos]?.value !== "$") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Trim the LaTeX source
+    latexSource = latexSource.trim();
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "math-inline",
+          data: {
+            "latex-source": latexSource,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,78 @@
+/**
+ *
+ * Parses the Wikidot monospace (teletype) formatting syntax: `{{text}}`.
+ *
+ * Monospace text is delimited by double curly braces. 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.
+ *
+ * Note: the opening marker is `MONO_MARKER` (`{{`) and the closing marker
+ * is `MONO_CLOSE` (`}}`). These are distinct token types because `{` and
+ * `}` have different lexer significance in some contexts.
+ *
+ * Monospace is a "container" element, meaning it can nest other inline
+ * formatting within its body. It renders as a `<tt>` element in HTML.
+ *
+ * Wikidot syntax: `{{monospace text}}`
+ *
+ * Produces a `"container"` AST element with `type: "monospace"`.
+ *
+ * @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 `{{monospace}}` formatting.
+ *
+ * Triggered by a `MONO_MARKER` token (`{{`). Checks for a matching
+ * `MONO_CLOSE` (`}}`) 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.
+ */
+export const monospaceRule: InlineRule = {
+  name: "monospace",
+  startTokens: ["MONO_MARKER"],
+
+  /**
+   * Attempts to parse monospace 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: "monospace"`, 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 }, "MONO_CLOSE")) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: startToken.value }],
+        consumed: 1,
+      };
+    }
+
+    // Parse content between markers
+    const result = parseInlineUntil({ ...ctx, pos: ctx.pos + 1 }, "MONO_CLOSE");
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "monospace",
+            attributes: {},
+            elements: result.elements,
+          },
+        },
+      ],
+      consumed: 1 + result.consumed + 1, // open + content + close
+    };
+  },
+};