@patrickdk77/office-defuse 0.0.0-stage → 0.1.0

package/dist/xml.d.ts

@@ -0,0 +1,256 @@
+export declare const XML_NS = "http://www.w3.org/XML/1998/namespace";
+export declare const XMLNS_NS = "http://www.w3.org/2000/xmlns/";
+/**
+ * Stands in text for a reference to an external entity, whose content office-defuse never fetches: UNKNOWN, the
+ * entity's name, UNKNOWN again. U+FFFF cannot occur in XML, so nothing a part holds is taken for it.
+ */
+export declare const UNKNOWN: string;
+/** A value with each reference to an external entity written back as `&name;`, for a finding to show. */
+export declare const showReferences: (s: string) => string;
+/** The name of the first external entity whose content stands in `s`, or undefined when none does. */
+export declare const unknownEntity: (s: string) => string | undefined;
+export interface XmlAttribute {
+    /** Namespace URI, '' for none. */
+    ns: string;
+    local: string;
+    qname: string;
+    /** Normalized value, with references expanded. An attribute-list declaration can give it a default or normalize it further. */
+    value: string;
+}
+export interface XmlElement {
+    /** Namespace URI, '' for none. */
+    ns: string;
+    local: string;
+    qname: string;
+    /** Attributes other than namespace declarations. */
+    attributes: XmlAttribute[];
+    /** 1 for the root element. */
+    depth: number;
+    /**
+     * Offsets of the start tag in the decoded text, end exclusive. An element from an entity's text has the offsets of
+     * the reference to that entity in the part, or of the outermost one when references nest.
+     */
+    start: number;
+    end: number;
+}
+export interface XmlHandler {
+    start?(el: XmlElement): void;
+    /** `start` and `end` are the offsets of the end tag, or of the start tag again for an empty element. */
+    end?(el: XmlElement, start: number, end: number): void;
+    /** Character data and CDATA content, decoded, in pieces of any size. A reference to an external entity comes as one piece. */
+    text?(text: string): void;
+}
+export interface XmlLimits {
+    depth: number;
+    tokenSize: number;
+    /** Entity references nested inside entity text. */
+    entityDepth: number;
+    /** Entity references expanded, counted in the budget. */
+    entityExpansions: number;
+    /** Characters of entity text expanded, counted in the budget. */
+    entitySize: number;
+}
+/** Entity expansion so far. One inspection shares it among its parts, so the limits bound the whole package. */
+export interface EntityBudget {
+    expansions: number;
+    size: number;
+}
+/** A document type declaration. */
+export interface XmlDoctype {
+    /** The root element type it names. */
+    name: string;
+    publicId?: string;
+    systemId?: string;
+    /** Whether it has an internal subset, declarations between square brackets. */
+    internalSubset: boolean;
+    /** General entities the internal subset declares, and how many of them are external. */
+    entities: number;
+    externalEntities: number;
+    /** Attribute defaults the internal subset declares. */
+    attributeDefaults: number;
+    /** Entity and attribute-list declarations skipped after a parameter entity that was not read. */
+    skipped: number;
+    /** Offsets of the declaration in the decoded text, end exclusive. */
+    start: number;
+    end: number;
+}
+/** A reference to an external entity in content, which is never fetched. */
+export interface XmlExternalReference {
+    name: string;
+    publicId?: string;
+    systemId: string;
+    /** Offsets of the reference in the decoded text, or of the outermost reference whose entity text holds it. */
+    start: number;
+    end: number;
+}
+/** What the tokenizer reports besides elements and text. */
+export interface XmlNotes {
+    doctype?(d: XmlDoctype): void;
+    externalEntity?(r: XmlExternalReference): void;
+}
+export interface XmlOptions {
+    /** Reads the dialect Office writes in VML drawing parts. See XmlTokenizer. */
+    vml?: boolean;
+    notes?: XmlNotes;
+    /** Shared with the other parts of a package. A tokenizer without one counts on its own. */
+    budget?: EntityBudget;
+}
+/** The value of the attribute with this namespace and local name. */
+export declare function attr(el: XmlElement, ns: string, local: string): string | undefined;
+/** An XML name without a colon. */
+export declare const isNcName: (s: string) => boolean;
+/**
+ * A streaming XML 1.0 tokenizer with namespaces. It refuses references to entities nothing declares, encodings other
+ * than UTF-8 and UTF-16, and anything not well-formed. It holds one markup token at a time; text goes to the handler
+ * in pieces.
+ *
+ * A document type declaration goes to `notes.doctype`. No external DTD or other external entity is ever loaded. The
+ * internal subset is read as XML 1.0 (5.1) has a processor read it that reads internal parameter entities and no
+ * external ones: it keeps the general entities and attribute-list declarations, reads the text of each internal
+ * parameter entity it refers to, and skips the entity and attribute-list declarations after a parameter entity it
+ * does not read, unless the XML declaration says standalone="yes".
+ *
+ * A reference to an internal entity is expanded, within the entity limits, and the handler sees its text, markup
+ * included, as if the part held it. A reference to an external entity in content goes to `notes.externalEntity`, and
+ * stands in the text as UNKNOWN marks it. One in an attribute value, directly or through other entities, is refused,
+ * as XML 1.0 refuses it. An attribute an element leaves out gets the default its attribute-list declaration gives, and
+ * an attribute declared with a type other than CDATA is normalized further, as expat does. Each default added counts
+ * as an expansion against the entity limits.
+ */
+export declare class XmlTokenizer {
+    private readonly handler;
+    private readonly limits;
+    private readonly part;
+    private decoder?;
+    private head;
+    private buf;
+    private pos;
+    /** Offset in the decoded text of buf[0]. */
+    private base;
+    private readonly stack;
+    private rootSeen;
+    private doctypeSeen;
+    /** The XML declaration says standalone="yes". */
+    private standalone;
+    private encoding;
+    /** The last text piece ended in CR, so an LF that starts the next piece belongs to the same line end. */
+    private lastCr;
+    private scan?;
+    /** General entities the internal subset declares, by name. */
+    private readonly entities;
+    /** Parameter entities the internal subset declares, by name. */
+    private readonly parameters;
+    /** What the attribute-list declarations say, by element type as written. */
+    private readonly declared;
+    /** The entities being expanded, outermost first. A parameter entity's name has "%" in front. */
+    private readonly active;
+    /** While entity text is read, the offsets of the outermost reference, which its elements report. */
+    private span?;
+    /** The stack depth at which the entity text being read started. Its end tags close nothing below it. */
+    private floor;
+    private readonly vml;
+    private readonly notes;
+    private readonly budget;
+    /**
+     * `options.vml` reads the dialect Office writes in VML drawing parts, which is not well-formed XML: it skips the
+     * `<![if ...]>` and `<![endif]>` markers around content and takes an unclosed `<br>` as an empty element. Both
+     * branches of a marker reach the handler.
+     */
+    constructor(handler: XmlHandler, limits: XmlLimits, part: string, options?: XmlOptions);
+    private stop;
+    private malformed;
+    write(bytes: Uint8Array): void;
+    end(): void;
+    /** Picks the encoding from the first bytes, as XML 1.0 Appendix F does, and reads the bytes held so far. */
+    private begin;
+    private decode;
+    /** Checks the XML declaration against the encoding the bytes are in, and notes whether it says standalone="yes". */
+    private declaration;
+    private feed;
+    /** Reads the text and markup in buf from pos. Entity text is read with `final` set, since all of it is there. */
+    private loop;
+    /** The offset in the decoded text of buf[i], or while entity text is read, that of the reference to it. */
+    private at;
+    /**
+     * Character data at `offset` in the decoded text. References are expanded and line ends turned into LF. Entity
+     * text had its line ends normalized where it was declared, so a CR in it, which only a character reference makes,
+     * stays.
+     */
+    private text;
+    /** Hands decoded text to the handler. Outside the root element only white space may stand. */
+    private characters;
+    /**
+     * Normalizes an attribute value as XML 1.0 (3.3.3) says: references expanded, and each white space character a
+     * space, except one written as a character reference. `normalized` marks entity text, whose line ends were
+     * normalized where it was declared, so a CR and LF in it are two characters.
+     */
+    private attributeValue;
+    /** The text a predefined entity or a character reference stands for, or undefined for any other entity. */
+    private plainReference;
+    private characterReference;
+    /** The entity a reference names. A reference to one nothing declares is refused. */
+    private entity;
+    /** Starts expanding an entity, within the limits. */
+    private enter;
+    /**
+     * Counts one expansion of `size` characters of declared text, an entity's or an attribute default's, against the
+     * limits, so a document type cannot make the part cost more than they allow.
+     */
+    private charge;
+    /** A reference to a general entity in content. Its text is read as content, in place of the reference. */
+    private contentReference;
+    /** A reference to a general entity in an attribute value. Its text is normalized into the value. */
+    private attributeReference;
+    /** Reads one markup token at pos. Returns false when the buffer does not yet hold all of it. */
+    private markup;
+    private wait;
+    private advance;
+    private checkChars;
+    private instruction;
+    /**
+     * Finds the end of the document type declaration at p: the ">" outside its literals and its internal subset, where
+     * comments, processing instructions and declarations may hold either. Returns the offset after it, or -1 when buf
+     * does not hold all of it yet. The scan goes on from where it stopped.
+     */
+    private scanDoctype;
+    /** Reads a whole document type declaration, keeping the entities and attributes its internal subset declares. */
+    private doctype;
+    /** SYSTEM and a system literal, or PUBLIC and a public and a system literal, or undefined when neither is next. */
+    private externalId;
+    /**
+     * Reads markup declarations: the internal subset up to and past its "]", or with `nested` the whole text of a
+     * parameter entity.
+     */
+    private declarations;
+    /**
+     * A parameter entity reference between declarations. An internal entity's text is read as declarations, with a
+     * space on each side as XML 1.0 (4.4.8) says. An external or undeclared one is not read, and the entity and
+     * attribute-list declarations after it are skipped, since it could have declared the same names first.
+     */
+    private parameterReference;
+    /**
+     * Reads an entity declaration after its keyword, and keeps the entity unless it comes after a parameter entity that
+     * was not read, or gives one of the predefined names, or a name already declared: the first declaration binds.
+     */
+    private entityDeclaration;
+    /**
+     * The text an entity value expands to: line ends normalized, unless `normalized` says they were, and character
+     * references replaced. References to general entities stay as written, to be expanded where the entity is used. A
+     * parameter entity reference cannot stand inside a declaration in the internal subset.
+     */
+    private entityValue;
+    /**
+     * Reads an attribute-list declaration after its keyword. Each attribute it names for the first time is kept, with
+     * its default normalized now, as the entities declared so far give it. After a parameter entity that was not read,
+     * the declaration is skipped.
+     */
+    private attributeListDeclaration;
+    /** Reads an attribute type and tells whether its values are tokens, normalized further than CDATA. */
+    private attributeType;
+    /** An enumerated type: name tokens between parentheses, separated by "|". */
+    private enumeration;
+    private lookup;
+    private split;
+    private startTag;
+    private endTag;
+}