xml

Documentation

Overview

Package xml is a Jsonic plugin that parses XML into a tree of elements. The parser supports: elements with open/close and self-closing tags, attributes (single and double quoted with entity decoding), mixed element/text content, predefined and numeric character entity references, namespace resolution from xmlns/xmlns:* declarations, comments, CDATA sections, processing instructions and DOCTYPE declarations.

The returned tree uses `map[string]any` nodes with keys `name`, `localName`, optional `prefix`, optional `namespace`, `attributes` (map of string -> string) and `children` (array of nested elements or text strings).

Index

• Constants
• Variables
• func DecodeBOM(src string) string
• func Xml(j *jsonic.Jsonic, options map[string]any) error
• type EntityDecoder

Constants

const Version = "0.1.1"

Variables

var Defaults = map[string]any{
	"namespaces":     true,
	"entities":       true,
	"customEntities": map[string]string{},
	"strictEntities": true,
	"embed":          false,
}

Defaults are merged with caller-supplied options when the plugin is registered via jsonic.UseDefaults.

Option keys:

namespaces     bool              resolve xmlns / xmlns:* into prefix /
                                 localName / namespace fields on every
                                 element. Default: true.
entities       bool              decode the five predefined entities and
                                 numeric character references in text and
                                 attribute values. Default: true.
customEntities map[string]string extra named entities to recognise.
strictEntities bool              enforce XML 1.0 §4.1: every named entity
                                 reference must resolve to a declared
                                 entity. Default: true. When false,
                                 references to unknown names are left
                                 as-is in the output.
embed          bool              when true, keep Jsonic's JSON/JSONIC
                                 grammar in place and splice an XML
                                 literal alternate into the `val` rule
                                 so `<tag>…</tag>` can appear wherever
                                 Jsonic expects a value. When false
                                 (default) the parser is reconfigured
                                 as a pure-XML parser.

Functions

func DecodeBOM

func DecodeBOM(src string) string

DecodeBOM detects a byte-order mark at the start of `src` and, when the input is encoded as UTF-16 LE/BE or UTF-32 LE/BE, returns a transcoded UTF-8 string. UTF-8 BOMs are returned with the BOM bytes stripped. For input without a recognised BOM, the original string is returned unchanged.

Use this when feeding XML files of unknown encoding into the parser:

body, _ := os.ReadFile(path)
doc, err := j.Parse(xml.DecodeBOM(string(body)))

func Xml

func Xml(j *jsonic.Jsonic, options map[string]any) error

Xml is the Jsonic plugin entry point. Register via:

j := jsonic.Make()
j.UseDefaults(xml.Xml, xml.Defaults)
result, err := j.Parse(src)

Types

type EntityDecoder

type EntityDecoder func(s string, dtd map[string]string) string

EntityDecoder decodes XML entity references in `s`. The optional `dtd` map supplies general entity declarations parsed from the DOCTYPE internal subset; values are recursively expanded with cycle detection.