@asciidoctor/core 3.0.4 → 4.0.0-alpha.2

package/types/inline.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Represents an inline element in an AsciiDoc document.
+ */
+export class Inline extends AbstractNode {
+    /**
+     * @param {AbstractNode} parent
+     * @param {string} context
+     * @param {string|null} [text=null] - The String text of this inline element.
+     * @param {Object} [opts={}] - A plain object of options:
+     *   id     - The String id of this inline element.
+     *   type   - The String type qualifier (e.g. 'ref', 'bibref').
+     *   target - The String target (e.g. a URI).
+     */
+    constructor(parent: AbstractNode, context: string, text?: string | null, opts?: any);
+    /** @type {string|null} */
+    type: string | null;
+    /** @type {string|null} */
+    target: string | null;
+    /** @type {string|null} */
+    text: string | null;
+    /**
+     * Convert this inline element using the document's converter.
+     * @returns {Promise<string>}
+     */
+    convert(): Promise<string>;
+    /** @deprecated Use convert() instead. */
+    render(): Promise<string>;
+    /**
+     * Get the converted content (alias for text).
+     * @returns {string|null}
+     */
+    content(): string | null;
+    /**
+     * Alias for {@link getAlt}.
+     * @see {getAlt}
+     */
+    get alt(): any;
+    /**
+     * Generate cross-reference text (xreftext) that can be used to refer to this inline node.
+     *
+     * Uses the explicit reftext for this inline node, if specified, retrieved by calling the
+     * reftext method. Otherwise, returns null.
+     *
+     * @param {string|null} [_xrefstyle=null] - Not currently used.
+     * @returns {string|null} the reftext to refer to this inline node, or null if no reftext is defined.
+     */
+    xreftext(_xrefstyle?: string | null): string | null;
+    /**
+     * Return the text of this inline node.
+     * @returns {string|null}
+     */
+    getText(): string | null;
+    /**
+     * Return the type qualifier of this inline node (e.g. 'ref', 'bibref').
+     * @returns {string|null}
+     */
+    getType(): string | null;
+    /**
+     * Return the target (e.g. URI or anchor) of this inline node.
+     * @returns {string|null}
+     */
+    getTarget(): string | null;
+    /**
+     * Get the alt text for this inline image.
+     * @returns {string} the value of the alt attribute, or ''.
+     */
+    getAlt(): string;
+}
+import { AbstractNode } from './abstract_node.js';

package/types/list.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @extends {AbstractBlock<any[]>}
+ */
+export class List extends AbstractBlock<any[]> {
+    constructor(parent: any, context: any, opts?: {});
+    /** Alias for blocks — the list content. */
+    content(): Promise<AbstractBlock<string>[]>;
+    /**
+     * Alias for {@link getItems}.
+     * @returns {ListItem[]}
+     * @see {getItems}
+     */
+    get items(): ListItem[];
+    /**
+     * Check whether this list has items (blocks).
+     * @returns {boolean}
+     */
+    hasItems(): boolean;
+    /**
+     * Check whether this list is an outline list (unordered or ordered).
+     * @returns {boolean}
+     */
+    outline(): boolean;
+    /**
+     * Return the list items.
+     * @returns {ListItem[]}
+     */
+    getItems(): ListItem[];
+}
+/**
+ * Methods for managing items for AsciiDoc olists, ulists, and dlists.
+ *
+ * In a description list (dlist), each item is a tuple: `[[term, term, ...], desc]`.
+ * If a description is not set, the second entry is null.
+ */
+export class ListItem extends AbstractBlock<string> {
+    /**
+     * @param {List} parent - The parent List block.
+     * @param {string|null} [text=null] - The text of this item.
+     */
+    constructor(parent: List, text?: string | null);
+    /**
+     * The string marker used for this list item.
+     * @type {string|null}
+     */
+    marker: string | null;
+    /**
+     * Contextual alias for parent.
+     * @see {getParent}
+     */
+    get list(): import("./abstract_node.js").AbstractNode;
+    /**
+     * Alias for {@link setText}.
+     * @see {setText}
+     */
+    set text(val: any);
+    /**
+     * Alias for {@link getText}.
+     * @see {getText}
+     */
+    get text(): any;
+    /**
+     * Check whether the text of this list item is non-blank.
+     * @returns {boolean}
+     */
+    hasText(): boolean;
+    /**
+     * Pre-compute the converted text asynchronously.
+     * Called during `Document.parse()` so the synchronous getter works during conversion.
+     * @returns {Promise<void>}
+     */
+    precomputeText(): Promise<void>;
+    /**
+     * Check whether this list item has simple content.
+     * @returns {boolean} `true` if the item has no blocks or only a single nested outline list.
+     */
+    simple(): boolean;
+    /**
+     * Check whether this list item has compound content.
+     * @returns {boolean} `true` if the item contains blocks other than a single nested outline list.
+     */
+    compound(): boolean;
+    /**
+     * Return the parent List block (alias of {@link getParent}).
+     * @returns {List}
+     * @see {getParent}
+     */
+    getList(): List;
+    /**
+     * Return the list marker string for this item (e.g. '.', '..', '*').
+     * @returns {string|null}
+     */
+    getMarker(): string | null;
+    /**
+     * Return the text of this list item with substitutions applied.
+     * The result is pre-computed during `Document.parse()` via {@link precomputeText}.
+     * Falls back to the raw text if {@link precomputeText} has not been called yet.
+     *
+     * In Ruby, text is lazy (`apply_subs` on first access), so API callers can modify
+     * subs before accessing text and get the result they expect. Here we replicate
+     * that by invalidating the pre-computed value when subs have changed since it
+     * was computed: returning raw text mirrors what Ruby would produce when subs are
+     * cleared or reduced to a no-op set (since `applySubs` is async and cannot be
+     * re-run synchronously).
+     * @returns {string|null}
+     */
+    getText(): string | null;
+    /**
+     * Set the raw text of this list item.
+     * @param {string|null} val
+     */
+    setText(val: string | null): void;
+}
+import { AbstractBlock } from './abstract_block.js';

package/types/load.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Parse the AsciiDoc source input into a Document.
+ *
+ * Accepts input as a Node.js Readable stream (or any object with a read()
+ * method), a String, or a String Array. If the input is a file descriptor
+ * object produced by openFile() / Node's fs.openSync(), pass a plain object
+ * with { path, read() } instead; the function sets docfile/docdir/docname
+ * attributes automatically.
+ *
+ * @param {Buffer|string|string[]|{path?: string, read(): string|Promise<string>, mtime?: Date}} input - The AsciiDoc source.
+ * @param {Object} [options={}] - Options to control processing. See Document for the full list.
+ * @param {string|string[]|Object} [options.attributes] - Document attributes.
+ * @param {boolean} [options.parse] - Set to false to skip parsing after Document creation.
+ * @param {Object} [options.logger] - Logger instance to use for this call.
+ * @param {{start(label: string): void, record(label: string): void}} [options.timings] - Timings object.
+ * @returns {Promise<Document>} A Promise that resolves to the Document.
+ */
+export function load(input: Buffer | string | string[] | {
+    path?: string;
+    read(): string | Promise<string>;
+    mtime?: Date;
+}, options?: {
+    attributes?: string | string[] | any;
+    parse?: boolean;
+    logger?: any;
+    timings?: {
+        start(label: string): void;
+        record(label: string): void;
+    };
+}): Promise<Document>;
+/**
+ * Parse the contents of the AsciiDoc source file into a Document.
+ *
+ * @param {string} filename - The path to the AsciiDoc source file.
+ * @param {Object} [options={}] - Options to control processing.
+ * @returns {Promise<Document>} A Promise that resolves to the Document.
+ */
+export function loadFile(filename: string, options?: any): Promise<Document>;
+import { Document } from './document.js';

package/types/logging.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Apply the Logging mixin to a class prototype.
+ *
+ * Installs the following on proto:
+ * - `logger` getter — returns `LoggerManager.logger`
+ * - `getLogger()` — method alias for the logger getter
+ * - `messageWithContext(text, context)` — builds an auto-formatting message object
+ * - `createLogMessage(text, context)` — alias for messageWithContext (used in extensions)
+ *
+ * @param {Object} proto - The prototype object (e.g. MyClass.prototype) to augment.
+ */
+export function applyLogging(proto: any): void;
+export namespace Severity {
+    let DEBUG: number;
+    let INFO: number;
+    let WARN: number;
+    let ERROR: number;
+    let FATAL: number;
+    let UNKNOWN: number;
+}
+/** Standard logger that writes formatted messages to stderr or a custom pipe. */
+export class Logger {
+    constructor(opts?: {});
+    progname: any;
+    level: any;
+    set formatter(f: any);
+    /** getter/setter so custom logger impls can access this.formatter */
+    get formatter(): any;
+    /**
+     * @returns {number|null} The highest severity level logged so far.
+     */
+    get maxSeverity(): number | null;
+    getLevel(): any;
+    setLevel(n: any): void;
+    getFormatter(): any;
+    setFormatter(f: any): void;
+    getProgramName(): any;
+    setProgramName(n: any): void;
+    getMaxSeverity(): number;
+    /**
+     * @returns {boolean} Whether DEBUG-level messages will be logged.
+     */
+    isDebugEnabled(): boolean;
+    /**
+     * @returns {boolean} Whether INFO-level messages will be logged.
+     */
+    isInfoEnabled(): boolean;
+    /**
+     * @returns {boolean} Whether WARN-level messages will be logged.
+     */
+    isWarnEnabled(): boolean;
+    /**
+     * @returns {boolean} Whether ERROR-level messages will be logged.
+     */
+    isErrorEnabled(): boolean;
+    /**
+     * @returns {boolean} Whether FATAL-level messages will be logged.
+     */
+    isFatalEnabled(): boolean;
+    isDebug(): boolean;
+    isInfo(): boolean;
+    /**
+     * Log a message at the given severity level.
+     * @param {number|string} severity - Severity level (numeric constant or string name).
+     * @param {string|{inspect?(): string}|null} [message=null] - The message to log.
+     * @param {string|Function|null} [progname=null] - Program name or message supplier function.
+     * @returns {boolean}
+     */
+    add(severity: number | string, message?: string | {
+        inspect?(): string;
+    } | null, progname?: string | Function | null): boolean;
+    /** Alias for {@link add} (Ruby Logger API). */
+    log(severity: any, message: any, progname: any): boolean;
+    debug(msg: any, progname: any): boolean;
+    info(msg: any, progname: any): boolean;
+    warn(msg: any, progname: any): boolean;
+    error(msg: any, progname: any): boolean;
+    fatal(msg: any, progname: any): boolean;
+    unknown(msg: any, progname: any): boolean;
+}
+export namespace Logger {
+    export { BasicFormatter };
+    export namespace AutoFormattingMessage {
+        /**
+         * Attach auto-formatting to any plain object carrying { text, source_location }.
+         * @param {{text: string, source_location?: string}} obj
+         * @returns {typeof obj} The same object with inspect() and toString() added.
+         */
+        function attach(obj: {
+            text: string;
+            source_location?: string;
+        }): typeof obj;
+    }
+}
+/** In-memory logger that stores all log messages for later inspection. */
+export class MemoryLogger {
+    static create(): MemoryLogger;
+    level: number;
+    messages: any[];
+    getMessages(): any[];
+    getMaxSeverity(): number;
+    add(severity: any, message?: any, progname?: any): boolean;
+    debug(msg: any, pn: any): boolean;
+    info(msg: any, pn: any): boolean;
+    warn(msg: any, pn: any): boolean;
+    error(msg: any, pn: any): boolean;
+    fatal(msg: any, pn: any): boolean;
+    unknown(msg: any, pn: any): boolean;
+    log(severity: any, message: any, progname: any): boolean;
+    isDebug(): boolean;
+    isInfo(): boolean;
+    /**
+     * Write a string at INFO level (trailing newline stripped).
+     * Allows MemoryLogger to be used with Timings.printReport().
+     * @param {string} s
+     * @returns {boolean}
+     */
+    write(s: string): boolean;
+    clear(): void;
+    empty(): boolean;
+}
+/** Logger that discards all messages but still tracks the maximum severity. */
+export class NullLogger {
+    static create(): NullLogger;
+    level: number;
+    _maxSeverity: number;
+    get maxSeverity(): number;
+    getMaxSeverity(): number;
+    add(severity: any): boolean;
+    log(severity: any): boolean;
+    debug(): boolean;
+    info(): boolean;
+    warn(): boolean;
+    error(): boolean;
+    fatal(): boolean;
+    unknown(): boolean;
+}
+export namespace LoggerManager {
+    let loggerClass: typeof Logger;
+    let logger: any;
+    function getLogger(): any;
+    function setLogger(newLogger: any): void;
+    /**
+     * Create a new formatter whose call() delegates to the provided impl.
+     * @param {string} _name
+     * @param {{call: Function}} impl
+     * @returns {{call: Function}}
+     */
+    function newFormatter(_name: string, impl: {
+        call: Function;
+    }): {
+        call: Function;
+    };
+    /**
+     * Create a new Logger instance with custom behaviour supplied via impl.
+     * @param {string} _name
+     * @param {{add?: (severity: number, message: any, progname: any) => boolean, postConstruct?: (this: Logger) => void}} impl
+     *   - `add(severity, message, progname)` — overrides the default add method; severity is always numeric.
+     *   - `postConstruct()` — called once after the instance is created (`this` is the logger instance).
+     * @returns {Logger}
+     */
+    function newLogger(_name: string, impl: {
+        add?: (severity: number, message: any, progname: any) => boolean;
+        postConstruct?: (this: Logger) => void;
+    }): Logger;
+}
+export namespace Logging {
+    const logger_1: any;
+    export { logger_1 as logger };
+    export function getLogger(): any;
+    export function messageWithContext(text: any, context?: {}): any;
+    export function createLogMessage(text: any, context?: {}): any;
+}
+declare class BasicFormatter {
+    /**
+     * Format a log entry as "progname: SEVERITY: message\n".
+     * @param {number|string} severity
+     * @param {null} _time
+     * @param {string} progname
+     * @param {string|{inspect?(): string}} msg
+     * @returns {string}
+     */
+    call(severity: number | string, _time: null, progname: string, msg: string | {
+        inspect?(): string;
+    }): string;
+}
+export {};

package/types/parser.d.ts

@@ -0,0 +1,114 @@
+export class Parser {
+    /**
+     * Parse AsciiDoc source from reader into document.
+     * @param {Reader} reader
+     * @param {Document} document
+     * @param {{header_only?: boolean}} [options={}]
+     * @returns {Promise<Document>}
+     */
+    static parse(reader: Reader, document: Document, options?: {
+        header_only?: boolean;
+    }): Promise<Document>;
+    /**
+     * Parse the document header.
+     * @param {Reader} reader
+     * @param {Document} document
+     * @param {boolean} [headerOnly=false]
+     * @returns {Promise<Object>} Block attributes after the header.
+     */
+    static parseDocumentHeader(reader: Reader, document: Document, headerOnly?: boolean): Promise<any>;
+    /**
+     * Parse manpage header.
+     * @param {Reader} reader
+     * @param {Document} document
+     * @param {Object} blockAttributes
+     * @param {boolean} [headerOnly=false]
+     * @returns {Promise<void>}
+     */
+    static parseManpageHeader(reader: Reader, document: Document, blockAttributes: any, headerOnly?: boolean): Promise<void>;
+    /**
+     * Return the next section from the reader.
+     * @param {Reader} reader
+     * @param {Document|Section} parent
+     * @param {Object} [attributes={}]
+     * @returns {Promise<[Section|null, Object]>} Tuple of the new section (or null) and orphaned attributes.
+     */
+    static nextSection(reader: Reader, parent: Document | Section, attributes?: any): Promise<[Section | null, any]>;
+    /**
+     * Parse and return the next Block at the Reader's current location.
+     * @param {Reader} reader
+     * @param {AbstractBlock} parent
+     * @param {Object} [attributes={}]
+     * @param {Object} [options={}]
+     * @returns {Promise<Block|null>}
+     */
+    static nextBlock(reader: Reader, parent: AbstractBlock, attributes?: any, options?: any): Promise<Block | null>;
+    /**
+     * Parse blocks from reader until exhausted.
+     * @param {Reader} reader
+     * @param {AbstractBlock} parent
+     * @param {Object|null} [attributes=null]
+     * @returns {Promise<void>}
+     */
+    static parseBlocks(reader: Reader, parent: AbstractBlock, attributes?: any | null): Promise<void>;
+    /**
+     * Check if line1 (and optionally line2) form a section title.
+     * @param {string} line1
+     * @param {string|null} [line2=null]
+     * @returns {number|null} The section level, or null.
+     */
+    static isSectionTitle(line1: string, line2?: string | null): number | null;
+    /**
+     * Parse section title from reader.
+     * @param {Reader} reader
+     * @param {Document} document
+     * @param {string|null} [sectId=null]
+     * @returns {Promise<[string|null, string|null, string, number, boolean]>} Tuple of [id, reftext, title, level, atx].
+     */
+    static parseSectionTitle(reader: Reader, document: Document, sectId?: string | null): Promise<[string | null, string | null, string, number, boolean]>;
+    /**
+     * Parse header metadata (author line and revision line).
+     * @param {Reader} reader
+     * @param {Document|null} [document=null]
+     * @param {boolean} [retrieve=true]
+     * @returns {Promise<Object|null>}
+     */
+    static parseHeaderMetadata(reader: Reader, document?: Document | null, retrieve?: boolean): Promise<any | null>;
+    /**
+     * Store the attribute in the document.
+     * @param {string} name
+     * @param {string} value
+     * @param {Document|null} [doc=null]
+     * @param {Object|null} [attrs=null]
+     * @param {Object} [opts={}]
+     * @returns {[string, string|null]} Tuple of the resolved name and value.
+     */
+    static storeAttribute(name: string, value: string, doc?: Document | null, attrs?: any | null, opts?: any): [string, string | null];
+    /**
+     * Check if line is the start of a delimited block.
+     * @param {string} line
+     * @param {boolean} [returnMatchData=false]
+     * @returns {{context: string, masq: string[], tip: string, terminator: string}|true|null}
+     *   BlockMatchData object if returnMatchData is true, true/null otherwise.
+     */
+    static isDelimitedBlock(line: string, returnMatchData?: boolean): {
+        context: string;
+        masq: string[];
+        tip: string;
+        terminator: string;
+    } | true | null;
+    /**
+     * Parse the first positional attribute for style, role, id, and options.
+     * @param {Object} attributes
+     * @param {Reader|null} [reader=null]
+     * @returns {string|null} The resolved style value.
+     */
+    static parseStyleAttribute(attributes: any, reader?: Reader | null): string | null;
+    static _yieldBufferedAttribute(attrs: any, name: any, value: any, reader: any): void;
+}
+import { Reader } from './reader.js';
+import { Section } from './section.js';
+import { Block } from './block.js';
+import { List } from './list.js';
+import { ListItem } from './list.js';
+import { Table } from './table.js';

package/types/path_resolver.d.ts

@@ -0,0 +1,103 @@
+/** Handles all operations for resolving, cleaning and joining paths. */
+export class PathResolver {
+    /**
+     * Construct a new PathResolver.
+     * @param {string|null} fileSeparator - The file separator (default: '/' or '\\' on Windows).
+     * @param {string|null} workingDir - The working directory (default: process.cwd()).
+     */
+    constructor(fileSeparator?: string | null, workingDir?: string | null);
+    fileSeparator: string;
+    workingDir: any;
+    _partitionPathSys: {};
+    _partitionPathWeb: {};
+    /**
+     * Check whether the specified path is an absolute path.
+     * @param {string} path
+     * @returns {boolean}
+     */
+    absolutePath(path: string): boolean;
+    /**
+     * Check if the specified path is an absolute root path.
+     * @param {string} path
+     * @returns {boolean}
+     */
+    root(path: string): boolean;
+    /**
+     * Determine if the path is a UNC (root) path.
+     * @param {string} path
+     * @returns {boolean}
+     */
+    unc(path: string): boolean;
+    /**
+     * Determine if the path is an absolute (root) web path.
+     * @param {string} path
+     * @returns {boolean}
+     */
+    webRoot(path: string): boolean;
+    /**
+     * Determine whether path descends from base.
+     * @param {string} path
+     * @param {string} base
+     * @returns {number|false} Offset if path descends from base, false otherwise.
+     */
+    descendsFrom(path: string, base: string): number | false;
+    /**
+     * Calculate the relative path to this absolute path from the specified base directory.
+     * @param {string} path
+     * @param {string} base
+     * @returns {string} Relative path, or the original path if it cannot be made relative.
+     */
+    relativePath(path: string, base: string): string;
+    /**
+     * Normalize path by converting backslashes to forward slashes.
+     * @param {string} path
+     * @returns {string} The posixified path.
+     */
+    posixify(path: string): string;
+    /**
+     * @param {string} path
+     * @returns {string}
+     */
+    posixfy(path: string): string;
+    /**
+     * Expand the path by resolving parent references (..) and removing self references (.).
+     * @param {string} path
+     * @returns {string} The expanded path.
+     */
+    expandPath(path: string): string;
+    /**
+     * Partition the path into segments and a root prefix.
+     * @param {string} path - The path to partition.
+     * @param {boolean} [web=false] - Treat as web path.
+     * @returns {[string[], string|null]} A 2-item array [segments, root] where root may be null.
+     */
+    partitionPath(path: string, web?: boolean): [string[], string | null];
+    /**
+     * Join segments with posix separator, prepending root if provided.
+     * @param {string[]} segments
+     * @param {string|null} [root=null]
+     * @returns {string} The joined path.
+     */
+    joinPath(segments: string[], root?: string | null): string;
+    /**
+     * Securely resolve a system path.
+     * @param {string} target - The target path.
+     * @param {string|null} [start=null] - The start path.
+     * @param {string|null} [jail=null] - The jail path.
+     * @param {Object} [opts={}] - Options.
+     * @param {boolean} [opts.recover=true] - Recover from jail escapes instead of throwing.
+     * @param {string} [opts.targetName='path'] - Name used in error messages.
+     * @returns {string} An absolute posix path.
+     */
+    systemPath(target: string, start?: string | null, jail?: string | null, opts?: {
+        recover?: boolean;
+        targetName?: string;
+    }): string;
+    /**
+     * Resolve a web path from the target and start paths.
+     * @param {string} target - The target path.
+     * @param {string|null} [start=null] - The start (parent) path.
+     * @returns {string} Path with parent references resolved and self references removed.
+     */
+    webPath(target: string, start?: string | null): string;
+}