xml

Documentation

Overview

Package xml implements a simple XML 1.0 parser that understands XML name spaces.

Index

• Variables
• func Escape(w io.Writer, s []byte)
• func Unmarshal(r io.Reader, val interface{}) os.Error
• type Attr
• type CharData
  • func (c CharData) Copy() CharData
• type Comment
  • func (c Comment) Copy() Comment
• type Directive
  • func (d Directive) Copy() Directive
• type EndElement
• type Name
• type Parser
  • func NewParser(r io.Reader) *Parser
  • func (p *Parser) RawToken() (Token, os.Error)
  • func (p *Parser) Skip() os.Error
  • func (p *Parser) Token() (t Token, err os.Error)
  • func (p *Parser) Unmarshal(val interface{}, start *StartElement) os.Error
• type ProcInst
  • func (p ProcInst) Copy() ProcInst
• type StartElement
  • func (e StartElement) Copy() StartElement
• type SyntaxError
  • func (e *SyntaxError) String() string
• type TagPathError
  • func (e *TagPathError) String() string
• type Token
  • func CopyToken(t Token) Token
• type UnmarshalError
  • func (e UnmarshalError) String() string
• Bugs

Variables

var HTMLAutoClose = htmlAutoClose

HTMLAutoClose is the set of HTML elements that should be considered to close automatically.

var HTMLEntity = htmlEntity

HTMLEntity is an entity map containing translations for the standard HTML entity characters.

Functions

func Escape

func Escape(w io.Writer, s []byte)

Escape writes to w the properly escaped XML equivalent of the plain text data s.

func Unmarshal

func Unmarshal(r io.Reader, val interface{}) os.Error

Unmarshal parses an XML element from r and uses the reflect library to fill in an arbitrary struct, slice, or string pointed at by val. Well-formed data that does not fit into val is discarded.

For example, given these definitions:

type Email struct {
	Where string "attr"
	Addr  string
}

type Result struct {
	XMLName xml.Name "result"
	Name	string
	Phone	string
	Email	[]Email
	Groups  []string "group>value"
}

result := Result{Name: "name", Phone: "phone", Email: nil}

unmarshalling the XML input

<result>
	<email where="home">
		<addr>gre@example.com</addr>
	</email>
	<email where='work'>
		<addr>gre@work.com</addr>
	</email>
	<name>Grace R. Emlin</name>
	<group>
		<value>Friends</value>
		<value>Squash</value>
	</group>
	<address>123 Main Street</address>
</result>

via Unmarshal(r, &result) is equivalent to assigning

r = Result{xml.Name{"", "result"},
	"Grace R. Emlin", // name
	"phone",	  // no phone given
	[]Email{
		Email{"home", "gre@example.com"},
		Email{"work", "gre@work.com"},
	},
	[]string{"Friends", "Squash"},
}

Note that the field r.Phone has not been modified and that the XML <address> element was discarded. Also, the field Groups was assigned considering the element path provided in the field tag.

Because Unmarshal uses the reflect package, it can only assign to upper case fields. Unmarshal uses a case-insensitive comparison to match XML element names to struct field names.

Unmarshal maps an XML element to a struct using the following rules:

• If the struct has a field of type []byte or string with tag "innerxml", Unmarshal accumulates the raw XML nested inside the element in that field. The rest of the rules still apply.

• If the struct has a field named XMLName of type xml.Name, Unmarshal records the element name in that field.

• If the XMLName field has an associated tag string of the form "tag" or "namespace-URL tag", the XML element must have the given tag (and, optionally, name space) or else Unmarshal returns an error.

• If the XML element has an attribute whose name matches a struct field of type string with tag "attr", Unmarshal records the attribute value in that field.

• If the XML element contains character data, that data is accumulated in the first struct field that has tag "chardata". The struct field may have type []byte or string. If there is no such field, the character data is discarded.

• If the XML element contains a sub-element whose name matches the prefix of a struct field tag formatted as "a>b>c", unmarshal will descend into the XML structure looking for elements with the given names, and will map the innermost elements to that struct field. A struct field tag starting with ">" is equivalent to one starting with the field name followed by ">".

• If the XML element contains a sub-element whose name matches a struct field whose tag is neither "attr" nor "chardata", Unmarshal maps the sub-element to that struct field. Otherwise, if the struct has a field named Any, unmarshal maps the sub-element to that struct field.

Unmarshal maps an XML element to a string or []byte by saving the concatenation of that element's character data in the string or []byte.

Unmarshal maps an XML element to a slice by extending the length of the slice and mapping the element to the newly created value.

Unmarshal maps an XML element to a bool by setting it to the boolean value represented by the string.

Unmarshal maps an XML element to an integer or floating-point field by setting the field to the result of interpreting the string value in decimal. There is no check for overflow.

Unmarshal maps an XML element to an xml.Name by recording the element name.

Unmarshal maps an XML element to a pointer by setting the pointer to a freshly allocated value and then mapping the element to that value.

Types

type Attr

type Attr struct {
	Name  Name
	Value string
}

An Attr represents an attribute in an XML element (Name=Value).

type CharData

type CharData []byte

A CharData represents XML character data (raw text), in which XML escape sequences have been replaced by the characters they represent.

func (CharData) Copy

func (c CharData) Copy() CharData

type Comment

type Comment []byte

A Comment represents an XML comment of the form <!--comment-->. The bytes do not include the <!-- and --> comment markers.

func (Comment) Copy

func (c Comment) Copy() Comment

type Directive

type Directive []byte

A Directive represents an XML directive of the form <!text>. The bytes do not include the <! and > markers.

func (Directive) Copy

func (d Directive) Copy() Directive

type EndElement

type EndElement struct {
	Name Name
}

An EndElement represents an XML end element.

type Name

type Name struct {
	Space, Local string
}

A Name represents an XML name (Local) annotated with a name space identifier (Space). In tokens returned by Parser.Token, the Space identifier is given as a canonical URL, not the short prefix used in the document being parsed.

type Parser

type Parser struct {
	// Strict defaults to true, enforcing the requirements
	// of the XML specification.
	// If set to false, the parser allows input containing common
	// mistakes:
	//	* If an element is missing an end tag, the parser invents
	//	  end tags as necessary to keep the return values from Token
	//	  properly balanced.
	//	* In attribute values and character data, unknown or malformed
	//	  character entities (sequences beginning with &) are left alone.
	//
	// Setting:
	//
	//	p.Strict = false;
	//	p.AutoClose = HTMLAutoClose;
	//	p.Entity = HTMLEntity
	//
	// creates a parser that can handle typical HTML.
	Strict bool

	// When Strict == false, AutoClose indicates a set of elements to
	// consider closed immediately after they are opened, regardless
	// of whether an end element is present.
	AutoClose []string

	// Entity can be used to map non-standard entity names to string replacements.
	// The parser behaves as if these standard mappings are present in the map,
	// regardless of the actual map content:
	//
	//	"lt": "<",
	//	"gt": ">",
	//	"amp": "&",
	//	"apos": "'",
	//	"quot": `"`,
	Entity map[string]string

	// CharsetReader, if non-nil, defines a function to generate
	// charset-conversion readers, converting from the provided
	// non-UTF-8 charset into UTF-8. If CharsetReader is nil or
	// returns an error, parsing stops with an error. One of the
	// the CharsetReader's result values must be non-nil.
	CharsetReader func(charset string, input io.Reader) (io.Reader, os.Error)
	// contains filtered or unexported fields
}

A Parser represents an XML parser reading a particular input stream. The parser assumes that its input is encoded in UTF-8.

func NewParser

func NewParser(r io.Reader) *Parser

NewParser creates a new XML parser reading from r.

func (*Parser) RawToken

func (p *Parser) RawToken() (Token, os.Error)

RawToken is like Token but does not verify that start and end elements match and does not translate name space prefixes to their corresponding URLs.

func (*Parser) Skip

func (p *Parser) Skip() os.Error

Have already read a start element. Read tokens until we find the end element. Token is taking care of making sure the end element matches the start element we saw.

func (*Parser) Token

func (p *Parser) Token() (t Token, err os.Error)

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

Slices of bytes in the returned token data refer to the parser's internal buffer and remain valid only until the next call to Token. To acquire a copy of the bytes, call CopyToken or the token's Copy method.

Token expands self-closing elements such as <br/> into separate start and end elements returned by successive calls.

Token guarantees that the StartElement and EndElement tokens it returns are properly nested and matched: if Token encounters an unexpected end element, it will return an error.

Token implements XML name spaces as described by http://www.w3.org/TR/REC-xml-names/. Each of the Name structures contained in the Token has the Space set to the URL identifying its name space when known. If Token encounters an unrecognized name space prefix, it uses the prefix as the Space rather than report an error.

func (*Parser) Unmarshal

func (p *Parser) Unmarshal(val interface{}, start *StartElement) os.Error

The Parser's Unmarshal method is like xml.Unmarshal except that it can be passed a pointer to the initial start element, useful when a client reads some raw XML tokens itself but also defers to Unmarshal for some elements. Passing a nil start element indicates that Unmarshal should read the token stream to find the start element.

type ProcInst

type ProcInst struct {
	Target string
	Inst   []byte
}

A ProcInst represents an XML processing instruction of the form <?target inst?>

func (ProcInst) Copy

func (p ProcInst) Copy() ProcInst

type StartElement

type StartElement struct {
	Name Name
	Attr []Attr
}

A StartElement represents an XML start element.

func (StartElement) Copy

func (e StartElement) Copy() StartElement

type SyntaxError

type SyntaxError struct {
	Msg  string
	Line int
}

A SyntaxError represents a syntax error in the XML input stream.

func (*SyntaxError) String

func (e *SyntaxError) String() string

type TagPathError

type TagPathError struct {
	Struct       reflect.Type
	Field1, Tag1 string
	Field2, Tag2 string
}

A TagPathError represents an error in the unmarshalling process caused by the use of field tags with conflicting paths.

func (*TagPathError) String

func (e *TagPathError) String() string

type Token

type Token interface{}

A Token is an interface holding one of the token types: StartElement, EndElement, CharData, Comment, ProcInst, or Directive.

func CopyToken

func CopyToken(t Token) Token

CopyToken returns a copy of a Token.

type UnmarshalError

type UnmarshalError string

An UnmarshalError represents an error in the unmarshalling process.

func (UnmarshalError) String

func (e UnmarshalError) String() string

Notes

Bugs

• Mapping between XML elements and data structures is inherently flawed: an XML element is an order-dependent collection of anonymous values, while a data structure is an order-independent collection of named values. See package json for a textual representation more suitable to data structures.