package core:encoding/xml
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'sencodingis only recorded inDocument.encoding; the bytes are never converted. ConvertUTF-16and other encodings toUTF-8first. ForUTF-16, our condolences. -
The DOCTYPE's internal subset (
<!ENTITY,<!ELEMENT,<!ATTLISTand the rest) is skipped. With.Ignore_Unsupported(part ofDEFAULT_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
Index
Constants (5)
Variables (0)
This section is empty.
Procedure Groups (1)
Types
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
- load_from_file
- parse_bytes
- parse_string
- parse (procedure groups)
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 ¶
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, }
Option_Flags ¶
Option_Flags :: bit_set[Option_Flag; u16]
Options ¶
Options :: struct { flags: bit_set[Option_Flag; u16], expected_doctype: string, }
Related Procedures With Parameters
- load_from_file
- parse_body
- parse_bytes
- parse_string
- validate_options
- parse (procedure groups)
Related Constants
Token ¶
Token :: struct { kind: Token_Kind, text: string, pos: Pos, }
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_END ¶
CDATA_END :: "]]>"
CDATA_START ¶
CDATA_START :: "<![CDATA["
COMMENT_END ¶
COMMENT_END :: "-->"
COMMENT_START ¶
COMMENT_START :: "<!--"
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) {…}
destroy ¶
destroy :: proc(doc: ^Document, allocator := context.allocator) {…}
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, ) {…}
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
print ¶
Just for debug purposes.
scan_comment ¶
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 >.
skip_cdata ¶
Skip CDATA
skip_whitespace ¶
@(optimization_mode="favor_size") skip_whitespace :: proc(t: ^Tokenizer) {…}
Procedure Groups
parse ¶
parse :: proc{ parse_string, parse_bytes, }
Source Files
Generation Information
Generated with odin version dev-2026-11 (vendor "odin") Windows_amd64 @ 2026-11-18 21:05:19.828955300 +0000 UTC