Parser Events: Text and CDATA

Relevant source files

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

• src/Parser.ts
• src/Tokenizer.ts
• src/Parser.events.spec.ts
• README.md
• src/Parser.spec.ts

In htmlparser2, Text and CDATA events represent the primary mechanisms for handling non-markup content within a document. The parser distinguishes between standard character data, encoded entities, and explicit CDATA sections, providing specialized callbacks to manage these transitions based on the parser's configuration and the current context (such as being inside a script tag or a foreign namespace).

Sources: src/Parser.ts:327-340, README.md:65-88

Text Content and Entities

Text events are triggered whenever the parser encounters character data that is not part of a tag, comment, or processing instruction. In HTML mode, text can also include content inside "special" tags like <script> or <style>, which the tokenizer treats as raw text or RCDATA.

The ontext Event

The ontext event is the primary callback for character data. It may fire multiple times for a single logical text node, especially when data is received in chunks or when entities are interleaved with plain text.

Sources: src/Parser.ts:327-333, README.md:74-81

Entity Decoding

When decodeEntities is enabled, the parser identifies HTML/XML entities (e.g., &, a). These are decoded by a dedicated EntityDecoder and passed to the ontext callback as individual characters or strings.

Sources: src/Tokenizer.ts:167-175, src/Parser.ts:335-340

CDATA Sections

CDATA (Character Data) sections are used in XML to escape blocks of text that would otherwise be interpreted as markup. The handling of CDATA in htmlparser2 is highly dependent on the xmlMode and recognizeCDATA options.

CDATA Lifecycle Events

The parser provides three specific callbacks for CDATA sections:

• oncdatastart: Signals the beginning of a <![CDATA[ sequence.
• ontext: Delivers the content inside the CDATA section.
• oncdataend: Signals the end of the ]]> sequence.

Sources: src/Parser.ts:599-603, README.md:85-86

Contextual CDATA Logic

The behavior for a CDATA section changes based on the parser state:

Context	Behavior
XML Mode	Recognized as CDATA; triggers oncdatastart, ontext, and oncdataend.
HTML Mode (recognizeCDATA: true)	Treated exactly like XML mode.
Foreign Context (SVG/MathML)	Content is emitted via ontext without CDATA-specific start/end events.
Standard HTML	Treated as a "bogus comment"; content emitted via oncomment.

Sources: src/Parser.ts:594-611, src/Tokenizer.ts:811-831

Special Tag Handling

In HTML mode, certain tags change how text is parsed. The Tokenizer uses "Sequences" to identify when to exit these special modes.

Raw Text and RCDATA

• Raw Text Tags: <script>, <style>, <iframe>, <xmp>, <noembed>, <noframes>. The parser ignores all markup until the corresponding closing tag is found.
• RCDATA Tags: <title>, <textarea>. Entities are decoded, but tags are ignored.
• Plaintext: The <plaintext> tag causes the remainder of the document to be treated as literal text.

Sources: src/Tokenizer.ts:186-218, src/Tokenizer.ts:476-512

Special Tag State Machine

When a special tag is identified, the tokenizer enters the InSpecialTag state. It then performs a low-cost "fast-forward" to the next < character before checking if it signifies the correct closing tag.

Sources: src/Tokenizer.ts:476-512, src/Tokenizer.ts:689-693

Configuration Summary

The following options directly impact how Text and CDATA events are generated:

Option	Type	Default	Impact on Text/CDATA
xmlMode	boolean	false	Enables strict CDATA handling and XML entity decoding.
decodeEntities	boolean	true	When false, entities like & are emitted as literal text.
recognizeCDATA	boolean	xmlMode	Allows CDATA sections to be recognized in HTML documents.

Sources: src/Parser.ts:175-215, README.md:95-108

Implementation Details

Parser Index Tracking

The Parser class tracks indices to ensure that text segments are reported correctly relative to the original buffer.

• startIndex: The absolute buffer index where the current event begins.
• endIndex: The absolute buffer index where the current event ends.

Sources: src/Parser.ts:257-260, src/Parser.spec.ts:86-100

Tokenizer Buffer Management

The Tokenizer uses a sectionStart pointer to track the beginning of the current text chunk. When cleanup() is called (usually at the end of a buffer chunk), any pending text is flushed to the parser.

Sources: src/Tokenizer.ts:680-700, src/Parser.ts:646-665

Conclusion

Text and CDATA events in htmlparser2 are designed for high performance by utilizing state-based tokenization and fast-forwarding through raw content. By distinguishing between standard HTML text, XML CDATA sections, and foreign context content, the parser provides the flexibility required for both forgiving HTML parsing and strict XML compliance.

Sources: README.md:12-18, src/Parser.ts:608-611