@wdprlib/parser 3.1.2 → 4.0.0

package/src/parser/rules/block/module/listpages/resolution/items.ts

@@ -0,0 +1,43 @@
+import type { Element } from "@wdprlib/ast";
+import type { CompiledTemplate, ListPagesExternalData, VariableContext } from "../types";
+import type { ParseFunction } from "../../types";
+import type { ListPagesModuleData } from "../resolve";
+
+export function renderListPagesItems(
+  module: ListPagesModuleData,
+  data: ListPagesExternalData,
+  compiledTemplate: CompiledTemplate,
+  parse: ParseFunction,
+): Element[] {
+  const items: Element[] = [];
+
+  for (let i = 0; i < data.pages.length; i++) {
+    const page = data.pages[i];
+    if (!page) continue;
+
+    const ctx: VariableContext = {
+      page,
+      index: i + 1,
+      total: data.totalCount,
+      limit: module.limit,
+      site: data.site,
+    };
+
+    const itemAst = parse(compiledTemplate(ctx));
+
+    if (module.separate) {
+      items.push({
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "list-pages-item" },
+          elements: itemAst.elements,
+        },
+      });
+    } else {
+      items.push(...itemAst.elements);
+    }
+  }
+
+  return items;
+}

package/src/parser/rules/block/module/listpages/resolution/wrapper.ts

@@ -0,0 +1,42 @@
+import type { Element } from "@wdprlib/ast";
+import type { ParseFunction } from "../../types";
+import type { ListPagesModuleData } from "../resolve";
+
+export function wrapListPagesResult(
+  module: ListPagesModuleData,
+  items: Element[],
+  parse: ParseFunction,
+): Element[] {
+  if (items.length === 0) {
+    return [];
+  }
+
+  const result: Element[] = [];
+
+  if (module["prepend-line"] && !module.separate) {
+    const prependAst = parse(module["prepend-line"]);
+    result.push(...prependAst.elements);
+  }
+
+  result.push(...items);
+
+  if (module["append-line"] && !module.separate) {
+    const appendAst = parse(module["append-line"]);
+    result.push(...appendAst.elements);
+  }
+
+  if (module.wrapper) {
+    return [
+      {
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "list-pages-box" },
+          elements: result,
+        },
+      },
+    ];
+  }
+
+  return result;
+}

package/src/parser/rules/block/module/listpages/resolve.ts

@@ -0,0 +1,60 @@
+/**
+ *
+ * ListPages module resolution (phase 3 of the ListPages lifecycle).
+ *
+ * After the application has fetched page data based on the extracted requirements,
+ * this module substitutes that data into the pre-compiled templates and re-parses
+ * the resulting wikitext to produce final AST elements.
+ *
+ * For each page in the fetched data:
+ * 1. Build a `VariableContext` with page data, index, total count, and site info
+ * 2. Execute the compiled template to produce a wikitext string
+ * 3. Re-parse the wikitext string into AST elements
+ * 4. Optionally wrap each item in a `div.list-pages-item` (when `separate=true`)
+ *
+ * The final result may also include prepend/append lines and be wrapped in a
+ * `div.list-pages-box` (when `wrapper=true`).
+ *
+ * @module
+ */
+
+import type { Element, Module } from "@wdprlib/ast";
+import type { ListPagesExternalData, CompiledTemplate } from "./types";
+import type { ParseFunction } from "../types";
+import { renderListPagesItems } from "./resolution/items";
+import { wrapListPagesResult } from "./resolution/wrapper";
+export type { ParseFunction };
+
+/**
+ * Narrowed type for the list-pages variant of the Module discriminated union.
+ */
+export type ListPagesModuleData = Extract<Module, { module: "list-pages" }>;
+
+/**
+ * Type guard to check if a Module is a list-pages module.
+ *
+ * @param module - A Module discriminated union value
+ * @returns true if the module is a list-pages module
+ */
+export function isListPagesModule(module: Module): module is ListPagesModuleData {
+  return module.module === "list-pages";
+}
+
+/**
+ * Resolve a single ListPages module
+ *
+ * @param module - ListPages module data from AST
+ * @param data - External data fetched for this module
+ * @param compiledTemplate - Pre-compiled template function
+ * @param parse - Parser function for re-parsing templates
+ * @returns Resolved elements
+ */
+export function resolveListPages(
+  module: ListPagesModuleData,
+  data: ListPagesExternalData,
+  compiledTemplate: CompiledTemplate,
+  parse: ParseFunction,
+): Element[] {
+  const items = renderListPagesItems(module, data, compiledTemplate, parse);
+  return wrapListPagesResult(module, items, parse);
+}

package/src/parser/rules/block/module/listpages/template/format/content.ts

@@ -0,0 +1,41 @@
+import type { PageData } from "../../types";
+
+/**
+ * Split content by ==== separators.
+ *
+ * Wikidot uses preg_split('/^([=]{4,})$/m', $source); %%content{n}%%
+ * references sections[n-1] (1-indexed).
+ */
+export function splitContentSections(content: string): string[] {
+  return content.split(/^={4,}$/m).map((section) => section.trim());
+}
+
+/**
+ * Extract a summary from page content.
+ */
+export function getSummary(page: PageData): string {
+  if (page.content) {
+    const sections = splitContentSections(page.content);
+    if (sections.length > 1) {
+      return sections[0]?.trim() ?? "";
+    }
+  }
+  return getFirstParagraph(page.content);
+}
+
+/**
+ * Extract the first paragraph from wikitext content.
+ */
+export function getFirstParagraph(content?: string): string {
+  if (!content) return "";
+
+  const stripped = content
+    .replace(/^(\+{1,6}) (.*)/gm, "")
+    .replace(/^\[\[toc(\s[^\]]+)?\]\]/gim, "")
+    .replace(/^\[\[\/?div(\s[^\]]+)?\]\]/gim, "")
+    .replace(/^\[\[\/?module(\s[^\]]+)?\]\]/gim, "")
+    .trim();
+
+  const paragraphs = stripped.split(/\n{2,}/);
+  return paragraphs[0]?.trim() ?? "";
+}

package/src/parser/rules/block/module/listpages/template/format/date.ts

@@ -0,0 +1,116 @@
+/**
+ * Format a Date object using an optional strftime-like format string.
+ *
+ * When no format is provided, returns the ISO 8601 string representation.
+ */
+export function formatDate(date: Date, format?: string): string {
+  if (!format) {
+    return date.toISOString();
+  }
+  if (format === "%Y-%m-%d") {
+    return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`;
+  }
+  return strftime(date, format);
+}
+
+/** Full month names for strftime `%B` token. Static to avoid per-call allocation. */
+const MONTHS = [
+  "January",
+  "February",
+  "March",
+  "April",
+  "May",
+  "June",
+  "July",
+  "August",
+  "September",
+  "October",
+  "November",
+  "December",
+];
+/** Abbreviated month names for strftime `%b` token. */
+const MONTHS_SHORT = [
+  "Jan",
+  "Feb",
+  "Mar",
+  "Apr",
+  "May",
+  "Jun",
+  "Jul",
+  "Aug",
+  "Sep",
+  "Oct",
+  "Nov",
+  "Dec",
+];
+/** Full day names for strftime `%A` token. */
+const DAYS = ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"];
+/** Abbreviated day names for strftime `%a` token. */
+const DAYS_SHORT = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+
+/** Pre-compiled regex matching strftime tokens (`%X` where X is supported). */
+const STRFTIME_REGEX = /%([YymdHeHIMSpbBaAwjZz%])/g;
+
+function strftime(date: Date, format: string): string {
+  return format.replace(STRFTIME_REGEX, (_, token: string) => {
+    switch (token) {
+      case "Y":
+        return String(date.getFullYear());
+      case "y":
+        return String(date.getFullYear()).slice(-2);
+      case "m":
+        return pad2(date.getMonth() + 1);
+      case "d":
+        return pad2(date.getDate());
+      case "e":
+        return String(date.getDate());
+      case "H":
+        return pad2(date.getHours());
+      case "I":
+        return pad2(date.getHours() % 12 || 12);
+      case "M":
+        return pad2(date.getMinutes());
+      case "S":
+        return pad2(date.getSeconds());
+      case "p":
+        return date.getHours() < 12 ? "AM" : "PM";
+      case "b":
+        return MONTHS_SHORT[date.getMonth()] ?? "";
+      case "B":
+        return MONTHS[date.getMonth()] ?? "";
+      case "a":
+        return DAYS_SHORT[date.getDay()] ?? "";
+      case "A":
+        return DAYS[date.getDay()] ?? "";
+      case "w":
+        return String(date.getDay());
+      case "j":
+        return pad3(getDayOfYear(date));
+      case "Z":
+        return "UTC";
+      case "z":
+        return "+0000";
+      case "%":
+        return "%";
+      default:
+        return `%${token}`;
+    }
+  });
+}
+
+function pad2(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+
+function pad3(n: number): string {
+  if (n < 10) return `00${n}`;
+  if (n < 100) return `0${n}`;
+  return String(n);
+}
+
+function getDayOfYear(date: Date): number {
+  const start = new Date(date.getFullYear(), 0, 0);
+  const diff = date.getTime() - start.getTime();
+  const oneDay = 1000 * 60 * 60 * 24;
+  return Math.floor(diff / oneDay);
+}

package/src/parser/rules/block/module/listpages/template/format/index.ts

@@ -0,0 +1,4 @@
+export { formatDate } from "./date";
+export { getFirstParagraph, getSummary, splitContentSections } from "./content";
+export { formatTagsLinked } from "./tags";
+export { formatUserLinked } from "./user";

package/src/parser/rules/block/module/listpages/template/format/tags.ts

@@ -0,0 +1,7 @@
+/**
+ * Format an array of tags as space-separated Wikidot link syntax.
+ */
+export function formatTagsLinked(tags: string[], prefix: string): string {
+  if (tags.length === 0) return "";
+  return tags.map((tag) => `[${prefix}${tag} ${tag}]`).join(" ");
+}

package/src/parser/rules/block/module/listpages/template/format/user.ts

@@ -0,0 +1,9 @@
+import type { UserInfo } from "../../types";
+
+/**
+ * Format a user as Wikidot's `[[*user name]]` inline syntax for linked display.
+ */
+export function formatUserLinked(user?: UserInfo): string {
+  if (!user) return "Anonymous";
+  return `[[*user ${user.name}]]`;
+}

package/src/parser/rules/block/module/listpages/template/getters/index.ts

@@ -0,0 +1,36 @@
+import {
+  createBraceParamGetter,
+  createFormattedGetter,
+  createParenParamGetter,
+  createTagsLinkedGetter,
+} from "./parameterized";
+import { SIMPLE_GETTERS } from "./simple";
+import type { VariableGetter } from "./types";
+
+/**
+ * Create a getter function for a specific template variable.
+ *
+ * Handles all variable variants: parameterized (`{param}`), parenthesized
+ * (`(param)`), formatted (`|format`), and simple. Unknown variable names return
+ * a function that always returns an empty string, matching Wikidot's behavior.
+ */
+export function createVariableGetter(
+  name: string,
+  braceParam?: string,
+  parenParam?: string,
+  format?: string,
+): VariableGetter {
+  const braceGetter = braceParam !== undefined ? createBraceParamGetter(name, braceParam) : null;
+  if (braceGetter) return braceGetter;
+
+  const parenGetter = parenParam !== undefined ? createParenParamGetter(name, parenParam) : null;
+  if (parenGetter) return parenGetter;
+
+  const formattedGetter = format !== undefined ? createFormattedGetter(name, format) : null;
+  if (formattedGetter) return formattedGetter;
+
+  const linkedTagsGetter = createTagsLinkedGetter(name, format);
+  if (linkedTagsGetter) return linkedTagsGetter;
+
+  return SIMPLE_GETTERS[name] ?? (() => "");
+}

package/src/parser/rules/block/module/listpages/template/getters/parameterized.ts

@@ -0,0 +1,60 @@
+import { formatDate, formatTagsLinked, splitContentSections } from "../format";
+import type { VariableGetter } from "./types";
+
+export function createBraceParamGetter(name: string, param: string): VariableGetter | null {
+  switch (name) {
+    case "content": {
+      const idx = Number(param) - 1;
+      return (ctx) => {
+        if (!ctx.page.content) return "";
+        const sections = splitContentSections(ctx.page.content);
+        return sections[idx] ?? "";
+      };
+    }
+    case "form_data":
+      return (ctx) => ctx.page.formData?.[param] ?? "";
+    case "form_raw":
+      return (ctx) => ctx.page.formRaw?.[param] ?? "";
+    case "form_label":
+      return (ctx) => ctx.page.formLabel?.[param] ?? "";
+    case "form_hint":
+      return (ctx) => ctx.page.formHint?.[param] ?? "";
+    default:
+      return null;
+  }
+}
+
+export function createParenParamGetter(name: string, param: string): VariableGetter | null {
+  if (name !== "preview") return null;
+
+  const len = Number(param);
+  return (ctx) => (ctx.page.content ?? "").slice(0, len);
+}
+
+export function createFormattedGetter(name: string, format: string): VariableGetter | null {
+  switch (name) {
+    case "created_at":
+      return (ctx) => formatDate(ctx.page.createdAt, format);
+    case "updated_at":
+      return (ctx) => formatDate(ctx.page.updatedAt, format);
+    case "commented_at":
+      return (ctx) => (ctx.page.commentedAt ? formatDate(ctx.page.commentedAt, format) : "");
+    default:
+      return null;
+  }
+}
+
+export function createTagsLinkedGetter(
+  name: string,
+  format: string | undefined,
+): VariableGetter | null {
+  if (name === "tags_linked") {
+    const prefix = format ?? "/system:page-tags/tag/";
+    return (ctx) => formatTagsLinked(ctx.page.tags, prefix);
+  }
+  if (name === "_tags_linked") {
+    const prefix = format ?? "/system:page-tags/tag/";
+    return (ctx) => formatTagsLinked(ctx.page.hiddenTags, prefix);
+  }
+  return null;
+}

package/src/parser/rules/block/module/listpages/template/getters/simple.ts

@@ -0,0 +1,65 @@
+import { formatDate, formatUserLinked, getFirstParagraph, getSummary } from "../format";
+import type { VariableGetter } from "./types";
+
+/** Default character count for `%%preview%%` when no length is specified (Wikidot default). */
+const DEFAULT_PREVIEW_LENGTH = 200;
+
+export const SIMPLE_GETTERS: Record<string, VariableGetter> = {
+  created_at: (ctx) => formatDate(ctx.page.createdAt),
+  created_by: (ctx) => ctx.page.createdBy?.name ?? "Anonymous",
+  created_by_unix: (ctx) => ctx.page.createdBy?.unixName ?? "",
+  created_by_id: (ctx) => String(ctx.page.createdBy?.id ?? 0),
+  created_by_linked: (ctx) => formatUserLinked(ctx.page.createdBy),
+
+  updated_at: (ctx) => formatDate(ctx.page.updatedAt),
+  updated_by: (ctx) => ctx.page.updatedBy?.name ?? "Anonymous",
+  updated_by_unix: (ctx) => ctx.page.updatedBy?.unixName ?? "",
+  updated_by_id: (ctx) => String(ctx.page.updatedBy?.id ?? 0),
+  updated_by_linked: (ctx) => formatUserLinked(ctx.page.updatedBy),
+
+  commented_at: (ctx) => (ctx.page.commentedAt ? formatDate(ctx.page.commentedAt) : ""),
+  commented_by: (ctx) => ctx.page.commentedBy?.name ?? "",
+  commented_by_unix: (ctx) => ctx.page.commentedBy?.unixName ?? "",
+  commented_by_id: (ctx) => String(ctx.page.commentedBy?.id ?? 0),
+  commented_by_linked: (ctx) => formatUserLinked(ctx.page.commentedBy),
+
+  name: (ctx) => ctx.page.name,
+  category: (ctx) => ctx.page.category,
+  fullname: (ctx) => ctx.page.fullname,
+  title: (ctx) => ctx.page.title,
+  title_linked: (ctx) => `[[[${ctx.page.fullname} | ${ctx.page.title}]]]`,
+  link: (ctx) => `https://${ctx.site.domain}/${ctx.page.fullname}`,
+
+  parent_name: (ctx) => ctx.page.parentName ?? "",
+  parent_category: (ctx) => ctx.page.parentCategory ?? "",
+  parent_fullname: (ctx) => ctx.page.parentFullname ?? "",
+  parent_title: (ctx) => ctx.page.parentTitle ?? "",
+  parent_title_linked: (ctx) =>
+    ctx.page.parentFullname ? `[[[${ctx.page.parentFullname} | ${ctx.page.parentTitle}]]]` : "",
+
+  content: (ctx) => ctx.page.content ?? "",
+  preview: (ctx) => (ctx.page.content ?? "").slice(0, DEFAULT_PREVIEW_LENGTH),
+  summary: (ctx) => getSummary(ctx.page),
+  first_paragraph: (ctx) => getFirstParagraph(ctx.page.content),
+
+  tags: (ctx) => ctx.page.tags.join(" "),
+  _tags: (ctx) => ctx.page.hiddenTags.join(" "),
+
+  children: (ctx) => String(ctx.page.children),
+  comments: (ctx) => String(ctx.page.comments),
+  size: (ctx) => String(ctx.page.size),
+  rating: (ctx) => String(ctx.page.rating),
+  rating_votes: (ctx) => String(ctx.page.ratingVotes),
+  rating_percent: (ctx) => String(ctx.page.ratingPercent ?? 0),
+  revisions: (ctx) => String(ctx.page.revisions),
+
+  index: (ctx) => String(ctx.index),
+  total: (ctx) => String(ctx.total),
+  limit: (ctx) => (ctx.limit !== undefined ? String(ctx.limit) : ""),
+  total_or_limit: (ctx) =>
+    String(ctx.limit !== undefined ? Math.min(ctx.total, ctx.limit) : ctx.total),
+
+  site_title: (ctx) => ctx.site.title,
+  site_name: (ctx) => ctx.site.name,
+  site_domain: (ctx) => ctx.site.domain,
+};

package/src/parser/rules/block/module/listpages/template/getters/types.ts

@@ -0,0 +1,3 @@
+import type { VariableContext } from "../../types";
+
+export type VariableGetter = (ctx: VariableContext) => string;

package/src/parser/rules/block/module/listpages/template/syntax.ts

@@ -0,0 +1,97 @@
+export interface TemplateVariableMatch {
+  raw: string;
+  index: number;
+  name: string;
+  braceParam?: string;
+  parenParam?: string;
+  format?: string;
+}
+
+/**
+ * Scans ListPages template variables without a backtracking regex.
+ *
+ * Supported syntax:
+ * - `%%name%%`
+ * - `%%name{param}%%`
+ * - `%%name(param)%%`
+ * - `%%name|format%%`
+ */
+export function scanTemplateVariables(template: string): TemplateVariableMatch[] {
+  const matches: TemplateVariableMatch[] = [];
+  let searchFrom = 0;
+
+  while (searchFrom < template.length) {
+    const start = template.indexOf("%%", searchFrom);
+    if (start === -1) break;
+
+    const contentStart = start + 2;
+    const end = template.indexOf("%%", contentStart);
+    if (end === -1) break;
+
+    const parsed = parseTemplateVariableContent(template.slice(contentStart, end));
+    if (parsed !== null) {
+      matches.push({
+        raw: template.slice(start, end + 2),
+        index: start,
+        ...parsed,
+      });
+    }
+
+    searchFrom = end + 2;
+  }
+
+  return matches;
+}
+
+function parseTemplateVariableContent(
+  content: string,
+): Omit<TemplateVariableMatch, "raw" | "index"> | null {
+  let cursor = 0;
+  while (cursor < content.length && isVariableNameChar(content[cursor]!)) {
+    cursor++;
+  }
+  if (cursor === 0) return null;
+
+  const name = content.slice(0, cursor);
+  let braceParam: string | undefined;
+  let parenParam: string | undefined;
+  let format: string | undefined;
+
+  if (content[cursor] === "{") {
+    const close = content.indexOf("}", cursor + 1);
+    if (close === -1) return null;
+    braceParam = content.slice(cursor + 1, close);
+    cursor = close + 1;
+  }
+
+  if (content[cursor] === "(") {
+    const close = content.indexOf(")", cursor + 1);
+    if (close === -1) return null;
+    const value = content.slice(cursor + 1, close);
+    if (!isDigits(value)) return null;
+    parenParam = value;
+    cursor = close + 1;
+  }
+
+  if (content[cursor] === "|") {
+    format = content.slice(cursor + 1);
+    cursor = content.length;
+  }
+
+  if (cursor !== content.length) return null;
+  return { name, braceParam, parenParam, format };
+}
+
+function isVariableNameChar(char: string): boolean {
+  const code = char.charCodeAt(0);
+  return (code >= 0x41 && code <= 0x5a) || (code >= 0x61 && code <= 0x7a) || char === "_";
+}
+
+function isDigits(value: string): boolean {
+  if (value.length === 0) return false;
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code < 0x30 || code > 0x39) return false;
+  }
+  return true;
+}

package/src/parser/rules/block/module/listpages/types/data-fetcher.ts

@@ -0,0 +1,15 @@
+import type { ListPagesDataRequirement } from "./data-requirements";
+import type { ListPagesExternalData } from "./external-data";
+import type { NormalizedListPagesQuery } from "./normalized-query";
+
+/**
+ * Callback to fetch data for a ListPages module.
+ *
+ * Called by resolveModules for each ListPages module in the AST. Receives a
+ * normalized query with all `@URL` parameters resolved. Return null/undefined
+ * to skip the module.
+ */
+export type ListPagesDataFetcher = (
+  query: NormalizedListPagesQuery,
+  requirement: ListPagesDataRequirement,
+) => ListPagesExternalData | null | undefined | Promise<ListPagesExternalData | null | undefined>;

package/src/parser/rules/block/module/listpages/types/data-requirements.ts

@@ -0,0 +1,52 @@
+import type { ListUsersDataRequirement } from "../../listusers/types";
+import type { ListPagesQuery } from "./query";
+import type { ListPagesVariable } from "./variables";
+
+/**
+ * Data requirement for a single ListPages module.
+ */
+export interface ListPagesDataRequirement {
+  /** Unique identifier for this module instance */
+  id: number;
+
+  /** Query parameters */
+  query: ListPagesQuery;
+
+  /** Variables used in the template */
+  neededVariables: ListPagesVariable[];
+
+  /** Indices needed for content{n} */
+  contentSectionIndices?: number[];
+
+  /** Lengths needed for preview(n) */
+  previewLengths?: number[];
+
+  /** Field names needed for form_data{field} etc. */
+  formFields?: string[];
+
+  /** Prefix for tags_linked|prefix */
+  tagsLinkPrefix?: string;
+
+  /** Prefix for _tags_linked|prefix */
+  hiddenTagsLinkPrefix?: string;
+
+  /**
+   * URL attribute prefix for multiple ListPages modules.
+   * When set, URL parameters are prefixed, e.g. "page2" -> "/page2_limit/1".
+   */
+  urlAttrPrefix?: string;
+
+  /**
+   * Raw attribute values before URL resolution.
+   * Contains original string values that may include "@URL" or "@URL|default".
+   */
+  rawAttributes: Record<string, string>;
+}
+
+/**
+ * All data requirements from parsing.
+ */
+export interface DataRequirements {
+  listPages: ListPagesDataRequirement[];
+  listUsers: ListUsersDataRequirement[];
+}