@wdprlib/parser 3.1.2 → 3.2.0

package/src/parser/rules/block/module/listusers/compiler.ts

@@ -0,0 +1,77 @@
+/**
+ *
+ * Template compiler for the ListUsers module.
+ *
+ * Compiles ListUsers template strings (e.g., `"%%title%% (%%name%%)"`) into
+ * executable functions for efficient rendering. The compilation approach is
+ * identical to the ListPages compiler: the template is split into static
+ * string segments and dynamic getter functions.
+ *
+ * Only three variables are supported: `%%number%%`, `%%title%%`, and `%%name%%`.
+ *
+ * @module
+ */
+
+import type { ListUsersCompiledTemplate, ListUsersVariableContext } from "./types";
+
+/** Regex for matching `%%variable%%` patterns in the template. */
+const VARIABLE_REGEX = /%%([a-z_]+)%%/gi;
+
+/**
+ * Compile a ListUsers template string into an executable function.
+ *
+ * The template is split into alternating static strings and dynamic getter
+ * functions. The returned function concatenates these parts for each call.
+ *
+ * @param template - The template string containing `%%variable%%` placeholders
+ * @returns A compiled function that accepts a `ListUsersVariableContext` and returns rendered text
+ */
+export function compileListUsersTemplate(template: string): ListUsersCompiledTemplate {
+  const parts: (string | ((ctx: ListUsersVariableContext) => string))[] = [];
+  let lastIndex = 0;
+
+  for (const match of template.matchAll(VARIABLE_REGEX)) {
+    if (match.index !== undefined && match.index > lastIndex) {
+      parts.push(template.slice(lastIndex, match.index));
+    }
+
+    const [, varName] = match;
+    if (!varName) continue;
+    const getter = createVariableGetter(varName.toLowerCase());
+    parts.push(getter);
+
+    lastIndex = match.index !== undefined ? match.index + match[0].length : lastIndex;
+  }
+
+  if (lastIndex < template.length) {
+    parts.push(template.slice(lastIndex));
+  }
+
+  return (ctx: ListUsersVariableContext): string => {
+    let result = "";
+    for (const part of parts) {
+      result += typeof part === "string" ? part : part(ctx);
+    }
+    return result;
+  };
+}
+
+/**
+ * Create a getter function for a specific ListUsers variable.
+ *
+ * @param name - Lowercase variable name
+ * @returns A function that extracts the variable's value from a ListUsersVariableContext.
+ *          Unknown names return a function that always returns an empty string.
+ */
+function createVariableGetter(name: string): (ctx: ListUsersVariableContext) => string {
+  switch (name) {
+    case "number":
+      return (ctx) => String(ctx.user.number);
+    case "title":
+      return (ctx) => ctx.user.title;
+    case "name":
+      return (ctx) => ctx.user.name;
+    default:
+      return () => "";
+  }
+}

package/src/parser/rules/block/module/listusers/extract.ts

@@ -0,0 +1,45 @@
+/**
+ *
+ * Data requirement extraction for the ListUsers module.
+ *
+ * Analyzes a ListUsers template string to determine which variables
+ * (`%%number%%`, `%%title%%`, `%%name%%`) are referenced. This tells the
+ * external application which user data fields need to be provided.
+ *
+ * @module
+ */
+
+import type { ListUsersVariable } from "./types";
+import { compileListUsersTemplate } from "./compiler";
+
+/** Regex for matching `%%variable%%` patterns in ListUsers templates. */
+const VARIABLE_REGEX = /%%([a-z_]+)%%/gi;
+
+/** The complete list of recognized ListUsers template variables. */
+const KNOWN_VARIABLES: ListUsersVariable[] = ["number", "title", "name"];
+
+/**
+ * Extract the set of template variables referenced in a ListUsers template string.
+ *
+ * Scans for `%%variable%%` patterns and returns only those that match known
+ * ListUsers variables. Unknown variables are silently ignored.
+ *
+ * @param template - The template string from the module body
+ * @returns Deduplicated array of referenced variable names
+ */
+export function extractListUsersVariables(template: string): ListUsersVariable[] {
+  const variables = new Set<ListUsersVariable>();
+
+  for (const match of template.matchAll(VARIABLE_REGEX)) {
+    const [, varName] = match;
+    if (!varName) continue;
+    const normalized = varName.toLowerCase();
+    if (KNOWN_VARIABLES.includes(normalized as ListUsersVariable)) {
+      variables.add(normalized as ListUsersVariable);
+    }
+  }
+
+  return Array.from(variables);
+}
+
+export { compileListUsersTemplate };

package/src/parser/rules/block/module/listusers/index.ts

@@ -0,0 +1,36 @@
+/**
+ *
+ * ListUsers module for Wikidot's `[[module ListUsers users="."]]` block.
+ *
+ * Displays information about site members using a template with
+ * `%%number%%`, `%%title%%`, and `%%name%%` variables. Currently only
+ * `users="."` (the logged-in user) is supported.
+ *
+ * Follows the same three-phase lifecycle as ListPages: parse, extract, resolve.
+ *
+ * @module
+ */
+
+// Parser
+export { listUsersModuleRule } from "./parser";
+
+// Types
+export type {
+  ListUsersVariable,
+  ListUsersUserData,
+  ListUsersDataRequirement,
+  ListUsersExternalData,
+  ListUsersDataFetcher,
+  ListUsersVariableContext,
+  ListUsersCompiledTemplate,
+} from "./types";
+
+// Extraction
+export { extractListUsersVariables } from "./extract";
+
+// Compiler
+export { compileListUsersTemplate } from "./compiler";
+
+// Resolution
+export type { ListUsersModuleData } from "./resolve";
+export { isListUsersModule, resolveListUsers } from "./resolve";

package/src/parser/rules/block/module/listusers/parser.ts

@@ -0,0 +1,54 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module ListUsers ...]]` block.
+ *
+ * Parses the module's attributes into a `list-users` Module AST node.
+ * Currently only `users="."` (logged-in user) is supported; other values
+ * produce an error block element.
+ *
+ * @module
+ */
+
+import type { Element, Module } from "@wdprlib/ast";
+import type { ModuleRule } from "../types";
+
+/** Error message displayed when an unsupported `users` value is provided. */
+const ERROR_MESSAGE = 'Currently only users="." is implemented.';
+
+/**
+ * Module rule for `[[module ListUsers ...]]`.
+ *
+ * ListUsers displays information about site members. The `users` attribute
+ * controls which users are listed. Currently only `"."` (the logged-in user)
+ * is implemented. Any other value produces an error block.
+ *
+ * The template body uses `%%number%%`, `%%title%%`, and `%%name%%` variables.
+ */
+export const listUsersModuleRule: ModuleRule = {
+  name: "module-listusers",
+  acceptsNames: ["listusers"],
+  hasBody: true,
+
+  parse(_ctx, _pos, args, body): Module | Element {
+    const { users, ...rest } = args;
+    const usersValue = users ?? ".";
+
+    if (usersValue !== ".") {
+      return {
+        element: "container",
+        data: {
+          type: "div",
+          attributes: { class: "error-block" },
+          elements: [{ element: "text", data: ERROR_MESSAGE }],
+        },
+      };
+    }
+
+    return {
+      module: "list-users",
+      users: usersValue,
+      body,
+      attributes: rest,
+    };
+  },
+};

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

@@ -0,0 +1,58 @@
+/**
+ *
+ * ListUsers module resolution.
+ *
+ * After the application has fetched user data based on the extracted requirements,
+ * this module substitutes that data into the pre-compiled template and re-parses
+ * the resulting wikitext to produce final AST elements.
+ *
+ * @module
+ */
+
+import type { Element, Module } from "@wdprlib/ast";
+import type {
+  ListUsersExternalData,
+  ListUsersCompiledTemplate,
+  ListUsersVariableContext,
+} from "./types";
+import type { ParseFunction } from "../types";
+
+/**
+ * Narrowed type for the list-users variant of the Module discriminated union.
+ */
+export type ListUsersModuleData = Extract<Module, { module: "list-users" }>;
+
+/**
+ * Type guard to check if a Module is a list-users module.
+ *
+ * @param module - A Module discriminated union value
+ * @returns true if the module is a list-users module
+ */
+export function isListUsersModule(module: Module): module is ListUsersModuleData {
+  return module.module === "list-users";
+}
+
+/**
+ * Resolve a single ListUsers module by substituting fetched user data into
+ * the pre-compiled template and re-parsing the result as wikitext.
+ *
+ * Currently ListUsers only renders the logged-in user (no iteration over
+ * multiple users), so the template is executed exactly once.
+ *
+ * @param _module - The list-users module data from the AST (unused, reserved for future use)
+ * @param data - External user data fetched by the application
+ * @param compiledTemplate - Pre-compiled template function from the extraction phase
+ * @param parse - Parser function for re-parsing the substituted template as wikitext
+ * @returns Array of AST elements produced by parsing the rendered template
+ */
+export function resolveListUsers(
+  _module: ListUsersModuleData,
+  data: ListUsersExternalData,
+  compiledTemplate: ListUsersCompiledTemplate,
+  parse: ParseFunction,
+): Element[] {
+  const ctx: ListUsersVariableContext = { user: data.user };
+  const substituted = compiledTemplate(ctx);
+  const itemAst = parse(substituted);
+  return itemAst.elements;
+}

package/src/parser/rules/block/module/listusers/types.ts

@@ -0,0 +1,93 @@
+/**
+ *
+ * Type definitions for the ListUsers module.
+ *
+ * The `[[module ListUsers users="."]]` block displays information about site
+ * members. Currently, only `users="."` (the logged-in user) is supported.
+ * The template body can reference three variables: `%%number%%`, `%%title%%`,
+ * and `%%name%%`.
+ *
+ * @module
+ */
+
+/**
+ * Supported template variables for ListUsers.
+ *
+ * - `number` - The user's numeric ID
+ * - `title` - The user's display title/nickname
+ * - `name` - The user's account name
+ */
+export type ListUsersVariable = "number" | "title" | "name";
+
+/**
+ * User data that must be provided by the external data source.
+ *
+ * Each field corresponds to a template variable of the same name.
+ */
+export interface ListUsersUserData {
+  /** The user's numeric ID, rendered by `%%number%%` */
+  number: number;
+  /** The user's display title, rendered by `%%title%%` */
+  title: string;
+  /** The user's account name, rendered by `%%name%%` */
+  name: string;
+}
+
+/**
+ * Data requirement for a single ListUsers module instance.
+ *
+ * Produced by the extraction phase and consumed by the application to
+ * determine what data to fetch.
+ */
+export interface ListUsersDataRequirement {
+  /** Unique identifier for this module instance (sequential, 0-based) */
+  id: number;
+  /** The `users` attribute value (currently only `"."` is supported) */
+  users: string;
+  /** Template variables that need data from the external source */
+  neededVariables: ListUsersVariable[];
+}
+
+/**
+ * External data provided by the application for a single ListUsers module.
+ *
+ * Currently ListUsers only returns information about the logged-in user.
+ * Return null/undefined from the fetcher to indicate no user is logged in.
+ */
+export interface ListUsersExternalData {
+  /** Data for the logged-in user */
+  user: ListUsersUserData;
+}
+
+/**
+ * Callback to fetch user data for a ListUsers module.
+ *
+ * Called during the resolution phase for each ListUsers module in the AST.
+ * Return null/undefined to skip the module (outputs nothing, e.g., when
+ * no user is logged in).
+ *
+ * @param requirement - The data requirement describing what data is needed
+ * @returns User data, null/undefined to skip, or a Promise of the same
+ */
+export type ListUsersDataFetcher = (
+  requirement: ListUsersDataRequirement,
+) => ListUsersExternalData | null | undefined | Promise<ListUsersExternalData | null | undefined>;
+
+/**
+ * Context passed to a compiled ListUsers template function during rendering.
+ */
+export interface ListUsersVariableContext {
+  /** The user whose data is being rendered */
+  user: ListUsersUserData;
+}
+
+/**
+ * A compiled ListUsers template function.
+ *
+ * Accepts a variable context and returns the rendered wikitext string
+ * with all `%%variable%%` placeholders substituted.
+ *
+ * @param ctx - The variable context containing user data
+ * @returns Rendered wikitext string
+ */
+export type ListUsersCompiledTemplate = (ctx: ListUsersVariableContext) => string;

package/src/parser/rules/block/module/mapping.ts

@@ -0,0 +1,61 @@
+/**
+ *
+ * Module rule registry and name-based lookup.
+ *
+ * This module maintains the complete list of supported Wikidot module rules
+ * and provides a case-insensitive lookup by module name. When the parser
+ * encounters `[[module XYZ ...]]`, it uses `getModuleRuleByName("xyz")` to
+ * find the corresponding rule handler.
+ *
+ * @module
+ */
+
+import type { ModuleRule } from "./types";
+import { rateModuleRule } from "./rate/index";
+import { cssModuleRule } from "./css/index";
+import { backlinksModuleRule } from "./backlinks/index";
+import { categoriesModuleRule } from "./categories/index";
+import { joinModuleRule } from "./join/index";
+import { pageTreeModuleRule } from "./page-tree/index";
+import { listPagesModuleRule } from "./listpages/parser";
+import { listUsersModuleRule } from "./listusers/parser";
+
+/**
+ * Complete list of all registered module rules.
+ *
+ * Each rule handles one or more Wikidot module names. The order does not
+ * affect lookup behavior since the lookup map is built from `acceptsNames`.
+ */
+export const MODULE_RULES: ModuleRule[] = [
+  rateModuleRule,
+  cssModuleRule,
+  backlinksModuleRule,
+  categoriesModuleRule,
+  joinModuleRule,
+  pageTreeModuleRule,
+  listPagesModuleRule,
+  listUsersModuleRule,
+];
+
+/**
+ * Internal lookup map from lowercase module name to its rule handler.
+ * Built once at module load time from the `acceptsNames` arrays.
+ */
+const moduleRuleMap: Map<string, ModuleRule> = new Map();
+
+// Build the map
+for (const rule of MODULE_RULES) {
+  for (const name of rule.acceptsNames) {
+    moduleRuleMap.set(name.toLowerCase(), rule);
+  }
+}
+
+/**
+ * Look up a module rule by its Wikidot module name (case-insensitive).
+ *
+ * @param name - The module name from `[[module Name ...]]` syntax
+ * @returns The matching module rule, or undefined if no rule handles this name
+ */
+export function getModuleRuleByName(name: string): ModuleRule | undefined {
+  return moduleRuleMap.get(name.toLowerCase());
+}

package/src/parser/rules/block/module/page-tree/index.ts

@@ -0,0 +1,38 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module PageTree]]` block.
+ *
+ * Renders a hierarchical tree of pages based on parent-child relationships.
+ * Accepts optional `root`, `show-root`, and `depth` attributes.
+ *
+ * @module
+ */
+
+import type { ModuleRule } from "../types";
+import { parseInt32 } from "../utils";
+import type { PageTreeModuleData } from "./types";
+
+/**
+ * Module rule for `[[module PageTree]]`.
+ *
+ * Parses `root`, `show-root`, and `depth` attributes. The `show-root`
+ * attribute intentionally uses strict comparison with `"true"` (not
+ * `parseBool`) because Wikidot only accepts `"true"` for this attribute,
+ * not `"yes"`.
+ */
+export const pageTreeModuleRule: ModuleRule = {
+  name: "module-page-tree",
+  acceptsNames: ["pagetree"],
+  hasBody: false,
+
+  parse(_ctx, _pos, args): PageTreeModuleData {
+    // Note: Wikidot only accepts "true" for showRoot, not "yes"
+    const showRootValue = args["show-root"] ?? args.showroot;
+    return {
+      module: "page-tree",
+      root: args.root ?? null,
+      "show-root": showRootValue === "true",
+      depth: parseInt32(args.depth) ?? null,
+    };
+  },
+};

package/src/parser/rules/block/module/page-tree/types.ts

@@ -0,0 +1,29 @@
+/**
+ *
+ * Type definitions for the PageTree module.
+ *
+ * The `[[module PageTree]]` block renders a hierarchical tree view of pages
+ * based on parent-child relationships. It starts from a specified root page
+ * (or the current page) and displays descendants up to a configurable depth.
+ *
+ * @module
+ */
+
+/**
+ * AST data for a `[[module PageTree]]` element.
+ *
+ * The rendering application should build a tree of pages starting from the
+ * root and display them as a nested list.
+ */
+export interface PageTreeModuleData {
+  module: "page-tree";
+  /** Root page to start the tree from, or null for the current page */
+  root: string | null;
+  /**
+   * Whether to display the root page itself in the tree.
+   * Note: Wikidot only accepts the string `"true"` for this attribute, not `"yes"`.
+   */
+  "show-root": boolean;
+  /** Maximum depth of the tree, or null for unlimited depth */
+  depth: number | null;
+}

package/src/parser/rules/block/module/rate/index.ts

@@ -0,0 +1,28 @@
+/**
+ *
+ * Parser rule for the Wikidot `[[module Rate]]` block.
+ *
+ * Renders a page rating widget. This is a simple module with no attributes
+ * and no body content.
+ *
+ * @module
+ */
+
+import type { ModuleRule } from "../types";
+import type { RateModuleData } from "./types";
+
+/**
+ * Module rule for `[[module Rate]]`.
+ *
+ * Simply produces a `{ module: "rate" }` AST node. The rendering application
+ * is responsible for displaying upvote/downvote buttons and the current rating.
+ */
+export const rateModuleRule: ModuleRule = {
+  name: "module-rate",
+  acceptsNames: ["rate"],
+  hasBody: false,
+
+  parse(): RateModuleData {
+    return { module: "rate" };
+  },
+};

package/src/parser/rules/block/module/rate/types.ts

@@ -0,0 +1,19 @@
+/**
+ *
+ * Type definitions for the Rate module.
+ *
+ * The `[[module Rate]]` block renders a page rating widget (upvote/downvote buttons).
+ * It takes no attributes and has no body.
+ *
+ * @module
+ */
+
+/**
+ * AST data for a `[[module Rate]]` element.
+ *
+ * This module has no configurable properties. The rendering application
+ * is responsible for displaying the appropriate rating widget.
+ */
+export interface RateModuleData {
+  module: "rate";
+}