@rgrove/parse-xml 3.0.0 → 4.0.1

package/dist/lib/Parser.d.ts

@@ -0,0 +1,218 @@
+import { XmlDocument } from './XmlDocument.js';
+import type { XmlNode } from './XmlNode.js';
+/**
+ * Parses an XML string into an `XmlDocument`.
+ *
+ * @private
+ */
+export declare class Parser {
+    readonly document: XmlDocument;
+    private currentNode;
+    private readonly options;
+    private readonly scanner;
+    /**
+     * @param xml XML string to parse.
+     * @param options Parser options.
+     */
+    constructor(xml: string, options?: ParserOptions);
+    /**
+     * Adds the given `XmlNode` as a child of `this.currentNode`.
+     */
+    addNode(node: XmlNode): void;
+    /**
+     * Adds the given _text_ to the document, either by appending it to a
+     * preceding `XmlText` node (if possible) or by creating a new `XmlText` node.
+     */
+    addText(text: string): void;
+    /**
+     * Consumes element attributes.
+     *
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-starttags
+     */
+    consumeAttributes(): Record<string, string>;
+    /**
+     * Consumes an `AttValue` (attribute value) if possible.
+     *
+     * @returns
+     *   Contents of the `AttValue` minus quotes, or `false` if nothing was
+     *   consumed. An empty string indicates that an `AttValue` was consumed but
+     *   was empty.
+     *
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-AttValue
+     */
+    consumeAttributeValue(): string | false;
+    /**
+     * Consumes a CDATA section if possible.
+     *
+     * @returns Whether a CDATA section was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-cdata-sect
+     */
+    consumeCdataSection(): boolean;
+    /**
+     * Consumes character data if possible.
+     *
+     * @returns Whether character data was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#dt-chardata
+     */
+    consumeCharData(): boolean;
+    /**
+     * Consumes a comment if possible.
+     *
+     * @returns Whether a comment was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Comment
+     */
+    consumeComment(): boolean;
+    /**
+     * Consumes a reference in a content context if possible.
+     *
+     * This differs from `consumeReference()` in that a consumed reference will be
+     * added to the document as a text node instead of returned.
+     *
+     * @returns Whether a reference was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#entproc
+     */
+    consumeContentReference(): boolean;
+    /**
+     * Consumes a doctype declaration if possible.
+     *
+     * This is a loose implementation since doctype declarations are currently
+     * discarded without further parsing.
+     *
+     * @returns Whether a doctype declaration was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#dtd
+     */
+    consumeDoctypeDeclaration(): boolean;
+    /**
+     * Consumes an element if possible.
+     *
+     * @returns Whether an element was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-element
+     */
+    consumeElement(): boolean;
+    /**
+     * Consumes an `Eq` production if possible.
+     *
+     * @returns Whether an `Eq` production was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Eq
+     */
+    consumeEqual(): boolean;
+    /**
+     * Consumes `Misc` content if possible.
+     *
+     * @returns Whether anything was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Misc
+     */
+    consumeMisc(): boolean;
+    /**
+     * Consumes one or more `Name` characters if possible.
+     *
+     * @returns `Name` characters, or an empty string if none were consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Name
+     */
+    consumeName(): string;
+    /**
+     * Consumes a processing instruction if possible.
+     *
+     * @returns Whether a processing instruction was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-pi
+     */
+    consumeProcessingInstruction(): boolean;
+    /**
+     * Consumes a prolog if possible.
+     *
+     * @returns Whether a prolog was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-prolog-dtd
+     */
+    consumeProlog(): boolean;
+    /**
+     * Consumes a reference if possible.
+     *
+     * This differs from `consumeContentReference()` in that a consumed reference
+     * will be returned rather than added to the document.
+     *
+     * @returns
+     *   Parsed reference value, or `false` if nothing was consumed (to
+     *   distinguish from a reference that resolves to an empty string).
+     *
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Reference
+     */
+    consumeReference(): string | false;
+    /**
+     * Consumes a `SystemLiteral` if possible.
+     *
+     * A `SystemLiteral` is similar to an attribute value, but allows the
+     * characters `<` and `&` and doesn't replace references.
+     *
+     * @returns
+     *   Value of the `SystemLiteral` minus quotes, or `false` if nothing was
+     *   consumed. An empty string indicates that a `SystemLiteral` was consumed
+     *   but was empty.
+     *
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-SystemLiteral
+     */
+    consumeSystemLiteral(): string | false;
+    /**
+     * Consumes one or more whitespace characters if possible.
+     *
+     * @returns Whether any whitespace characters were consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#white
+     */
+    consumeWhitespace(): boolean;
+    /**
+     * Consumes an XML declaration if possible.
+     *
+     * @returns Whether an XML declaration was consumed.
+     * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-XMLDecl
+     */
+    consumeXmlDeclaration(): boolean;
+    /**
+     * Throws an error at the current scanner position.
+     */
+    error(message: string): Error;
+    /**
+     * Throws an invalid character error if any character in the given _string_
+     * isn't a valid XML character.
+     */
+    validateChars(string: string): void;
+}
+export declare type ParserOptions = {
+    /**
+     * When `true`, an undefined named entity (like "&bogus;") will be left in the
+     * output as is instead of causing a parse error.
+     *
+     * @default false
+     */
+    ignoreUndefinedEntities?: boolean;
+    /**
+     * When `true`, CDATA sections will be preserved in the document as `XmlCdata`
+     * nodes. Otherwise CDATA sections will be represented as `XmlText` nodes,
+     * which keeps the node tree simpler and easier to work with.
+     *
+     * @default false
+     */
+    preserveCdata?: boolean;
+    /**
+     * When `true`, comments will be preserved in the document as `XmlComment`
+     * nodes. Otherwise comments will not be included in the node tree.
+     *
+     * @default false
+     */
+    preserveComments?: boolean;
+    /**
+     * When an undefined named entity is encountered, this function will be called
+     * with the entity as its only argument. It should return a string value with
+     * which to replace the entity, or `null` or `undefined` to treat the entity
+     * as undefined (which may result in a parse error depending on the value of
+     * `ignoreUndefinedEntities`).
+     */
+    resolveUndefinedEntity?: (entity: string) => string | null | undefined;
+    /**
+     * When `true`, attributes in an element's `attributes` object will be sorted
+     * in alphanumeric order by name. Otherwise they'll retain their original
+     * order as found in the XML.
+     *
+     * @default false
+     */
+    sortAttributes?: boolean;
+};
+//# sourceMappingURL=Parser.d.ts.map

package/dist/lib/Parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Parser.d.ts","sourceRoot":"","sources":["../../src/lib/Parser.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAK/C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAK5C;;;;GAIG;AACH,qBAAa,MAAM;IACjB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAE/B,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC;;;OAGG;gBACS,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB;IAmBpD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,OAAO;IASrB;;;OAGG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM;IAkBpB;;;;OAIG;IACH,iBAAiB,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC;IA6C3C;;;;;;;;;OASG;IACH,qBAAqB,IAAI,MAAM,GAAG,KAAK;IAkDvC;;;;;OAKG;IACH,mBAAmB,IAAI,OAAO;IAuB9B;;;;;OAKG;IACH,eAAe,IAAI,OAAO;IAkB1B;;;;;OAKG;IACH,cAAc,IAAI,OAAO;IAyBzB;;;;;;;;OAQG;IACH,uBAAuB,IAAI,OAAO;IAWlC;;;;;;;;OAQG;IACH,yBAAyB,IAAI,OAAO;IAsBpC;;;;;OAKG;IACH,cAAc,IAAI,OAAO;IA8DzB;;;;;OAKG;IACH,YAAY,IAAI,OAAO;IAWvB;;;;;OAKG;IACH,WAAW,IAAI,OAAO;IAMtB;;;;;OAKG;IACH,WAAW,IAAI,MAAM;IAMrB;;;;;OAKG;IACH,4BAA4B,IAAI,OAAO;IAuCvC;;;;;OAKG;IACH,aAAa,IAAI,OAAO;IAexB;;;;;;;;;;;OAWG;IACH,gBAAgB,IAAI,MAAM,GAAG,KAAK;IAoElC;;;;;;;;;;;;OAYG;IACH,oBAAoB,IAAI,MAAM,GAAG,KAAK;IAkBtC;;;;;OAKG;IACH,iBAAiB,IAAI,OAAO;IAI5B;;;;;OAKG;IACH,qBAAqB,IAAI,OAAO;IAkDhC;;OAEG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM;IAuDrB;;;OAGG;IACH,aAAa,CAAC,MAAM,EAAE,MAAM;CAgB7B;AAiBD,oBAAY,aAAa,GAAG;IAC1B;;;;;OAKG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAElC;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAE3B;;;;;;OAMG;IACH,sBAAsB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IAEvE;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC"}