@wdprlib/parser 3.1.2 → 4.0.0

package/src/parser/rules/inline/formatting/container.ts

@@ -0,0 +1,50 @@
+import type { Element, StringContainerType } from "@wdprlib/ast";
+import type { TokenType } from "../../../../lexer";
+import type { ParseContext, RuleResult } from "../../types";
+import { currentToken, hasClosingMarkerBeforeNewline } from "../../types";
+import { parseInlineUntil } from "../utils";
+
+export function createInlineContainer(type: StringContainerType, elements: Element[]): Element {
+  return {
+    element: "container",
+    data: {
+      type,
+      attributes: {},
+      elements,
+    },
+  };
+}
+
+export function parseSameLineDelimitedContainer(
+  ctx: ParseContext,
+  closeToken: TokenType,
+  type: StringContainerType,
+  options: { discardEmpty?: boolean } = {},
+): RuleResult<Element> {
+  const startToken = currentToken(ctx);
+
+  if (!hasClosingMarkerBeforeNewline({ ...ctx, pos: ctx.pos + 1 }, closeToken)) {
+    return {
+      success: true,
+      elements: [{ element: "text", data: startToken.value }],
+      consumed: 1,
+    };
+  }
+
+  const result = parseInlineUntil({ ...ctx, pos: ctx.pos + 1 }, closeToken);
+  const consumed = 1 + result.consumed + 1;
+
+  if (options.discardEmpty === true && result.elements.length === 0) {
+    return {
+      success: true,
+      elements: [],
+      consumed,
+    };
+  }
+
+  return {
+    success: true,
+    elements: [createInlineContainer(type, result.elements)],
+    consumed,
+  };
+}

package/src/parser/rules/inline/guillemet/index.ts

@@ -0,0 +1,56 @@
+/**
+ *
+ * Parses Wikidot's guillemet (angle quotation mark) syntax.
+ *
+ * Converts ASCII double-angle-bracket sequences into their Unicode
+ * typographic equivalents:
+ * - `<<` becomes `\u00AB` (LEFT-POINTING DOUBLE ANGLE QUOTATION MARK)
+ * - `>>` becomes `\u00BB` (RIGHT-POINTING DOUBLE ANGLE QUOTATION MARK)
+ *
+ * These typographic characters are commonly used in European languages
+ * (particularly French and Russian) as quotation marks. Wikidot provides
+ * this shorthand so authors do not need to type the Unicode characters
+ * directly.
+ *
+ * Produces a `"text"` AST element containing the Unicode character.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { guillemetText } from "./text";
+
+/**
+ * Inline rule for converting `<<` and `>>` to typographic guillemets.
+ *
+ * Triggered by `LEFT_DOUBLE_ANGLE` or `RIGHT_DOUBLE_ANGLE` tokens.
+ * This is a simple one-to-one token replacement with no content
+ * parsing or nesting.
+ */
+export const guillemetRule: InlineRule = {
+  name: "guillemet",
+  startTokens: ["LEFT_DOUBLE_ANGLE", "RIGHT_DOUBLE_ANGLE"],
+
+  /**
+   * Converts a double-angle-bracket token to its Unicode guillemet equivalent.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"text"` element containing the
+   *          Unicode guillemet character, or `{ success: false }` if the
+   *          token is neither `<<` nor `>>`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const token = ctx.tokens[ctx.pos];
+    const text = guillemetText(token?.type);
+
+    if (text) {
+      return {
+        success: true,
+        elements: [{ element: "text", data: text }],
+        consumed: 1,
+      };
+    }
+
+    return { success: false };
+  },
+};

package/src/parser/rules/inline/guillemet/text.ts

@@ -0,0 +1,11 @@
+import type { TokenType } from "../../../../lexer";
+
+export function guillemetText(tokenType: TokenType | undefined): string | null {
+  if (tokenType === "LEFT_DOUBLE_ANGLE") {
+    return "\u00AB";
+  }
+  if (tokenType === "RIGHT_DOUBLE_ANGLE") {
+    return "\u00BB";
+  }
+  return null;
+}

package/src/parser/rules/inline/html/gate.ts

@@ -0,0 +1,64 @@
+import type { ParseContext } from "../../types";
+import { parseBlockName } from "../../common";
+import { lookaheadHasHtmlClose } from "../../block/html";
+
+export interface DisabledHtmlBody {
+  consumed: number;
+  foundClose: boolean;
+}
+
+export function consumeDisabledHtmlBody(ctx: ParseContext, startPos: number): DisabledHtmlBody {
+  const hasCloseAhead = lookaheadHasHtmlClose(ctx, startPos);
+  let pos = startPos;
+  let consumed = 0;
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "EOF") {
+      break;
+    }
+
+    if (!hasCloseAhead && token.type === "NEWLINE" && ctx.tokens[pos + 1]?.type === "NEWLINE") {
+      break;
+    }
+
+    const closeResult = tryConsumeHtmlClose(ctx, pos);
+    if (closeResult) {
+      return {
+        consumed: consumed + closeResult.consumed,
+        foundClose: true,
+      };
+    }
+
+    pos++;
+    consumed++;
+  }
+
+  return { consumed, foundClose: false };
+}
+
+function tryConsumeHtmlClose(ctx: ParseContext, pos: number): { consumed: number } | null {
+  if (ctx.tokens[pos]?.type !== "BLOCK_END_OPEN") {
+    return null;
+  }
+
+  const closeNameResult = parseBlockName(ctx, pos + 1);
+  if (closeNameResult?.name.toLowerCase() !== "html") {
+    return null;
+  }
+
+  let checkPos = pos + 1 + closeNameResult.consumed;
+  while (ctx.tokens[checkPos]?.type === "WHITESPACE") {
+    checkPos++;
+  }
+  if (ctx.tokens[checkPos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  let consumed = checkPos - pos + 1;
+  if (ctx.tokens[checkPos + 1]?.type === "NEWLINE") {
+    consumed++;
+  }
+
+  return { consumed };
+}

package/src/parser/rules/inline/html/index.ts

@@ -0,0 +1,81 @@
+/**
+ *
+ * Inline-position gate for `[[html]]...[[/html]]` when the parser is
+ * configured with `allowHtmlBlocks: false`.
+ *
+ * The block-level {@link htmlBlockRule} already removes `[[html]]` blocks
+ * that sit at the start of a line, but the block dispatcher never
+ * reaches a `[[html]]` that appears mid-paragraph. Without this inline
+ * rule, the body of a disabled-but-inline-positioned `[[html]]` would
+ * end up parsed as paragraph text and leak into the output as escaped
+ * HTML.
+ *
+ * When enabled (`allowHtmlBlocks !== false`), the rule does nothing
+ * (returns `success: false`) so the existing paragraph behaviour is
+ * preserved: a stray inline `[[html]]` renders as text. The block-level
+ * rule handles the proper case where `[[html]]` is on its own line.
+ *
+ * When disabled (`allowHtmlBlocks === false`):
+ * - A well-formed `[[html ...]]...[[/html]]` is fully consumed and
+ *   produces no AST element, emitting an `html-block-disabled` info
+ *   diagnostic.
+ * - An unclosed `[[html ...]]` is consumed to the end of the token
+ *   stream so the body cannot leak as inline text, emitting both
+ *   `unclosed-block` (warning) and `html-block-disabled` (info).
+ *
+ * @module
+ */
+
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { consumeDisabledHtmlBody } from "./gate";
+import { parseHtmlInlineOpen } from "./open";
+
+/**
+ * Inline rule that gates `[[html]]` when the setting disallows it.
+ */
+export const htmlInlineRule: InlineRule = {
+  name: "html",
+  startTokens: ["BLOCK_OPEN"],
+
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseHtmlInlineOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    // Enabled: leave inline `[[html]]` alone — it falls through to text
+    // rendering, matching the historical behaviour for stray block-named
+    // openers used inline.
+    if (ctx.settings.allowHtmlBlocks !== false) {
+      return { success: false };
+    }
+
+    const bodyResult = consumeDisabledHtmlBody(ctx, openResult.bodyStart);
+    const consumed = openResult.consumed + bodyResult.consumed;
+
+    if (!bodyResult.foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/html]] for [[html]]",
+        position: openToken.position,
+      });
+    }
+
+    ctx.diagnostics.push({
+      severity: "info",
+      code: "html-block-disabled",
+      message: "[[html]] block ignored: disabled by settings",
+      position: openToken.position,
+    });
+
+    return { success: true, elements: [], consumed };
+  },
+};

package/src/parser/rules/inline/html/open.ts

@@ -0,0 +1,37 @@
+import type { ParseContext } from "../../types";
+import { parseAttributesRaw, parseBlockName } from "../../block/utils";
+
+export interface HtmlInlineOpenResult {
+  bodyStart: number;
+  consumed: number;
+}
+
+export function parseHtmlInlineOpen(ctx: ParseContext): HtmlInlineOpenResult | 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.toLowerCase() !== "html") {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const attrResult = parseAttributesRaw(ctx, pos);
+  pos += attrResult.consumed;
+  consumed += attrResult.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  return { bodyStart: pos, consumed };
+}

package/src/parser/rules/inline/image/attributes.ts

@@ -0,0 +1,22 @@
+import type { AttributeMap } from "@wdprlib/ast";
+import type { ParseContext } from "../../types";
+import { parseAttributesRaw } from "../../block/utils";
+import { filterUnsafeAttributes } from "../../common";
+
+export interface ImageAttributes {
+  attributes: AttributeMap;
+  link: string | null;
+  consumed: number;
+}
+
+export function parseImageAttributes(ctx: ParseContext, startPos: number): ImageAttributes {
+  const result = parseAttributesRaw(ctx, startPos, false);
+  const link = result.attrs.link ?? null;
+  const { link: _link, ...htmlAttributes } = result.attrs;
+
+  return {
+    attributes: filterUnsafeAttributes(htmlAttributes),
+    link,
+    consumed: result.consumed,
+  };
+}

package/src/parser/rules/inline/image/body.ts

@@ -0,0 +1,36 @@
+import type { ParseContext } from "../../types";
+
+export interface ImageSourceText {
+  sourceText: string;
+  consumed: number;
+}
+
+export function parseImageSourceText(ctx: ParseContext, startPos: number): ImageSourceText {
+  let pos = startPos;
+  let consumed = 0;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  let sourceText = "";
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (
+      !token ||
+      token.type === "WHITESPACE" ||
+      token.type === "BLOCK_CLOSE" ||
+      token.type === "NEWLINE" ||
+      token.type === "EOF"
+    ) {
+      break;
+    }
+
+    sourceText += token.value;
+    pos++;
+    consumed++;
+  }
+
+  return { sourceText, consumed };
+}

package/src/parser/rules/inline/image/index.ts

@@ -0,0 +1,89 @@
+/**
+ *
+ * Parses the Wikidot image block syntax: `[[image source attributes]]`.
+ *
+ * Images support several alignment/float prefixes that modify how the
+ * image is positioned on the page:
+ * - `[[image src]]` -- default (no alignment)
+ * - `[[=image src]]` -- centered
+ * - `[[<image src]]` -- left-aligned
+ * - `[[>image src]]` -- right-aligned
+ * - `[[f<image src]]` -- float left
+ * - `[[f>image src]]` -- float right
+ * - `[[f=image src]]` -- float center
+ *
+ * Image sources can be:
+ * - Full URLs (`http://...`, `https://...`, `/path`)
+ * - Local file references in three formats:
+ *   - `file.ext` (file on current page, type `file1`)
+ *   - `page/file.ext` (file on another page, type `file2`)
+ *   - `site:page/file.ext` or `site/page/file.ext` (cross-site file, type `file3`)
+ *
+ * Optional attributes follow the source (e.g. `alt`, `title`, `width`,
+ * `height`, `style`, `class`, `link`). The `link` attribute is treated
+ * specially: it wraps the image in a hyperlink rather than being applied
+ * as an HTML attribute. Unsafe attributes are filtered out.
+ *
+ * Produces an `"image"` AST element with source, alignment, link, and
+ * attribute data.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../../types";
+import { currentToken } from "../../types";
+import { parseImageOpen } from "./open";
+import { parseAlignment, parseImageSource } from "./source";
+
+/**
+ * Inline rule for parsing `[[image source attributes]]` and its alignment variants.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. The rule identifies the image
+ * block name (with optional alignment prefix), extracts the image source,
+ * parses remaining attributes, filters unsafe attributes, and extracts the
+ * `link` attribute for special handling.
+ *
+ * Fails if the block name is not an image variant, if no source is provided,
+ * or if `]]` is not found.
+ */
+export const imageRule: InlineRule = {
+  name: "image",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse an image block at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with an `"image"` element, or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    const openResult = parseImageOpen(ctx);
+    if (!openResult) {
+      return { success: false };
+    }
+
+    const source = parseImageSource(openResult.sourceText);
+    const alignment = parseAlignment(openResult.blockName);
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "image",
+          data: {
+            source,
+            link: openResult.link,
+            alignment,
+            attributes: openResult.attributes,
+          },
+        },
+      ],
+      consumed: openResult.consumed,
+    };
+  },
+};

package/src/parser/rules/inline/image/open.ts

@@ -0,0 +1,56 @@
+import type { ParseContext } from "../../types";
+import { parseImageAttributes } from "./attributes";
+import { parseImageSourceText } from "./body";
+import { isImageBlockName, parseImageBlockName } from "./syntax";
+
+export interface ImageOpenResult {
+  blockName: string;
+  sourceText: string;
+  link: string | null;
+  attributes: Record<string, string>;
+  consumed: number;
+}
+
+export function parseImageOpen(ctx: ParseContext): ImageOpenResult | null {
+  if (ctx.tokens[ctx.pos]?.type !== "BLOCK_OPEN") {
+    return null;
+  }
+
+  let pos = ctx.pos + 1;
+  let consumed = 1;
+
+  const nameResult = parseImageBlockName(ctx, pos);
+  if (!nameResult || !isImageBlockName(nameResult.name)) {
+    return null;
+  }
+
+  pos += nameResult.consumed;
+  consumed += nameResult.consumed;
+
+  const sourceText = parseImageSourceText(ctx, pos);
+  pos += sourceText.consumed;
+  consumed += sourceText.consumed;
+
+  const attrs = parseImageAttributes(ctx, pos);
+  pos += attrs.consumed;
+  consumed += attrs.consumed;
+
+  if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+    return null;
+  }
+
+  pos++;
+  consumed++;
+
+  if (!sourceText.sourceText) {
+    return null;
+  }
+
+  return {
+    blockName: nameResult.name,
+    sourceText: sourceText.sourceText,
+    link: attrs.link,
+    attributes: attrs.attributes,
+    consumed,
+  };
+}

package/src/parser/rules/inline/image/source.ts

@@ -0,0 +1,62 @@
+import type { Alignment, FloatAlignment, ImageSource } from "@wdprlib/ast";
+
+export function parseImageSource(src: string): ImageSource {
+  if (src.startsWith("http://") || src.startsWith("https://") || src.startsWith("/")) {
+    return { type: "url", data: src };
+  }
+
+  const colonIdx = src.indexOf(":");
+  const slashIdx = src.indexOf("/");
+
+  if (colonIdx > 0 && slashIdx > colonIdx) {
+    const site = src.substring(0, colonIdx);
+    const rest = src.substring(colonIdx + 1);
+    const lastSlash = rest.lastIndexOf("/");
+    const page = rest.substring(0, lastSlash);
+    const file = rest.substring(lastSlash + 1);
+    return { type: "file3", data: { site, page, file } };
+  }
+
+  const slashes = src.split("/").length - 1;
+  if (slashes >= 2) {
+    const firstSlash = src.indexOf("/");
+    const lastSlash = src.lastIndexOf("/");
+    const site = src.substring(0, firstSlash);
+    const page = src.substring(firstSlash + 1, lastSlash);
+    const file = src.substring(lastSlash + 1);
+    return { type: "file3", data: { site, page, file } };
+  }
+  if (slashIdx > 0) {
+    const page = src.substring(0, slashIdx);
+    const file = src.substring(slashIdx + 1);
+    return { type: "file2", data: { page, file } };
+  }
+
+  return { type: "file1", data: { file: src } };
+}
+
+export function parseAlignment(blockName: string): FloatAlignment | null {
+  let align: Alignment = "left";
+  let float = false;
+
+  if (blockName === "=image") {
+    align = "center";
+  } else if (blockName === "<image") {
+    align = "left";
+  } else if (blockName === ">image") {
+    align = "right";
+  } else if (blockName === "f<image") {
+    align = "left";
+    float = true;
+  } else if (blockName === "f>image") {
+    align = "right";
+    float = true;
+  } else if (blockName === "f=image") {
+    align = "center";
+    float = true;
+  } else if (blockName === "image") {
+    return null;
+  }
+
+  return { align, float };
+}

package/src/parser/rules/inline/image/syntax.ts

@@ -0,0 +1,76 @@
+import type { ParseContext } from "../../types";
+
+const IMAGE_BLOCK_NAMES = new Set([
+  "image",
+  "=image",
+  "<image",
+  ">image",
+  "f<image",
+  "f>image",
+  "f=image",
+]);
+
+export interface ImageBlockName {
+  name: string;
+  consumed: number;
+}
+
+export function parseImageBlockName(ctx: ParseContext, startPos: number): ImageBlockName | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  const prefixResult = parseImagePrefix(ctx, pos);
+  const prefix = prefixResult.prefix;
+  pos += prefixResult.consumed;
+  consumed += prefixResult.consumed;
+
+  const nameToken = ctx.tokens[pos];
+  if (!nameToken || (nameToken.type !== "TEXT" && nameToken.type !== "IDENTIFIER")) {
+    return null;
+  }
+
+  return { name: prefix + nameToken.value.toLowerCase(), consumed: consumed + 1 };
+}
+
+export function isImageBlockName(blockName: string): boolean {
+  return IMAGE_BLOCK_NAMES.has(blockName);
+}
+
+function parseImagePrefix(ctx: ParseContext, pos: number): { prefix: string; consumed: number } {
+  const token = ctx.tokens[pos];
+
+  if (token?.type === "EQUALS") {
+    return { prefix: "=", consumed: 1 };
+  }
+  if (token?.type === "TEXT" && token.value === "<") {
+    return { prefix: "<", consumed: 1 };
+  }
+  if ((token?.type === "TEXT" || token?.type === "BLOCKQUOTE_MARKER") && token.value === ">") {
+    return { prefix: ">", consumed: 1 };
+  }
+  if (token?.type === "IDENTIFIER" && token.value.toLowerCase() === "f") {
+    return parseFloatPrefix(ctx, pos + 1);
+  }
+
+  return { prefix: "", consumed: 0 };
+}
+
+function parseFloatPrefix(ctx: ParseContext, pos: number): { prefix: string; consumed: number } {
+  const token = ctx.tokens[pos];
+  if (token?.type === "TEXT" && token.value === "<") {
+    return { prefix: "f<", consumed: 2 };
+  }
+  if ((token?.type === "TEXT" || token?.type === "BLOCKQUOTE_MARKER") && token.value === ">") {
+    return { prefix: "f>", consumed: 2 };
+  }
+  if (token?.type === "EQUALS") {
+    return { prefix: "f=", consumed: 2 };
+  }
+
+  return { prefix: "", consumed: 0 };
+}