@wdprlib/parser 3.1.2 → 4.0.0

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

@@ -0,0 +1,150 @@
+/**
+ *
+ * Central registry and priority-ordered list of all inline parsing rules.
+ *
+ * This module imports every inline rule, re-exports them for individual use,
+ * and assembles them into the {@link inlineRules} array, which defines the
+ * order in which rules are attempted during inline parsing.
+ *
+ * Rule ordering matters: earlier rules take priority when multiple rules
+ * could match the same token. For example, formatting rules (bold, italic,
+ * etc.) are tried before link rules, and the text/fallback rules are
+ * placed last as catch-alls.
+ *
+ * The `fallbackRule` is exported separately as `inlineFallbackRule` because
+ * it matches any token type and is used as a last resort when no other rule
+ * succeeds. It is NOT included in the `inlineRules` array to prevent it
+ * from short-circuiting more specific rules.
+ *
+ * @module
+ */
+import type { InlineRule } from "../types";
+import { boldRule } from "./bold";
+import { italicRule } from "./italic";
+import { underlineRule } from "./underline";
+import { strikethroughRule } from "./strikethrough";
+import { superscriptRule } from "./superscript";
+import { subscriptRule } from "./subscript";
+import { monospaceRule } from "./monospace";
+import { linkTripleRule } from "./link-triple";
+import { linkSingleRule } from "./link-single";
+import { linkAnchorRule } from "./link-anchor";
+import { linkStarRule } from "./link-star";
+import { colorRule } from "./color";
+import {
+  backslashLineBreakRule,
+  newlineLineBreakRule,
+  underscoreLineBreakRule,
+} from "./line-break";
+import { commentRule } from "./comment";
+import { htmlInlineRule } from "./html";
+import { rawRule } from "./raw";
+import { spanRule, closeSpanRule } from "./span";
+import { sizeRule } from "./size";
+import { footnoteRule } from "./footnote";
+import { imageRule } from "./image";
+import { guillemetRule } from "./guillemet";
+import { userRule } from "./user";
+import { anchorNameRule } from "./anchor-name";
+import { anchorRule } from "./anchor";
+import { mathInlineRule } from "./math-inline";
+import { equationRefRule } from "./equation-ref";
+import { exprRule, ifRule, ifExprRule } from "./expr";
+import { bibciteRule } from "./bibcite";
+import { textRule, fallbackRule } from "./text";
+
+export { boldRule } from "./bold";
+export { italicRule } from "./italic";
+export { underlineRule } from "./underline";
+export { strikethroughRule } from "./strikethrough";
+export { superscriptRule } from "./superscript";
+export { subscriptRule } from "./subscript";
+export { monospaceRule } from "./monospace";
+export { linkTripleRule } from "./link-triple";
+export { linkSingleRule } from "./link-single";
+export { linkAnchorRule } from "./link-anchor";
+export { linkStarRule } from "./link-star";
+export { colorRule } from "./color";
+export {
+  backslashLineBreakRule,
+  newlineLineBreakRule,
+  underscoreLineBreakRule,
+} from "./line-break";
+export { commentRule } from "./comment";
+export { htmlInlineRule } from "./html";
+export { rawRule } from "./raw";
+export { spanRule, closeSpanRule } from "./span";
+export { sizeRule } from "./size";
+export { footnoteRule } from "./footnote";
+export { imageRule } from "./image";
+export { guillemetRule } from "./guillemet";
+export { userRule } from "./user";
+export { anchorNameRule } from "./anchor-name";
+export { anchorRule } from "./anchor";
+export { mathInlineRule } from "./math-inline";
+export { equationRefRule } from "./equation-ref";
+export { exprRule, ifRule, ifExprRule } from "./expr";
+export { bibciteRule } from "./bibcite";
+export { textRule, fallbackRule } from "./text";
+
+/**
+ * All inline rules in priority order.
+ *
+ * Rules are tried top-to-bottom against the current token. The first
+ * rule whose `startTokens` match the token type and whose `parse()`
+ * returns `{ success: true }` wins.
+ *
+ * Ordering rationale:
+ * 1. Paired formatting markers (bold, italic, underline, strikethrough,
+ *    superscript, subscript, monospace) -- most common inline syntax
+ * 2. Link rules (triple, single, anchor, star) -- order matters because
+ *    `[[[` must be tried before `[`
+ * 3. Color, line-break, and comment rules
+ * 4. Raw (verbatim) text
+ * 5. Block-open-triggered rules (image, size, footnote, span, user,
+ *    expr/if/ifexpr, anchor-name, anchor, math-inline, equation-ref)
+ * 6. Bibcite (double-parenthesis syntax)
+ * 7. Guillemet (typographic angle quotes)
+ * 8. Text rule (catch-all for TEXT and WHITESPACE tokens)
+ *
+ * The `fallbackRule` is intentionally excluded; it is used as a
+ * separate last-resort handler.
+ */
+export const inlineRules: InlineRule[] = [
+  boldRule,
+  italicRule,
+  underlineRule,
+  strikethroughRule,
+  superscriptRule,
+  subscriptRule,
+  monospaceRule,
+  linkTripleRule,
+  linkSingleRule,
+  linkAnchorRule,
+  linkStarRule,
+  colorRule,
+  backslashLineBreakRule,
+  underscoreLineBreakRule,
+  newlineLineBreakRule,
+  commentRule,
+  htmlInlineRule,
+  rawRule,
+  imageRule,
+  sizeRule,
+  footnoteRule,
+  spanRule,
+  closeSpanRule,
+  userRule,
+  exprRule,
+  ifRule,
+  ifExprRule,
+  anchorNameRule,
+  anchorRule,
+  mathInlineRule,
+  equationRefRule,
+  bibciteRule,
+  guillemetRule,
+  textRule,
+];
+
+export { fallbackRule as inlineFallbackRule };

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

@@ -0,0 +1,46 @@
+/**
+ *
+ * Parses the Wikidot italic formatting syntax: `//text//`.
+ *
+ * Italic text is delimited by double forward slashes. 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.
+ *
+ * Unlike bold (which discards empty markers), italic markers with empty
+ * content (`////`) still produce an italic container, matching Wikidot's
+ * behavior.
+ *
+ * Italic may nest other inline formatting within its body.
+ *
+ * Produces a `"container"` AST element with `type: "italics"`.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { parseSameLineDelimitedContainer } from "./formatting/container";
+
+/**
+ * Inline rule for parsing `//italic//` formatting.
+ *
+ * Triggered by an `ITALIC_MARKER` token (`//`). Checks for a matching
+ * closing marker on the same line, then recursively parses inline content.
+ *
+ * When no closing marker is found, the opening `//` is treated as
+ * literal text.
+ */
+export const italicRule: InlineRule = {
+  name: "italic",
+  startTokens: ["ITALIC_MARKER"],
+
+  /**
+   * Attempts to parse italic 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: "italics"`, or a text fallback for unmatched markers
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    return parseSameLineDelimitedContainer(ctx, "ITALIC_MARKER", "italics");
+  },
+};

package/src/parser/rules/inline/line-break/backslash.ts

@@ -0,0 +1,58 @@
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { createPreservedLineBreak } from "./elements";
+
+export const backslashLineBreakRule: InlineRule = {
+  name: "backslashLineBreak",
+  startTokens: ["WHITESPACE", "BACKSLASH_BREAK"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const currentTok = ctx.tokens[ctx.pos];
+    if (!currentTok) {
+      return { success: false };
+    }
+
+    if (currentTok.type === "WHITESPACE") {
+      const nextTok = ctx.tokens[ctx.pos + 1];
+      if (nextTok?.type !== "BACKSLASH_BREAK") {
+        return { success: false };
+      }
+
+      if (isFollowedByUnderscoreBreak(ctx, ctx.pos + 2)) {
+        return {
+          success: true,
+          elements: [createPreservedLineBreak()],
+          consumed: 2,
+        };
+      }
+
+      return {
+        success: true,
+        elements: [createPreservedLineBreak(), { element: "text", data: " " }],
+        consumed: 2,
+      };
+    }
+
+    if (currentTok.type === "BACKSLASH_BREAK") {
+      return {
+        success: true,
+        elements: [createPreservedLineBreak()],
+        consumed: 1,
+      };
+    }
+
+    return { success: false };
+  },
+};
+
+function isFollowedByUnderscoreBreak(ctx: ParseContext, startPos: number): boolean {
+  const afterBreak = ctx.tokens[startPos];
+  const afterAfter = ctx.tokens[startPos + 1];
+  const afterAfterAfter = ctx.tokens[startPos + 2];
+
+  return (
+    afterBreak?.type === "WHITESPACE" &&
+    afterAfter?.type === "UNDERSCORE" &&
+    (afterAfterAfter?.type === "NEWLINE" || afterAfterAfter?.type === "EOF")
+  );
+}

package/src/parser/rules/inline/line-break/elements.ts

@@ -0,0 +1,9 @@
+import type { Element } from "@wdprlib/ast";
+
+export type PreservedLineBreak = Extract<Element, { element: "line-break" }> & {
+  _preservedTrailingBreak?: boolean;
+};
+
+export function createPreservedLineBreak(): PreservedLineBreak {
+  return { element: "line-break", _preservedTrailingBreak: true };
+}

package/src/parser/rules/inline/line-break/index.ts

@@ -0,0 +1,3 @@
+export { newlineLineBreakRule } from "./newline";
+export { backslashLineBreakRule } from "./backslash";
+export { underscoreLineBreakRule } from "./underscore";

package/src/parser/rules/inline/line-break/newline.ts

@@ -0,0 +1,82 @@
+import type { Element } from "@wdprlib/ast";
+import type { TokenType } from "../../../../lexer";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+
+export const newlineLineBreakRule: InlineRule = {
+  name: "newlineLineBreak",
+  startTokens: ["NEWLINE"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const currentTok = ctx.tokens[ctx.pos];
+    if (!currentTok || currentTok.type !== "NEWLINE") {
+      return { success: false };
+    }
+
+    const lookAhead = skipWhitespace(ctx, ctx.pos + 1) - ctx.pos;
+    const nextMeaningfulToken = ctx.tokens[ctx.pos + lookAhead];
+    const suppressLineBreak =
+      !nextMeaningfulToken ||
+      nextMeaningfulToken.type === "EOF" ||
+      nextMeaningfulToken.type === "NEWLINE" ||
+      isValidBlockStartAfterNewline(ctx, ctx.pos + lookAhead) ||
+      hasBackslashBreakAfterNewline(ctx);
+
+    if (suppressLineBreak) {
+      return { success: true, elements: [], consumed: 1 };
+    }
+
+    return {
+      success: true,
+      elements: [{ element: "line-break" }],
+      consumed: 1,
+    };
+  },
+};
+
+function isBlockStartToken(type: TokenType | undefined): boolean {
+  switch (type) {
+    case "BLOCKQUOTE_MARKER":
+    case "LIST_BULLET":
+    case "LIST_NUMBER":
+    case "HEADING_MARKER":
+    case "HR_MARKER":
+    case "TABLE_MARKER":
+      return true;
+    default:
+      return false;
+  }
+}
+
+function isValidBlockStartAfterNewline(ctx: ParseContext, tokenPos: number): boolean {
+  const token = ctx.tokens[tokenPos];
+  if (!isBlockStartToken(token?.type) || !token?.lineStart) {
+    return false;
+  }
+
+  if (token.type !== "HEADING_MARKER") {
+    return true;
+  }
+
+  const markerLen = token.value.length;
+  const afterMarker = ctx.tokens[tokenPos + 1];
+  if (markerLen > 6) {
+    return false;
+  }
+  if (afterMarker?.type === "STAR") {
+    return ctx.tokens[tokenPos + 2]?.type === "WHITESPACE";
+  }
+  return afterMarker?.type === "WHITESPACE";
+}
+
+function hasBackslashBreakAfterNewline(ctx: ParseContext): boolean {
+  const nextPos = skipWhitespace(ctx, ctx.pos + 1);
+  return ctx.tokens[nextPos]?.type === "BACKSLASH_BREAK";
+}
+
+function skipWhitespace(ctx: ParseContext, startPos: number): number {
+  let pos = startPos;
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+  }
+  return pos;
+}

package/src/parser/rules/inline/line-break/underscore.ts

@@ -0,0 +1,45 @@
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { createPreservedLineBreak } from "./elements";
+
+export const underscoreLineBreakRule: InlineRule = {
+  name: "underscoreLineBreak",
+  startTokens: ["WHITESPACE", "UNDERSCORE"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const currentTok = ctx.tokens[ctx.pos];
+    if (!currentTok) {
+      return { success: false };
+    }
+
+    if (currentTok.type === "WHITESPACE") {
+      const nextTok = ctx.tokens[ctx.pos + 1];
+      const afterTok = ctx.tokens[ctx.pos + 2];
+
+      if (
+        nextTok?.type === "UNDERSCORE" &&
+        afterTok &&
+        (afterTok.type === "NEWLINE" || afterTok.type === "EOF")
+      ) {
+        return {
+          success: true,
+          elements: [createPreservedLineBreak()],
+          consumed: 3,
+        };
+      }
+    }
+
+    if (currentTok.type === "UNDERSCORE" && currentTok.lineStart) {
+      const nextTok = ctx.tokens[ctx.pos + 1];
+      if (nextTok && (nextTok.type === "NEWLINE" || nextTok.type === "EOF")) {
+        return {
+          success: true,
+          elements: [createPreservedLineBreak()],
+          consumed: 2,
+        };
+      }
+    }
+
+    return { success: false };
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ *
+ * Parses the Wikidot anchor link syntax: `[#anchor-name Label text]`
+ * and the "fake link" variant `[# Label text]`.
+ *
+ * An anchor link creates a hyperlink that targets a named anchor on
+ * the same page. The link's `href` is set to `#normalized-anchor-name`.
+ *
+ * The "fake link" variant (`[# Label]`) has no anchor name and generates
+ * a link with `href="javascript:;"`. This is used in Wikidot for
+ * interactive elements like collapsible blocks where the link serves
+ * as a click target rather than navigation.
+ *
+ * Anchor names are normalized to lowercase with spaces replaced by hyphens.
+ *
+ * The opening delimiter is tokenized as `BRACKET_ANCHOR` (`[#`) by the
+ * lexer, distinguishing it from regular bracket links.
+ *
+ * Produces a `"link"` AST element with `type: "anchor"`.
+ *
+ * @module
+ */
+import type { Element, LinkLabel } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { parseAnchorBracketLink } from "./link-bracket/parsed";
+
+/**
+ * Inline rule for parsing `[#anchor Label]` anchor links.
+ *
+ * Triggered by a `BRACKET_ANCHOR` (`[#`) token. Collects the optional
+ * anchor name, then the required label text, stopping at the closing
+ * `]` bracket.
+ *
+ * Fails if:
+ * - No closing `]` is found on the same line
+ * - The label text is empty
+ */
+export const linkAnchorRule: InlineRule = {
+  name: "linkAnchor",
+  startTokens: ["BRACKET_ANCHOR"],
+
+  /**
+   * Attempts to parse an anchor link at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"link"` element of type `"anchor"`,
+   *          or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const parsed = parseAnchorBracketLink(ctx);
+    if (!parsed) return { success: false };
+
+    const linkLabel: LinkLabel = { text: parsed.labelText };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: "anchor",
+            link: parsed.link,
+            extra: null,
+            label: linkLabel,
+            target: null,
+          },
+        },
+      ],
+      consumed: parsed.consumed,
+    };
+  },
+};

package/src/parser/rules/inline/link-bracket/anchor.ts

@@ -0,0 +1,3 @@
+export function normalizeAnchor(anchor: string): string {
+  return anchor.toLowerCase().replace(/\s+/g, "-");
+}

package/src/parser/rules/inline/link-bracket/direct-url.ts

@@ -0,0 +1,5 @@
+export function isDirectBracketUrl(url: string): boolean {
+  return (
+    url !== "" && (url.startsWith("/") || url.startsWith("http://") || url.startsWith("https://"))
+  );
+}

package/src/parser/rules/inline/link-bracket/parsed.ts

@@ -0,0 +1,81 @@
+import type { AnchorTarget } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { normalizeAnchor } from "./anchor";
+import { isDirectBracketUrl } from "./direct-url";
+import { collectBracketLinkParts } from "./parts";
+import { parseBracketLinkPrefix } from "./prefix";
+
+export interface ParsedBracketLink {
+  link: string;
+  labelText: string;
+  target: AnchorTarget | null;
+  consumed: number;
+}
+
+export function parseSingleBracketLink(ctx: ParseContext): ParsedBracketLink | null {
+  const prefix = parseBracketLinkPrefix(ctx, ctx.pos + 1);
+  const parts = collectBracketLinkParts(ctx, prefix.bodyStart);
+  if (!parts) {
+    return null;
+  }
+
+  const link = parts.first.trim();
+  if (!isDirectBracketUrl(link)) {
+    return null;
+  }
+
+  const labelText = parts.label.trim();
+  if (!labelText) {
+    return null;
+  }
+
+  return {
+    link,
+    labelText,
+    target: prefix.target,
+    consumed: 1 + prefix.consumed + parts.consumed,
+  };
+}
+
+export function parseStarBracketLink(ctx: ParseContext): ParsedBracketLink | null {
+  const parts = collectBracketLinkParts(ctx, ctx.pos + 1);
+  if (!parts) {
+    return null;
+  }
+
+  const link = parts.first.trim();
+  if (!link) {
+    return null;
+  }
+
+  const labelText = parts.label.trim() || link;
+
+  return {
+    link,
+    labelText,
+    target: "new-tab",
+    consumed: 1 + parts.consumed,
+  };
+}
+
+export function parseAnchorBracketLink(
+  ctx: ParseContext,
+): Omit<ParsedBracketLink, "target"> | null {
+  const parts = collectBracketLinkParts(ctx, ctx.pos + 1);
+  if (!parts) {
+    return null;
+  }
+
+  const labelText = parts.label.trim();
+  if (!labelText) {
+    return null;
+  }
+
+  const anchor = parts.first.trim();
+
+  return {
+    link: anchor ? `#${normalizeAnchor(anchor)}` : "javascript:;",
+    labelText,
+    consumed: 1 + parts.consumed,
+  };
+}

package/src/parser/rules/inline/link-bracket/parts.ts

@@ -0,0 +1,64 @@
+import type { ParseContext } from "../../types";
+import { hasClosingMarkerBeforeNewline } from "../../types";
+
+export interface BracketLinkParts {
+  first: string;
+  label: string;
+  consumed: number;
+}
+
+export function collectBracketLinkParts(
+  ctx: ParseContext,
+  startPos: number,
+): BracketLinkParts | null {
+  if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: startPos }, "BRACKET_CLOSE")) {
+    return null;
+  }
+
+  let pos = startPos;
+  let consumed = 0;
+  let first = "";
+
+  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;
+    }
+    first += token.value;
+    pos++;
+    consumed++;
+  }
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  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++;
+  }
+
+  if (ctx.tokens[pos]?.type !== "BRACKET_CLOSE") {
+    return null;
+  }
+
+  return { first, label, consumed: consumed + 1 };
+}

package/src/parser/rules/inline/link-bracket/prefix.ts

@@ -0,0 +1,15 @@
+import type { ParseContext } from "../../types";
+
+export interface BracketLinkPrefix {
+  target: "new-tab" | null;
+  bodyStart: number;
+  consumed: number;
+}
+
+export function parseBracketLinkPrefix(ctx: ParseContext, startPos: number): BracketLinkPrefix {
+  if (ctx.tokens[startPos]?.type === "STAR") {
+    return { target: "new-tab", bodyStart: startPos + 1, consumed: 1 };
+  }
+
+  return { target: null, bodyStart: startPos, consumed: 0 };
+}