xml

README

XML

An experimental XML library in Go.

To use it in your project, import it like so:

import mellium.im/xml

If you'd like to contribute to the project, see CONTRIBUTING.md.

License

The package may be used under the terms of the BSD 2-Clause License a copy of which may be found in the file "LICENSE".

Unless you explicitly state otherwise, any contribution submitted for inclusion in the work by you shall be licensed as above, without any additional terms or conditions.

Documentation

Overview

Package xml contains experimental XML functionality.

This package may be deprecated or removed at any time.

Example (CustomMarshalXML)

package main

import (
	"encoding/xml"
	"fmt"
	"log"
	"strings"
)

type Animal int

const (
	Unknown Animal = iota
	Gopher
	Zebra
)

func (a *Animal) UnmarshalXML(d *xml.Decoder, start xml.StartElement) error {
	var s string
	if err := d.DecodeElement(&s, &start); err != nil {
		return err
	}
	switch strings.ToLower(s) {
	default:
		*a = Unknown
	case "gopher":
		*a = Gopher
	case "zebra":
		*a = Zebra
	}

	return nil
}

func (a Animal) MarshalXML(e *xml.Encoder, start xml.StartElement) error {
	var s string
	switch a {
	default:
		s = "unknown"
	case Gopher:
		s = "gopher"
	case Zebra:
		s = "zebra"
	}
	return e.EncodeElement(s, start)
}

func main() {
	blob := `
	<animals>
		<animal>gopher</animal>
		<animal>armadillo</animal>
		<animal>zebra</animal>
		<animal>unknown</animal>
		<animal>gopher</animal>
		<animal>bee</animal>
		<animal>gopher</animal>
		<animal>zebra</animal>
	</animals>`
	var zoo struct {
		Animals []Animal `xml:"animal"`
	}
	if err := xml.Unmarshal([]byte(blob), &zoo); err != nil {
		log.Fatal(err)
	}

	census := make(map[Animal]int)
	for _, animal := range zoo.Animals {
		census[animal] += 1
	}

	fmt.Printf("Zoo Census:\n* Gophers: %d\n* Zebras:  %d\n* Unknown: %d\n",
		census[Gopher], census[Zebra], census[Unknown])

}

Output:

Zoo Census:
* Gophers: 3
* Zebras:  2
* Unknown: 3

Example (TextMarshalXML)

package main

import (
	"encoding/xml"
	"fmt"
	"log"
	"strings"
)

type Size int

const (
	Unrecognized Size = iota
	Small
	Large
)

func (s *Size) UnmarshalText(text []byte) error {
	switch strings.ToLower(string(text)) {
	default:
		*s = Unrecognized
	case "small":
		*s = Small
	case "large":
		*s = Large
	}
	return nil
}

func (s Size) MarshalText() ([]byte, error) {
	var name string
	switch s {
	default:
		name = "unrecognized"
	case Small:
		name = "small"
	case Large:
		name = "large"
	}
	return []byte(name), nil
}

func main() {
	blob := `
	<sizes>
		<size>small</size>
		<size>regular</size>
		<size>large</size>
		<size>unrecognized</size>
		<size>small</size>
		<size>normal</size>
		<size>small</size>
		<size>large</size>
	</sizes>`
	var inventory struct {
		Sizes []Size `xml:"size"`
	}
	if err := xml.Unmarshal([]byte(blob), &inventory); err != nil {
		log.Fatal(err)
	}

	counts := make(map[Size]int)
	for _, size := range inventory.Sizes {
		counts[size] += 1
	}

	fmt.Printf("Inventory Counts:\n* Small:        %d\n* Large:        %d\n* Unrecognized: %d\n",
		counts[Small], counts[Large], counts[Unrecognized])

}

Output:

Inventory Counts:
* Small:        3
* Large:        2
* Unrecognized: 3

Index

• Variables
• func Split(data []byte, atEOF bool) (advance int, token []byte, err error)
• type Attr
• type CharData
• type Comment
• type Decoder
  • func NewDecoder(r io.Reader) *Decoder
• type Directive
• type Encoder
• type EndElement
• type Marshaler
• type MarshalerAttr
• type Name
• type ProcInst
• type StartElement
• type SyntaxError
• type TagPathError
• type Token
• type TokenReader
• type Tokenizer
  • func NewTokenizer(r io.Reader) *Tokenizer
  • func (t *Tokenizer) Token() (Token, error)
• type Unmarshaler
• type UnmarshalerAttr
• type UnsupportedTypeError

Examples

• Package (CustomMarshalXML)
• Package (TextMarshalXML)
• Encoder

Variables

var (
	MarshalIndent   = xml.MarshalIndent
	Marshal         = xml.Marshal
	Unmarshal       = xml.Unmarshal
	NewEncoder      = xml.NewEncoder
	NewTokenDecoder = xml.NewTokenDecoder
	CopyToken       = xml.CopyToken
	EscapeText      = xml.EscapeText
	HTMLAutoClose   = xml.HTMLAutoClose
	HTMLEntity      = xml.HTMLEntity
)

Functions

func Split

func Split(data []byte, atEOF bool) (advance int, token []byte, err error)

Split is a bufio.SplitFunc that splits on XML tokens.

Types

type Attr

type Attr = xml.Attr

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type CharData

type CharData = xml.CharData

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Comment

type Comment = xml.Comment

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Decoder

type Decoder = xml.Decoder

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

func NewDecoder

func NewDecoder(r io.Reader) *Decoder

NewDecoder creates a new XML parser reading from r. If r does not implement io.ByteReader, NewDecoder will do its own buffering.

type Directive

type Directive = xml.Directive

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Encoder

type Encoder = xml.Encoder

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

Example

package main

import (
	"encoding/xml"
	"fmt"
	"os"
)

func main() {
	type Address struct {
		City, State string
	}
	type Person struct {
		XMLName   xml.Name `xml:"person"`
		Id        int      `xml:"id,attr"`
		FirstName string   `xml:"name>first"`
		LastName  string   `xml:"name>last"`
		Age       int      `xml:"age"`
		Height    float32  `xml:"height,omitempty"`
		Married   bool
		Address
		Comment string `xml:",comment"`
	}

	v := &Person{Id: 13, FirstName: "John", LastName: "Doe", Age: 42}
	v.Comment = " Need more details. "
	v.Address = Address{"Hanga Roa", "Easter Island"}

	enc := xml.NewEncoder(os.Stdout)
	enc.Indent("  ", "    ")
	if err := enc.Encode(v); err != nil {
		fmt.Printf("error: %v\n", err)
	}

}

Output:

  <person id="13">
      <name>
          <first>John</first>
          <last>Doe</last>
      </name>
      <age>42</age>
      <Married>false</Married>
      <City>Hanga Roa</City>
      <State>Easter Island</State>
      <!-- Need more details. -->
  </person>

type EndElement

type EndElement = xml.EndElement

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Marshaler

type Marshaler = xml.Marshaler

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type MarshalerAttr

type MarshalerAttr = xml.MarshalerAttr

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Name

type Name = xml.Name

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type ProcInst

type ProcInst = xml.ProcInst

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type StartElement

type StartElement = xml.StartElement

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type SyntaxError

type SyntaxError = xml.SyntaxError

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type TagPathError

type TagPathError = xml.TagPathError

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Token

type Token = xml.Token

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type TokenReader

type TokenReader = xml.TokenReader

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type Tokenizer

type Tokenizer struct {
	// contains filtered or unexported fields
}

Tokenizer splits a reader into XML tokens without performing any verification or namespace resolution on those tokens.

func NewTokenizer

func NewTokenizer(r io.Reader) *Tokenizer

NewTokenizer creates a new XML parser reading from r. If r does not implement io.ByteReader, NewDecoder will do its own buffering.

func (*Tokenizer) Token

func (t *Tokenizer) Token() (Token, error)

Token returns the next XML token in the input stream. At the end of the input stream, Token returns nil, io.EOF.

type Unmarshaler

type Unmarshaler = xml.Unmarshaler

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type UnmarshalerAttr

type UnmarshalerAttr = xml.UnmarshalerAttr

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.

type UnsupportedTypeError

type UnsupportedTypeError = xml.UnsupportedTypeError

Various types re-used from the standard library XML package, aliased here so that both packages don't need to be imported.