@tabnas/markdown 0.6.2 → 0.7.1

package/dist/block.d.ts

@@ -1,5 +1,262 @@
 import { MdNode } from './node.ts';
+import type { NodeType, TableAlign } from './node.ts';
 import type { ParserOptions, RefMap } from './options.ts';
+export declare function isBlank(s: string): boolean;
+/** One physical line of `src` starting at `pos`, with §2.3's NUL replacement. */
+export type LineSegment = {
+    text: string;
+    next: number;
+};
+/**
+ * Cut the next physical line out of `src` at `pos`: up to (not including)
+ * the next `\n`, `\r` or `\r\n`, with `next` past the terminator. Null at
+ * the end of the source — which is why a final line ending does not
+ * introduce a trailing blank line. Insecure NULs are replaced here, before
+ * anything else looks at the text.
+ */
+export declare function segmentNextLine(src: string, pos: number): LineSegment | null;
+/** §4.1: is `rest` a thematic break? */
+export declare function isThematicBreakLine(rest: string): boolean;
+/** §4.2: the ATX marker opening `rest`, with its heading level. */
+export declare function matchAtxHeading(rest: string): {
+    marker: string;
+    level: number;
+} | null;
+/**
+ * §4.2: drop an optional closing sequence of `#`s, preceded by spaces or
+ * tabs; a line of nothing but `#`s has empty content.
+ */
+export declare function stripAtxClosing(content: string): string;
+/** §4.5: the opening code fence at the start of `rest`, or null. */
+export declare function matchCodeFence(rest: string): string | null;
+/**
+ * §4.5: the closing-fence candidate at the start of `rest`, or null. The
+ * caller still checks the fence character and length against the open block.
+ */
+export declare function matchClosingCodeFence(rest: string): string | null;
+/** §4.3: setext underline level — 1 for `=`, 2 for `-`, 0 if neither. */
+export declare function setextHeadingLevel(rest: string): number;
+/**
+ * §4.6: which of the seven HTML block kinds `rest` opens, or 0. The type-7
+ * paragraph-interrupt restriction is contextual and stays with the caller.
+ */
+export declare function htmlBlockOpenKind(rest: string): number;
+/** §4.6: does `rest` contain the closing condition for HTML block `type`? */
+export declare function htmlBlockCloses(rest: string, type: number): boolean;
+/** §5.2: the bullet list marker opening `rest`, or null. */
+export declare function matchBulletListMarker(rest: string): {
+    marker: string;
+    char: string;
+} | null;
+/** §5.2: the ordered list marker opening `rest`, or null. */
+export declare function matchOrderedListMarker(rest: string): {
+    marker: string;
+    start: number;
+    delimiter: string;
+} | null;
+/**
+ * Split one row of a table into its cell texts.
+ *
+ * Cells are separated by *unescaped* pipes; a leading and a trailing pipe are
+ * both optional and may differ from row to row, so they are stripped before
+ * the split rather than producing empty cells at the ends. A trailing pipe is
+ * only a delimiter if it is itself unescaped, which is why the backslash run
+ * before it is counted.
+ *
+ * `\|` is resolved to a literal `|` *here*, as the extension requires ("include
+ * a pipe in a cell's content by escaping it, including inside other inline
+ * spans"). Doing it at split time is the whole point: the inline phase never
+ * sees the backslash, so a code span in the cell yields a real pipe —
+ * `` b `\|` az `` is `b <code>|</code> az`, which no amount of unescaping
+ * *after* inline parsing could produce. Every other backslash escape is left
+ * exactly as written for the inline phase to handle in the usual way, so no
+ * cell text is unescaped twice.
+ *
+ * Scanning skips the character after any backslash, so `\\` cannot shield the
+ * pipe that follows it: `a\\|b` is two cells, the first holding `a\\`.
+ *
+ * A row of nothing but whitespace has no cells at all, which is how a header
+ * candidate that is really empty fails the cell-count test instead of matching
+ * a one-column delimiter row.
+ */
+export declare function splitTableRow(line: string): string[];
+/**
+ * Read a line as a table's delimiter row, returning one alignment per column,
+ * or null if it is not one.
+ */
+export declare function parseDelimiterRow(line: string): TableAlign[] | null;
+export declare class BlockParser {
+    options: ParserOptions;
+    refmap: RefMap;
+    doc: MdNode;
+    /** Deepest open block; null only once the document itself is finalized. */
+    tip: MdNode | null;
+    /** The tip as it was before the current line was walked. */
+    oldtip: MdNode;
+    lastMatchedContainer: MdNode;
+    /** False while some open block failed its continuation condition. */
+    allClosed: boolean;
+    currentLine: string;
+    lineNumber: number;
+    lastLineLength: number;
+    /**
+     * GFM table probe gate. True by default — the batch driver probes every
+     * candidate line, as it always has. The engine driver sets it per line
+     * from the `#LB` token's `tblArm` bit (a provable superset of "could be
+     * a delimiter row"; see engine-block.ts), which is what lets the GFM alt
+     * be a genuine, subtractable extension seam without moving any table
+     * decision out of this file.
+     */
+    tableArmed: boolean;
+    /**
+     * The length of the line before the one `lastLineLength` measures.
+     *
+     * `finalize` dates a block's end from `lastLineLength`, which is right for
+     * every block that ends on the line before the current one. A GFM table
+     * splits its paragraph *two* lines back — the header row is the previous
+     * line and stays with the table, so the paragraph left behind ends on the
+     * line before that — and needs this one instead.
+     */
+    prevLineLength: number;
+    colAnchorOffset: number;
+    colAnchorChars: number;
+    /** UTF-16 index into `currentLine`. */
+    offset: number;
+    /** Tab-expanded display column matching `offset` (§2.2). */
+    column: number;
+    /** True when `offset` sits inside a tab whose columns were partly consumed. */
+    partiallyConsumedTab: boolean;
+    nextNonspace: number;
+    nextNonspaceColumn: number;
+    /** Columns between `column` and the next non-space character. */
+    indent: number;
+    indented: boolean;
+    blank: boolean;
+    /** Empty cells inserted so far to pad short table rows. See MAX_AUTOCOMPLETED_CELLS. */
+    autocompletedCells: number;
+    /**
+     * The text `addLine` last appended, the column it started in, and the block
+     * it went to.
+     *
+     * `tryOpenTable` needs the *last line* of an open paragraph, and reading it
+     * back out of `stringContent` is not affordable: that content is built by
+     * repeated `+=`, so every index into it flattens a fresh rope — O(n) per
+     * line, O(n²) over a paragraph whose every other line looks like a delimiter
+     * row, which untrusted input can write. Keeping the line itself here costs
+     * two field writes and never touches the accumulated string.
+     *
+     * The node is recorded alongside it because "the previous line went to this
+     * very paragraph" is the extension's own rule, not a cache-validity trick:
+     * a header row is by definition the line immediately above the delimiter
+     * row. If some other block took that line, there is no header row.
+     *
+     * The column is what a table's sourcepos starts at: a table opens on its
+     * header row, which is a line already consumed by the time the delimiter row
+     * identifies it, so its column has to have been recorded when it went past.
+     */
+    lastAddedLine: string;
+    lastAddedColumn: number;
+    lastAddedTo: MdNode | null;
+    /** Step 2's fast reject, widened for a table's delimiter row when `gfm` is on. */
+    readonly maybeSpecial: RegExp;
+    private htmlBlockTypes;
+    constructor(options: ParserOptions);
+    /** The deepest open block. Only valid while a line is being processed. */
+    get openTip(): MdNode;
+    htmlBlockType(block: MdNode): number;
+    setHtmlBlockType(block: MdNode, type: number): void;
+    /**
+     * Advance `count` characters (`columns` false) or `count` columns (`columns`
+     * true), expanding tabs to the next 4-column tab stop (§2.2). A tab whose
+     * columns are only partly consumed leaves `offset` on the tab itself and
+     * sets `partiallyConsumedTab`, so `addLine` can re-emit the remainder as
+     * spaces.
+     */
+    advanceOffset(count: number, columns: boolean): void;
+    advanceNextNonspace(): void;
+    /** Locate the next non-space character and the indent leading up to it. */
+    findNextNonspace(): void;
+    /** Add the rest of the current line to the tip's raw content. */
+    addLine(): void;
+    /**
+     * Open a block of `tag` as a child of the tip, closing blocks that cannot
+     * contain it first.
+     */
+    /**
+     * Characters of `currentLine` before UTF-16 offset `offset` — what a
+     * sourcepos column counts.
+     *
+     * Not simply `offset`: a JavaScript string index counts UTF-16 units, so an
+     * astral character (emoji, rare CJK) would advance the column by two. A
+     * column means a character, so `\u{1F600} *x*` must report the same columns
+     * in both runtimes.
+     *
+     * Counted incrementally from the last offset already measured. `addChild`
+     * runs once per container opened, so counting from the start of the line
+     * every time would make a line of n nested containers — `> - > - …` — cost
+     * O(n²); untrusted input picks n. Offsets advance monotonically as a line is
+     * consumed, making this amortized O(1); a smaller offset than the anchor is
+     * still correct, just recounted from the start.
+     */
+    sourceColumn(offset: number): number;
+    addChild(tag: NodeType, offset: number): MdNode;
+    /**
+     * GFM tables: try to read the current line as the delimiter row of a table
+     * whose header row is the last line of the open paragraph `container`.
+     *
+     * The two rows must agree on the number of cells; if they do not, there is
+     * no table and the line is nothing special (spec example 6 keeps the whole
+     * thing a paragraph). The header row is the paragraph's **last** line only,
+     * so a paragraph that had earlier lines is split: those lines stay a
+     * paragraph — finalized here, which is what still lets them contribute link
+     * reference definitions — and the table is opened after it.
+     *
+     * On success the table is the tip and the caller returns "leaf started", so
+     * step 3 adds the delimiter row itself to the table's raw content. It is
+     * skipped again by `finalizeTable`; keeping it costs nothing and makes the
+     * table's accumulated lines line up one-for-one with the source lines.
+     */
+    tryOpenTable(container: MdNode): boolean;
+    /** Close every block that failed its continuation condition on this line. */
+    closeUnmatchedBlocks(): void;
+    /**
+     * Close a block, record its end position, and run its finalizer.
+     *
+     * `endColumn` defaults to the previous line's length, which is where every
+     * block that ends on `lineNumber` ends. Only a table's paragraph split
+     * passes it: that one closes a block two lines back, where the default is
+     * one line too recent.
+     */
+    finalize(block: MdNode, lineNumber: number, endColumn?: number): void;
+    /**
+     * Incorporate one line into the tree — the three steps of Appendix A.
+     */
+    incorporateLine(ln: string): void;
+    parse(input: string): {
+        doc: MdNode;
+        refmap: RefMap;
+    };
+    /**
+     * Close every still-open block, stamp the parse-time `gfm` flag, and run
+     * the task-list post-pass. `lineNumber` is the count of incorporated
+     * lines, so an incremental driver — one that feeds `incorporateLine`
+     * itself instead of calling `parse` — finishes with exactly the same
+     * finalization the batch loop above gets.
+     */
+    finish(): {
+        doc: MdNode;
+        refmap: RefMap;
+    };
+}
+/**
+ * GFM: the task list item marker opening `content`, or null. Whitespace
+ * between the brackets is unchecked; `x`/`X` is checked. `length` is what the
+ * caller strips, trailing whitespace included.
+ */
+export declare function matchTaskListMarker(content: string): {
+    checked: boolean;
+    length: number;
+} | null;
 /**
  * Phase 1: build the block tree and collect link reference definitions.
  * Paragraph and heading text is left raw in `stringContent` for phase 2.