@wdprlib/parser 3.1.2 → 3.2.0

package/src/parser/rules/inline/raw.ts

@@ -0,0 +1,262 @@
+/**
+ *
+ * Parses the Wikidot raw (verbatim) text syntaxes: `@@...@@` and `@<...>@`.
+ *
+ * Raw text bypasses all inline formatting -- the content between the
+ * delimiters is emitted as-is without interpretation of any Wikidot
+ * markup characters.
+ *
+ * Two syntax variants are supported:
+ *
+ * 1. Double-at syntax (`@@...@@`): The more common form. Content between
+ *    the markers is treated as raw text. Several Wikidot quirks apply:
+ *    - Empty raw (`@@@@` = two consecutive `RAW_OPEN` tokens) produces
+ *      no output
+ *    - `@@\n@@` (raw spanning a newline with no content) also produces
+ *      no output
+ *    - Content containing both `@<` and `>@` is discarded entirely
+ *    - `>@` followed immediately by `@@` is split: `>` becomes raw
+ *      content, `@@` acts as the closer, and the leftover `@` becomes text
+ *
+ * 2. Angle-bracket syntax (`@<...>@`): A less common form that also
+ *    treats content as raw text. If the closing `>@` is not found on the
+ *    same line, `@<` is treated as literal text. The `@<\n>@` spanning
+ *    pattern outputs only `@<` as text.
+ *
+ * Produces a `"raw"` AST element whose `data` field contains the
+ * verbatim text string, or empty elements when the raw content is discarded.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken, hasClosingMarkerBeforeNewline } from "../types";
+
+/**
+ * Inline rule for parsing `@@...@@` and `@<...>@` raw (verbatim) text.
+ *
+ * Triggered by either `RAW_OPEN` (`@@`) or `RAW_BLOCK_OPEN` (`@<`) tokens.
+ * Delegates to the appropriate handler based on the opening token type.
+ */
+export const rawRule: InlineRule = {
+  name: "raw",
+  startTokens: ["RAW_OPEN", "RAW_BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse raw text at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with `"raw"` element(s), text fallback,
+   *          or empty elements depending on the variant and content
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const startToken = currentToken(ctx);
+
+    // Handle @<...>@ syntax
+    if (startToken.type === "RAW_BLOCK_OPEN") {
+      return parseAngleRaw(ctx);
+    }
+
+    // Handle @@...@@ syntax
+    return parseDoubleAtRaw(ctx);
+  },
+};
+
+/**
+ * Parses the `@@...@@` double-at raw text syntax.
+ *
+ * Handles several Wikidot-specific edge cases:
+ * - Consecutive `@@@@` (two RAW_OPEN tokens) = empty raw, no output
+ * - `@@\n@@` = empty raw spanning newline, no output
+ * - Content with both `@<` and `>@` embedded = entirely discarded
+ * - `>@` immediately before `@@` = split into raw content + text
+ *
+ * When no closing `@@` is found on the same line, the opening `@@`
+ * is emitted as literal text.
+ *
+ * @param ctx - Parse context positioned at the opening `@@` token
+ * @returns Parse result with raw element(s), empty array, or text fallback
+ */
+function parseDoubleAtRaw(ctx: ParseContext): RuleResult<Element> {
+  const startToken = currentToken(ctx);
+  let pos = ctx.pos + 1;
+
+  const next1 = ctx.tokens[pos];
+
+  // Wikidot behavior for consecutive @@:
+  // @@@@ (RAW_OPEN RAW_OPEN) -> empty raw (no output), rest becomes plain text
+  // @@@@@ (5 @s) -> empty raw + @ (text)
+  // @@@@@@ (6 @s) -> empty raw + @@ (text)
+  // Empty raw produces no output, so we just consume the tokens.
+  if (next1?.type === "RAW_OPEN") {
+    return {
+      success: true,
+      elements: [], // Empty raw produces no output
+      consumed: 2, // Only consume the two RAW_OPEN tokens (@@@@)
+    };
+  }
+
+  // Check if closing @@ exists before newline
+  if (!hasClosingMarkerBeforeNewline({ ...ctx, pos }, "RAW_OPEN")) {
+    // Special case: @@\n@@ (empty raw spanning newline)
+    // Wikidot treats this as an empty raw that produces no output
+    const nextToken = ctx.tokens[pos];
+    if (nextToken?.type === "NEWLINE") {
+      const afterNewline = ctx.tokens[pos + 1];
+      if (afterNewline?.type === "RAW_OPEN") {
+        // Consume @@, NEWLINE, @@ and produce no output
+        return {
+          success: true,
+          elements: [],
+          consumed: 3, // @@ + NEWLINE + @@
+        };
+      }
+    }
+    return {
+      success: true,
+      elements: [{ element: "text", data: startToken.value }],
+      consumed: 1,
+    };
+  }
+
+  // Collect raw content and check for embedded @< and >@
+  let value = "";
+  let consumed = 1; // opening @@
+  let hasBlockOpen = false; // has @<
+  let hasBlockClose = false; // has >@
+
+  // In @@...@@ syntax, only RAW_OPEN (@@) acts as closer.
+  // Special handling for RAW_BLOCK_CLOSE (>@) followed by RAW_OPEN (@@):
+  // Wikidot treats ">@@@" as ">@@" + "@", so we only take ">" and let the
+  // @ combine with the following @@ to form the closer.
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (!token || token.type === "RAW_OPEN" || token.type === "NEWLINE" || token.type === "EOF") {
+      break;
+    }
+    // Check if RAW_BLOCK_CLOSE (>@) is followed by RAW_OPEN (@@)
+    // Wikidot interprets ">@@@" as ">" (raw content) + "@@" (closer) + "@" (text)
+    // We need to only take ">" and output "@" as trailing text after the raw element
+    if (token.type === "RAW_BLOCK_CLOSE") {
+      const nextToken = ctx.tokens[pos + 1];
+      if (nextToken?.type === "RAW_OPEN") {
+        // Only take the ">" part
+        value += ">";
+        consumed += 2; // Consume both RAW_BLOCK_CLOSE and RAW_OPEN (as closer)
+        // Return raw element followed by "@" text (from the >@ token's @)
+        return {
+          success: true,
+          elements: [
+            { element: "raw", data: value },
+            { element: "text", data: "@" },
+          ],
+          consumed,
+        };
+      }
+      // Mark that we have embedded >@ (not followed by @@)
+      hasBlockClose = true;
+    }
+    // Track embedded @< token
+    if (token.type === "RAW_BLOCK_OPEN") {
+      hasBlockOpen = true;
+    }
+    value += token.value;
+    consumed++;
+    pos++;
+  }
+
+  // Consume closing @@
+  if (ctx.tokens[pos]?.type === "RAW_OPEN") {
+    consumed++;
+    pos++;
+  }
+
+  // Wikidot quirk: @@...@@ containing BOTH @< AND >@ is discarded entirely
+  // (produces no output, not even text fallback)
+  // Having only @< or only >@ is fine - they're treated as raw content.
+  if (hasBlockOpen && hasBlockClose) {
+    return {
+      success: true,
+      elements: [],
+      consumed,
+    };
+  }
+
+  return {
+    success: true,
+    elements: [{ element: "raw", data: value }],
+    consumed,
+  };
+}
+
+/**
+ * Parses the `@<...>@` angle-bracket raw text syntax.
+ *
+ * This is the less common raw text form. Content between `@<` and `>@`
+ * is treated as verbatim text.
+ *
+ * Edge cases:
+ * - `@<\n>@` (spanning a newline) outputs only `@<` as text and
+ *   consumes all three tokens
+ * - No closing `>@` on the same line = `@<` emitted as literal text
+ *
+ * @param ctx - Parse context positioned at the opening `@<` token
+ * @returns Parse result with a raw element or text fallback
+ */
+function parseAngleRaw(ctx: ParseContext): RuleResult<Element> {
+  const startToken = currentToken(ctx);
+  let pos = ctx.pos + 1;
+
+  // Check if closing >@ exists before newline
+  if (!hasClosingMarkerBeforeNewline({ ...ctx, pos }, "RAW_BLOCK_CLOSE")) {
+    // Special case: @<\n>@ (empty raw spanning newline)
+    // Wikidot treats @< as text and >@ disappears
+    const nextToken = ctx.tokens[pos];
+    if (nextToken?.type === "NEWLINE") {
+      const afterNewline = ctx.tokens[pos + 1];
+      if (afterNewline?.type === "RAW_BLOCK_CLOSE") {
+        // Consume @<, NEWLINE, >@ - output only @< as text
+        return {
+          success: true,
+          elements: [{ element: "text", data: startToken.value }],
+          consumed: 3, // @< + NEWLINE + >@
+        };
+      }
+    }
+    return {
+      success: true,
+      elements: [{ element: "text", data: startToken.value }],
+      consumed: 1,
+    };
+  }
+
+  // Collect raw content
+  let value = "";
+  let consumed = 1; // opening @<
+
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (
+      !token ||
+      token.type === "RAW_BLOCK_CLOSE" ||
+      token.type === "NEWLINE" ||
+      token.type === "EOF"
+    ) {
+      break;
+    }
+    value += token.value;
+    consumed++;
+    pos++;
+  }
+
+  // Consume closing >@
+  if (ctx.tokens[pos]?.type === "RAW_BLOCK_CLOSE") {
+    consumed++;
+  }
+
+  return {
+    success: true,
+    elements: [{ element: "raw", data: value }],
+    consumed,
+  };
+}

package/src/parser/rules/inline/size.ts

@@ -0,0 +1,244 @@
+/**
+ *
+ * Parses the Wikidot font size syntax: `[[size value]]text[[/size]]`.
+ *
+ * This syntax wraps inline content in a `<span>` with an explicit
+ * `font-size` CSS style. The size value must include a number and
+ * a supported CSS unit.
+ *
+ * Supported units (matching Wikidot's implementation):
+ * `px`, `em`, `rem`, `ex`, `%`, `cm`, `mm`, `in`, `pc`
+ *
+ * Notably, `pt`, `vh`, `vw`, and other modern CSS units are NOT
+ * supported and will cause the parse to fail.
+ *
+ * Wikidot syntax examples:
+ * - `[[size 120%]]larger text[[/size]]`
+ * - `[[size 0.8em]]smaller text[[/size]]`
+ * - `[[size 24px]]fixed size[[/size]]`
+ *
+ * Produces a `"container"` AST element with `type: "size"` and a
+ * `style` attribute containing the `font-size` declaration.
+ *
+ * @module
+ */
+import type { Element } from "@wdprlib/ast";
+import type { InlineRule, ParseContext, RuleResult } from "../types";
+import { currentToken } from "../types";
+import { parseBlockName } from "../utils";
+import { parseInlineUntil } from "./utils";
+
+/**
+ * CSS size units that Wikidot recognizes in `[[size]]` blocks.
+ * Other valid CSS units (like `pt`, `vh`, `vw`) are deliberately
+ * excluded to match original Wikidot behavior.
+ */
+const VALID_SIZE_UNITS = ["px", "em", "rem", "ex", "%", "cm", "mm", "in", "pc"];
+
+/**
+ * Validates a size string against Wikidot-supported CSS units.
+ *
+ * The value must match the pattern `<number><unit>`, where the number
+ * can be an integer or decimal and the unit must be one of the
+ * {@link VALID_SIZE_UNITS}.
+ *
+ * @param size - The size string to validate (e.g. `"120%"`, `"1.5em"`)
+ * @returns `true` if the size value is valid
+ */
+function isValidSizeValue(size: string): boolean {
+  // Match number + unit pattern
+  const unitPattern = VALID_SIZE_UNITS.join("|");
+  const match = size.match(new RegExp(`^(\\d+(?:\\.\\d+)?)(${unitPattern})$`, "i"));
+  return match !== null;
+}
+
+/**
+ * Extracts and validates a size value from the token stream.
+ *
+ * Skips leading whitespace, then collects consecutive non-whitespace,
+ * non-delimiter tokens and joins them into a size string. The resulting
+ * string is validated against {@link isValidSizeValue}.
+ *
+ * @param ctx - The current parse context
+ * @param startPos - Token index at which to begin scanning
+ * @returns An object with the validated size string and tokens consumed,
+ *          or `null` if no valid size value was found
+ */
+function parseSizeValue(
+  ctx: ParseContext,
+  startPos: number,
+): { size: string; consumed: number } | null {
+  let pos = startPos;
+  let consumed = 0;
+
+  // Skip whitespace
+  while (ctx.tokens[pos]?.type === "WHITESPACE") {
+    pos++;
+    consumed++;
+  }
+
+  // Collect size value tokens until ]]
+  const parts: string[] = [];
+  while (pos < ctx.tokens.length) {
+    const token = ctx.tokens[pos];
+    if (
+      !token ||
+      token.type === "BLOCK_CLOSE" ||
+      token.type === "NEWLINE" ||
+      token.type === "EOF"
+    ) {
+      break;
+    }
+    if (token.type === "WHITESPACE") {
+      break; // Size value shouldn't have spaces
+    }
+    parts.push(token.value);
+    pos++;
+    consumed++;
+  }
+
+  if (parts.length === 0) {
+    return null;
+  }
+
+  const size = parts.join("");
+
+  // Validate against supported units
+  if (!isValidSizeValue(size)) {
+    return null;
+  }
+
+  return { size, consumed };
+}
+
+/**
+ * Inline rule for parsing `[[size value]]text[[/size]]`.
+ *
+ * Triggered by a `BLOCK_OPEN` (`[[`) token. Verifies the block name
+ * is `size`, parses and validates the size value, then recursively
+ * parses inline content until the matching `[[/size]]` closing tag.
+ *
+ * Fails if:
+ * - The block name is not `size`
+ * - The size value is missing or uses an unsupported unit
+ * - No closing `]]` after the size value
+ */
+export const sizeRule: InlineRule = {
+  name: "size",
+  startTokens: ["BLOCK_OPEN"],
+
+  /**
+   * Attempts to parse a size block at the current position.
+   *
+   * @param ctx - Parse context with token stream and current position
+   * @returns A successful result with a `"container"` element of type `"size"`,
+   *          or `{ success: false }`
+   */
+  parse(ctx: ParseContext): RuleResult<Element> {
+    const openToken = currentToken(ctx);
+    if (openToken.type !== "BLOCK_OPEN") {
+      return { success: false };
+    }
+
+    let pos = ctx.pos + 1;
+    let consumed = 1;
+
+    // Parse block name
+    const nameResult = parseBlockName(ctx, pos);
+    if (!nameResult) {
+      return { success: false };
+    }
+
+    const blockName = nameResult.name;
+    if (blockName !== "size") {
+      return { success: false };
+    }
+
+    pos += nameResult.consumed;
+    consumed += nameResult.consumed;
+
+    // Parse size value
+    const sizeResult = parseSizeValue(ctx, pos);
+    if (!sizeResult) {
+      return { success: false };
+    }
+
+    pos += sizeResult.consumed;
+    consumed += sizeResult.consumed;
+
+    // Expect ]]
+    if (ctx.tokens[pos]?.type !== "BLOCK_CLOSE") {
+      return { success: false };
+    }
+    pos++;
+    consumed++;
+
+    // Parse inline content until [[/size]]
+    const children: Element[] = [];
+    let foundClose = false;
+
+    while (pos < ctx.tokens.length) {
+      const token = ctx.tokens[pos];
+      if (!token || token.type === "EOF") {
+        break;
+      }
+
+      // Check for [[/size]]
+      if (token.type === "BLOCK_END_OPEN") {
+        const closeNameResult = parseBlockName(ctx, pos + 1);
+        if (closeNameResult && closeNameResult.name === "size") {
+          foundClose = true;
+          // Skip [[/size]]
+          pos++; // [[/
+          consumed++;
+          pos += closeNameResult.consumed; // size
+          consumed += closeNameResult.consumed;
+          // Skip ]]
+          if (ctx.tokens[pos]?.type === "BLOCK_CLOSE") {
+            pos++;
+            consumed++;
+          }
+          break;
+        }
+      }
+
+      // Parse inline content
+      const inlineCtx: ParseContext = { ...ctx, pos };
+      const inlineResult = parseInlineUntil(inlineCtx, "BLOCK_END_OPEN");
+      if (inlineResult.elements.length > 0) {
+        children.push(...inlineResult.elements);
+        pos += inlineResult.consumed;
+        consumed += inlineResult.consumed;
+      } else {
+        // Fallback: just add as text
+        children.push({ element: "text", data: token.value });
+        pos++;
+        consumed++;
+      }
+    }
+
+    if (!foundClose) {
+      ctx.diagnostics.push({
+        severity: "warning",
+        code: "unclosed-block",
+        message: "Missing closing tag [[/size]] for [[size]]",
+        position: openToken.position,
+      });
+    }
+
+    return {
+      success: true,
+      elements: [
+        {
+          element: "container",
+          data: {
+            type: "size",
+            attributes: { style: `font-size:${sizeResult.size};` },
+            elements: children,
+          },
+        },
+      ],
+      consumed,
+    };
+  },
+};