europa-core/lib/cjs/Conversion.d.ts

Europa core engine for converting HTML into valid Markdown

import { ConversionContext } from "./ConversionContext";
import { EuropaOptions } from "./EuropaOptions";
import { Environment } from "./environment/Environment";
import { DomElement } from "./environment/dom/DomElement";
import { DomNode } from "./environment/dom/DomNode";
import { PluginManager } from "./plugin/PluginManager";
declare const _buffer: unique symbol;
declare const _context: unique symbol;
declare const _environment: unique symbol;
declare const _options: unique symbol;
declare const _pluginManager: unique symbol;
declare const _referenceCache: unique symbol;
declare const _references: unique symbol;
declare const _skipTagNames: unique symbol;
/**
 * Contains contextual information for a single conversion process.
 */
export declare class Conversion {
    /**
     * Whether the buffer is at the start of the current line.
     */
    atLeft: boolean;
    /**
     * Whether any whitespace should be removed from the start of the next output.
     */
    atNoWhitespace: boolean;
    /**
     * Whether the buffer is at the start of a paragraph.
     */
    atParagraph: boolean;
    /**
     * The current element for this {@link Conversion}.
     */
    element: DomElement;
    /**
     * The last string to be output next to the buffer.
     */
    last: string | null;
    /**
     * The start of the current line.
     */
    left: string;
    /**
     * The depth of nested lists.
     */
    listDepth: number;
    /**
     * The one-based index for the current list item within the current list.
     */
    listIndex: number;
    private [_buffer];
    private readonly [_context];
    private readonly [_environment];
    private readonly [_options];
    private readonly [_pluginManager];
    private readonly [_referenceCache];
    private readonly [_references];
    private readonly [_skipTagNames];
    /**
     * Creates an instance of {@link Conversion} using the `options` provided.
     *
     * @param options - The options to be used.
     */
    constructor(options: ConversionOptions);
    /**
     * Adds a reference to this {@link Conversion} using the `key` and `value` provided.
     *
     * A numeric ID is associated with `value` and is included in the returned reference. If a reference already exists
     * for the given `key` and `value` then this ID will be the same as the existing reference in order to avoid
     * duplications. Otherwise, the ID will be the next number in the sequence for `key`.
     *
     * At the end of the conversion, the reference will be appended to the output string.
     *
     * @param key - The key (prefix) for the reference.
     * @param value - The value for the reference.
     * @return The reference.
     * @throws If the `inline` option is enabled.
     */
    addReference(key: string, value: string): string;
    /**
     * Appends the last output string to the buffer and then queues the specified `str` to be output.
     *
     * @param str - The string to be appended.
     * @return A reference to this {@link Conversion} for chaining purposes.
     */
    append(str: string): this;
    /**
     * Appends a paragraph to the output buffer.
     *
     * @return A reference to this {@link Conversion} for chaining purposes.
     */
    appendParagraph(): this;
    /**
     * Converts the specified `node` and it's children into Markdown.
     *
     * Nothing happens if `node` is nullable or hidden (see {@link Conversion#isHidden}.
     *
     * @param node - The node (along well as it's children) to be converted into Markdown.
     * @return A reference to this {@link Conversion} for chaining purposes.
     */
    convertNode(node: DomNode | null | undefined): this;
    /**
     * Ensures any recorded references are generated and that output buffer contains last output string before returning
     * the trimmed output buffer.
     *
     * @return The complete output buffer.
     */
    end(): string;
    /**
     * Escapes special characters from the specified `str`.
     *
     * If `character` is provided, this method escapes all occurrences of the specified special `character` within the
     * `str` provided by prefixing them with a backslash. Otherwise, some special characters in Markdown are escaped using
     * backslashes, others are simple replacements of potentially confusing Unicode characters, before finally allowing
     * plugins to hook in and provide any additional escaping.
     *
     * @param str - The string to be escaped.
     * @param [character] - The special character to be escaped by prefixing with a backslash in all cases.
     * @return The escaped `str`.
     */
    escape(str: string, character?: string): string;
    /**
     * Returns the value of the option for the {@link EuropaCore} instance responsible for this {@link Conversion} with
     * the specified `name`.
     *
     * @param name - The name of the option whose value is to be returned.
     * @return The value of the named option.
     */
    getOption<N extends keyof EuropaOptions>(name: N): Required<EuropaOptions>[N];
    /**
     * Checks whether the specified `element` is currently hidden.
     *
     * This check is very basic as it checks whether `element` has any of the following styles applied:
     *
     * | Style Property | Value    |
     * | -------------- | -------- |
     * | `display`      | `none`   |
     * | `visibility`   | `hidden` |
     *
     * The accuracy of the resolution of the styles is left to the active {@link Environment} and may be limited.
     *
     * @param element - The element whose visibility is to be checked.
     * @return `true` if `element` is hidden; otherwise `false`.
     */
    isHidden(element: DomElement): boolean;
    /**
     * Outputs the specified `str` to the buffer.
     *
     * @param str - The string to be output.
     * @param [options] - The options to be used.
     * @return A reference to this {@link Conversion} for chaining purposes.
     */
    output(str: string, options?: ConversionOutputOptions): this;
    /**
     * Returns the specified `url` relative to the `baseUri` option in a manner similar to that of a browser resolving an
     * anchor element.
     *
     * A relative URL may still be returned but only if the `baseUri` option is relative.
     *
     * @param url - The target URL to resolve.
     * @return The resolved `url`.
     */
    resolveUrl(url: string): string;
    /**
     * The global context for this {@link Conversion}.
     */
    get context(): ConversionContext;
    /**
     * The end of line character to be used by this {@link Conversion}.
     */
    get eol(): string;
    /**
     * The options for the {@link EuropaCore} instance responsible for this {@link Conversion}.
     */
    get options(): Required<EuropaOptions>;
    /**
     * The set of tag upper-case names for which conversion should be skipped for this {@link Conversion}.
     */
    get skipTagNames(): Set<string>;
}
/**
 * The options used by {@link Conversion}.
 */
export declare type ConversionOptions = {
    /**
     * The initial DOM element.
     */
    readonly element: DomElement;
    /**
     * The active {@link Environment}.
     */
    readonly environment: Environment<any, any>;
    /**
     * The options for the {@link EuropaCore} instance responsible for this {@link Conversion}.
     */
    readonly options: Required<EuropaOptions>;
    /**
     * The {@link PluginManager} to be used to invoke plugin converters.
     */
    readonly pluginManager: PluginManager;
};
/**
 * The options used by {@link Conversion#output}.
 */
export declare type ConversionOutputOptions = {
    /**
     * Escape certain special characters as well as some whitespace before appending to the output buffer.
     */
    readonly clean?: boolean;
    /**
     * Preserve any leading whitespace, preventing it from being removed before appending to the output buffer.
     */
    readonly preserveLeadingWhitespace?: boolean;
};
/**
 * A reference to be included at the end of the converted Markdown.
 */
export declare type ConversionReference = {
    /**
     * The numeric ID of this {@link ConversionReference}.
     *
     * This is unique across all references with the same key.
     */
    readonly id: number;
    /**
     * The key of this {@link ConversionReference}.
     */
    readonly key: string;
    /**
     * The value of this {@link ConversionReference}.
     *
     * This is unique across all references with the same key.
     */
    readonly value: string;
};
/**
 * Contains cached information for all references recorded for a {@link Conversion}.
 *
 * This is used to ensure uniqueness of {@link ConversionReference} numeric IDs and values, while also aiding in the
 * generation of the former.
 */
export declare type ConversionReferenceCache = {
    /**
     * A mapping of cache keys (containing both the key and value of a {@link ConversionReference}) to their corresponding
     * numeric IDs, if previously recorded.
     */
    readonly all: Record<string, number>;
    /**
     * A mapping of {@link ConversionReference} keys to their last recorded numeric ID, if any.
     */
    readonly last: Record<string, number>;
};
export {};