@rgrove/parse-xml 4.0.1 → 4.2.0

package/src/lib/StringScanner.ts

@@ -42,16 +42,6 @@ export class StringScanner {
 
   // -- 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.
@@ -75,60 +65,76 @@ export class StringScanner {
     this.charIndex = Math.min(this.charCount, this.charIndex + count);
   }
 
+  /**
+   * Returns the byte index of the given character index in the string. The two
+   * may differ in strings that contain multibyte characters.
+   */
+  charIndexToByteIndex(charIndex: number = this.charIndex): number {
+    return this.multiByteMode
+      ? (this.charsToBytes as number[])[charIndex] ?? Infinity
+      : charIndex;
+  }
+
   /**
    * 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);
+  consume(charCount = 1): string {
+    let chars = this.peek(charCount);
+    this.advance(charCount);
     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.
+   * Consumes and returns the given number of bytes if possible, advancing the
+   * scanner and stopping if the end of the string is reached.
    *
-   * 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.
+   * It's up to the caller to ensure that the given byte count doesn't split a
+   * multibyte character.
    *
-   * Returns the consumed string, or an empty string if nothing was consumed.
+   * If no bytes could be consumed, an empty string will be returned.
    */
-  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;
+  consumeBytes(byteCount: number): string {
+    let byteIndex = this.charIndexToByteIndex();
+    let result = this.string.slice(byteIndex, byteIndex + byteCount);
+    this.advance(this.charLength(result));
+    return result;
   }
 
   /**
-   * 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.
+   * Consumes and returns all characters for which the given function returns
+   * `true`, stopping when `false` is returned or the end of the input is
+   * reached.
    */
   consumeMatchFn(fn: (char: string) => boolean): string {
-    let char;
-    let match = emptyString;
+    let { length, multiByteMode, string } = this;
+    let startByteIndex = this.charIndexToByteIndex();
+    let endByteIndex = startByteIndex;
+
+    if (multiByteMode) {
+      while (endByteIndex < length) {
+        let char = string[endByteIndex] as string;
+        let isSurrogatePair = char >= '\uD800' && char <= '\uDBFF';
+
+        if (isSurrogatePair) {
+          char += string[endByteIndex + 1];
+        }
+
+        if (!fn(char)) {
+          break;
+        }
 
-    while ((char = this.peek()) && fn(char)) {
-      match += char;
-      this.advance();
+        endByteIndex += isSurrogatePair ? 2 : 1;
+      }
+    } else {
+      while (endByteIndex < length && fn(string[endByteIndex] as string)) {
+        ++endByteIndex;
+      }
     }
 
-    return match;
+    return this.consumeBytes(endByteIndex - startByteIndex);
   }
 
   /**
@@ -139,35 +145,11 @@ export class StringScanner {
    * 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;
+    let byteIndex = this.charIndexToByteIndex();
 
-    if (this.peek(length) === stringToConsume) {
-      this.advance(length);
+    if (stringToConsume === this.string.slice(byteIndex, byteIndex + length)) {
+      this.advance(length === 1 ? 1 : this.charLength(stringToConsume));
       return stringToConsume;
     }
 
@@ -182,16 +164,13 @@ export class StringScanner {
    * 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 matchByteIndex = this.string
+      .slice(this.charIndexToByteIndex())
+      .search(regex);
 
-    let result = restOfString.slice(0, matchByteIndex);
-    this.advance(this.charLength(result));
-    return result;
+    return matchByteIndex > 0
+      ? this.consumeBytes(matchByteIndex)
+      : emptyString;
   }
 
   /**
@@ -202,17 +181,12 @@ export class StringScanner {
    * 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 matchByteIndex = this.string.indexOf(searchString, byteIndex);
 
-    let result = string.slice(byteIndex, matchByteIndex);
-    this.advance(this.charLength(result));
-    return result;
+    return matchByteIndex > 0
+      ? this.consumeBytes(matchByteIndex - byteIndex)
+      : emptyString;
   }
 
   /**
@@ -221,22 +195,11 @@ export class StringScanner {
    * 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;
-      }
+    let { charIndex, string } = this;
 
-      return string.slice(
-        this.charIndexToByteIndex(charIndex),
-        this.charIndexToByteIndex(charIndex + count),
-      );
-    }
-
-    return string.slice(charIndex, charIndex + count);
+    return this.multiByteMode
+      ? string.slice(this.charIndexToByteIndex(charIndex), this.charIndexToByteIndex(charIndex + count))
+      : string.slice(charIndex, charIndex + count);
   }
 
   /**

package/src/lib/XmlDeclaration.ts

@@ -0,0 +1,58 @@
+import { XmlNode } from './XmlNode.js';
+
+/**
+ * An XML declaration within an XML document.
+ *
+ * @example
+ *
+ * ```xml
+ * <?xml version="1.0" encoding="UTF-8"?>
+ * ```
+ */
+export class XmlDeclaration extends XmlNode {
+  /**
+   * Value of the encoding declaration in this XML declaration, or `null` if no
+   * encoding declaration was present.
+   */
+  encoding: string | null;
+
+  /**
+   * Value of the standalone declaration in this XML declaration, or `null` if
+   * no standalone declaration was present.
+   */
+  standalone: 'yes' | 'no' | null;
+
+  /**
+   * Value of the version declaration in this XML declaration.
+   */
+  version: string;
+
+  constructor(
+    version: string,
+    encoding?: string,
+    standalone?: typeof XmlDeclaration.prototype.standalone,
+  ) {
+    super();
+
+    this.version = version;
+    this.encoding = encoding ?? null;
+    this.standalone = standalone ?? null;
+  }
+
+  override get type() {
+    return XmlNode.TYPE_XML_DECLARATION;
+  }
+
+  override toJSON() {
+    let json = XmlNode.prototype.toJSON.call(this);
+    json.version = this.version;
+
+    for (let key of ['encoding', 'standalone'] as const) {
+      if (this[key] !== null) {
+        json[key] = this[key];
+      }
+    }
+
+    return json;
+  }
+}

package/src/lib/XmlDocument.ts

@@ -2,6 +2,8 @@ import { XmlElement } from './XmlElement.js';
 import { XmlNode } from './XmlNode.js';
 
 import type { XmlComment } from './XmlComment.js';
+import type { XmlDeclaration } from './XmlDeclaration.js';
+import type { XmlDocumentType } from './XmlDocumentType.js';
 import type { XmlProcessingInstruction } from './XmlProcessingInstruction.js';
 
 /**
@@ -12,9 +14,9 @@ export class XmlDocument extends XmlNode {
   /**
    * Child nodes of this document.
    */
-  readonly children: Array<XmlComment | XmlProcessingInstruction | XmlElement>;
+  readonly children: Array<XmlComment | XmlDeclaration | XmlDocumentType | XmlProcessingInstruction | XmlElement>;
 
-  constructor(children: Array<XmlComment | XmlElement | XmlProcessingInstruction> = []) {
+  constructor(children: Array<XmlComment | XmlDeclaration | XmlDocumentType | XmlElement | XmlProcessingInstruction> = []) {
     super();
     this.children = children;
   }

package/src/lib/XmlDocumentType.ts

@@ -0,0 +1,67 @@
+import { XmlNode } from './XmlNode.js';
+
+/**
+ * A document type declaration within an XML document.
+ *
+ * @example
+ *
+ * ```xml
+ * <!DOCTYPE kittens [
+ *   <!ELEMENT kittens (#PCDATA)>
+ * ]>
+ * ```
+ */
+export class XmlDocumentType extends XmlNode {
+  /**
+   * Name of the root element described by this document type declaration.
+   */
+  name: string;
+
+  /**
+   * Public identifier of the external subset of this document type declaration,
+   * or `null` if no public identifier was present.
+   */
+  publicId: string | null;
+
+  /**
+   * System identifier of the external subset of this document type declaration,
+   * or `null` if no system identifier was present.
+   */
+  systemId: string | null;
+
+  /**
+   * Internal subset of this document type declaration, or `null` if no internal
+   * subset was present.
+   */
+  internalSubset: string | null;
+
+  constructor(
+    name: string,
+    publicId?: string,
+    systemId?: string,
+    internalSubset?: string,
+  ) {
+    super();
+    this.name = name;
+    this.publicId = publicId ?? null;
+    this.systemId = systemId ?? null;
+    this.internalSubset = internalSubset ?? null;
+  }
+
+  override get type() {
+    return XmlNode.TYPE_DOCUMENT_TYPE;
+  }
+
+  override toJSON() {
+    let json = XmlNode.prototype.toJSON.call(this);
+    json.name = this.name;
+
+    for (let key of ['publicId', 'systemId', 'internalSubset'] as const) {
+      if (this[key] !== null) {
+        json[key] = this[key];
+      }
+    }
+
+    return json;
+  }
+}

package/src/lib/XmlError.ts

@@ -0,0 +1,80 @@
+/**
+ * An error that occurred while parsing XML.
+ */
+export class XmlError extends Error {
+  /**
+   * Character column at which this error occurred (1-based).
+   */
+  readonly column: number;
+
+  /**
+   * Short excerpt from the input string that contains the problem.
+   */
+  readonly excerpt: string;
+
+  /**
+   * Line number at which this error occurred (1-based).
+   */
+  readonly line: number;
+
+  /**
+   * Character position at which this error occurred relative to the beginning
+   * of the input (0-based).
+   */
+  readonly pos: number;
+
+  constructor(
+    message: string,
+    charIndex: number,
+    xml: string,
+  ) {
+    let column = 1;
+    let excerpt = '';
+    let line = 1;
+
+    // Find the line and column where the error occurred.
+    for (let i = 0; i < charIndex; ++i) {
+      let char = xml[i];
+
+      if (char === '\n') {
+        column = 1;
+        excerpt = '';
+        line += 1;
+      } else {
+        column += 1;
+        excerpt += char;
+      }
+    }
+
+    let eol = xml.indexOf('\n', charIndex);
+
+    excerpt += eol === -1
+      ? xml.slice(charIndex)
+      : xml.slice(charIndex, eol);
+
+    let excerptStart = 0;
+
+    // Keep the excerpt below 50 chars, but always keep the error position in
+    // view.
+    if (excerpt.length > 50) {
+      if (column < 40) {
+        excerpt = excerpt.slice(0, 50);
+      } else {
+        excerptStart = column - 20;
+        excerpt = excerpt.slice(excerptStart, column + 30);
+      }
+    }
+
+    super(
+      `${message} (line ${line}, column ${column})\n`
+        + `  ${excerpt}\n`
+        + ' '.repeat(column - excerptStart + 1) + '^\n',
+    );
+
+    this.column = column;
+    this.excerpt = excerpt;
+    this.line = line;
+    this.name = 'XmlError';
+    this.pos = charIndex;
+  }
+}

package/src/lib/XmlNode.ts

@@ -21,6 +21,11 @@ export class XmlNode {
    */
   static readonly TYPE_DOCUMENT = 'document';
 
+  /**
+   * Type value for an `XmlDocumentType` node.
+   */
+  static readonly TYPE_DOCUMENT_TYPE = 'doctype';
+
   /**
    * Type value for an `XmlElement` node.
    */
@@ -36,11 +41,28 @@ export class XmlNode {
    */
   static readonly TYPE_TEXT = 'text';
 
+  /**
+   * Type value for an `XmlDeclaration` node.
+   */
+  static readonly TYPE_XML_DECLARATION = 'xmldecl';
+
   /**
    * Parent node of this node, or `null` if this node has no parent.
    */
   parent: XmlDocument | XmlElement | null = null;
 
+  /**
+   * Starting byte offset of this node in the original XML string, or `-1` if
+   * the offset is unknown.
+   */
+  start = -1;
+
+  /**
+   * Ending byte offset of this node in the original XML string, or `-1` if the
+   * offset is unknown.
+   */
+  end = -1;
+
   /**
    * Document that contains this node, or `null` if this node is not associated
    * with a document.
@@ -50,10 +72,13 @@ export class XmlNode {
   }
 
   /**
-   * Whether this node is the root node of the document.
+   * Whether this node is the root node of the document (also known as the
+   * document element).
    */
   get isRootNode(): boolean {
-    return this.parent !== null && this.parent === this.document;
+    return this.parent !== null
+      && this.parent === this.document
+      && this.type === XmlNode.TYPE_ELEMENT;
   }
 
   /**
@@ -68,7 +93,7 @@ export class XmlNode {
    * @see https://www.w3.org/TR/2008/REC-xml-20081126/#sec-white-space
    */
   get preserveWhitespace(): boolean {
-    return Boolean(this.parent?.preserveWhitespace);
+    return !!this.parent?.preserveWhitespace;
   }
 
   /**
@@ -102,6 +127,11 @@ export class XmlNode {
       json.preserveWhitespace = true;
     }
 
+    if (this.start !== -1) {
+      json.start = this.start;
+      json.end = this.end;
+    }
+
     return json;
   }
 }

package/src/lib/syntax.ts

@@ -4,7 +4,7 @@
  *
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-AttValue
  */
-export const attValueCharDoubleQuote = /[^"&<]+/y;
+export const attValueCharDoubleQuote = /["&<]/;
 
 /**
  * Regular expression that matches one or more `AttValue` characters in a
@@ -12,7 +12,7 @@ export const attValueCharDoubleQuote = /[^"&<]+/y;
  *
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-AttValue
  */
-export const attValueCharSingleQuote = /[^'&<]+/y;
+export const attValueCharSingleQuote = /['&<]/;
 
 /**
  * Regular expression that matches a whitespace character that should be
@@ -20,7 +20,7 @@ export const attValueCharSingleQuote = /[^'&<]+/y;
  *
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#AVNormalize
  */
-export const attValueNormalizedWhitespace = /[\t\n]/g;
+export const attValueNormalizedWhitespace = /\r\n|[\n\r\t]/g;
 
 /**
  * Regular expression that matches one or more characters that signal the end of
@@ -49,7 +49,7 @@ export const predefinedEntities: Readonly<{[name: string]: string;}> = Object.fr
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-NameChar
  */
 export function isNameChar(char: string): boolean {
-  let cp = getCodePoint(char);
+  let cp = char.codePointAt(0) as number;
 
   // Including the most common NameStartChars here improves performance
   // slightly.
@@ -60,7 +60,8 @@ export function isNameChar(char: string): boolean {
     || cp === 0x2E // .
     || cp === 0xB7
     || (cp >= 0x300 && cp <= 0x36F)
-    || (cp >= 0x203F && cp <= 0x2040)
+    || cp === 0x203F
+    || cp === 0x2040
     || isNameStartChar(char, cp);
 }
 
@@ -69,7 +70,7 @@ export function isNameChar(char: string): boolean {
  *
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-NameStartChar
  */
-export function isNameStartChar(char: string, cp = getCodePoint(char)): boolean {
+export function isNameStartChar(char: string, cp = char.codePointAt(0) as number): boolean {
   return (cp >= 0x61 && cp <= 0x7A) // a-z
     || (cp >= 0x41 && cp <= 0x5A) // A-Z
     || cp === 0x3A // :
@@ -79,7 +80,8 @@ export function isNameStartChar(char: string, cp = getCodePoint(char)): boolean
     || (cp >= 0xF8 && cp <= 0x2FF)
     || (cp >= 0x370 && cp <= 0x37D)
     || (cp >= 0x37F && cp <= 0x1FFF)
-    || (cp >= 0x200C && cp <= 0x200D)
+    || cp === 0x200C
+    || cp === 0x200D
     || (cp >= 0x2070 && cp <= 0x218F)
     || (cp >= 0x2C00 && cp <= 0x2FEF)
     || (cp >= 0x3001 && cp <= 0xD7FF)
@@ -104,7 +106,7 @@ export function isReferenceChar(char: string): boolean {
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#white
  */
 export function isWhitespace(char: string): boolean {
-  let cp = getCodePoint(char);
+  let cp = char.codePointAt(0);
 
   return cp === 0x20
     || cp === 0x9
@@ -119,18 +121,10 @@ export function isWhitespace(char: string): boolean {
  * @see https://www.w3.org/TR/2008/REC-xml-20081126/#NT-Char
  */
 export function isXmlCodePoint(cp: number): boolean {
-  return cp === 0x9
+  return (cp >= 0x20 && cp <= 0xD7FF)
     || cp === 0xA
+    || cp === 0x9
     || cp === 0xD
-    || (cp >= 0x20 && cp <= 0xD7FF)
     || (cp >= 0xE000 && cp <= 0xFFFD)
     || (cp >= 0x10000 && cp <= 0x10FFFF);
 }
-
-/**
- * Returns the Unicode code point value of the given character, or `-1` if
- * _char_ is empty.
- */
-function getCodePoint(char: string): number {
-  return char.codePointAt(0) || -1;
-}