@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/rules/block/collapsible/attributes.ts

@@ -0,0 +1,95 @@
+import type { ParseContext } from "../../types";
+
+export type CollapsibleAttributes = Record<string, string>;
+
+/**
+ * Parses collapsible attributes that may be spread across multiple lines.
+ */
+export function parseMultilineAttributes(
+  ctx: ParseContext,
+  startPos: number,
+): { attrs: CollapsibleAttributes; consumed: number } {
+  const attrs: CollapsibleAttributes = {};
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "BLOCK_CLOSE" || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type === "WHITESPACE" || token.type === "NEWLINE") {
+      pos++;
+      consumed++;
+      continue;
+    }
+
+    if (token.type === "TEXT" || token.type === "IDENTIFIER") {
+      let name = token.value;
+      pos++;
+      consumed++;
+
+      while (
+        ctx.tokens[pos]?.type === "TEXT" &&
+        ctx.tokens[pos]?.value === "-" &&
+        (ctx.tokens[pos + 1]?.type === "IDENTIFIER" || ctx.tokens[pos + 1]?.type === "TEXT")
+      ) {
+        name += "-";
+        pos++;
+        consumed++;
+        name += ctx.tokens[pos]?.value ?? "";
+        pos++;
+        consumed++;
+      }
+
+      const eqToken = ctx.tokens[pos];
+      if (eqToken?.type === "EQUALS") {
+        pos++;
+        consumed++;
+        const valueToken = ctx.tokens[pos];
+        if (valueToken?.type === "QUOTED_STRING") {
+          let value = valueToken.value;
+          if (value.startsWith('"') && value.endsWith('"')) {
+            value = value.slice(1, -1);
+          }
+          attrs[name] = value;
+          pos++;
+          consumed++;
+        } else if (valueToken?.type === "TEXT" || valueToken?.type === "IDENTIFIER") {
+          attrs[name] = valueToken.value;
+          pos++;
+          consumed++;
+        }
+      } else {
+        attrs[name] = "true";
+      }
+    } else {
+      break;
+    }
+  }
+
+  return { attrs, consumed };
+}
+
+export interface CollapsibleToggleVisibility {
+  showTop: boolean;
+  showBottom: boolean;
+}
+
+export function resolveToggleVisibility(
+  attrs: Record<string, string>,
+): CollapsibleToggleVisibility {
+  const hideLocation = (attrs.hideLocation ?? attrs.hidelocation ?? "top").toLowerCase();
+
+  if (hideLocation === "both") {
+    return { showTop: true, showBottom: true };
+  }
+  if (hideLocation === "bottom") {
+    return { showTop: false, showBottom: true };
+  }
+  if (hideLocation === "neither" || hideLocation === "none") {
+    return { showTop: false, showBottom: false };
+  }
+  return { showTop: true, showBottom: false };
+}

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

@@ -0,0 +1,69 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseBlocksUntil } from "../utils";
+import { isCollapsibleClose } from "./tags";
+
+const EXCLUDED_BLOCKS = new Set(["collapsible"]);
+
+export function parseCollapsibleBody(
+  ctx: ParseContext,
+  startPos: number,
+  hasNewlineAfterOpen: boolean,
+): { elements: Element[]; consumed: number } {
+  if (
+    !hasNewlineAfterOpen &&
+    ctx.tokens[startPos]?.type !== "EOF" &&
+    ctx.tokens[startPos]?.type !== "BLOCK_END_OPEN"
+  ) {
+    return parseInlineCollapsibleBody(ctx, startPos);
+  }
+
+  const bodyCtx: ParseContext = { ...ctx, pos: startPos };
+  const closeCondition = (checkCtx: ParseContext): boolean => {
+    return isCollapsibleClose(checkCtx, checkCtx.pos);
+  };
+  const bodyResult = parseBlocksUntil(bodyCtx, closeCondition, {
+    excludedBlockNames: EXCLUDED_BLOCKS,
+  });
+
+  return {
+    elements: bodyResult.elements,
+    consumed: bodyResult.consumed,
+  };
+}
+
+function parseInlineCollapsibleBody(
+  ctx: ParseContext,
+  startPos: number,
+): { elements: Element[]; consumed: number } {
+  const inlineElements: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF" || token.type === "NEWLINE") break;
+    if (isCollapsibleClose(ctx, pos)) break;
+    inlineElements.push({ element: "text", data: token.value });
+    pos++;
+    consumed++;
+  }
+
+  if (inlineElements.length === 0) {
+    return { elements: [], consumed };
+  }
+
+  return {
+    elements: [
+      {
+        element: "container",
+        data: {
+          type: "paragraph",
+          attributes: {},
+          elements: inlineElements,
+        },
+      },
+    ],
+    consumed,
+  };
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Block rule for Wikidot collapsible blocks: `[[collapsible]]...[[/collapsible]]`.
+ *
+ * A collapsible renders as a show/hide toggle with body content that can
+ * be expanded or collapsed. The opening tag accepts several attributes
+ * (which may span multiple lines):
+ *
+ * - `show`           -- label text for the "show" link (default: "+ show block").
+ * - `hide`           -- label text for the "hide" link (default: "- hide block").
+ * - `folded`         -- when `"no"`, the block starts in the expanded state.
+ * - `hideLocation`   -- where the toggle link appears: `"top"` (default),
+ *                       `"bottom"`, `"both"`, or `"neither"`/`"none"`.
+ *
+ * Key Wikidot-specific behaviours:
+ * - Collapsibles cannot nest. When the body parser encounters a second
+ *   `[[collapsible]]`, it is treated as plain text. This is achieved by
+ *   filtering the collapsible rule out of the block rule list for body parsing.
+ * - Orphaned `[[/collapsible]]` tags after the matched close are consumed and
+ *   emitted as `<br />` + literal text, matching Wikidot rendering.
+ * - An inline form (`[[collapsible]]text[[/collapsible]]` on one line) is
+ *   supported but uncommon.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { resolveToggleVisibility } from "./attributes";
+import { parseCollapsibleBody } from "./body";
+import { parseCollapsibleOpen } from "./open";
+import { consumeOrphanedCollapsibleCloses } from "./orphans";
+import { consumeCollapsibleCloseTag, isCollapsibleClose } from "./tags";
+
+/**
+ * Block rule for `[[collapsible ...]]...[[/collapsible]]`.
+ *
+ * Parsing strategy:
+ * 1. Match BLOCK_OPEN + name "collapsible".
+ * 2. Parse multiline attributes (show, hide, folded, hideLocation, etc.).
+ * 3. If a NEWLINE follows the opening tag, parse body as block content
+ *    with the collapsible rule itself excluded (to prevent nesting).
+ *    Otherwise, parse inline content until close tag or end of line
+ *    (inline form).
+ * 4. Consume the `[[/collapsible]]` closing tag.
+ * 5. Consume any orphaned `[[/collapsible]]` tags that follow, converting
+ *    them to `<br />` + literal text.
+ * 6. Derive `show-top` / `show-bottom` booleans from the `hideLocation`
+ *    attribute.
+ */
+export const collapsibleRule: BlockRule = {
+  name: "collapsible",
+  startTokens: ["BLOCK_OPEN"],
+  requiresLineStart: false,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseCollapsibleOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    // Record opening tag position for diagnostics
+    const openPosition = openToken.position;
+
+    let pos = openResult.bodyStart;
+    let consumed = openResult.consumed;
+    const bodyResult = parseCollapsibleBody(ctx, pos, openResult.hasNewlineAfterOpen);
+    consumed += bodyResult.consumed;
+    pos += bodyResult.consumed;
+
+    // Check for missing close tag
+    if (!isCollapsibleClose(ctx, pos)) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/collapsible]] for [[collapsible]]",
+        position: openPosition,
+      });
+    }
+
+    // Consume [[/collapsible]]
+    if (isCollapsibleClose(ctx, pos)) {
+      const closeConsumed = consumeCollapsibleCloseTag(ctx, pos);
+      consumed += closeConsumed;
+      pos += closeConsumed;
+    }
+
+    const orphanedResult = consumeOrphanedCollapsibleCloses(ctx, pos);
+    consumed += orphanedResult.consumed;
+
+    const toggleVisibility = resolveToggleVisibility(openResult.attrs);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "collapsible",
+          data: {
+            elements: bodyResult.elements,
+            attributes: {},
+            "start-open": openResult.attrs.folded === "no",
+            "show-text": openResult.attrs.show ?? null,
+            "hide-text": openResult.attrs.hide ?? null,
+            "show-top": toggleVisibility.showTop,
+            "show-bottom": toggleVisibility.showBottom,
+          },
+        },
+        ...orphanedResult.elements,
+      ],
+      consumed,
+    };
+  },
+};

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

@@ -0,0 +1,51 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+import { parseMultilineAttributes, type CollapsibleAttributes } from "./attributes";
+
+export interface CollapsibleOpenResult {
+  attrs: CollapsibleAttributes;
+  bodyStart: number;
+  consumed: number;
+  hasNewlineAfterOpen: boolean;
+}
+
+export function parseCollapsibleOpen(ctx: ParseContext): CollapsibleOpenResult | null {
+  if (ctx.tokens[ctx.pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  const nameResult = parseBlockName(ctx, pos);
+  if (!nameResult || nameResult.name !== "collapsible") {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseMultilineAttributes(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  const hasNewlineAfterOpen = ctx.tokens[pos]?.type === "NEWLINE";
+  if (hasNewlineAfterOpen) {
+    pos++;
+    consumed++;
+  }
+
+  return {
+    attrs: attrResult.attrs,
+    bodyStart: pos,
+    consumed,
+    hasNewlineAfterOpen,
+  };
+}

package/src/parser/rules/block/collapsible/orphans.ts

@@ -0,0 +1,31 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { isCollapsibleClose } from "./tags";
+
+export function consumeOrphanedCollapsibleCloses(
+  ctx: ParseContext,
+  startPos: number,
+): { elements: Element[]; consumed: number } {
+  const elements: Element[] = [];
+  let pos = startPos;
+  let consumed = 0;
+
+  while (isCollapsibleClose(ctx, pos)) {
+    elements.push({ element: "line-break" });
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "NEWLINE" || token.type === "EOF") break;
+      elements.push({ element: "text", data: token.value });
+      consumed++;
+      pos++;
+    }
+
+    if (ctx.tokens[pos]?.type === "NEWLINE") {
+      consumed++;
+      pos++;
+    }
+  }
+
+  return { elements, consumed };
+}

package/src/parser/rules/block/collapsible/tags.ts

@@ -0,0 +1,17 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../utils";
+
+export function isCollapsibleClose(ctx: ParseContext, pos: number): boolean {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") return false;
+  const nameResult = parseBlockName(ctx, pos + 1);
+  return nameResult?.name === "collapsible";
+}
+
+export function consumeCollapsibleCloseTag(ctx: ParseContext, pos: number): number {
+  let closeConsumed = 1;
+  const nameResult = parseBlockName(ctx, pos + 1);
+  if (nameResult) closeConsumed += nameResult.consumed;
+  if (ctx.tokens[pos + closeConsumed]?.type === "BLOCK_CLOSE") closeConsumed++;
+  if (ctx.tokens[pos + closeConsumed]?.type === "NEWLINE") closeConsumed++;
+  return closeConsumed;
+}

package/src/parser/rules/block/comment/consume.ts

@@ -0,0 +1,37 @@
+import type { ParseContext } from "../../types";
+
+export interface BlockCommentConsumeResult {
+  consumed: number;
+}
+
+export function consumeBlockComment(ctx: ParseContext): BlockCommentConsumeResult | null {
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token) {
+      break;
+    }
+
+    if (token.type === "COMMENT_CLOSE") {
+      consumed++;
+      pos++;
+
+      if (ctx.tokens[pos]?.type === "NEWLINE") {
+        consumed++;
+      }
+
+      return { consumed };
+    }
+
+    if (token.type === "EOF") {
+      return null;
+    }
+
+    pos++;
+    consumed++;
+  }
+
+  return null;
+}

package/src/parser/rules/block/{comment.ts → comment/index.ts}

@@ -16,7 +16,8 @@
  * @module
  */
 import type { Element } from "@wdprlib/ast";
-import type { BlockRule, ParseContext, RuleResult } from "../types";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { consumeBlockComment } from "./consume";
 
 /**
  * Block rule for line-start comments (`[!-- ... --]`).
@@ -29,45 +30,18 @@ export const blockCommentRule: BlockRule = {
   requiresLineStart: true,
 
   parse(ctx: ParseContext): RuleResult<Element> {
-    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++;
-
-        // Consume trailing newline if present
-        if (ctx.tokens[pos]?.type === "NEWLINE") {
-          consumed++;
-        }
-
-        // Return empty elements - comment is discarded
-        return {
-          success: true,
-          elements: [],
-          consumed,
-        };
-      }
-
-      if (token.type === "EOF") {
-        // Unterminated comment — let the inline comment rule emit the diagnostic
-        // to avoid duplication when the paragraph fallback retries this token.
-        return { success: false };
-      }
-
-      pos++;
-      consumed++;
-    }
+    const result = consumeBlockComment(ctx);
 
     // Unterminated comment — let the inline comment rule emit the diagnostic
     // to avoid duplication when the paragraph fallback retries this token.
-    return { success: false };
+    if (!result) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [],
+      consumed: result.consumed,
+    };
   },
 };

package/src/parser/rules/block/{content-separator.ts → content-separator/index.ts}

@@ -19,8 +19,8 @@
  * @module
  */
 import type { Element } from "@wdprlib/ast";
-import type { BlockRule, ParseContext, RuleResult } from "../types";
-import { currentToken } from "../types";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { parseContentSeparatorSyntax } from "./syntax";
 
 /**
  * Block rule for the content separator (`====`).
@@ -33,38 +33,8 @@ export const contentSeparatorRule: BlockRule = {
   requiresLineStart: true,
 
   parse(ctx: ParseContext): RuleResult<Element> {
-    const first = currentToken(ctx);
-
-    if (!first.lineStart) {
-      return { success: false };
-    }
-
-    // Count consecutive = tokens at line start
-    let pos = ctx.pos;
-    let equalsCount = 0;
-
-    while (ctx.tokens[pos]?.type === "EQUALS") {
-      equalsCount++;
-      pos++;
-    }
-
-    // Need at least 4 equals signs for content separator
-    if (equalsCount < 4) {
-      return { success: false };
-    }
-
-    // Must be followed by newline or EOF
-    const nextToken = ctx.tokens[pos];
-    if (nextToken && nextToken.type !== "NEWLINE" && nextToken.type !== "EOF") {
-      return { success: false };
-    }
-
-    let consumed = equalsCount;
-
-    // Consume newline if present
-    if (ctx.tokens[pos]?.type === "NEWLINE") {
-      consumed++;
-    }
+    const syntax = parseContentSeparatorSyntax(ctx);
+    if (!syntax) return { success: false };
 
     return {
       success: true,
@@ -73,7 +43,7 @@ export const contentSeparatorRule: BlockRule = {
           element: "content-separator",
         },
       ],
-      consumed,
+      consumed: syntax.consumed,
     };
   },
 };

package/src/parser/rules/block/content-separator/syntax.ts

@@ -0,0 +1,33 @@
+import type { ParseContext } from "../../types";
+
+export interface ContentSeparatorSyntax {
+  consumed: number;
+}
+
+export function parseContentSeparatorSyntax(ctx: ParseContext): ContentSeparatorSyntax | null {
+  const first = ctx.tokens[ctx.pos];
+  if (first?.type !== "EQUALS" || !first.lineStart) {
+    return null;
+  }
+
+  let pos = ctx.pos;
+  let equalsCount = 0;
+
+  while (ctx.tokens[pos]?.type === "EQUALS") {
+    equalsCount++;
+    pos++;
+  }
+
+  if (equalsCount < 4) {
+    return null;
+  }
+
+  const nextToken = ctx.tokens[pos];
+  if (nextToken && nextToken.type !== "NEWLINE" && nextToken.type !== "EOF") {
+    return null;
+  }
+
+  return {
+    consumed: equalsCount + (nextToken?.type === "NEWLINE" ? 1 : 0),
+  };
+}

package/src/parser/rules/block/definition-list/collect.ts

@@ -0,0 +1,40 @@
+import type { ParseContext } from "../../types";
+import { parseDefinitionItem, type ParsedDefinitionItem } from "./items";
+
+export interface DefinitionListParseResult {
+  items: ParsedDefinitionItem[];
+  consumed: number;
+}
+
+export function collectDefinitionItems(ctx: ParseContext): DefinitionListParseResult {
+  const items: ParsedDefinitionItem[] = [];
+  let pos = ctx.pos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (token.type !== "COLON" || !token.lineStart) {
+      break;
+    }
+
+    const result = parseDefinitionItem(ctx, pos);
+    if (!result) {
+      break;
+    }
+
+    items.push(result.item);
+    pos += result.consumed;
+    consumed += result.consumed;
+
+    while (ctx.tokens[pos]?.type === "WHITESPACE") {
+      pos++;
+      consumed++;
+    }
+  }
+
+  return { items, consumed };
+}

package/src/parser/rules/block/definition-list/index.ts

@@ -0,0 +1,63 @@
+/**
+ *
+ * Block rule for Wikidot definition lists written with the `: key : value` syntax.
+ *
+ * Each item starts at the beginning of a line with a COLON, followed by
+ * mandatory whitespace, the key (term), a second COLON, and then the value
+ * (definition). Multiple consecutive items form a single `<dl>` block.
+ *
+ * ```
+ * : Apple : A fruit that grows on trees.
+ * : Banana : A yellow curved fruit.
+ * ```
+ *
+ * Key parsing details:
+ * - Whitespace after the first colon is required (`": key"` not `":key"`).
+ * - The key portion supports inline markup (bold, links, etc.).
+ * - The value continues until a double newline, a new definition entry, or
+ *   the end of the document.
+ * - A single newline within the value does NOT break the entry -- parsing
+ *   continues on the next line.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { BlockRule, ParseContext, RuleResult } from "../../types";
+import { collectDefinitionItems } from "./collect";
+import { toDefinitionListItems } from "./items";
+
+/**
+ * Block rule for Wikidot definition lists (`: key : value`).
+ *
+ * Parsing strategy:
+ * 1. Verify the first token is a line-start COLON.
+ * 2. Repeatedly call `parseDefinitionItem()` to collect entries.
+ * 3. Stop when the current token is no longer a line-start COLON (i.e.
+ *    the definition list block has ended).
+ * 4. Convert internal items into the AST {@link DefinitionListItem} format.
+ * 5. Emit a single `definition-list` element.
+ */
+export const definitionListRule: BlockRule = {
+  name: "definitionList",
+  startTokens: ["COLON"],
+  requiresLineStart: true,
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const result = collectDefinitionItems(ctx);
+
+    if (result.items.length === 0) {
+      return { success: false };
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "definition-list",
+          data: toDefinitionListItems(result.items),
+        },
+      ],
+      consumed: result.consumed,
+    };
+  },
+};