README
¶
Author: Jim Teeuwen <jimteeuwen at gmail.com>
This package wraps the standard XML library and uses it to build a node tree of
any document you load. This allows you to look up nodes forwards and backwards,
as well as perform search queries (no xpath support).
Nodes now simply become collections and don't require you to read them in the
order in which the xml.Parser finds them.
================================================================================
DEPENDENCIES
================================================================================
goinstall go-charset.googlecode.com/hg/charset
================================================================================
USAGE
================================================================================
Getting the package up and running is simple enough. This should also
automatically take care of any dependencies for you:
$ goinstall github.com/jteeuwen/go-pkg-xmlx
Using it:
import xmlx "github.com/jteeuwen/go-pkg-xmlx"
================================================================================
API
================================================================================
The Document currently implements 2 simple search functions which allow you to
look for specific nodes.
*document.SelectNode(namespace, name string) *Node;
*document.SelectNodes(namespace, name string) []*Node;
SelectNode() returns the first, single node it finds matching the given name
and namespace. SelectNodes() returns a slice containing all the matching nodes.
Note that these search functions can be invoked on individual nodes as well.
This allows you to search only a subset of the entire document.
Each node exposes also a number of functions which allow easy access to a node
value or an attribute value. They come in various forms to allow transparent
conversion to types: int, int64, uint, uint64, float, float32, float64:
*node.S(ns, name string) string
*node.I(ns, name string) int
*node.I64(ns, name string) int64
*node.U(ns, name string) uint
*node.U64(ns, name string) uint64
*node.F(ns, name string) float
*node.F32(ns, name string) float32
*node.F64(ns, name string) float64
*node.B(namespace, name string) bool
Note that these functions actually consider child nodes for matching names as
well as the current node. In effect they first perform a node.SelectNode() and
then return the value of the resulting node converted to the appropriate type.
This allows you to do this:
Consider this piece of xml:
<car>
<color>red</color>
<brand>BMW</brand>
</car>
Now this code:
node := doc.SelectNode("", "car")
brand := node.S("", "brand")
Eventhough 'brand' is not the name of @node, we still get the right value
back (BMW), because node.S() searches through the child nodes when looking
for the value if the current node does not match the given namespace and
name.
For attributes, we only go through the attributes of the current node this
function is invoked on:
*node.As(ns, name string) string
*node.Ai(ns, name string) int
*node.Ai64(ns, name string) int64
*node.Au(ns, name string) uint
*node.Au64(ns, name string) uint64
*node.Af(ns, name string) float
*node.Af32(ns, name string) float32
*node.Af64(ns, name string) float64
*node.Ab(namespace, name string) bool
All of these functions return either "" or 0 when the specified node or
attribute could not be found. No errors are generated.
The namespace name specified in the functions above must either match the
namespace you expect a node/attr to have, or you can specify a wildcard "*".
This makes node searches easier in case you do not care what namespace name
there is or if there is one at all. Node and attribute names as well, may
be supplied as the wildcard "*". This allows us to fetch all child nodes for
a given namespace, regardless of their names.
Documentation
¶
Overview ¶
This package wraps the standard XML library and uses it to build a node tree of any document you load. This allows you to look up nodes forwards and backwards, as well as perform simple search queries.
Nodes now simply become collections and don't require you to read them in the order in which the xml.Parser finds them.
The Document currently implements 2 search functions which allow you to look for specific nodes.
*xmlx.Document.SelectNode(namespace, name string) *Node; *xmlx.Document.SelectNodes(namespace, name string) []*Node;
SelectNode() returns the first, single node it finds matching the given name and namespace. SelectNodes() returns a slice containing all the matching nodes.
Note that these search functions can be invoked on individual nodes as well. This allows you to search only a subset of the entire document.
Index ¶
- Constants
- func EntityToUtf8(entity string) string
- func Utf8ToEntity(entity string) string
- type Attr
- type Document
- func (this *Document) LoadBytes(d []byte) (err error)
- func (this *Document) LoadExtendedEntityMap()
- func (this *Document) LoadFile(filename string) (err error)
- func (this *Document) LoadStream(r io.Reader) (err error)
- func (this *Document) LoadString(s string) (err error)
- func (this *Document) LoadUri(uri string) (err error)
- func (this *Document) SaveBytes() []byte
- func (this *Document) SaveFile(path string) error
- func (this *Document) SaveStream(w io.Writer) (err error)
- func (this *Document) SaveString() string
- func (this *Document) SelectNode(namespace, name string) *Node
- func (this *Document) SelectNodes(namespace, name string) []*Node
- func (this *Document) String() string
- type Node
- func (this *Node) Ab(namespace, name string) bool
- func (this *Node) AddChild(t *Node)
- func (this *Node) Af32(namespace, name string) float32
- func (this *Node) Af64(namespace, name string) float64
- func (this *Node) Ai(namespace, name string) int
- func (this *Node) Ai64(namespace, name string) int64
- func (this *Node) As(namespace, name string) string
- func (this *Node) Au(namespace, name string) uint
- func (this *Node) Au64(namespace, name string) uint64
- func (this *Node) B(namespace, name string) bool
- func (this *Node) Bytes() (b []byte)
- func (this *Node) F32(namespace, name string) float32
- func (this *Node) F64(namespace, name string) float64
- func (this *Node) HasAttr(namespace, name string) bool
- func (this *Node) I(namespace, name string) int
- func (this *Node) I64(namespace, name string) int64
- func (this *Node) RemoveChild(t *Node)
- func (this *Node) S(namespace, name string) string
- func (this *Node) SelectNode(namespace, name string) *Node
- func (this *Node) SelectNodes(namespace, name string) []*Node
- func (this *Node) String() (s string)
- func (this *Node) U(namespace, name string) uint
- func (this *Node) U64(namespace, name string) uint64
- func (this *Node) Unmarshal(obj interface{}) error
Constants ¶
const ( NT_ROOT = iota NT_DIRECTIVE NT_PROCINST NT_COMMENT NT_ELEMENT )
Variables ¶
This section is empty.
Functions ¶
func EntityToUtf8 ¶
Converts a single numerical html entity to a regular Go utf8-token.
func Utf8ToEntity ¶
Converts a single Go utf8-token to a Html entity.
Types ¶
type Document ¶
type Document struct {
Version string // XML version
Encoding string // Encoding found in document. If absent, assumes UTF-8.
StandAlone string // Value of XML doctype's 'standalone' attribute.
SaveDocType bool // Whether not to include the XML doctype in saves.
Root *Node // The document's root node.
Entity map[string]string // Mapping of custom entity conversions.
Verbose bool // [depracated] Not actually used anymore.
}
represents a single XML document.
func (*Document) LoadExtendedEntityMap ¶
func (this *Document) LoadExtendedEntityMap()
This loads a rather massive table of non-conventional xml escape sequences. Needed to make the parser map them to characters properly. It is advised to set only those entities needed manually using the document.Entity map, but if need be, this method can be called to fill the map with the entire set defined on http://www.w3.org/TR/html4/sgml/entities.html
func (*Document) LoadStream ¶
Load the contents of this document from the supplied reader.
func (*Document) LoadString ¶
Load the contents of this document from the supplied string.
func (*Document) SaveStream ¶
Save the contents of this document to the supplied writer.
func (*Document) SaveString ¶
Save the contents of this document as a string.
func (*Document) SelectNode ¶
Select a single node with the given namespace and name. Returns nil if no matching node was found.
func (*Document) SelectNodes ¶
Select all nodes with the given namespace and name. Returns an empty slice if no matches were found.
type Node ¶
type Node struct {
Type byte // Node type.
Name xml.Name // Node namespace and name.
Children []*Node // Child nodes.
Attributes []*Attr // Node attributes.
Parent *Node // Parent node.
Value string // Node value.
Target string // procinst field.
}
func (*Node) Bytes ¶
Convert node to appropriate []byte representation based on it's @Type. Note that NT_ROOT is a special-case empty node used as the root for a Document. This one has no representation by itself. It merely forwards the String() call to it's child nodes.
func (*Node) SelectNode ¶
Select single node by name
func (*Node) SelectNodes ¶
Select multiple nodes by name
Source Files