xml

func Format ¶

func Format() string

Format returns the format identifier for this parser. Returns "XML" to identify this as the XML data format parser.

func InterfaceToNode ¶

func InterfaceToNode(v interface{}) (ast.SchemaNode, error)

InterfaceToNode converts native Go types to AST nodes for XML.

Converts:

• string → *ast.LiteralNode
• int, int64, int32, etc → *ast.LiteralNode
• float64, float32 → *ast.LiteralNode
• bool → *ast.LiteralNode
• nil → *ast.LiteralNode
• []interface{} → *ast.ArrayDataNode
• map[string]interface{} → *ast.ObjectNode
• *Element → *ast.ObjectNode

This function recursively processes nested structures.

For XML structure, expects:

• Attributes as "@attrname" keys
• Text content as "#text" key
• CDATA sections as "#cdata" key
• Child elements as nested maps

Example:

data := map[string]interface{}{
    "@id": "123",
    "name": map[string]interface{}{"#text": "Alice"},
}
node, _ := xml.InterfaceToNode(data)
// node is an *ast.ObjectNode representing the XML structure

func Marshal ¶

func Marshal(v interface{}) ([]byte, error)

Marshal returns the XML encoding of v.

Marshal traverses the value v recursively. If an encountered value implements the xml.Marshaler interface, Marshal calls its MarshalXML method to produce XML.

Otherwise, Marshal uses the following type-dependent default encodings:

Boolean values encode as XML text (true/false).

Floating point, integer values encode as XML text.

String values encode as XML text with proper escaping.

Array and slice values encode as a sequence of XML elements with the same name.

Struct values encode as XML elements. Each exported struct field becomes either an XML element or attribute, using the field name as the element/attribute name, unless the field is omitted for one of the reasons given below.

The encoding of each struct field can be customized by the format string stored under the "xml" key in the struct field's tag. The format string gives the name of the field, possibly followed by a comma-separated list of options. The name may be empty in order to specify options without overriding the default field name.

The "attr" option specifies that the field should be encoded as an XML attribute.

The "chardata" option specifies that the field contains the text content of the element.

The "cdata" option specifies that the field contains CDATA content.

The "omitempty" option specifies that the field should be omitted from the encoding if the field has an empty value, defined as false, 0, a nil pointer, a nil interface value, and any empty array, slice, map, or string.

As a special case, if the field tag is "-", the field is always omitted.

Map values encode as XML elements with map keys as element names. The map's key type must be a string; the map keys are used as XML element names.

Pointer values encode as the value pointed to. A nil pointer encodes as an empty XML element.

Interface values encode as the value contained in the interface. A nil interface value encodes as an empty XML element.

XML cannot represent cyclic data structures and Marshal does not handle them. Passing cyclic structures to Marshal will result in an error.

func MarshalIndent ¶

func MarshalIndent(v interface{}, prefix, indent string) ([]byte, error)

MarshalIndent works like Marshal but with indentation for readability. Each XML element begins on a new line starting with prefix followed by one or more copies of indent according to the nesting depth.

func NodeToInterface ¶

func NodeToInterface(node ast.SchemaNode) interface{}

NodeToInterface converts an AST node to native Go types.

Converts:

• *ast.LiteralNode → primitives (string, int64, float64, bool, nil)
• *ast.ArrayDataNode → []interface{}
• *ast.ObjectNode (array - legacy) → []interface{}
• *ast.ObjectNode (object) → map[string]interface{}

This function recursively processes nested structures.

For XML, this preserves the structure:

• Attributes as "@attrname" keys
• Text content as "#text" key
• CDATA sections as "#cdata" key
• Child elements as nested maps

Example:

node, _ := xml.Parse(`<user id="123"><name>Alice</name></user>`)
data := xml.NodeToInterface(node)
// data is map[string]interface{}{"@id":"123", "name":map[string]interface{}{"#text":"Alice"}}

func Parse ¶

func Parse(input string) (ast.SchemaNode, error)

Parse parses XML format into an AST from a string.

The input is a complete XML document with a root element.

Returns an ast.SchemaNode representing the parsed XML:

• *ast.ObjectNode for elements
• Properties prefixed with "@" for attributes
• "#text" property for text content
• "#cdata" property for CDATA sections

For parsing large files or streaming data, use ParseReader instead.

Example:

node, err := xml.Parse(`<user id="123"><name>Alice</name></user>`)
obj := node.(*ast.ObjectNode)
idNode, _ := obj.GetProperty("@id")
id := idNode.(*ast.LiteralNode).Value().(string) // "123"

func ParseReader ¶

func ParseReader(reader io.Reader) (ast.SchemaNode, error)

ParseReader parses XML format into an AST from an io.Reader.

This function is designed for parsing large XML files or streaming data with constant memory usage. It uses a buffered stream implementation that reads data in chunks, making it suitable for files that don't fit entirely in memory.

The reader can be any io.Reader implementation:

• os.File for reading from files
• strings.Reader for reading from strings
• bytes.Buffer for reading from byte slices
• Network streams, compressed streams, etc.

Returns an ast.SchemaNode representing the parsed XML:

• *ast.ObjectNode for elements
• Properties prefixed with "@" for attributes
• "#text" property for text content
• "#cdata" property for CDATA sections

Example parsing from a file:

file, err := os.Open("data.xml")
if err != nil {
    // handle error
}
defer file.Close()

node, err := xml.ParseReader(file)
if err != nil {
    // handle error
}
// node is now a *ast.ObjectNode representing the XML data

func ReleaseTree ¶

func ReleaseTree(node ast.SchemaNode)

ReleaseTree recursively releases all nodes in an AST tree back to their pools. This should be called when you're completely done with an AST (after conversion, rendering, etc.) to enable node reuse and reduce memory pressure.

Example:

node, _ := xml.Parse(`<user id="123"><name>Alice</name></user>`)
data := xml.NodeToInterface(node)
xml.ReleaseTree(node)  // Release nodes back to pool

func Render ¶

func Render(node ast.SchemaNode) ([]byte, error)

Render converts an AST node to compact XML bytes.

The node should be the result of Parse() or ParseReader(). Returns XML bytes with no unnecessary whitespace.

The XML structure uses Shape's conventions:

• Properties prefixed with "@" are attributes
• Property "#text" contains text content
• Property "#cdata" contains CDATA sections
• Other properties are child elements

Example:

node, _ := xml.Parse(`<user id="123"><name>Alice</name></user>`)
bytes, _ := xml.Render(node)
// bytes: <user id="123"><name>Alice</name></user>

func RenderIndent ¶

func RenderIndent(node ast.SchemaNode, prefix, indent string) ([]byte, error)

RenderIndent converts an AST node to pretty-printed XML bytes with indentation.

The prefix is added to the beginning of each line, and indent specifies the indentation string (typically spaces or tabs).

Common usage:

• RenderIndent(node, "", " ") - 2-space indentation
• RenderIndent(node, "", "\t") - tab indentation
• RenderIndent(node, ">>", " ") - prefix each line with ">>"

Example:

node, _ := xml.Parse(`<user id="123"><name>Alice</name></user>`)
bytes, _ := xml.RenderIndent(node, "", "  ")
// Output:
// <user id="123">
//   <name>Alice</name>
// </user>

func Unmarshal ¶

func Unmarshal(data []byte, v interface{}) error

Unmarshal parses the XML-encoded data and stores the result in the value pointed to by v.

This function uses a high-performance fast path that bypasses AST construction for optimal performance (4-5x faster than AST path). If you need the AST for advanced features, use Parse() followed by NodeToInterface().

Unmarshal uses XML struct tags to map XML elements and attributes to struct fields:

type User struct {
    ID   string `xml:"id,attr"`     // Attribute
    Name string `xml:"name"`         // Child element
    Bio  string `xml:",chardata"`    // Text content
}

To unmarshal XML into an interface value, Unmarshal stores a map[string]interface{} representation:

• "@attrname" for attributes
• "#text" for text content
• "#cdata" for CDATA sections
• "childname" for child elements

func Validate ¶

func Validate(input string) error

Validate checks if the given string is valid XML. It uses the fast parser for efficient validation without AST construction.

Returns nil if the input is valid XML. Returns an error with details about why the XML is invalid.

This is the idiomatic Go approach - check the error:

if err := xml.Validate(input); err != nil {
    // Invalid XML
    fmt.Println("Invalid XML:", err)
}
// Valid XML - err is nil

For validating large files or streaming data, use ValidateReader instead.

func ValidateReader ¶

func ValidateReader(reader io.Reader) error

ValidateReader checks if the XML from an io.Reader is valid. It uses the fast parser for efficient validation without AST construction.

This function is designed for validating large XML files or streaming data without loading the entire content into memory.

Returns nil if the input is valid XML. Returns an error with details about why the XML is invalid.

Example validating from a file:

file, err := os.Open("data.xml")
if err != nil {
    // handle error
}
defer file.Close()

if err := xml.ValidateReader(file); err != nil {
    // Invalid XML
    fmt.Println("Invalid XML:", err)
}
// Valid XML - err is nil