mwn/build/wikitext.d.ts

JavaScript & TypeScript MediaWiki bot framework for Node.js

/**
 * Class for some basic wikitext parsing, involving
 * links, files, categories, templates and simple tables
 * and sections.
 *
 * For more advanced and sophisticated wikitext parsing, use
 * mwparserfromhell <https://github.com/earwig/mwparserfromhell>
 * implemented in python (which you can use within node.js using
 * the child_process interface). However, mwparserfromhell doesn't
 * recognize localised namespaces and wiki-specific configs.
 *
 * This class is for methods for parsing wikitext, for the
 * static methods for creating wikitext, see static_utils.js.
 */
import type { Mwn } from './bot';
import type { MwnTitle } from './title';
import type { ApiParseParams } from 'types-mediawiki-api';
export interface MwnWikitextStatic {
    new (text: string): MwnWikitext;
    /** Static version of {@link MwnWikitext.parseTemplates} */
    parseTemplates(wikitext: string, config: TemplateConfig): Template[];
    /**
     * Simple table parser.
     * Parses tables provided:
     *  1. It doesn't have any merged or joined cells.
     *  2. It doesn't use any templates to produce any table markup.
     *  3. Further restrictions may apply.
     *
     * Tables generated via mwn.Table() class are intended to be parsable.
     *
     * This method throws when it finds an inconsistency (rather than silently
     * cause undesired behaviour).
     *
     * @param {string} text
     * @returns {Object[]} - each object in the returned array represents a row,
     * with its keys being column names, and values the cell content
     */
    parseTable(text: string): {
        [column: string]: string;
    }[];
    /** Static version of {@link MwnWikitext.parseSections} */
    parseSections(text: string): Section[];
}
export interface MwnWikitext extends Unbinder {
    links: Array<PageLink>;
    templates: Array<Template>;
    files: Array<FileLink>;
    categories: Array<CategoryLink>;
    sections: Array<Section>;
    /** Parse links, file usages and categories from the wikitext */
    parseLinks(): void;
    /**
     * Parses templates from wikitext.
     * Returns an array of Template objects
     * ```js
     * let templates = parseTemplates("Hello {{foo |Bar|baz=qux |2=loremipsum|3=}} world");
     *  console.log(templates[0]); // gives:
     *		{
     *			name: "foo",
     *			wikitext:"{{foo |Bar|baz=qux | 2 = loremipsum  |3=}}",
     *			parameters: [ { name: 1, value: 'Bar', wikitext: '|Bar' },
     *				{ name: 'baz', value: 'qux', wikitext: '|baz=qux ' },
     *				{ name: '2', value: 'loremipsum', wikitext: '| 2 = loremipsum  ' },
     *				{ name: '3', value: '', wikitext: '|3=' }
     *			]
     *		}
     *```
     * @param {TemplateConfig} config
     * @returns {Template[]}
     */
    parseTemplates(config: TemplateConfig): Template[];
    /**
     * Remove a template, link, file or category from the text
     * CAUTION: If an entity with the very same wikitext exists earlier in the text,
     * that one will be removed instead.
     * @param {Object|Template} entity - anything with a wikitext attribute
     * and end index
     */
    removeEntity(entity: Link | Template): void;
    /**
     * Parse sections from wikitext
     * CAUTION: section header syntax in comments, nowiki tags,
     * pre, source or syntaxhighlight tags can lead to wrong results.
     * You're advised to run unbind() first.
     * @returns {Section[]} array of
     * section objects. Each section object has the level, header, index (of beginning) and content.
     * Content *includes* the equal signs and the header.
     * The top is represented as level 1, with header `null`.
     */
    parseSections(): Section[];
    /**
     * Parse the text using the API.
     * @see https://www.mediawiki.org/wiki/API:Parsing_wikitext
     * @param {Object} [options] - additional API options
     * @returns {Promise<string>}
     */
    apiParse(options: ApiParseParams): Promise<string>;
}
export interface Link {
    wikitext: string;
    target: MwnTitle;
}
export interface PageLink extends Link {
    displaytext: string;
}
export interface FileLink extends Link {
    props: string;
}
export interface CategoryLink extends Link {
    sortkey: string;
}
export interface Section {
    level: number;
    header: string | null;
    index: number;
    content: string;
}
/**
 * Configuration for parsing templates.
 */
export interface TemplateConfig {
    /**
     * Also parse templates within subtemplates. The other config parameters
     * (namePredicate, templatePredicate, count) are *not* compatible
     * with recursive mode. Expect unexpected results if used.
     */
    recursive?: boolean;
    /**
     * Include template in result only if its name matches this predicate.
     * More efficient than templatePredicate as the template parameters
     * aren't parsed if name didn't match.
     */
    namePredicate?: (name: string) => boolean;
    /**
     * Include template in result only if it matches this predicate
     */
    templatePredicate?: (template: Template) => boolean;
    /**
     * Max number of templates to be parsed
     */
    count?: number;
}
/**
 * Represents the wikitext of template transclusion. Used by {@link parseTemplates}.
 */
export declare class Template {
    /**
     * Full wikitext of the transclusion
     */
    wikitext: string;
    /**
     * Parameters used in the transclusion
     */
    parameters: Array<Parameter>;
    /**
     * Name of the template
     */
    name: string | number;
    /**
     * @param {String} wikitext Wikitext of a template transclusion,
     * starting with '{{' and ending with '}}'.
     */
    constructor(wikitext: string);
    addParam(name: string | number, val: string, wikitext: string): void;
    getParam(paramName: string | number): Parameter;
    getValue(paramName: string | number): string | null;
    setName(name: string): void;
}
/**
 * Represents a template parameter
 */
export declare class Parameter {
    /**
     * parameter name, or position for unnamed parameters
     */
    name: string | number;
    /**
     * Wikitext passed to the parameter (whitespace trimmed)
     */
    value: string;
    /**
     * Full wikitext (including leading pipe, parameter name/equals sign (if applicable), value, and any whitespace)
     */
    wikitext: string;
    constructor(name: string | number, val: string, wikitext: string);
}
/** See {@link MwnWikitext.parseTemplates} */
export declare function parseTemplates(wikitext: string, config?: TemplateConfig): Template[];
/** See {@link MwnWikitextStatic.parseTable} */
export declare function parseTable(text: string): {
    [column: string]: string;
}[];
/** See {@link MwnWikitext.parseSections} */
export declare function parseSections(text: string): Section[];
export declare class Unbinder {
    text: string;
    constructor(text: string);
    private unbinder;
    /**
     * Temporarily hide a part of the string while processing the rest of it.
     *
     * eg.  let u = new bot.Wikitext("Hello world <!-- world --> world");
     *      u.unbind('<!--','-->');
     *      u.content = u.content.replace(/world/g, 'earth');
     *      u.rebind(); // gives "Hello earth <!-- world --> earth"
     *
     * Text within the 'unbinded' part (in this case, the HTML comment) remains intact
     * unbind() can be called multiple times to unbind multiple parts of the string.
     *
     * @param {string} prefix
     * @param {string} postfix
     */
    unbind(prefix: string, postfix: string): void;
    /**
     * Rebind after unbinding.
     */
    rebind(): string;
    /** Get the updated text */
    getText(): string;
}
export default function (bot: Mwn): MwnWikitextStatic;