@rgrove/parse-xml 3.0.0 → 4.0.1

package/src/lib/StringScanner.ts

@@ -0,0 +1,254 @@
+const emptyString = '';
+const surrogatePair = /[\uD800-\uDBFF][\uDC00-\uDFFF]/g;
+
+/** @private */
+export class StringScanner {
+  charIndex: number;
+  readonly string: string;
+
+  private readonly charCount: number;
+  private readonly charsToBytes: number[] | undefined;
+  private readonly length: number;
+  private readonly multiByteMode: boolean;
+
+  constructor(string: string) {
+    this.charCount = this.charLength(string, true);
+    this.charIndex = 0;
+    this.length = string.length;
+    this.multiByteMode = this.charCount !== this.length;
+    this.string = string;
+
+    if (this.multiByteMode) {
+      let charsToBytes = [];
+
+      // Create a mapping of character indexes to byte indexes. Since the string
+      // contains multibyte characters, a byte index may not necessarily align
+      // with a character index.
+      for (let byteIndex = 0, charIndex = 0; charIndex < this.charCount; ++charIndex) {
+        charsToBytes[charIndex] = byteIndex;
+        byteIndex += (string.codePointAt(byteIndex) as number) > 65535 ? 2 : 1;
+      }
+
+      this.charsToBytes = charsToBytes;
+    }
+  }
+
+  /**
+   * Whether the current character index is at the end of the input string.
+   */
+  get isEnd() {
+    return this.charIndex >= this.charCount;
+  }
+
+  // -- Protected Methods ------------------------------------------------------
+
+  /**
+   * Returns the byte index of the given character index in the string. The two
+   * may differ in strings that contain multibyte characters.
+   */
+  protected charIndexToByteIndex(charIndex: number = this.charIndex): number {
+    return this.multiByteMode
+      ? (this.charsToBytes as number[])[charIndex] ?? Infinity
+      : charIndex;
+  }
+
+  /**
+   * Returns the number of characters in the given string, which may differ from
+   * the byte length if the string contains multibyte characters.
+   */
+  protected charLength(string: string, multiByteSafe = this.multiByteMode): number {
+    // We could get the char length with `[ ...string ].length`, but that's
+    // actually slower than replacing surrogate pairs with single-byte
+    // characters and then counting the result.
+    return multiByteSafe
+      ? string.replace(surrogatePair, '_').length
+      : string.length;
+  }
+
+  // -- Public Methods ---------------------------------------------------------
+
+  /**
+   * Advances the scanner by the given number of characters, stopping if the end
+   * of the string is reached.
+   */
+  advance(count = 1) {
+    this.charIndex = Math.min(this.charCount, this.charIndex + count);
+  }
+
+  /**
+   * Consumes and returns the given number of characters if possible, advancing
+   * the scanner and stopping if the end of the string is reached.
+   *
+   * If no characters could be consumed, an empty string will be returned.
+   */
+  consume(count = 1): string {
+    let chars = this.peek(count);
+    this.advance(count);
+    return chars;
+  }
+
+  /**
+   * Consumes a match for the given sticky regex, advances the scanner, updates
+   * the `lastIndex` property of the regex, and returns the matching string.
+   *
+   * The regex must have a sticky flag ("y") so that its `lastIndex` prop can be
+   * used to anchor the match at the current scanner position.
+   *
+   * Returns the consumed string, or an empty string if nothing was consumed.
+   */
+  consumeMatch(regex: RegExp): string {
+    if (!regex.sticky) {
+      throw new Error('`regex` must have a sticky flag ("y")');
+    }
+
+    regex.lastIndex = this.charIndexToByteIndex();
+
+    let result = regex.exec(this.string);
+
+    if (result === null || result.length === 0) {
+      return emptyString;
+    }
+
+    let match = result[0] as string;
+    this.advance(this.charLength(match));
+    return match;
+  }
+
+  /**
+   * Consumes and returns all characters for which the given function returns a
+   * truthy value, stopping on the first falsy return value or if the end of the
+   * input is reached.
+   */
+  consumeMatchFn(fn: (char: string) => boolean): string {
+    let char;
+    let match = emptyString;
+
+    while ((char = this.peek()) && fn(char)) {
+      match += char;
+      this.advance();
+    }
+
+    return match;
+  }
+
+  /**
+   * Consumes the given string if it exists at the current character index, and
+   * advances the scanner.
+   *
+   * If the given string doesn't exist at the current character index, an empty
+   * string will be returned and the scanner will not be advanced.
+   */
+  consumeString(stringToConsume: string): string {
+    if (this.consumeStringFast(stringToConsume)) {
+      return stringToConsume;
+    }
+
+    if (this.multiByteMode) {
+      let { length } = stringToConsume;
+      let charLengthToMatch = this.charLength(stringToConsume);
+
+      if (charLengthToMatch !== length
+          && stringToConsume === this.peek(charLengthToMatch)) {
+
+        this.advance(charLengthToMatch);
+        return stringToConsume;
+      }
+    }
+
+    return emptyString;
+  }
+
+  /**
+   * Does the same thing as `consumeString()`, but doesn't support consuming
+   * multibyte characters. This can be faster if you only need to match single
+   * byte characters.
+   */
+  consumeStringFast(stringToConsume: string): string {
+    let { length } = stringToConsume;
+
+    if (this.peek(length) === stringToConsume) {
+      this.advance(length);
+      return stringToConsume;
+    }
+
+    return emptyString;
+  }
+
+  /**
+   * Consumes characters until the given global regex is matched, advancing the
+   * scanner up to (but not beyond) the beginning of the match. If the regex
+   * doesn't match, nothing will be consumed.
+   *
+   * Returns the consumed string, or an empty string if nothing was consumed.
+   */
+  consumeUntilMatch(regex: RegExp): string {
+    let restOfString = this.string.slice(this.charIndexToByteIndex());
+    let matchByteIndex = restOfString.search(regex);
+
+    if (matchByteIndex <= 0) {
+      return emptyString;
+    }
+
+    let result = restOfString.slice(0, matchByteIndex);
+    this.advance(this.charLength(result));
+    return result;
+  }
+
+  /**
+   * Consumes characters until the given string is found, advancing the scanner
+   * up to (but not beyond) that point. If the string is never found, nothing
+   * will be consumed.
+   *
+   * Returns the consumed string, or an empty string if nothing was consumed.
+   */
+  consumeUntilString(searchString: string): string {
+    let { string } = this;
+    let byteIndex = this.charIndexToByteIndex();
+    let matchByteIndex = string.indexOf(searchString, byteIndex);
+
+    if (matchByteIndex <= 0) {
+      return emptyString;
+    }
+
+    let result = string.slice(byteIndex, matchByteIndex);
+    this.advance(this.charLength(result));
+    return result;
+  }
+
+  /**
+   * Returns the given number of characters starting at the current character
+   * index, without advancing the scanner and without exceeding the end of the
+   * input string.
+   */
+  peek(count = 1): string {
+    let { charIndex, multiByteMode, string } = this;
+
+    if (multiByteMode) {
+      // Inlining this comparison instead of checking `this.isEnd` improves perf
+      // slightly since `peek()` is called so frequently.
+      if (charIndex >= this.charCount) {
+        return emptyString;
+      }
+
+      return string.slice(
+        this.charIndexToByteIndex(charIndex),
+        this.charIndexToByteIndex(charIndex + count),
+      );
+    }
+
+    return string.slice(charIndex, charIndex + count);
+  }
+
+  /**
+   * Resets the scanner position to the given character _index_, or to the start
+   * of the input string if no index is given.
+   *
+   * If _index_ is negative, the scanner position will be moved backward by that
+   * many characters, stopping if the beginning of the string is reached.
+   */
+  reset(index = 0) {
+    this.charIndex = index >= 0
+      ? Math.min(this.charCount, index)
+      : Math.max(0, this.charIndex + index);
+  }
+}

package/src/lib/XmlCdata.ts

@@ -0,0 +1,11 @@
+import { XmlNode } from './XmlNode.js';
+import { XmlText } from './XmlText.js';
+
+/**
+ * A CDATA section within an XML document.
+ */
+export class XmlCdata extends XmlText {
+  override get type() {
+    return XmlNode.TYPE_CDATA;
+  }
+}

package/src/lib/XmlComment.ts

@@ -0,0 +1,26 @@
+import { XmlNode } from './XmlNode.js';
+
+/**
+ * A comment within an XML document.
+ */
+export class XmlComment extends XmlNode {
+  /**
+   * Content of this comment.
+   */
+  content: string;
+
+  constructor(content = '') {
+    super();
+    this.content = content;
+  }
+
+  override get type() {
+    return XmlNode.TYPE_COMMENT;
+  }
+
+  override toJSON() {
+    return Object.assign(XmlNode.prototype.toJSON.call(this), {
+      content: this.content,
+    });
+  }
+}

package/src/lib/XmlDocument.ts

@@ -0,0 +1,57 @@
+import { XmlElement } from './XmlElement.js';
+import { XmlNode } from './XmlNode.js';
+
+import type { XmlComment } from './XmlComment.js';
+import type { XmlProcessingInstruction } from './XmlProcessingInstruction.js';
+
+/**
+ * Represents an XML document. All elements within the document are descendants
+ * of this node.
+ */
+export class XmlDocument extends XmlNode {
+  /**
+   * Child nodes of this document.
+   */
+  readonly children: Array<XmlComment | XmlProcessingInstruction | XmlElement>;
+
+  constructor(children: Array<XmlComment | XmlElement | XmlProcessingInstruction> = []) {
+    super();
+    this.children = children;
+  }
+
+  override get document() {
+    return this;
+  }
+
+  /**
+   * Root element of this document, or `null` if this document is empty.
+   */
+  get root(): XmlElement | null {
+    for (let child of this.children) {
+      if (child instanceof XmlElement) {
+        return child;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Text content of this document and all its descendants.
+   */
+  get text(): string {
+    return this.children
+      .map(child => 'text' in child ? child.text : '')
+      .join('');
+  }
+
+  override get type() {
+    return XmlNode.TYPE_DOCUMENT;
+  }
+
+  override toJSON() {
+    return Object.assign(XmlNode.prototype.toJSON.call(this), {
+      children: this.children.map(child => child.toJSON()),
+    });
+  }
+}

package/src/lib/XmlElement.ts

@@ -0,0 +1,81 @@
+import { XmlNode } from './XmlNode.js';
+
+import type { JsonObject } from './types.js';
+import type { XmlCdata } from './XmlCdata.js';
+import type { XmlComment } from './XmlComment.js';
+import type { XmlProcessingInstruction } from './XmlProcessingInstruction.js';
+import type { XmlText } from './XmlText.js';
+
+/**
+ * Element in an XML document.
+ */
+export class XmlElement extends XmlNode {
+  /**
+   * Attributes on this element.
+   */
+  attributes: {[attrName: string]: string};
+
+  /**
+   * Child nodes of this element.
+   */
+  children: Array<XmlCdata | XmlComment | XmlElement | XmlProcessingInstruction | XmlText>;
+
+  /**
+   * Name of this element.
+   */
+  name: string;
+
+  constructor(
+    name: string,
+    attributes: {[attrName: string]: string} = Object.create(null),
+    children: Array<XmlCdata | XmlComment | XmlElement | XmlProcessingInstruction | XmlText> = [],
+  ) {
+    super();
+
+    this.name = name;
+    this.attributes = attributes;
+    this.children = children;
+  }
+
+  /**
+   * Whether this element is empty (meaning it has no children).
+   */
+  get isEmpty(): boolean {
+    return this.children.length === 0;
+  }
+
+  override get preserveWhitespace(): boolean {
+    let node: XmlNode | null = this; // eslint-disable-line @typescript-eslint/no-this-alias
+
+    while (node instanceof XmlElement) {
+      if ('xml:space' in node.attributes) {
+        return node.attributes['xml:space'] === 'preserve';
+      }
+
+      node = node.parent;
+    }
+
+    return false;
+  }
+
+  /**
+   * Text content of this element and all its descendants.
+   */
+  get text(): string {
+    return this.children
+      .map(child => 'text' in child ? child.text : '')
+      .join('');
+  }
+
+  override get type() {
+    return XmlNode.TYPE_ELEMENT;
+  }
+
+  override toJSON(): JsonObject {
+    return Object.assign(XmlNode.prototype.toJSON.call(this), {
+      name: this.name,
+      attributes: this.attributes,
+      children: this.children.map(child => child.toJSON()),
+    });
+  }
+}

package/src/lib/XmlNode.ts

@@ -0,0 +1,107 @@
+import type { JsonObject } from './types.js';
+import type { XmlDocument } from './XmlDocument.js';
+import type { XmlElement } from './XmlElement.js';
+
+/**
+ * Base interface for a node in an XML document.
+ */
+export class XmlNode {
+  /**
+   * Type value for an `XmlCdata` node.
+   */
+  static readonly TYPE_CDATA = 'cdata';
+
+  /**
+   * Type value for an `XmlComment` node.
+   */
+  static readonly TYPE_COMMENT = 'comment';
+
+  /**
+   * Type value for an `XmlDocument` node.
+   */
+  static readonly TYPE_DOCUMENT = 'document';
+
+  /**
+   * Type value for an `XmlElement` node.
+   */
+  static readonly TYPE_ELEMENT = 'element';
+
+  /**
+   * Type value for an `XmlProcessingInstruction` node.
+   */
+  static readonly TYPE_PROCESSING_INSTRUCTION = 'pi';
+
+  /**
+   * Type value for an `XmlText` node.
+   */
+  static readonly TYPE_TEXT = 'text';
+
+  /**
+   * Parent node of this node, or `null` if this node has no parent.
+   */
+  parent: XmlDocument | XmlElement | null = null;
+
+  /**
+   * Document that contains this node, or `null` if this node is not associated
+   * with a document.
+   */
+  get document(): XmlDocument | null {
+    return this.parent?.document ?? null;
+  }
+
+  /**
+   * Whether this node is the root node of the document.
+   */
+  get isRootNode(): boolean {
+    return this.parent !== null && this.parent === this.document;
+  }
+
+  /**
+   * Whether whitespace should be preserved in the content of this element and
+   * its children.
+   *
+   * This is influenced by the value of the special `xml:space` attribute, and
+   * will be `true` for any node whose `xml:space` attribute is set to
+   * "preserve". If a node has no such attribute, it will inherit the value of
+   * the nearest ancestor that does (if any).
+   *
+   * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-white-space
+   */
+  get preserveWhitespace(): boolean {
+    return Boolean(this.parent?.preserveWhitespace);
+  }
+
+  /**
+   * Type of this node.
+   *
+   * The value of this property is a string that matches one of the static
+   * `TYPE_*` properties on the `XmlNode` class (e.g. `TYPE_ELEMENT`,
+   * `TYPE_TEXT`, etc.).
+   *
+   * The `XmlNode` class itself is a base class and doesn't have its own type
+   * name.
+   */
+  get type() {
+    return '';
+  }
+
+  /**
+   * Returns a JSON-serializable object representing this node, minus properties
+   * that could result in circular references.
+   */
+  toJSON(): JsonObject {
+    let json: JsonObject = {
+      type: this.type,
+    };
+
+    if (this.isRootNode) {
+      json.isRootNode = true;
+    }
+
+    if (this.preserveWhitespace) {
+      json.preserveWhitespace = true;
+    }
+
+    return json;
+  }
+}

package/src/lib/XmlProcessingInstruction.ts

@@ -0,0 +1,35 @@
+import { XmlNode } from './XmlNode.js';
+
+/**
+ * A processing instruction within an XML document.
+ */
+export class XmlProcessingInstruction extends XmlNode {
+  /**
+   * Content of this processing instruction.
+   */
+  content: string;
+
+  /**
+   * Name of this processing instruction. Also sometimes referred to as the
+   * processing instruction "target".
+   */
+  name: string;
+
+  constructor(name: string, content = '') {
+    super();
+
+    this.name = name;
+    this.content = content;
+  }
+
+  override get type() {
+    return XmlNode.TYPE_PROCESSING_INSTRUCTION;
+  }
+
+  override toJSON() {
+    return Object.assign(XmlNode.prototype.toJSON.call(this), {
+      name: this.name,
+      content: this.content,
+    });
+  }
+}

package/src/lib/XmlText.ts

@@ -0,0 +1,26 @@
+import { XmlNode } from './XmlNode.js';
+
+/**
+ * Text content within an XML document.
+ */
+export class XmlText extends XmlNode {
+  /**
+   * Text content of this node.
+   */
+  text: string;
+
+  constructor(text = '') {
+    super();
+    this.text = text;
+  }
+
+  override get type() {
+    return XmlNode.TYPE_TEXT;
+  }
+
+  override toJSON() {
+    return Object.assign(XmlNode.prototype.toJSON.call(this), {
+      text: this.text,
+    });
+  }
+}