foremark
Version:
A technology for writing semi-plain text documents that extends upon the concept of Markdeep.
132 lines (131 loc) • 5.18 kB
TypeScript
export declare const enum InternalTagNames {
/**
* The tag name used for placeholders by `transformHtmlWith`. However,
* if the replaced node is an element, then the name of the element will be
* used instead.
*/
Placeholder = "mf-ph"
}
/**
* Constructors of DOM types;
*
* Node.js does not provide DOM types, so they must be supplied externally
* when we are in a Node.js environment.
*/
export declare let DomTypes: DomTypes;
export interface DomTypes {
Text: typeof Text;
Element: typeof Element;
HTMLElement: typeof HTMLElement;
}
export interface Dom extends DomTypes {
document: Document;
}
/**
* Specifies a DOM global object used for internal operations.
*
* You must call this function first if the library is being used in a Node.js
* environment.
*
* # Example
*
* import {JSDOM} from 'jsdom';
* const dom = new JSDOM('<html />', {
* contentType: 'application/xml',
* });
* setWorkingDom(dom.window);
*
*/
export declare function setWorkingDom(window: Dom): void;
/**
* Assuming `setWorkingDomUnchecked` already has been called, performs the
* sanity check that would be done by `setWorkingDom`.
*/
export declare function checkXhtml(): void;
export interface TransformHtmlWithContext {
/**
* Expands all placeholders in a given HTML markup.
*
* Note: Currently, only elements are expanded.
*/
expand(html: string): string;
}
export declare function isElement(node: Node | null | undefined): node is HTMLElement;
export declare function isText(node: Node | null | undefined): node is Text;
/**
* Transforms the HTML markup of a given node's contents using a supplied
* function.
*
* Before passing a HTML markup to a given function, this function protects
* child elements by replacing them with placeholders. A placeholder is a
* self-closing tag that looks like `<tagname ph-id="12345" />`. The tag name is
* identical to the original tag name (if the original node was an element), or
* `InternalTagNames.Placeholder` (otherwise).
*
* If `recursionFilter` is specified, the contents of a child element is
* transformed as well if the element matches the predicate specified by
* `recursionFilter`.
*/
export declare function transformHtmlWith(node: Element, tx: (s: string, ctx: TransformHtmlWithContext) => string, recursionFilter?: (e: Element) => boolean, reverse?: boolean): void;
/**
* Transforms the HTML markup of text nodes in a given node using a supplied
* function.
*
* The HTML markup of a text node is passed to `tx`. `tx` returns a transformed
* HTML markup, which may include other kinds of nodes.
*
* If `recursionFilter` is specified, the contents of a child element is
* transformed as well if the element matches the predicate specified by
* `recursionFilter`.
*
* This function is theoretically faster than `transformHtmlWith`. This function
* can be used in place of `transformHtmlWith` if:
*
* - Replaced substrings never include a XML element.
* - Replaced substrings are not insensitive to context such as line breaks and
* the start and end of an input string.
* - In addition, there are no sequences of two or more consecutive text nodes.
*
*/
export declare function transformTextNodeWith(node: Node, tx: (s: string) => string, recursionFilter: (e: Element) => boolean | void, reverse: boolean): void;
/**
* Iterate all nodes in pre-order using a callback function.
*
* Child nodes are not traversed if the callback function returns `false`.
*/
export declare function forEachNodePreorder(node: Node, f: (node: Node) => boolean | void): void;
/**
* Iterate all nodes in pre-order using a callback function. The iteration order
* of child nodes is reversed.
*
* Child nodes are not traversed if the callback function returns `false`.
*/
export declare function forEachNodeReversePreorder(node: Node, f: (node: Node) => boolean | void): void;
/**
* Attempts to fix malformed XML attributes.
*
* `attributeNames` specifies the list of other attributes used to reject
* duplicate attributes. Found attributes are added to `attributeNames`.
*
* Example: `legalizeAttributes(' a b="<>"')` returns `' a="a" b="<>"'`.
*
* # Positional attributes
*
* This function can automatically add a name to an attribute without one. The
* attribute names are chosen from `positionalAttributes`.
*/
export declare function legalizeAttributes(xml: string, attributeNames: string[], onwarning?: (message: string) => void, positionalAttributes?: ArrayLike<string>): string;
export declare function escapeXmlText(text: string): string;
export declare function unescapeXmlText(xml: string): string;
/**
* Attempts to fix malformed XML markup.
*
* This function is designed to only fix particular classes of errors found in
* wild, specifically:
*
* - SoundCloud's oEmbed response includes unescaped ampersands in
* attributes.
* - Vimeo's oEmbed response uses attribute value elision.
* - Facebook's oEmbed response includes unescaped ampersands in text contents.
*/
export declare function legalizeXML(xml: string, onwarning?: (message: string) => void): string;