@wdprlib/parser 3.2.0 → 4.0.0

package/src/parser/postprocess/spanStrip/clean-element.ts

@@ -0,0 +1,168 @@
+import type { DefinitionListItem, Element, ListItem } from "@wdprlib/ast";
+import type { InternalContainerData } from "./predicates";
+
+type CleanElements = (elements: Element[]) => Element[];
+
+export function cleanElement(el: Element, cleanElements: CleanElements): Element {
+  if (el.element === "line-break") {
+    return cleanLineBreak(el);
+  }
+
+  if (el.element === "container") {
+    return cleanContainer(el, cleanElements);
+  }
+
+  if (el.element === "collapsible") {
+    const elements = cleanElements(el.data.elements);
+    if (elements === el.data.elements) {
+      return el;
+    }
+    return {
+      element: "collapsible",
+      data: {
+        ...el.data,
+        elements,
+      },
+    };
+  }
+
+  if (el.element === "color") {
+    const elements = cleanElements(el.data.elements);
+    if (elements === el.data.elements) {
+      return el;
+    }
+    return {
+      element: "color",
+      data: {
+        ...el.data,
+        elements,
+      },
+    };
+  }
+
+  if (el.element === "list") {
+    let items: typeof el.data.items | null = null;
+    for (let i = 0; i < el.data.items.length; i++) {
+      const item = el.data.items[i]!;
+      const cleaned = cleanListItem(item, cleanElements);
+      if (items !== null) {
+        items.push(cleaned);
+      } else if (cleaned !== item) {
+        items = el.data.items.slice(0, i);
+        items.push(cleaned);
+      }
+    }
+
+    if (items === null) {
+      return el;
+    }
+
+    return {
+      element: "list",
+      data: {
+        ...el.data,
+        items,
+      },
+    };
+  }
+
+  if (el.element === "definition-list") {
+    let items: typeof el.data | null = null;
+    for (let i = 0; i < el.data.length; i++) {
+      const item = el.data[i]!;
+      const cleaned = cleanDefinitionListItem(item, cleanElements);
+      if (items !== null) {
+        items.push(cleaned);
+      } else if (cleaned !== item) {
+        items = el.data.slice(0, i);
+        items.push(cleaned);
+      }
+    }
+
+    if (items === null) {
+      return el;
+    }
+
+    return {
+      element: "definition-list",
+      data: items,
+    };
+  }
+
+  return el;
+}
+
+function cleanLineBreak(el: Element): Element {
+  for (const key in el) {
+    if (key !== "element") {
+      return { element: "line-break" };
+    }
+  }
+  return el;
+}
+
+function cleanContainer(
+  el: Extract<Element, { element: "container" }>,
+  cleanElements: CleanElements,
+): Element {
+  const data = el.data as InternalContainerData;
+  const elements = cleanElements(data.elements);
+  const hasInternalFlags =
+    data._paragraphStrip !== undefined ||
+    data._emptyParagraphStrip !== undefined ||
+    data._escapedFromParagraph !== undefined ||
+    data._splitByBlankLine !== undefined;
+
+  if (!hasInternalFlags && elements === data.elements) {
+    return el;
+  }
+
+  return {
+    element: "container",
+    data: {
+      type: data.type,
+      attributes: data.attributes,
+      elements,
+    },
+  };
+}
+
+function cleanListItem(item: ListItem, cleanElements: CleanElements): ListItem {
+  if (item["item-type"] === "elements") {
+    const elements = cleanElements(item.elements);
+    return elements === item.elements
+      ? item
+      : {
+          ...item,
+          elements,
+        };
+  }
+
+  if (item["item-type"] === "sub-list") {
+    const cleanedList = cleanElement({ element: "list", data: item.data }, cleanElements);
+    return cleanedList.element === "list" && cleanedList.data !== item.data
+      ? {
+          "item-type": "sub-list",
+          element: "list",
+          data: cleanedList.data,
+        }
+      : item;
+  }
+
+  return item;
+}
+
+function cleanDefinitionListItem(
+  item: DefinitionListItem,
+  cleanElements: CleanElements,
+): DefinitionListItem {
+  const key = cleanElements(item.key);
+  const value = cleanElements(item.value);
+  return key === item.key && value === item.value
+    ? item
+    : {
+        ...item,
+        key,
+        value,
+      };
+}

package/src/parser/postprocess/spanStrip/cleanup.ts

@@ -0,0 +1,25 @@
+import type { Element } from "@wdprlib/ast";
+import { cleanElement } from "./clean-element";
+import { removeEmptySpansAndAdjacentWhitespace } from "./empty-spans";
+
+/**
+ * Recursively remove internal flags from AST elements and clean up empty spans.
+ */
+export function cleanInternalFlags(elements: Element[]): Element[] {
+  let cleaned: Element[] | null = null;
+
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (!el) continue;
+
+    const next = cleanElement(el, cleanInternalFlags);
+    if (cleaned !== null) {
+      cleaned.push(next);
+    } else if (next !== el) {
+      cleaned = elements.slice(0, i);
+      cleaned.push(next);
+    }
+  }
+
+  return removeEmptySpansAndAdjacentWhitespace(cleaned ?? elements);
+}

package/src/parser/postprocess/spanStrip/empty-spans.ts

@@ -0,0 +1,36 @@
+import type { Element } from "@wdprlib/ast";
+import { isEmptySpan, isWhitespaceText } from "./predicates";
+
+export function removeEmptySpansAndAdjacentWhitespace(elements: Element[]): Element[] {
+  let hasEmptySpan = false;
+  for (const el of elements) {
+    if (el && isEmptySpan(el)) {
+      hasEmptySpan = true;
+      break;
+    }
+  }
+  if (!hasEmptySpan) {
+    return elements;
+  }
+
+  const result: Element[] = [];
+
+  for (let i = 0; i < elements.length; i++) {
+    const el = elements[i];
+    if (!el) continue;
+
+    if (isEmptySpan(el)) {
+      if (result.length > 0 && isWhitespaceText(result[result.length - 1]!)) {
+        result.pop();
+      }
+      while (i + 1 < elements.length && elements[i + 1] && isWhitespaceText(elements[i + 1]!)) {
+        i++;
+      }
+      continue;
+    }
+
+    result.push(el);
+  }
+
+  return result;
+}

package/src/parser/postprocess/spanStrip/escaped.ts

@@ -0,0 +1,78 @@
+import type { Element } from "@wdprlib/ast";
+import { spanElement } from "./factory";
+import {
+  getContainerData,
+  isEscapedSpan,
+  isSpanStripMarker,
+  type InternalContainerData,
+} from "./predicates";
+
+export function extractEscapedSpans(children: Element[]): Element[] {
+  const escaped: Element[] = [];
+
+  let firstEscapedIndex = -1;
+  for (let i = 0; i < children.length; i++) {
+    const child = children[i];
+    if (child && isEscapedSpan(child)) {
+      firstEscapedIndex = i;
+      break;
+    }
+  }
+
+  if (firstEscapedIndex === -1) {
+    return escaped;
+  }
+
+  let currentSpanChildren: Element[] = [];
+
+  for (let i = firstEscapedIndex; i < children.length; i++) {
+    const child = children[i];
+    if (!child) continue;
+
+    if (isEscapedSpan(child)) {
+      if (currentSpanChildren.length > 0) {
+        escaped.push(spanElement(currentSpanChildren));
+        currentSpanChildren = [];
+      }
+      escaped.push(child);
+    } else if (isSpanStripMarker(child)) {
+      const childData = getContainerData(child);
+      if (childData) {
+        escaped.push(spanElement(childData.elements, childData.attributes));
+      }
+    } else {
+      currentSpanChildren.push(child);
+    }
+  }
+
+  if (currentSpanChildren.length > 0) {
+    escaped.push(spanElement(currentSpanChildren));
+  }
+
+  children.splice(firstEscapedIndex);
+
+  return escaped;
+}
+
+export function removeLineBreaksAroundSpanStrip(children: Element[]): void {
+  for (let i = children.length - 1; i >= 0; i--) {
+    const child = children[i];
+    if (!child) continue;
+
+    if (child.element === "line-break") {
+      const prev = children[i - 1];
+      const next = children[i + 1];
+      if (isSpanStripMarker(prev) || isSpanStripMarker(next)) {
+        children.splice(i, 1);
+        continue;
+      }
+    }
+
+    if (child.element === "container") {
+      const data = child.data as InternalContainerData;
+      if (data.type === "span" && data._emptyParagraphStrip) {
+        children.splice(i, 1);
+      }
+    }
+  }
+}

package/src/parser/postprocess/spanStrip/factory.ts

@@ -0,0 +1,23 @@
+import type { Element } from "@wdprlib/ast";
+
+export function paragraphElement(elements: Element[]): Element {
+  return {
+    element: "container",
+    data: {
+      type: "paragraph",
+      attributes: {},
+      elements,
+    },
+  };
+}
+
+export function spanElement(elements: Element[], attributes: Record<string, string> = {}): Element {
+  return {
+    element: "container",
+    data: {
+      type: "span",
+      attributes,
+      elements,
+    },
+  };
+}

package/src/parser/postprocess/spanStrip/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Public facade for span-strip post-processing.
+ *
+ * @module
+ */
+
+export { mergeSpanStripParagraphs } from "./merge";
+export { cleanInternalFlags } from "./cleanup";

package/src/parser/postprocess/spanStrip/merge.ts

@@ -0,0 +1,117 @@
+import type { Element } from "@wdprlib/ast";
+import { extractEscapedSpans, removeLineBreaksAroundSpanStrip } from "./escaped";
+import { paragraphElement } from "./factory";
+import {
+  getContainerData,
+  hasParagraphStripSpan,
+  isContainer,
+  isEmptyExpr,
+  isSplitSpan,
+} from "./predicates";
+import { splitParagraphAtBlankLineSpans, splitParagraphAtEmptyExpr } from "./split";
+
+/**
+ * Merge and split paragraphs according to Wikidot's `span_` and expr behaviors.
+ */
+export function mergeSpanStripParagraphs(children: Element[]): Element[] {
+  const expandedChildren = expandSplitParagraphs(children);
+  const result: Element[] = [];
+  let i = 0;
+
+  while (i < expandedChildren.length) {
+    const node = expandedChildren[i];
+
+    if (!node || !isContainer(node, "paragraph")) {
+      if (node) result.push(node);
+      i++;
+      continue;
+    }
+
+    if (!hasParagraphStripSpan(node)) {
+      result.push(node);
+      i++;
+      continue;
+    }
+
+    const paraData = getContainerData(node);
+    if (!paraData) {
+      result.push(node);
+      i++;
+      continue;
+    }
+
+    const mergedChildren: Element[] = [...paraData.elements];
+    i++;
+
+    while (i < expandedChildren.length) {
+      const nextPara = expandedChildren[i];
+      if (!nextPara || !isContainer(nextPara, "paragraph")) {
+        break;
+      }
+
+      const nextParaData = getContainerData(nextPara);
+      if (!nextParaData) {
+        break;
+      }
+
+      const hasSpanStrip = hasParagraphStripSpan(nextPara);
+      mergedChildren.push(...nextParaData.elements);
+      i++;
+
+      if (!hasSpanStrip) {
+        const peekNext = expandedChildren[i];
+        if (!peekNext || !isContainer(peekNext, "paragraph") || !hasParagraphStripSpan(peekNext)) {
+          break;
+        }
+      }
+    }
+
+    const escapedSpans = extractEscapedSpans(mergedChildren);
+    removeLineBreaksAroundSpanStrip(mergedChildren);
+
+    if (escapedSpans.length > 0) {
+      if (mergedChildren.length > 0) {
+        result.push(paragraphElement(mergedChildren));
+      }
+    } else {
+      result.push(...mergedChildren);
+    }
+
+    result.push(...escapedSpans);
+  }
+
+  return result;
+}
+
+function expandSplitParagraphs(children: Element[]): Element[] {
+  const expandedChildren: Element[] = [];
+  for (const child of children) {
+    if (isContainer(child, "paragraph")) {
+      const data = getContainerData(child);
+      if (data) {
+        const split = getParagraphSplitKind(data.elements);
+        if (split === "blank-line-span") {
+          expandedChildren.push(...splitParagraphAtBlankLineSpans(child));
+          continue;
+        }
+        if (split === "empty-expr") {
+          expandedChildren.push(...splitParagraphAtEmptyExpr(child));
+          continue;
+        }
+      }
+    }
+    expandedChildren.push(child);
+  }
+  return expandedChildren;
+}
+
+function getParagraphSplitKind(elements: Element[]): "blank-line-span" | "empty-expr" | null {
+  let hasEmptyExpr = false;
+  for (const element of elements) {
+    if (isSplitSpan(element)) {
+      return "blank-line-span";
+    }
+    hasEmptyExpr ||= isEmptyExpr(element);
+  }
+  return hasEmptyExpr ? "empty-expr" : null;
+}

package/src/parser/postprocess/spanStrip/predicates.ts

@@ -0,0 +1,59 @@
+import type { ContainerData, Element, ExprData } from "@wdprlib/ast";
+
+export type InternalContainerData = ContainerData & {
+  _paragraphStrip?: boolean;
+  _emptyParagraphStrip?: boolean;
+  _escapedFromParagraph?: boolean;
+  _splitByBlankLine?: boolean;
+};
+
+export function isContainer(el: Element, type: string): boolean {
+  if (el.element !== "container") return false;
+  return el.data.type === type;
+}
+
+export function getContainerData(el: Element): ContainerData | null {
+  if (el.element !== "container") return null;
+  return el.data;
+}
+
+export function isSpanStripMarker(el: Element | undefined): boolean {
+  if (!el || el.element !== "container") return false;
+  const data = el.data as InternalContainerData;
+  return (
+    data.type === "span" && (data._paragraphStrip === true || data._emptyParagraphStrip === true)
+  );
+}
+
+export function hasParagraphStripSpan(para: Element): boolean {
+  const data = getContainerData(para);
+  if (!data || data.type !== "paragraph") return false;
+  return data.elements.some((child) => isSpanStripMarker(child));
+}
+
+export function isEscapedSpan(el: Element): boolean {
+  if (el.element !== "container") return false;
+  const data = el.data as InternalContainerData;
+  return data.type === "span" && data._escapedFromParagraph === true;
+}
+
+export function isSplitSpan(el: Element): boolean {
+  if (el.element !== "container") return false;
+  const data = el.data as InternalContainerData;
+  return data.type === "span" && data._splitByBlankLine === true;
+}
+
+export function isEmptyExpr(el: Element): boolean {
+  if (el.element !== "expr") return false;
+  const data = el.data as ExprData;
+  return data.expression === "";
+}
+
+export function isEmptySpan(el: Element): boolean {
+  if (el.element !== "container") return false;
+  return el.data.type === "span" && el.data.elements.length === 0;
+}
+
+export function isWhitespaceText(el: Element): boolean {
+  return el.element === "text" && typeof el.data === "string" && /^\s+$/.test(el.data);
+}

package/src/parser/postprocess/spanStrip/split.ts

@@ -0,0 +1,67 @@
+import type { Element } from "@wdprlib/ast";
+import { paragraphElement } from "./factory";
+import { getContainerData, isEmptyExpr, isSplitSpan } from "./predicates";
+
+export function splitParagraphAtBlankLineSpans(para: Element): Element[] {
+  const data = getContainerData(para);
+  if (!data || data.type !== "paragraph") return [para];
+
+  const result: Element[] = [];
+  let currentElements: Element[] = [];
+
+  for (const child of data.elements) {
+    if (isSplitSpan(child)) {
+      if (currentElements.length > 0) {
+        result.push(paragraphElement(currentElements));
+        currentElements = [];
+      }
+      currentElements.push(child);
+    } else {
+      currentElements.push(child);
+    }
+  }
+
+  if (currentElements.length > 0) {
+    result.push(paragraphElement(currentElements));
+  }
+
+  return result.length > 0 ? result : [para];
+}
+
+export function splitParagraphAtEmptyExpr(para: Element): Element[] {
+  const data = getContainerData(para);
+  if (!data || data.type !== "paragraph") return [para];
+  if (!data.elements.some(isEmptyExpr)) return [para];
+
+  const result: Element[] = [];
+  let currentElements: Element[] = [];
+
+  for (let i = 0; i < data.elements.length; i++) {
+    const child = data.elements[i];
+    if (!child) continue;
+
+    if (isEmptyExpr(child)) {
+      if (
+        currentElements.length > 0 &&
+        currentElements[currentElements.length - 1]?.element === "line-break"
+      ) {
+        currentElements.pop();
+      }
+      if (currentElements.length > 0) {
+        result.push(paragraphElement(currentElements));
+        currentElements = [];
+      }
+      if (i + 1 < data.elements.length && data.elements[i + 1]?.element === "line-break") {
+        i++;
+      }
+    } else {
+      currentElements.push(child);
+    }
+  }
+
+  if (currentElements.length > 0) {
+    result.push(paragraphElement(currentElements));
+  }
+
+  return result.length > 0 ? result : [];
+}

package/src/parser/preprocess/expr/chars.ts

@@ -0,0 +1,15 @@
+export function isWhitespace(ch: string | undefined): boolean {
+  return ch === " " || ch === "\t" || ch === "\n" || ch === "\r";
+}
+
+export function isIdentChar(ch: string | undefined): boolean {
+  if (!ch) return false;
+  const code = ch.charCodeAt(0);
+  return (
+    (code >= 48 && code <= 57) ||
+    (code >= 65 && code <= 90) ||
+    (code >= 97 && code <= 122) ||
+    code === 95 ||
+    code === 45
+  );
+}

package/src/parser/preprocess/expr/evaluate.ts

@@ -0,0 +1,22 @@
+import { evaluateExpression, formatExprValue, isTruthy } from "@wdprlib/ast";
+import type { DirectiveKind, DirectiveMatch } from "./types";
+
+/** Evaluate a parsed directive into its replacement string. */
+export function evaluateDirective(kind: DirectiveKind, match: DirectiveMatch): string {
+  if (kind === "expr") {
+    const result = evaluateExpression(match.head);
+    if (result.success) return formatExprValue(result.value);
+    if (result.error === "empty expression") return "";
+    return "ERROR";
+  }
+
+  if (kind === "if") {
+    if (!match.hasPipe) return "";
+    return isTruthy(match.head) ? match.thenText : match.elseText;
+  }
+
+  if (!match.hasPipe) return "";
+  const result = evaluateExpression(match.head);
+  if (!result.success) return "ERROR";
+  return result.value !== 0 && !Number.isNaN(result.value) ? match.thenText : match.elseText;
+}

package/src/parser/preprocess/expr/index.ts

@@ -0,0 +1,45 @@
+/**
+ *
+ * Text-level expansion of `[[#if ...]]`, `[[#ifexpr ...]]`, and
+ * `[[#expr ...]]` directives that sit *inside* another block's opener.
+ *
+ * @module
+ */
+
+import { makeUniqueSentinels, maskRawRegions, restorePlaceholders } from "../utils";
+import { expandInnermost } from "./scan";
+
+/**
+ * Resolve every `[[#if]]` / `[[#ifexpr]]` / `[[#expr]]` that sits inside
+ * another block's opener (depth > 0). Top-level directives are left for
+ * the inline parser. Innermost-first reduction lets an outer directive
+ * re-process the flattened body on the next pass. Unmatched / malformed
+ * directives are left untouched.
+ */
+export function preprocessExpr(source: string): string {
+  if (!source.includes("[[#")) return source;
+
+  const sentinels = makeUniqueSentinels(source);
+  const { masked, placeholders } = maskRawRegions(source, sentinels);
+  const reduced = reduceExpr(masked);
+  return restorePlaceholders(reduced, placeholders, sentinels);
+}
+
+/**
+ * Backwards-compatible alias for the older `preprocessIf` name (used by
+ * external callers that target the previous, `[[#if]]`-only behaviour).
+ * Both names point at the same implementation, which now also resolves
+ * `[[#ifexpr]]` and `[[#expr]]` in opener context.
+ */
+export const preprocessIf: (source: string) => string = preprocessExpr;
+
+function reduceExpr(source: string): string {
+  let current = source;
+  const maxIterations = source.length + 1;
+  for (let i = 0; i < maxIterations; i++) {
+    const next = expandInnermost(current);
+    if (next === current) return current;
+    current = next;
+  }
+  return current;
+}

package/src/parser/preprocess/expr/kind.ts

@@ -0,0 +1,19 @@
+import type { DirectiveKind } from "./types";
+import { isIdentChar } from "./chars";
+
+/** Return the kind of `[[#xxx` directive at `i`, or null if none matches. */
+export function matchDirectiveKind(source: string, i: number): DirectiveKind | null {
+  if (!source.startsWith("[[#", i)) return null;
+  // Order matters: `ifexpr` must be checked before `if` because the
+  // shorter `if` prefix would otherwise consume `ifexpr` openings.
+  if (source.startsWith("ifexpr", i + 3) && !isIdentChar(source[i + 9])) {
+    return "ifexpr";
+  }
+  if (source.startsWith("if", i + 3) && !isIdentChar(source[i + 5])) {
+    return "if";
+  }
+  if (source.startsWith("expr", i + 3) && !isIdentChar(source[i + 7])) {
+    return "expr";
+  }
+  return null;
+}