package core:encoding/xml

⌘K
Ctrl+K
or
/

    Overview

    A parser for XML 1.0 (5th edition) documents: spec. Documents that declare another 1.x version are parsed as XML 1.0, as §2.8 allows.

    Features:

    • Checks the well-formedness of names, the XML declaration, comments, CDATA sections, processing instructions, references and the legal character range.
    • Decodes bodies and attribute values as the spec says. See Option_Flag.
    • Simple to understand and use. Small.

    Caveats:

    • We do NOT support HTML in this package, as that may or may not be valid XML. If it works, great. If it doesn't, that's not considered a bug.

    • The input must be UTF-8. The XML declaration's encoding is only recorded in Document.encoding; the bytes are never converted. Convert UTF-16 and other encodings to UTF-8 first. For UTF-16, our condolences.

    • The DOCTYPE's internal subset (<!ENTITY, <!ELEMENT, <!ATTLIST and the rest) is skipped. With .Ignore_Unsupported (part of DEFAULT_OPTIONS), a DOCTYPE with an internal subset or external ID keeps unknown references as written, since it may declare them; otherwise they're .Unknown_Entity.

    MAYBE:

    • XML writer?
    • Serialize/deserialize Odin types?

    For a full example, see: core/encoding/xml/example

    Types

    Attribute ¶

    Attribute :: struct {
    	key: string,
    	val: string,
    }

    Attributes ¶

    Attributes :: [dynamic]Attribute

    Related Procedures With Parameters

    Document ¶

    Document :: struct {
    	elements:                [dynamic]Element `fmt:"v,element_count"`,
    	element_count:           u32,
    	prologue:                [dynamic]Attribute,
    	encoding:                Encoding,
    	doctype:                 struct {
    		// We only scan the <!DOCTYPE IDENT part and skip the rest.
    		ident: string,
    		rest:  string,
    	},
    	// With `.Intern_Comments`, comments outside the root element, before or after it, live here.
    	// Comments inside it become `.Comment` elements, except those `.Keep_Tag_Body_Comments` keeps in the body text.
    	comments:                [dynamic]string `fmt:"-"`,
    	// Internal
    	tokenizer:               ^Tokenizer `fmt:"-"`,
    	allocator:               runtime.Allocator `fmt:"-"`,
    	options:                 Options `fmt:"-"`,
    	// Buffer the document allocated and `destroy` frees: the copy made when `.Input_May_Be_Modified` isn't specified, or the file `load_from_file` read.
    	// Empty otherwise: the caller owns the buffer, and must keep it alive while the document's strings point into it.
    	input:                   []u8 `fmt:"-"`,
    	// An arena for small strings, especially for attribute key-value pairs.
    	// This is a hot path optimization for large XML files.
    	extra_strings_arena:     mem.Dynamic_Arena `fmt:"-"`,
    	extra_strings_allocator: runtime.Allocator `fmt:"-"`,
    }

    Related Procedures With Parameters

    Related Procedures With Returns

    Element ¶

    Element :: struct {
    	ident:   string,
    	value:   [dynamic]Value,
    	attribs: [dynamic]Attribute,
    	kind:    enum int {
    		Element = 0, 
    		Comment, 
    	},
    	parent:  u32,
    }

    Element_ID ¶

    Element_ID :: u32

    Related Procedures With Parameters

    Encoding ¶

    Encoding :: enum int {
    	Unknown, 
    	UTF_8, 
    	ISO_8859_1, 
    	// Aliases
    	LATIN_1    = ISO_8859_1, 
    }

    Error ¶

    Error :: enum int {
    	// General return values.
    	None                          = 0, 
    	Unexpected_Token, 
    	Invalid_Token, 
    	// Couldn't find, open or read file.
    	File_Error, 
    	// File too short.
    	Premature_EOF, 
    	// XML-specific errors.
    	No_Prolog, 
    	Invalid_Prolog, 
    	Too_Many_Prologs, 
    	No_DocType, 
    	Too_Many_DocTypes, 
    	DocType_Must_Preceed_Elements, 
    	// If a DOCTYPE is present _or_ the caller
    	// asked for a specific DOCTYPE and the DOCTYPE
    	// and root tag don't match, we return `.Invalid_DocType`.
    	Invalid_DocType, 
    	Invalid_Tag_Value, 
    	Mismatched_Closing_Tag, 
    	Unclosed_Comment, 
    	Invalid_Sequence_In_Comment, 
    	Unsupported_Version, 
    	// <!FOO are usually skipped.
    	Unhandled_Bang, 
    	Duplicate_Attribute, 
    	Conflicting_Options, 
    	// An allocation failed.
    	Allocation_Failed, 
    	Unknown_Entity, 
    }

    Related Procedures With Returns

    Error_Handler ¶

    Error_Handler :: proc(pos: Pos, fmt: string, args: ..any)

    Matching Procedures (1)

    Option_Flag ¶

    Option_Flag :: enum int {
    	// Parse in the caller's buffer instead of a copy of it. Line ends are normalised and bodies and attribute values decoded in place, and the document's strings point into the buffer.
    	// `parse_string` ignores this flag, since string data may be read-only.
    	Input_May_Be_Modified, 
    	// Document MUST start with `<?xml` prologue.
    	Must_Have_Prolog, 
    	// Document MUST have a `<!DOCTYPE`.
    	Must_Have_DocType, 
    	// By default we skip comments. Use this option to intern a comment on a parented Element.
    	Intern_Comments, 
    	// How to handle unsupported parts of the specification, like <! other than <!DOCTYPE and <![CDATA[
    	Error_On_Unsupported, 
    	Error_on_Unsupported   = Error_On_Unsupported, 
    	Ignore_Unsupported, 
    	// Also decode the HTML, MathML and ISO 8879 names from `unicode.xml`, in bodies and attribute values.
    	// The 5 predefined entities and character references are always decoded. Other names are `.Unknown_Entity`,
    	// unless `.Ignore_Unsupported` is set and the DOCTYPE has an internal subset or external ID: then they're kept as they are.
    	Decode_SGML_Entities, 
    	// If a tag body has a comment, it will be stripped unless this option is given.
    	Keep_Tag_Body_Comments, 
    	// Trim whitespace around body text, so whitespace between elements is dropped, and collapse and trim attribute values.
    	Trim_Whitespace, 
    }

    Options ¶

    Options :: struct {
    	flags:            bit_set[Option_Flag; u16],
    	expected_doctype: string,
    }

    Related Procedures With Parameters

    Related Constants

    Pos ¶

    Pos :: struct {
    	file:   string,
    	offset: int,
    	// starting at 0
    	line:   int,
    	// starting at 1
    	column: int,
    }

    Token ¶

    Token :: struct {
    	kind: Token_Kind,
    	text: string,
    	pos:  Pos,
    }

    Related Procedures With Returns

    Token_Kind ¶

    Token_Kind :: enum int {
    	Invalid, 
    	Ident, 
    	Literal, 
    	Rune, 
    	String, 
    	Double_Quote,  // "
    	Single_Quote,  // '
    	Colon,         // :
    	Eq,            // =
    	Lt,            // <
    	Gt,            // >
    	Exclaim,       // !
    	Question,      // ?
    	Hash,          // #
    	Slash,         // /
    	Dash,          // -
    	Open_Bracket,  // [
    	Close_Bracket, // ]
    	EOF, 
    }

    Tokenizer ¶

    Tokenizer :: struct {
    	// Immutable data
    	path:              string,
    	src:               string,
    	err:               Error_Handler,
    	// Tokenizing state
    	ch:                rune,
    	offset:            int,
    	read_offset:       int,
    	line_offset:       int,
    	line_count:        int,
    	clean_offset:      int,
    	clean_line_offset: int,
    	// Mutable data
    	error_count:       int,
    }

    Related Procedures With Parameters

    Constants

    CDATA_START ¶

    CDATA_START :: "<![CDATA["

    DEFAULT_OPTIONS ¶

    DEFAULT_OPTIONS :: Options{flags = {.Ignore_Unsupported}, expected_doctype = ""}

    Variables

    This section is empty.

    Procedures

    advance_rune ¶

    @(optimization_mode="favor_size")
    advance_rune :: proc(t: ^Tokenizer) {…}

    check_duplicate_attributes ¶

    check_duplicate_attributes :: proc(
    	t:       ^Tokenizer, 
    	attribs: [dynamic]Attribute, 
    	attr:    Attribute, 
    	offset:  int, 
    ) -> (err: Error) {…}

    default_error_handler ¶

    default_error_handler :: proc(pos: Pos, msg: string, args: ..any) {…}

    destroy ¶

    destroy :: proc(doc: ^Document, allocator := context.allocator) {…}

    error ¶

    error :: proc(t: ^Tokenizer, offset: int, msg: string, args: ..any) {…}

    expect ¶

    expect :: proc(
    	t:                ^Tokenizer, 
    	kind:             Token_Kind, 
    	multiline_string: bool = false, 
    ) -> (tok: Token, err: Error) {…}

    find_attribute_val_by_key ¶

    find_attribute_val_by_key :: proc(
    	doc:       ^Document, 
    	parent_id: u32, 
    	key:       string, 
    ) -> (val: string, found: bool) {…}
     

    Find an attribute by key.

    find_child_by_ident ¶

    find_child_by_ident :: proc(
    	doc:       ^Document, 
    	parent_id: u32, 
    	ident:     string, 
    	nth:       int = 0, 
    ) -> (res: u32, found: bool) {…}
     

    Find parent's nth child with a given ident.

    init ¶

    init :: proc(
    	t:    ^Tokenizer, 
    	src:  string, 
    	path: string, 
    	err:  Error_Handler = default_error_handler, 
    ) {…}

    is_letter ¶

    @(optimization_mode="favor_size")
    is_letter :: proc(r: rune) -> bool {…}

    is_valid_identifier_rune ¶

    is_valid_identifier_rune :: proc(r: rune) -> bool {…}

    likely ¶

    likely :: intrinsics.expect
    likely :: proc(val, expected_val: T) -> T {…}
     

    Provides information about expected (the most probable) value of val, which can be used by optimizing backends.

    load_from_file ¶

    load_from_file :: proc(
    	filename:      string, 
    	options:       Options = DEFAULT_OPTIONS, 
    	error_handler: proc(pos: Pos, msg: string, args: ..any) = default_error_handler, 
    	allocator := context.allocator, 
    ) -> (doc: ^Document, err: Error) {…}
     

    Load an XML file

    new_element ¶

    new_element :: proc(doc: ^Document) -> (id: u32, err: Error) {…}

    parse_attribute ¶

    parse_attribute :: proc(doc: ^Document) -> (attr: Attribute, offset: int, err: Error) {…}

    parse_attributes ¶

    parse_attributes :: proc(doc: ^Document, attribs: ^[dynamic]Attribute) -> (err: Error) {…}

    parse_body ¶

    parse_body :: proc(doc: ^Document, element: u32, opts: Options) -> (err: Error) {…}

    parse_bytes ¶

    parse_bytes :: proc(
    	data:          []u8, 
    	options:       Options = DEFAULT_OPTIONS, 
    	path:          string = "", 
    	error_handler: proc(pos: Pos, msg: string, args: ..any) = default_error_handler, 
    	allocator := context.allocator, 
    ) -> (doc: ^Document, err: Error) {…}

    parse_doctype ¶

    parse_doctype :: proc(doc: ^Document) -> (err: Error) {…}

    parse_prologue ¶

    parse_prologue :: proc(doc: ^Document) -> (err: Error) {…}

    parse_string ¶

    parse_string :: proc(
    	data:          string, 
    	options:       Options = DEFAULT_OPTIONS, 
    	path:          string = "", 
    	error_handler: proc(pos: Pos, msg: string, args: ..any) = default_error_handler, 
    	allocator := context.allocator, 
    ) -> (doc: ^Document, err: Error) {…}

    peek ¶

    peek :: proc(t: ^Tokenizer) -> (token: Token) {…}

    peek_byte ¶

    peek_byte :: proc(t: ^Tokenizer, offset: int = 0) -> u8 {…}

    print ¶

    print :: proc(writer: io.Stream, doc: ^Document) -> (written: int, err: io.Error) {…}
     

    Just for debug purposes.

    print_element :: proc(
    	writer:     io.Stream, 
    	doc:        ^Document, 
    	element_id: u32, 
    	indent:     int = 0, 
    ) -> (written: int, err: io.Error) {…}

    scan ¶

    scan :: proc(t: ^Tokenizer, multiline_string: bool = false) -> Token {…}

    scan_comment ¶

    scan_comment :: proc(t: ^Tokenizer) -> (comment: string, err: Error) {…}
     

    A comment ends when we see -->, preceded by a character that's not a dash. "For compatibility, the string "--" (double-hyphen) must not occur within comments."

    See: https://www.w3.org/TR/2006/REC-xml11-20060816/#dt-comment

    Thanks to the length (4) of the comment start, we also have enough lookback, and the peek at the next byte asserts that there's at least one more character that's a >.

    scan_identifier ¶

    scan_identifier :: proc(t: ^Tokenizer) -> string {…}

    scan_string ¶

    @(optimization_mode="favor_size")
    scan_string :: proc(
    	t:                ^Tokenizer, 
    	offset:           int, 
    	close:            rune = '<', 
    	consume_close:    bool = false, 
    	multiline:        bool = true, 
    	stop_at_comments: bool = false, 
    ) -> (value: string, err: Error) {…}

    skip_cdata ¶

    skip_cdata :: proc(t: ^Tokenizer) -> (err: Error) {…}
     

    Skip CDATA

    skip_element ¶

    skip_element :: proc(t: ^Tokenizer) -> (err: Error) {…}

    skip_pi ¶

    skip_pi :: proc(t: ^Tokenizer) -> (err: Error) {…}

    skip_whitespace ¶

    @(optimization_mode="favor_size")
    skip_whitespace :: proc(t: ^Tokenizer) {…}

    validate_options ¶

    validate_options :: proc(options: Options) -> (validated: Options, err: Error) {…}

    Procedure Groups

    Source Files

    Generation Information

    Generated with odin version dev-2026-11 (vendor "odin") Windows_amd64 @ 2026-11-18 21:05:19.828955300 +0000 UTC