@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/block/align/body.ts

@@ -0,0 +1,46 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseBlocksUntil } from "../utils";
+import { type AlignDirection, parseAlignClose } from "./syntax";
+
+export interface AlignBodyResult {
+  elements: Element[];
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function parseAlignBody(
+  ctx: ParseContext,
+  startPos: number,
+  direction: AlignDirection,
+): AlignBodyResult {
+  const bodyCtx: ParseContext = { ...ctx, pos: startPos };
+  const bodyResult = parseBlocksUntil(bodyCtx, (checkCtx) => {
+    return parseAlignClose(checkCtx, direction).match;
+  });
+
+  let pos = startPos + bodyResult.consumed;
+  let consumed = bodyResult.consumed;
+
+  const closeCheck = parseAlignClose({ ...ctx, pos }, direction);
+  if (!closeCheck.match) {
+    return {
+      elements: bodyResult.elements,
+      consumed,
+      foundClose: false,
+    };
+  }
+
+  consumed += closeCheck.consumed;
+  pos += closeCheck.consumed;
+
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return {
+    elements: bodyResult.elements,
+    consumed,
+    foundClose: true,
+  };
+}

package/src/parser/rules/block/align/element.ts

@@ -0,0 +1,13 @@
+import type { Element } from "@wdprlib/ast";
+import type { AlignDirection } from "./syntax";
+
+export function createAlignElement(direction: AlignDirection, elements: Element[]): Element {
+  return {
+    element: "container",
+    data: {
+      type: { align: direction },
+      attributes: {},
+      elements,
+    },
+  };
+}

package/src/parser/rules/block/align/index.ts

@@ -0,0 +1,90 @@
+/**
+ *
+ * Block rule for Wikidot alignment containers.
+ *
+ * Wikidot provides a shorthand bracket syntax for wrapping content in a
+ * directional alignment container:
+ *
+ * ```
+ * [[>]]        ... [[/>]]        right-aligned
+ * [[<]]        ... [[/<]]        left-aligned
+ * [[=]]        ... [[/=]]        center-aligned
+ * [[==]]       ... [[/==]]       justify-aligned
+ * ```
+ *
+ * Each pair acts as a block-level wrapper. The opening tag must appear at
+ * the start of a line and be followed by a newline. Body content is parsed
+ * recursively as block-level markup, and the matching closing tag terminates
+ * the container.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseAlignBody } from "./body";
+import { createAlignElement } from "./element";
+import { alignDirectionSymbol, parseAlignOpen } from "./syntax";
+
+/**
+ * Block rule that matches Wikidot directional alignment containers.
+ *
+ * `preservesPrecedingLineBreak` is `true` because, unlike most block
+ * constructs, an alignment block does not suppress a preceding `\n` from
+ * becoming a `<br />` in Wikidot's output.
+ */
+export const alignRule: BlockRule = {
+  name: "align",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: true,
+  preservesPrecedingLineBreak: true,
+
+  isStartPattern(ctx: ParseContext, pos: number): boolean {
+    if (ctx.tokens[pos]?.type !== "BLOCK_OPEN") return false;
+    return parseAlignOpen(ctx, pos + 1) !== null;
+  },
+
+  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;
+
+    const alignResult = parseAlignOpen(ctx, pos);
+    if (!alignResult) {
+      return { success: false };
+    }
+
+    const { direction } = alignResult;
+    pos += alignResult.consumed;
+    consumed += alignResult.consumed;
+
+    if (ctx.tokens[pos]?.type !== "NEWLINE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    const bodyResult = parseAlignBody(ctx, pos, direction);
+    consumed += bodyResult.consumed;
+
+    if (!bodyResult.foundClose) {
+      const directionSymbol = alignDirectionSymbol(direction);
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: `Missing closing tag [[/${directionSymbol}]] for [[${directionSymbol}]]`,
+        position: openToken.position,
+      });
+    }
+
+    return {
+      success: true,
+      elements: [createAlignElement(direction, bodyResult.elements)],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/align/syntax.ts

@@ -0,0 +1,113 @@
+import type { ParseContext } from "../../types";
+
+/** The four text-alignment directions Wikidot supports. */
+export type AlignDirection = "left" | "right" | "center" | "justify";
+
+/**
+ * Attempts to parse the interior of an align opening tag starting after
+ * the BLOCK_OPEN (`[[`) token.
+ */
+export function parseAlignOpen(
+  ctx: ParseContext,
+  pos: number,
+): { direction: AlignDirection; consumed: number } | null {
+  const tokens = ctx.tokens;
+  const firstToken = tokens[pos];
+  if (!firstToken) return null;
+
+  if (
+    firstToken.type === "BLOCKQUOTE_MARKER" &&
+    firstToken.value === ">" &&
+    tokens[pos + 1]?.type === "BLOCK_CLOSE"
+  ) {
+    return { direction: "right", consumed: 2 };
+  }
+
+  if (
+    firstToken.type === "TEXT" &&
+    firstToken.value === ">" &&
+    tokens[pos + 1]?.type === "BLOCK_CLOSE"
+  ) {
+    return { direction: "right", consumed: 2 };
+  }
+
+  if (
+    firstToken.type === "TEXT" &&
+    firstToken.value === "<" &&
+    tokens[pos + 1]?.type === "BLOCK_CLOSE"
+  ) {
+    return { direction: "left", consumed: 2 };
+  }
+
+  if (firstToken.type === "EQUALS" && tokens[pos + 1]?.type === "BLOCK_CLOSE") {
+    return { direction: "center", consumed: 2 };
+  }
+
+  if (
+    firstToken.type === "EQUALS" &&
+    tokens[pos + 1]?.type === "EQUALS" &&
+    tokens[pos + 2]?.type === "BLOCK_CLOSE"
+  ) {
+    return { direction: "justify", consumed: 3 };
+  }
+
+  return null;
+}
+
+/**
+ * Tests whether the tokens at the current position form a closing align tag.
+ */
+export function parseAlignClose(
+  ctx: ParseContext,
+  direction: AlignDirection,
+): { match: boolean; consumed: number } {
+  const tokens = ctx.tokens;
+  let pos = ctx.pos;
+
+  if (tokens[pos]?.type !== "BLOCK_END_OPEN") {
+    return { match: false, consumed: 0 };
+  }
+  pos++;
+
+  if (direction === "right") {
+    if (
+      (tokens[pos]?.type === "BLOCKQUOTE_MARKER" || tokens[pos]?.type === "TEXT") &&
+      tokens[pos]?.value === ">" &&
+      tokens[pos + 1]?.type === "BLOCK_CLOSE"
+    ) {
+      return { match: true, consumed: 3 };
+    }
+  }
+
+  if (direction === "left") {
+    if (
+      tokens[pos]?.type === "TEXT" &&
+      tokens[pos]?.value === "<" &&
+      tokens[pos + 1]?.type === "BLOCK_CLOSE"
+    ) {
+      return { match: true, consumed: 3 };
+    }
+  }
+
+  if (direction === "center") {
+    if (tokens[pos]?.type === "EQUALS" && tokens[pos + 1]?.type === "BLOCK_CLOSE") {
+      return { match: true, consumed: 3 };
+    }
+  }
+
+  if (direction === "justify") {
+    if (
+      tokens[pos]?.type === "EQUALS" &&
+      tokens[pos + 1]?.type === "EQUALS" &&
+      tokens[pos + 2]?.type === "BLOCK_CLOSE"
+    ) {
+      return { match: true, consumed: 4 };
+    }
+  }
+
+  return { match: false, consumed: 0 };
+}
+
+export function alignDirectionSymbol(direction: AlignDirection): string {
+  return { left: "<", right: ">", center: "=", justify: "==" }[direction];
+}

package/src/parser/rules/block/bibliography/body.ts

@@ -0,0 +1,81 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+import { parseBibliographyEntry, type BibliographyEntry } from "./entries";
+
+export interface BibliographyBodyResult {
+  entries: BibliographyEntry[];
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function collectBibliographyBody(
+  ctx: ParseContext,
+  startPos: number,
+): BibliographyBodyResult {
+  const entries: BibliographyEntry[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    const closeConsumed = consumeBibliographyClose(ctx, pos);
+    if (closeConsumed !== null) {
+      return {
+        entries,
+        consumed: consumed + closeConsumed,
+        foundClose: true,
+      };
+    }
+
+    if (token.type === "WHITESPACE" || token.type === "NEWLINE") {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    if (token.type === "COLON" && token.lineStart) {
+      const result = parseBibliographyEntry(ctx, pos);
+      if (result) {
+        entries.push(result.entry);
+        pos += result.consumed;
+        consumed += result.consumed;
+        continue;
+      }
+    }
+
+    pos++;
+    consumed++;
+  }
+
+  return { entries, consumed, foundClose: false };
+}
+
+function consumeBibliographyClose(ctx: ParseContext, startPos: number): number | null {
+  const openToken = ctx.tokens[startPos];
+  if (openToken?.type !== "BLOCK_END_OPEN") {
+    return null;
+  }
+
+  const closeNameResult = parseBlockName(ctx, startPos + 1);
+  if (closeNameResult?.name !== "bibliography") {
+    return null;
+  }
+
+  let pos = startPos + 1 + closeNameResult.consumed;
+  let consumed = 1 + closeNameResult.consumed;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+    consumed++;
+  }
+
+  return consumed;
+}

package/src/parser/rules/block/bibliography/entries.ts

@@ -0,0 +1,49 @@
+import type { DefinitionListItem, Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseBibliographyContent } from "./entry-content";
+import { parseBibliographyKey } from "./entry-key";
+
+/**
+ * Internal representation of a single bibliography entry parsed from
+ * the `: label : content` line(s) inside the bibliography block.
+ */
+export interface BibliographyEntry {
+  /** The identifier used in `((bibcite label))` references. */
+  label: string;
+  /** Parsed inline elements for the label portion (the key). */
+  key: Element[];
+  /** Parsed inline elements for the citation text. */
+  content: Element[];
+}
+
+/**
+ * Parses one bibliography entry from the token stream.
+ */
+export function parseBibliographyEntry(
+  ctx: ParseContext,
+  startPos: number,
+): { entry: BibliographyEntry; consumed: number } | null {
+  const keyResult = parseBibliographyKey(ctx, startPos);
+  if (!keyResult) {
+    return null;
+  }
+
+  const contentResult = parseBibliographyContent(ctx, startPos + keyResult.consumed);
+
+  return {
+    entry: {
+      label: keyResult.label,
+      key: keyResult.key,
+      content: contentResult.content,
+    },
+    consumed: keyResult.consumed + contentResult.consumed,
+  };
+}
+
+export function toDefinitionListItems(entries: BibliographyEntry[]): DefinitionListItem[] {
+  return entries.map((entry) => ({
+    key_string: entry.label,
+    key: entry.key,
+    value: entry.content,
+  }));
+}

package/src/parser/rules/block/bibliography/entry-content.ts

@@ -0,0 +1,73 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseInlineUntil } from "../../inline/utils";
+import { parseBlockName } from "../utils";
+
+export interface BibliographyContentResult {
+  content: Element[];
+  consumed: number;
+}
+
+export function parseBibliographyContent(
+  ctx: ParseContext,
+  startPos: number,
+): BibliographyContentResult {
+  const content: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type === "BLOCK_END_OPEN") {
+      const closeNameResult = parseBlockName(ctx, pos + 1);
+      if (closeNameResult?.name === "bibliography") {
+        break;
+      }
+    }
+
+    if (token.type === "NEWLINE") {
+      const nextToken = ctx.tokens[pos + 1];
+      if (nextToken?.type === "COLON" && nextToken.lineStart) {
+        pos++;
+        consumed++;
+        break;
+      }
+      if (nextToken?.type === "BLOCK_END_OPEN") {
+        pos++;
+        consumed++;
+        break;
+      }
+      if (nextToken?.type === "NEWLINE" || !nextToken || nextToken.type === "EOF") {
+        pos++;
+        consumed++;
+        break;
+      }
+      content.push({ element: "line-break" });
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    const inlineCtx: ParseContext = { ...ctx, pos };
+    const result = parseInlineUntil(inlineCtx, "NEWLINE");
+    if (result.elements.length > 0) {
+      content.push(...result.elements);
+      pos += result.consumed;
+      consumed += result.consumed;
+    } else {
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { content, consumed };
+}

package/src/parser/rules/block/bibliography/entry-key.ts

@@ -0,0 +1,83 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+
+export interface BibliographyKeyResult {
+  label: string;
+  key: Element[];
+  consumed: number;
+}
+
+export function parseBibliographyKey(
+  ctx: ParseContext,
+  startPos: number,
+): BibliographyKeyResult | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  const colonToken = ctx.tokens[pos];
+  if (!colonToken || colonToken.type !== "COLON" || !colonToken.lineStart) {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  const whitespaceAfterColon = ctx.tokens[pos];
+  if (!whitespaceAfterColon || whitespaceAfterColon.type !== "WHITESPACE") {
+    return null;
+  }
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  let label = "";
+  let foundSecondColon = false;
+  const key: Element[] = [];
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "NEWLINE" || token.type === "EOF") {
+      break;
+    }
+    if (token.type === "COLON") {
+      foundSecondColon = true;
+      pos++;
+      consumed++;
+      break;
+    }
+
+    label += token.value;
+    key.push({ element: "text", data: token.value });
+    pos++;
+    consumed++;
+  }
+
+  if (!foundSecondColon) {
+    return null;
+  }
+
+  trimTrailingWhitespaceText(key);
+
+  return {
+    label: label.trim(),
+    key,
+    consumed,
+  };
+}
+
+function trimTrailingWhitespaceText(nodes: Element[]): void {
+  while (nodes.length > 0) {
+    const lastNode = nodes[nodes.length - 1];
+    if (
+      lastNode &&
+      lastNode.element === "text" &&
+      typeof lastNode.data === "string" &&
+      lastNode.data.trim() === ""
+    ) {
+      nodes.pop();
+    } else {
+      break;
+    }
+  }
+}

package/src/parser/rules/block/bibliography/index.ts

@@ -0,0 +1,90 @@
+/**
+ *
+ * Block rule for the Wikidot bibliography block: `[[bibliography]] ... [[/bibliography]]`.
+ *
+ * A bibliography block holds labelled citation entries in a definition-list
+ * format. Each entry follows the pattern:
+ *
+ * ```
+ * : label : Citation description text
+ * ```
+ *
+ * At render time the entries are cross-referenced with inline `((bibcite label))`
+ * markers that appear elsewhere in the document. The parser stores the entries
+ * in the AST as a `bibliography-block` element whose `entries` field is an
+ * array of {@link DefinitionListItem} objects.
+ *
+ * Optional attributes on the opening tag:
+ * - `title` -- custom heading for the bibliography section.
+ * - `hide`  -- when `"true"` or empty string, hides the block from output.
+ *
+ * If no closing `[[/bibliography]]` tag is found, the rule fails to avoid
+ * accidentally consuming the rest of the document.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { collectBibliographyBody } from "./body";
+import { toDefinitionListItems } from "./entries";
+import { parseBibliographyOpen } from "./open";
+
+/**
+ * Block rule for Wikidot `[[bibliography]]...[[/bibliography]]`.
+ *
+ * Parsing strategy:
+ * 1. Match BLOCK_OPEN + block name "bibliography".
+ * 2. Parse optional attributes (`title`, `hide`).
+ * 3. Consume the closing `]]` and optional newline.
+ * 4. Loop over the body, parsing each `: label : content` line via
+ *    `parseBibliographyEntry()`.
+ * 5. Require and consume `[[/bibliography]]`.
+ * 6. Convert entries into {@link DefinitionListItem} format and emit
+ *    a `bibliography-block` element.
+ */
+export const bibliographyRule: BlockRule = {
+  name: "bibliography",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseBibliographyOpen(ctx, ctx.pos);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    const bodyResult = collectBibliographyBody(ctx, openResult.pos);
+    const consumed = openResult.consumed + bodyResult.consumed;
+
+    if (!bodyResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/bibliography]] for [[bibliography]]",
+        position: openToken.position,
+      });
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "bibliography-block",
+          data: {
+            entries: toDefinitionListItems(bodyResult.entries),
+            title: openResult.title,
+            hide: openResult.hide,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};

package/src/parser/rules/block/bibliography/open.ts

@@ -0,0 +1,53 @@
+import type { ParseContext } from "../../types";
+import { parseAttributes, parseBlockName } from "../utils";
+
+export interface BibliographyOpenResult {
+  title: string | null;
+  hide: boolean;
+  pos: number;
+  consumed: number;
+}
+
+export function parseBibliographyOpen(
+  ctx: ParseContext,
+  startPos: number,
+): BibliographyOpenResult | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult || nameResult.name !== "bibliography") {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseAttributes(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+  pos++;
+  consumed++;
+
+  if (ctx.tokens[pos]?.type === "NEWLINE") {
+    pos++;
+    consumed++;
+  }
+
+  return {
+    title: attrResult.attrs.title ?? null,
+    hide: attrResult.attrs.hide === "true" || attrResult.attrs.hide === "",
+    pos,
+    consumed,
+  };
+}