saxparser

README

The saxparser package

A SAX parser in Go.

It parses an XML without loading the entire contents into memory. Instead it uses callback functions to notify the user of the different elements as it goes along the file. It is a very thin wrapper over encoding/xml.

Tests are provided with full code coverage (issue: go test and go test -cover).

Documentation is also provided, it can be viewed using the godoc tool.

Documentation

Overview

Package saxparser is a very thin wrapper over encoding/xml providing a SAX-like API with callback functions corresponding to all the XML element types.

Index

• type SaxHandler
• type SaxParser
  • func NewParser(reader io.Reader, handler SaxHandler) *SaxParser
  • func (p *SaxParser) Parse() error

Types

type SaxHandler

type SaxHandler interface {
	/*
		Characters is a handler function for character data -- i.e. the characters
		between and opening and a closing tag. Please note, that any whitespace between
		two tags is considered to be character data so a lot of these callback will be made
		for formatting spaces. This is relatively easy to filter out though.
	*/
	Characters(chars []byte)

	/*
		Comment is the callback function for comments (the starting and ending symbols are
		not included).
	*/
	Comment(chars []byte)

	/*
		Directive is the callback function for XML directives: <!directive ...>.
	*/
	Directive(chars []byte)

	/*
		EndElement is the callback function for end elements.
	*/
	EndElement(name string)

	/*
		ProcessingInstruction is the callback function for procInsts, i.e.
		elements in the form of: <?...>
	*/
	ProcessingInstruction(target string, instruction []byte)

	/*
		StartElement is the callback function for start elements. The name of
		the element and a map of attributes is given.
	*/
	StartElement(name string, attributes map[string]string)
}

SaxHandler is an interface for the callback functions for the SAX parser. It defines a function for each XML element type. By implementing the interface, an XML document can be processed as a series of events. If the implementing struct is given state, it can act as a state machine that is able determine the current position is a well-formed XML and act accordingly.

type SaxParser

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

SaxParser is the struct encompassing the XML parser. It holds a pointer to an xml.Decoder and the SaxHandler implementation.

func NewParser

func NewParser(reader io.Reader, handler SaxHandler) *SaxParser

NewParser creates a new SaxParser. It expects an io.Reader for the XML document and a SaxHandler implementation.

func (*SaxParser) Parse

func (p *SaxParser) Parse() error

Parse performs the actual parsing of the XML document. It processes the XML file, calls the callback functions of the provided SaxHandler implementation and returns an error if anything goes wrong -- it simply forwards the errors of encoding/xml.Decoder.Token().