tabnasxml

README

tabnas/xml (Go)

A Jsonic grammar plugin that parses XML text into a tree of elements, with support for attributes, mixed content, namespaces, entities, CDATA sections, comments, processing instructions, and DOCTYPE declarations.

This is the Go module. It is a faithful port of the canonical TypeScript package @tabnas/xml (see its README); both pass the same shared conformance fixtures.

Install

go get github.com/tabnas/xml/go

The jsonic engine (github.com/tabnas/jsonic/go) is pulled in as a dependency. While building from a source checkout before the modules are published, clone https://github.com/tabnas/jsonic as a sibling of this repo — the module's go.mod resolves github.com/tabnas/jsonic/go via a replace directive to ../../jsonic/go.

Example

package main

import (
	"fmt"

	tabnasjsonic "github.com/tabnas/jsonic/go"
	tabnasxml "github.com/tabnas/xml/go"
)

func main() {
	j := tabnasjsonic.Make()
	if err := j.UseDefaults(tabnasxml.Xml, tabnasxml.Defaults); err != nil {
		panic(err)
	}

	result, _ := j.Parse(`<a>Tom &amp; Jerry</a>`)
	fmt.Println(result)
	// map[attributes:map[] children:[Tom & Jerry] localName:a name:a]
}

The result is a tree of plain Go values: each element is a map[string]any with name, localName, attributes (map[string]any), and children ([]any), plus — where they apply — prefix, namespace, space, and lang.

Documentation

Organised by the Diátaxis framework:

• Tutorial — a guided first parse.
• How-to guide — task recipes (options, errors, embed mode).
• Reference — the public API, every option, and the accepted XML syntax.
• Concepts — how the parser works on the engine, plus a "Differences from the TS version" section.

License

Copyright (c) Richard Rodger and other contributors, MIT License.

Documentation

Overview

Package tabnasxml 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.2.0"

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.