Parser Configuration Options

Relevant source files

The following files were used as context for generating this wiki page:

• src/Parser.ts
• README.md
• src/Tokenizer.ts
• src/index.ts
• src/Parser.spec.ts
• src/Tokenizer.spec.ts
• src/WebWritableStream.ts
• src/WritableStream.ts

The htmlparser2 library provides a flexible configuration system through the ParserOptions interface. These options allow developers to control how the incremental parser and its underlying tokenizer handle various document types, including HTML and XML, as well as specific syntax features like CDATA sections, entity decoding, and self-closing tags.

Configuration is primarily handled during the instantiation of the Parser class or through helper functions like parseDocument and createDocumentStream. These options directly influence the internal state machines of the Parser and Tokenizer classes, determining how characters are grouped into tokens and how the parser maintains its element stack and foreign namespaces.

Sources: src/Parser.ts:258-261, README.md:143-152

Core Options Overview

The ParserOptions interface defines the primary behavioral switches for the library. Most options default to values appropriate for standard HTML but can be toggled for strict XML processing.

Option	Type	Default	Description
xmlMode	boolean	false	Enables strict XML parsing, affecting entity decoding and self-closing tag recognition.
decodeEntities	boolean	true	Determines if HTML/XML entities (e.g., &) should be decoded.
lowerCaseTags	boolean	!xmlMode	Automatically converts all tag names to lowercase.
lowerCaseAttributeNames	boolean	!xmlMode	Automatically converts all attribute names to lowercase.
recognizeCDATA	boolean	xmlMode	Recognizes CDATA sections (<![CDATA[...]]>) as text.
recognizeSelfClosing	boolean	xmlMode	Recognizes tags ending with /> as self-closing.
Tokenizer	Constructor	Tokenizer	Allows providing a custom Tokenizer implementation.

Sources: src/Parser.ts:212-256, README.md:154-162

Logic and Flow Architecture

The configuration options are passed from the Parser constructor down to the Tokenizer. The following diagram illustrates how options like xmlMode influence the initialization and data flow between the parser components.

Detailed Option Analysis

XML Mode and Namespace Handling

The xmlMode option is the most significant toggle. When false (default), the parser operates in HTML mode, enabling "forgiving" behaviors such as implied tag closing (e.g., a <li> closing a previous <li>) and specific handling for void elements like <img> or <br>. When true, it treats the document as strict XML.

• HTML Integration: In HTML mode, the parser identifies svg and math tags to enter foreign contexts. While in a foreign context, the parser adopts XML-like behavior for self-closing tags even if xmlMode is false.
• Tag Adjustment: In HTML mode, the parser automatically adjusts SVG tag names to their correct camelCase versions (e.g., altglyph becomes altGlyph).

Sources: src/Parser.ts:109-170, src/Parser.ts:352-385, src/Parser.ts:400-420

Entity Decoding

The decodeEntities option controls the EntityDecoder used by the Tokenizer. If enabled, the Tokenizer transitions to an InEntity state upon encountering an ampersand (&).

Custom Tokenizer Implementation

Advanced users can override the default Tokenizer class. This is useful for performance optimizations or supporting custom syntax. The Parser class accepts a Tokenizer constructor in its options and instantiates it during setup.

// src/Parser.spec.ts:219-232
it("should support custom tokenizer", () => {
    class CustomTokenizer extends Tokenizer {}

    const p = new Parser(
        {
            onparserinit(parser: Parser) {
                expect(parser.tokenizer).toBeInstanceOf(CustomTokenizer);
            },
        },
        { Tokenizer: CustomTokenizer },
    );
    p.end();
});

Sources: src/Parser.ts:322-325, src/Parser.spec.ts:219-232

Integration with Streams

Configuration options are also relevant when using streaming interfaces. The WritableStream (Node.js) and WebWritableStream (Web Streams API) wrappers accept ParserOptions as their second argument, ensuring that the underlying parser instance is configured correctly for the stream.

// src/WebWritableStream.ts:24-25
export class WebWritableStream extends WritableStream<string | Uint8Array> {
    constructor(cbs: Partial<Handler>, options?: ParserOptions) {
        const parser = new Parser(cbs, options);
        // ...
    }
}

Sources: src/WebWritableStream.ts:24-27, src/WritableStream.ts:23-26

Conclusion

ParserConfigurationOptions serve as the primary mechanism for fine-tuning htmlparser2 performance and compatibility. By toggling xmlMode, developers can switch between a high-performance, forgiving HTML parser and a strict XML parser. The granular options for casing, CDATA, and self-closing tags allow for hybrid behaviors often required when parsing modern web documents containing embedded SVG or MathML content.

Sources: src/Parser.ts:314-332, README.md:154-162