@wdprlib/parser 3.1.2 → 4.0.0

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

@@ -0,0 +1,73 @@
+/**
+ *
+ * Parses the Wikidot single-bracket link syntax: `[url label]`.
+ *
+ * Single-bracket links create hyperlinks to external URLs or
+ * site-relative paths. The URL and label are separated by whitespace.
+ *
+ * Supported URL formats:
+ * - Absolute URLs: `[https://example.com/ Label]`
+ * - Relative paths: `[/some-page Label]`
+ *
+ * An optional `*` prefix on the URL opens the link in a new tab:
+ * `[*https://example.com/ Opens in new tab]`.
+ *
+ * Unlike triple-bracket links (`[[[page]]]`), single-bracket links
+ * require a full URL (starting with `http://`, `https://`, or `/`).
+ * The label text is required.
+ *
+ * Produces a `"link"` AST element with `type: "direct"`.
+ *
+ * @module
+ */
+import type { Element, LinkLabel } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { parseSingleBracketLink } from "./link-bracket/parsed";
+
+/**
+ * Inline rule for parsing `[url label]` single-bracket links.
+ *
+ * Triggered by a `BRACKET_OPEN` (`[`) token. Optionally detects a
+ * `*` prefix for new-tab behavior, then collects the URL (until
+ * whitespace) and the label text (until `]`).
+ *
+ * Fails if:
+ * - No closing `]` is found on the same line
+ * - The URL does not start with `http://`, `https://`, or `/`
+ * - The label text is empty
+ */
+export const linkSingleRule: InlineRule = {
+  name: "linkSingle",
+  startTokens: ["BRACKET_OPEN"],
+
+  /**
+   * Attempts to parse a single-bracket 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 `"direct"`,
+   *          or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const parsed = parseSingleBracketLink(ctx);
+    if (!parsed) return { success: false };
+
+    const linkLabel: LinkLabel = { text: parsed.labelText };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: "direct",
+            link: parsed.link,
+            extra: null,
+            label: linkLabel,
+            target: parsed.target,
+          },
+        },
+      ],
+      consumed: parsed.consumed,
+    };
+  },
+};

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

@@ -0,0 +1,72 @@
+/**
+ *
+ * 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 { parseStarBracketLink } from "./link-bracket/parsed";
+
+/**
+ * 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> {
+    const parsed = parseStarBracketLink(ctx);
+    if (!parsed) return { success: false };
+
+    const linkLabel: LinkLabel = { text: parsed.labelText };
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: "direct",
+            link: parsed.link,
+            extra: null,
+            label: linkLabel,
+            target: parsed.target,
+          },
+        },
+      ],
+      consumed: parsed.consumed,
+    };
+  },
+};

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

@@ -0,0 +1,10 @@
+import type { Element } from "@wdprlib/ast";
+import type { RuleResult } from "../../types";
+
+export function literalOpenLink(value: string): RuleResult<Element> {
+  return {
+    success: true,
+    elements: [{ element: "text", data: value }],
+    consumed: 1,
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ *
+ * Parses the Wikidot triple-bracket link syntax: `[[[target | label]]]`.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { literalOpenLink } from "./fallback";
+import { buildTripleLinkLabel } from "./label";
+import { collectTripleLinkParts, hasClosingLinkMarker } from "./syntax";
+import {
+  determineLinkTypeAndLocation,
+  isInvalidTripleLinkTarget,
+  normalizeTripleLinkTarget,
+} from "./target";
+
+export const linkTripleRule: InlineRule = {
+  name: "linkTriple",
+  startTokens: ["LINK_OPEN"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const startToken = currentToken(ctx);
+
+    if (!hasClosingLinkMarker(ctx, ctx.pos + 1)) {
+      return literalOpenLink(startToken.value);
+    }
+
+    const parts = collectTripleLinkParts(ctx, ctx.pos + 1);
+    const trimmedTarget = parts.target.trim();
+    if (isInvalidTripleLinkTarget(trimmedTarget, parts.foundPipe)) {
+      return literalOpenLink(startToken.value);
+    }
+
+    const normalized = normalizeTripleLinkTarget(trimmedTarget);
+    const { linkType, link } = determineLinkTypeAndLocation(normalized.target);
+    const label = buildTripleLinkLabel({
+      foundPipe: parts.foundPipe,
+      labelText: parts.labelText,
+      finalTarget: normalized.target,
+      originalTarget: trimmedTarget,
+    });
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "link",
+          data: {
+            type: linkType,
+            link,
+            extra: null,
+            label,
+            target: normalized.hasStar && linkType === "direct" ? "new-tab" : null,
+          },
+        },
+      ],
+      consumed: parts.consumed,
+    };
+  },
+};

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

@@ -0,0 +1,11 @@
+const INTERWIKI_PREFIXES = new Set(["wikipedia", "google", "dictionary", "wikidot"]);
+
+export function isInterwikiTarget(target: string): boolean {
+  const colonIdx = target.indexOf(":");
+  if (colonIdx <= 0 || target.includes("/")) {
+    return false;
+  }
+
+  const prefix = target.slice(0, colonIdx).toLowerCase();
+  return INTERWIKI_PREFIXES.has(prefix);
+}

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

@@ -0,0 +1,35 @@
+import type { LinkLabel } from "@wdprlib/ast";
+
+export function buildTripleLinkLabel(args: {
+  foundPipe: boolean;
+  labelText: string;
+  finalTarget: string;
+  originalTarget: string;
+}): LinkLabel {
+  return {
+    text: getTripleLinkDisplayText(args),
+  };
+}
+
+function getTripleLinkDisplayText(args: {
+  foundPipe: boolean;
+  labelText: string;
+  finalTarget: string;
+  originalTarget: string;
+}): string {
+  const trimmedLabel = args.labelText.trim();
+  if (args.foundPipe) {
+    return trimmedLabel || args.finalTarget;
+  }
+
+  const colonIdx = args.originalTarget.indexOf(":");
+  if (
+    colonIdx !== -1 &&
+    !args.originalTarget.startsWith("http") &&
+    !args.originalTarget.startsWith("*")
+  ) {
+    return args.originalTarget.slice(colonIdx + 1).trim();
+  }
+
+  return args.originalTarget;
+}

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

@@ -0,0 +1,72 @@
+import type { ParseContext } from "../../types";
+
+export interface TripleLinkParts {
+  target: string;
+  labelText: string;
+  foundPipe: boolean;
+  consumed: number;
+}
+
+export 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;
+    }
+    if (token.type === "NEWLINE") {
+      const next = ctx.tokens[pos + 1];
+      if (next?.type === "NEWLINE" || next?.type === "LINK_CLOSE") {
+        return false;
+      }
+    }
+    pos++;
+  }
+  return false;
+}
+
+export function collectTripleLinkParts(ctx: ParseContext, startPos: number): TripleLinkParts {
+  let target = "";
+  let labelText = "";
+  let foundPipe = false;
+  let consumed = 1;
+  let pos = startPos;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "LINK_CLOSE" || token.type === "EOF") {
+      break;
+    }
+
+    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++;
+  }
+
+  if (ctx.tokens[pos]?.type === "LINK_CLOSE") {
+    consumed++;
+  }
+
+  return { target, labelText, foundPipe, consumed };
+}

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

@@ -0,0 +1,36 @@
+import type { LinkLocation, LinkType } from "@wdprlib/ast";
+import { isInterwikiTarget } from "./interwiki";
+
+export interface TripleLinkTarget {
+  target: string;
+  hasStar: boolean;
+}
+
+export function normalizeTripleLinkTarget(trimmedTarget: string): TripleLinkTarget {
+  if (trimmedTarget.startsWith("*")) {
+    return { target: trimmedTarget.slice(1), hasStar: true };
+  }
+  return { target: trimmedTarget, hasStar: false };
+}
+
+export function isInvalidTripleLinkTarget(trimmedTarget: string, foundPipe: boolean): boolean {
+  return (trimmedTarget === "" && foundPipe) || /#{2,}/.test(trimmedTarget);
+}
+
+export 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 };
+  }
+
+  if (isInterwikiTarget(target)) {
+    return { linkType: "interwiki", link: target };
+  }
+
+  return { linkType: "page", link: { site: null, page: target } };
+}

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

@@ -0,0 +1,40 @@
+/**
+ *
+ * Parses the Wikidot inline math syntax: `[[$ LaTeX $]]`.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseInlineMathSource } from "./syntax";
+
+export const mathInlineRule: InlineRule = {
+  name: "math-inline",
+  startTokens: ["BLOCK_OPEN"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const parsed = parseInlineMathSource(ctx, ctx.pos + 1);
+    if (!parsed) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "math-inline",
+          data: {
+            "latex-source": parsed.latexSource,
+          },
+        },
+      ],
+      consumed: 1 + parsed.consumed,
+    };
+  },
+};

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

@@ -0,0 +1,55 @@
+import type { ParseContext } from "../../types";
+
+export function parseInlineMathSource(
+  ctx: ParseContext,
+  startPos: number,
+): { latexSource: string; consumed: number } | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  if (ctx.tokens[pos]?.type !== "TEXT" || ctx.tokens[pos]?.value !== "$") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  let latexSource = "";
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "NEWLINE") {
+      return null;
+    }
+
+    if (
+      token.type === "TEXT" &&
+      token.value === "$" &&
+      ctx.tokens[pos + 1]?.type === "BLOCK_CLOSE"
+    ) {
+      break;
+    }
+
+    latexSource += token.value;
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type !== "TEXT" || ctx.tokens[pos]?.value !== "$") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  return {
+    latexSource: latexSource.trim(),
+    consumed: consumed + 1,
+  };
+}

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

@@ -0,0 +1,50 @@
+/**
+ *
+ * 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 { parseSameLineDelimitedContainer } from "./formatting/container";
+
+/**
+ * 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> {
+    return parseSameLineDelimitedContainer(ctx, "MONO_CLOSE", "monospace");
+  },
+};

package/src/parser/rules/inline/parsing/block-boundary.ts

@@ -0,0 +1,42 @@
+import type { ParseContext } from "../../types";
+import { INDENT_ACCEPTING_BLOCK_NAMES, KNOWN_BLOCK_NAMES } from "../../../constants";
+import { parseBlockName } from "../../common";
+
+/**
+ * Checks whether the block token at `tokenPos` names a block in the excluded set.
+ */
+export function isExcludedBlockToken(ctx: ParseContext, tokenPos: number): boolean {
+  const excluded = ctx.scope.excludedBlockNames;
+  if (!excluded?.size) return false;
+  const token = ctx.tokens[tokenPos];
+  if (token?.type !== "BLOCK_OPEN" && token?.type !== "BLOCK_END_OPEN") return false;
+  const nameResult = parseBlockName(ctx, tokenPos + 1);
+  return nameResult !== null && excluded.has(nameResult.name);
+}
+
+/**
+ * Checks whether the block token at `tokenPos` names a block that no rule recognizes.
+ */
+export function isUnknownBlockToken(ctx: ParseContext, tokenPos: number): boolean {
+  const token = ctx.tokens[tokenPos];
+  if (token?.type !== "BLOCK_OPEN" && token?.type !== "BLOCK_END_OPEN") return false;
+  const nameResult = parseBlockName(ctx, tokenPos + 1);
+  if (nameResult === null) {
+    if (ctx.tokens[tokenPos + 1]?.type === "EQUALS") {
+      return false;
+    }
+    return true;
+  }
+  return !KNOWN_BLOCK_NAMES.has(nameResult.name);
+}
+
+/**
+ * Checks whether the block token at `tokenPos` names a block whose rule accepts indentation.
+ */
+export function isIndentAcceptingBlock(ctx: ParseContext, tokenPos: number): boolean {
+  const token = ctx.tokens[tokenPos];
+  if (token?.type !== "BLOCK_OPEN" && token?.type !== "BLOCK_END_OPEN") return false;
+  const nameResult = parseBlockName(ctx, tokenPos + 1);
+  if (nameResult === null) return false;
+  return INDENT_ACCEPTING_BLOCK_NAMES.has(nameResult.name);
+}

package/src/parser/rules/inline/parsing/block-start-predicates.ts

@@ -0,0 +1,117 @@
+import type { ParseContext } from "../../types";
+import { BLOCK_START_TOKEN_SET } from "../../../constants";
+import {
+  isExcludedBlockToken,
+  isIndentAcceptingBlock,
+  isUnknownBlockToken,
+} from "./block-boundary";
+
+export function isParagraphBreakingBlockStart(
+  ctx: ParseContext,
+  newlinePos: number,
+  lookAhead: number,
+): boolean {
+  const nextPos = newlinePos + lookAhead;
+  const nextMeaningfulToken = ctx.tokens[nextPos];
+  if (!nextMeaningfulToken || !BLOCK_START_TOKEN_SET.has(nextMeaningfulToken.type)) {
+    return false;
+  }
+
+  const isIndentedBlockOpener =
+    (nextMeaningfulToken.type === "BLOCK_OPEN" || nextMeaningfulToken.type === "BLOCK_END_OPEN") &&
+    isIndentAcceptingBlock(ctx, nextPos);
+
+  if (!nextMeaningfulToken.lineStart && !isIndentedBlockOpener) {
+    return false;
+  }
+
+  return (
+    !isOrphanCloseSpan(ctx, nextPos) &&
+    !isAnchorName(ctx, nextPos) &&
+    !isInvalidBlockOpen(ctx, nextPos) &&
+    !isInvalidHeading(ctx, nextPos) &&
+    !isExcludedBlockStart(ctx, nextPos) &&
+    !isUnknownBlockStart(ctx, nextPos)
+  );
+}
+
+function isOrphanCloseSpan(ctx: ParseContext, blockEndOpenPos: number): boolean {
+  const token = ctx.tokens[blockEndOpenPos];
+  if (token?.type !== "BLOCK_END_OPEN") return false;
+
+  const namePos = skipWhitespace(ctx, blockEndOpenPos + 1);
+  const nameToken = ctx.tokens[namePos];
+  return nameToken?.type === "IDENTIFIER" && nameToken.value.toLowerCase() === "span";
+}
+
+function isAnchorName(ctx: ParseContext, blockOpenPos: number): boolean {
+  const token = ctx.tokens[blockOpenPos];
+  if (token?.type !== "BLOCK_OPEN") return false;
+
+  const hashPos = skipWhitespace(ctx, blockOpenPos + 1);
+  const hashToken = ctx.tokens[hashPos];
+  return hashToken?.type === "HASH" || (hashToken?.type === "TEXT" && hashToken.value === "#");
+}
+
+function isInvalidBlockOpen(ctx: ParseContext, blockOpenPos: number): boolean {
+  const token = ctx.tokens[blockOpenPos];
+  if (token?.type !== "BLOCK_OPEN") return false;
+
+  const firstAfter = ctx.tokens[blockOpenPos + 1];
+  if (firstAfter?.type === "TEXT" && (firstAfter.value === ">" || firstAfter.value === "<")) {
+    const secondAfter = ctx.tokens[blockOpenPos + 2];
+    if (secondAfter && secondAfter.type !== "BLOCK_CLOSE") {
+      return true;
+    }
+  }
+
+  const blockNamePos = skipWhitespace(ctx, blockOpenPos + 1);
+  const blockNameToken = ctx.tokens[blockNamePos];
+  return (
+    blockNameToken !== undefined &&
+    (blockNameToken.type === "TEXT" || blockNameToken.type === "IDENTIFIER") &&
+    blockNameToken.value.toLowerCase() === "footnoteblock" &&
+    Boolean(ctx.scope.footnoteBlockParsed)
+  );
+}
+
+function isInvalidHeading(ctx: ParseContext, markerPos: number): boolean {
+  const marker = ctx.tokens[markerPos];
+  if (marker?.type !== "HEADING_MARKER") return false;
+
+  const markerLen = marker.value.length;
+  const afterMarker = ctx.tokens[markerPos + 1];
+  if (markerLen > 6) {
+    return true;
+  }
+
+  if (afterMarker?.type === "STAR") {
+    return ctx.tokens[markerPos + 2]?.type !== "WHITESPACE";
+  }
+
+  return afterMarker?.type !== "WHITESPACE";
+}
+
+function isExcludedBlockStart(ctx: ParseContext, tokenPos: number): boolean {
+  const token = ctx.tokens[tokenPos];
+  return (
+    (token?.type === "BLOCK_OPEN" || token?.type === "BLOCK_END_OPEN") &&
+    isExcludedBlockToken(ctx, tokenPos)
+  );
+}
+
+function isUnknownBlockStart(ctx: ParseContext, tokenPos: number): boolean {
+  const token = ctx.tokens[tokenPos];
+  return (
+    (token?.type === "BLOCK_OPEN" || token?.type === "BLOCK_END_OPEN") &&
+    isUnknownBlockToken(ctx, tokenPos)
+  );
+}
+
+function skipWhitespace(ctx: ParseContext, startPos: number): number {
+  let pos = startPos;
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+  }
+  return pos;
+}