html API reference Changelog View on GitHub

API reference

HTML in Zig, the way the WHATWG HTML standard parses it.

parse turns UTF-8 bytes into a Document, and parseFragment parses markup in the context of an element, as innerHTML does. Parser does the same in chunks, so a document can stream through it. Tokenizer is the stage before tree construction, for callers who only want tokens. None of them do I/O.

module Parser

src

The HTML parser: tree construction, §13.2.6 of the standard.

Functions

pub fn init(gpa: Allocator, options: Options) Allocator.Error!Parser

src

A parser for a whole document.

pub fn initFragment(gpa: Allocator, context: Context, options: Options) Allocator.Error!Parser

src

A parser for a fragment in context, as the HTML fragment parsing algorithm defines it. The document's root is a fragment.

pub fn deinit(self: *Parser) void

src

pub fn feed(self: *Parser, bytes: []const u8) Allocator.Error!void

src

Parse more of the input. The bytes are copied, so the caller may reuse them.

pub fn finish(self: *Parser) Allocator.Error!Document

src

End the input and return the document, which the caller then owns and frees with Document.deinit. Call deinit on the parser as well.

pub fn parse(gpa: Allocator, bytes: []const u8, options: Options) Allocator.Error!Document

src

Parse a whole document.

pub fn parseFragment( gpa: Allocator, bytes: []const u8, context: Context, options: Options, ) Allocator.Error!Document

src

Parse a fragment in context. The document's root is the fragment.

Types

struct Options

src

Fields

scripting: Scripting = .enabled

Whether to parse as if scripting were enabled, as it is in browsers. It decides one thing: whether noscript holds raw text or markup.

enum Scripting

src

Fields

enabled enabled
disabled disabled

struct Context

src

The element whose contents a fragment is parsed as, as for innerHTML.

Fields

namespace: Namespace
name: []const u8
attributes: []const Attribute

Functions

pub fn init(namespace: Namespace, name: []const u8) Context

src

The context element in namespace with no attributes.

pub fn parse(gpa: Allocator, bytes: []const u8, options: Options) Allocator.Error!Document

src

Parse a whole document.

pub fn parseFragment( gpa: Allocator, bytes: []const u8, context: Context, options: Options, ) Allocator.Error!Document

src

Parse a fragment in context. The document's root is the fragment.

module Document

src

A parsed document or fragment.

Functions

pub fn init(gpa: Allocator, root: enum { document, fragment }) Allocator.Error!Document

src

A document with only its root: a document node, or a fragment.

pub fn deinit(doc: *Document) void

src

pub fn node(doc: *const Document, index: Node.Index) *const Node

src

pub fn nodeMut(doc: *Document, index: Node.Index) *Node

src

pub fn element(doc: *const Document, index: Node.Index) ?*const Element

src

The element at index, or null for any other kind of node.

pub fn children(doc: *const Document, parent: Node.Index) Children

src

pub fn create(doc: *Document, data: Node.Data) Allocator.Error!Node.Index

src

A new node with no parent. Its strings must already belong to the document; dupe copies one in.

pub fn dupe(doc: *Document, bytes: []const u8) Allocator.Error![]const u8

src

Copy bytes into the document's arena.

pub fn insertBefore(doc: *Document, parent: Node.Index, child: Node.Index, before: Node.Index) void

src

Insert child, which has no parent, into parent before before, or at the end when before is .none.

pub fn append(doc: *Document, parent: Node.Index, child: Node.Index) void

src

pub fn remove(doc: *Document, child: Node.Index) void

src

Take child out of its parent, if it has one.

pub fn isInclusiveAncestor(doc: *const Document, ancestor: Node.Index, descendant: Node.Index) bool

src

Whether ancestor is descendant or one of its ancestors.

Types

enum Mode

src

The DOM's document mode, which the DOCTYPE decides.

Fields

no_quirks no_quirks
quirks quirks
limited_quirks limited_quirks

enum Namespace

src

Fields

html html
svg svg
mathml mathml

enum AttributeNamespace

src

The namespaces an attribute can be in. Only the foreign attributes of §13.2.6.1, such as xlink:href on an SVG element, are in one.

Fields

none none
xml xml
xmlns xmlns

struct Attribute

src

Fields

namespace: AttributeNamespace
name: []const u8

The local name: href for xlink:href in the XLink namespace.

value: []const u8

Functions

pub fn init(name: []const u8, value: []const u8) Attribute

src

An attribute in no namespace, as every HTML attribute is.

struct Node

src

Fields

parent: Index
first_child: Index
last_child: Index
prev_sibling: Index
next_sibling: Index
data: Data

Functions

pub fn init(data: Data) Node

src

A node holding data, with no parent, children, or siblings.

Types

enum Index

src 
pub const Index = enum(u32)

Fields

root root = 0

The document, or the fragment for Parser.initFragment.

none none = std.math.maxInt(u32)
_ _

union Data

src 
pub const Data = union(enum)

Fields

document document
fragment fragment

A DocumentFragment: the result of fragment parsing, and the contents of a template element.

doctype: Doctype
element: Element
text: ArrayList(u8)

Adjacent text is one node, so this grows as the parser appends.

comment: []const u8
processing_instruction: ProcessingInstruction

struct Doctype

src

Fields

name: []const u8

Empty when the DOCTYPE token's field was missing, as in the DOM.

public_id: []const u8
system_id: []const u8

struct Element

src

Fields

namespace: Namespace
name: []const u8

The local name, with the case the standard gives foreign elements: foreignObject, not foreignobject.

tag: Tag

name as one of the tags the parser treats specially, or .other.

attributes: []const Attribute
template_contents: Node.Index

The fragment holding a template element's contents, or .none.

Functions

pub fn init(namespace: Namespace, name: []const u8, tag: Tag, attributes: []const Attribute) Element

src

An element with no template contents: every element but an HTML template.

pub fn attribute(self: *const Element, name: []const u8) ?[]const u8

src

struct ProcessingInstruction

src

Fields

target: []const u8
data: []const u8

enum Tag

src

The element names tree construction handles by name, in any namespace. The field names are the element names, so @tagName gives the name back.

Fields

a a
address address
@"annotation-xml" @"annotation-xml"
applet applet
area area
article article
aside aside
b b
base base
basefont basefont
bgsound bgsound
big big
blockquote blockquote
body body
br br
button button
caption caption
center center
code code
col col
colgroup colgroup
dd dd
desc desc
details details
dialog dialog
dir dir
div div
dl dl
dt dt
em em
embed embed
fieldset fieldset
figcaption figcaption
figure figure
font font
footer footer
foreignObject foreignObject
form form
frame frame
frameset frameset
h1 h1
h2 h2
h3 h3
h4 h4
h5 h5
h6 h6
head head
header header
hgroup hgroup
hr hr
html html
i i
iframe iframe
image image
img img
input input
keygen keygen
li li
listing listing
main main
malignmark malignmark
marquee marquee
math math
menu menu
meta meta
mglyph mglyph
mi mi
mn mn
mo mo
ms ms
mtext mtext
nav nav
nobr nobr
noembed noembed
noframes noframes
noscript noscript
object object
ol ol
optgroup optgroup
option option
p p
param param
plaintext plaintext
pre pre
rb rb
rp rp
rt rt
rtc rtc
ruby ruby
s s
script script
search search
section section
select select
small small
source source
span span
strike strike
strong strong
style style
sub sub
summary summary
sup sup
svg svg
table table
tbody tbody
td td
template template
textarea textarea
tfoot tfoot
th th
thead thead
title title
tr tr
track track
tt tt
u u
ul ul
@"var" @"var"
wbr wbr
xmp xmp
other other

Functions

pub fn fromName(name: []const u8) Tag

src

struct Children

src

Fields

doc: *const Document
next_child: Node.Index

Functions

pub fn next(it: *Children) ?Node.Index

src

struct Node

src 
pub const Node = Document.Node

Fields

parent: Index
first_child: Index
last_child: Index
prev_sibling: Index
next_sibling: Index
data: Data

Functions

pub fn init(data: Data) Node

src

A node holding data, with no parent, children, or siblings.

Types

enum Index

src 
pub const Index = enum(u32)

Fields

root root = 0

The document, or the fragment for Parser.initFragment.

none none = std.math.maxInt(u32)
_ _

union Data

src 
pub const Data = union(enum)

Fields

document document
fragment fragment

A DocumentFragment: the result of fragment parsing, and the contents of a template element.

doctype: Doctype
element: Element
text: ArrayList(u8)

Adjacent text is one node, so this grows as the parser appends.

comment: []const u8
processing_instruction: ProcessingInstruction

module Tokenizer

src

The HTML tokenizer, §13.2.5 of the standard.

Functions

pub fn init(gpa: Allocator, options: Options) Tokenizer

src

pub fn deinit(self: *Tokenizer) void

src

pub fn feed(self: *Tokenizer, bytes: []const u8) Allocator.Error!void

src

Append bytes to the input. They are copied, so the caller may reuse them.

pub fn finish(self: *Tokenizer) void

src

Mark the end of the input. next then runs to the eof token.

pub fn setState(self: *Tokenizer, state: TextState) void

src

Switch to one of the text states. Tree construction does this after a start tag such as <title> or <script>.

pub fn setLastStartTag(self: *Tokenizer, name: []const u8) Allocator.Error!void

src

Set the tag name an end tag must have to close an RCDATA, RAWTEXT, or script data run, as if a start tag with this name had just been emitted.

pub fn next(self: *Tokenizer) Allocator.Error!?Token

src

The next token, or null when the tokenizer needs more input. After eof every call returns eof again.

Types

union Token

src 
pub const Token = union(enum)

One token, as the standard defines them. Character tokens arrive in runs, as text; two text tokens in a row are one run split by the input.

Fields

doctype: Doctype
start_tag: Tag
end_tag: Tag
comment: []const u8
processing_instruction: ProcessingInstruction
text: []const u8
eof eof

struct Doctype

src

Fields

name: ?[]const u8

Null when the DOCTYPE had no name, which is distinct from an empty one.

public_id: ?[]const u8
system_id: ?[]const u8
force_quirks: bool

struct Tag

src

Fields

name: []const u8

Lowercased for ASCII letters, as the standard requires.

attributes: []const Attribute

In document order. A repeated name is dropped, as the standard requires.

self_closing: bool

struct Attribute

src

Fields

name: []const u8
value: []const u8

struct ProcessingInstruction

src

Fields

target: []const u8
data: []const u8

struct ParseError

src

A parse error, with the line and column, both counted from one, of the character the tokenizer was looking at when it found the error. Columns count UTF-16 code units, as browsers and html5lib-tests do, so a code point above U+FFFF takes two.

Fields

code: ErrorCode
line: u32
column: u32

enum ErrorCode

src

The parse error codes of §13.2.2 that the tokenizer can report. The names are the standard's, with _ for -.

Fields

abrupt_closing_of_empty_comment abrupt_closing_of_empty_comment
abrupt_doctype_public_identifier abrupt_doctype_public_identifier
abrupt_doctype_system_identifier abrupt_doctype_system_identifier
absence_of_digits_in_numeric_character_reference absence_of_digits_in_numeric_character_reference
cdata_in_html_content cdata_in_html_content
character_reference_outside_unicode_range character_reference_outside_unicode_range
control_character_in_input_stream control_character_in_input_stream
control_character_reference control_character_reference
disallowed_processing_instruction_target disallowed_processing_instruction_target
duplicate_attribute duplicate_attribute
end_tag_with_attributes end_tag_with_attributes
end_tag_with_trailing_solidus end_tag_with_trailing_solidus
eof_before_tag_name eof_before_tag_name
eof_in_cdata eof_in_cdata
eof_in_comment eof_in_comment
eof_in_doctype eof_in_doctype
eof_in_processing_instruction eof_in_processing_instruction
eof_in_script_html_comment_like_text eof_in_script_html_comment_like_text
eof_in_tag eof_in_tag
incorrectly_closed_comment incorrectly_closed_comment
incorrectly_opened_comment incorrectly_opened_comment
invalid_character_sequence_after_doctype_name invalid_character_sequence_after_doctype_name
invalid_first_character_of_processing_instruction_target invalid_first_character_of_processing_instruction_target
invalid_first_character_of_tag_name invalid_first_character_of_tag_name
invalid_processing_instruction_target invalid_processing_instruction_target
missing_attribute_value missing_attribute_value
missing_doctype_name missing_doctype_name
missing_doctype_public_identifier missing_doctype_public_identifier
missing_doctype_system_identifier missing_doctype_system_identifier
missing_end_tag_name missing_end_tag_name
missing_quote_before_doctype_public_identifier missing_quote_before_doctype_public_identifier
missing_quote_before_doctype_system_identifier missing_quote_before_doctype_system_identifier
missing_semicolon_after_character_reference missing_semicolon_after_character_reference
missing_whitespace_after_doctype_public_keyword missing_whitespace_after_doctype_public_keyword
missing_whitespace_after_doctype_system_keyword missing_whitespace_after_doctype_system_keyword
missing_whitespace_before_doctype_name missing_whitespace_before_doctype_name
missing_whitespace_between_attributes missing_whitespace_between_attributes
missing_whitespace_between_doctype_public_and_system_identifiers missing_whitespace_between_doctype_public_and_system_identifiers
nested_comment nested_comment
noncharacter_character_reference noncharacter_character_reference
noncharacter_in_input_stream noncharacter_in_input_stream
null_character_reference null_character_reference
surrogate_character_reference surrogate_character_reference
unexpected_character_after_doctype_system_identifier unexpected_character_after_doctype_system_identifier
unexpected_character_in_attribute_name unexpected_character_in_attribute_name
unexpected_character_in_unquoted_attribute_value unexpected_character_in_unquoted_attribute_value
unexpected_equals_sign_before_attribute_name unexpected_equals_sign_before_attribute_name
unexpected_null_character unexpected_null_character
unexpected_solidus_in_tag unexpected_solidus_in_tag
unknown_named_character_reference unknown_named_character_reference

struct Options

src

Fields

errors: ErrorMode = .ignore

Whether to record parse errors in errors. They never stop the tokenizer; the standard says how to recover from each one.

enum ErrorMode

src

Fields

ignore ignore
collect collect

enum TextState

src

The states tree construction switches the tokenizer into, for the contents of elements such as title, style, script, and plaintext.

Fields

data data
rcdata rcdata
rawtext rawtext
script_data script_data
plaintext plaintext
cdata_section cdata_section

enum CdataMode

src

Whether <![CDATA[ opens a CDATA section. Tree construction sets .foreign while the adjusted current node is outside the HTML namespace.

Fields

html html
foreign foreign

union Token

src 
pub const Token = Tokenizer.Token

One token, as the standard defines them. Character tokens arrive in runs, as text; two text tokens in a row are one run split by the input.

Fields

doctype: Doctype
start_tag: Tag
end_tag: Tag
comment: []const u8
processing_instruction: ProcessingInstruction
text: []const u8
eof eof

struct ParseError

src 
pub const ParseError = Tokenizer.ParseError

A parse error, with the line and column, both counted from one, of the character the tokenizer was looking at when it found the error. Columns count UTF-16 code units, as browsers and html5lib-tests do, so a code point above U+FFFF takes two.

Fields

code: ErrorCode
line: u32
column: u32

enum ErrorCode

src 
pub const ErrorCode = Tokenizer.ErrorCode

The parse error codes of §13.2.2 that the tokenizer can report. The names are the standard's, with _ for -.

Fields

abrupt_closing_of_empty_comment abrupt_closing_of_empty_comment
abrupt_doctype_public_identifier abrupt_doctype_public_identifier
abrupt_doctype_system_identifier abrupt_doctype_system_identifier
absence_of_digits_in_numeric_character_reference absence_of_digits_in_numeric_character_reference
cdata_in_html_content cdata_in_html_content
character_reference_outside_unicode_range character_reference_outside_unicode_range
control_character_in_input_stream control_character_in_input_stream
control_character_reference control_character_reference
disallowed_processing_instruction_target disallowed_processing_instruction_target
duplicate_attribute duplicate_attribute
end_tag_with_attributes end_tag_with_attributes
end_tag_with_trailing_solidus end_tag_with_trailing_solidus
eof_before_tag_name eof_before_tag_name
eof_in_cdata eof_in_cdata
eof_in_comment eof_in_comment
eof_in_doctype eof_in_doctype
eof_in_processing_instruction eof_in_processing_instruction
eof_in_script_html_comment_like_text eof_in_script_html_comment_like_text
eof_in_tag eof_in_tag
incorrectly_closed_comment incorrectly_closed_comment
incorrectly_opened_comment incorrectly_opened_comment
invalid_character_sequence_after_doctype_name invalid_character_sequence_after_doctype_name
invalid_first_character_of_processing_instruction_target invalid_first_character_of_processing_instruction_target
invalid_first_character_of_tag_name invalid_first_character_of_tag_name
invalid_processing_instruction_target invalid_processing_instruction_target
missing_attribute_value missing_attribute_value
missing_doctype_name missing_doctype_name
missing_doctype_public_identifier missing_doctype_public_identifier
missing_doctype_system_identifier missing_doctype_system_identifier
missing_end_tag_name missing_end_tag_name
missing_quote_before_doctype_public_identifier missing_quote_before_doctype_public_identifier
missing_quote_before_doctype_system_identifier missing_quote_before_doctype_system_identifier
missing_semicolon_after_character_reference missing_semicolon_after_character_reference
missing_whitespace_after_doctype_public_keyword missing_whitespace_after_doctype_public_keyword
missing_whitespace_after_doctype_system_keyword missing_whitespace_after_doctype_system_keyword
missing_whitespace_before_doctype_name missing_whitespace_before_doctype_name
missing_whitespace_between_attributes missing_whitespace_between_attributes
missing_whitespace_between_doctype_public_and_system_identifiers missing_whitespace_between_doctype_public_and_system_identifiers
nested_comment nested_comment
noncharacter_character_reference noncharacter_character_reference
noncharacter_in_input_stream noncharacter_in_input_stream
null_character_reference null_character_reference
surrogate_character_reference surrogate_character_reference
unexpected_character_after_doctype_system_identifier unexpected_character_after_doctype_system_identifier
unexpected_character_in_attribute_name unexpected_character_in_attribute_name
unexpected_character_in_unquoted_attribute_value unexpected_character_in_unquoted_attribute_value
unexpected_equals_sign_before_attribute_name unexpected_equals_sign_before_attribute_name
unexpected_null_character unexpected_null_character
unexpected_solidus_in_tag unexpected_solidus_in_tag
unknown_named_character_reference unknown_named_character_reference