README
¶
simplexml 
simplexml provides a simple API to read, create and manipulate XML documents at run time in pure Go.
Stability
simplxml underwent a major refactor for v0.1 in order to address comment support and a few other annoyances I had with the API. simplexml is now entering a more stable state as of v0.1. While trunk is not guaranteed to be clear of breaking changes, they will be well documented moving forward, and tags will be available of older releases. Please remember to vendor your dependencies :)
Usage
From Scratch
root := NewTag("root") // a tag is an element that can contain other elements
doc := NewDocument(root) // a document can only contain one root tag
doc.AddBefore(NewComment("simplexml has support for comments outside of the root document"), root)
root.AddAfter(NewTag("foo"), nil) // a nil pointer can be given to append to the end of all elements
root.AddBefore(NewTag("bar"), nil) // or prepend before all elements
bat := NewTag("bat")
bat.AddAfter(NewValue("bat value"), nil)
root.AddAfter(bat, nil)
b, err := doc.Marshal() // a simplexml document implements the Marshaler interface
if err != nil {
panic(err)
}
fmt.Println(string(b))
//Output:
//<!--simplexml has support for comments outside of the root document--><root><bar/><foo/><bat>bat value</bat></root>
From A Reader
xmlString := `<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!-- comment above root element -->
<root>
<!-- <comment>above foo</comment> -->
<foo>
<bar>bat</bar>
<baz/>
<fizz><![CDATA[<foo>contents</foo>]]></fizz>
</foo>
</root>
<!-- comment below root element -->`
// create a document from a reader
doc, err := NewDocumentFromReader(strings.NewReader(xmlString))
if err != nil {
panic(err)
}
// get the fizz tag and value
fizz := doc.Root().Search().ByName("foo").ByName("fizz").One()
if fizz == nil {
panic("fizz is missing")
}
fv, err := fizz.Value()
if err != nil {
panic(err)
}
fmt.Println("fizz: ", fv)
//Output:
//fizz: <foo>contents</foo>
Documentation
¶
Overview ¶
Package simplexml is a simple API to read, write, edit and search XML documents at run time in pure Go. A simplistic design relying on the fmt.Stringer interface to build a document.
Index ¶
- Constants
- func NeedCDATA(s string) bool
- type Attribute
- type CDATA
- type Comment
- type Document
- type Element
- type Search
- type Tag
- func (t *Tag) AddAfter(add Element, after Element) error
- func (t *Tag) AddAttribute(name string, value string, prefix string) *Tag
- func (t *Tag) AddBefore(add Element, before Element) error
- func (t *Tag) AddNamespace(name string, value string) *Tag
- func (t Tag) AvailableNamespaces() []Attribute
- func (t Tag) Elements() []Element
- func (t Tag) GetNamespace(prefix string) (string, error)
- func (t Tag) GetPrefix(ns string) (string, error)
- func (t *Tag) Marshal() ([]byte, error)
- func (t *Tag) Remove(remove Element) error
- func (t *Tag) Search() Search
- func (t Tag) String() string
- func (t Tag) Tags() []*Tag
- func (t Tag) Value() (string, error)
- type Value
- type XPath
- Bugs
Examples ¶
Constants ¶
const (
DefaultDeclaration = "<?xml version=\"1.0\" encding=\"UTF-8\"?>"
)
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Attribute ¶
Attribute is a simple representations of an XML attrbiute, consiting of a prefix, name and value.
func (Attribute) IsNamespace ¶
IsNamespace returns true if it's prefix = 'xmlns' (not case sensitive)
type CDATA ¶
type CDATA string
CDATA is a string representation of XML CDATA without the '<![CDATA[' and ']]>' markup.
type Comment ¶
type Comment string
Comments is a string representation of an XML comment without the '<!--' and '-->' markup.
type Document ¶
type Document struct {
Declaration string
// contains filtered or unexported fields
}
func NewDocument ¶
Example ¶
root := NewTag("root") // a tag is an element that can contain other elements
doc := NewDocument(root) // a document can only contain one root tag
doc.AddBefore(NewComment("simplexml has support for comments outside of the root document"), root)
root.AddAfter(NewTag("foo"), nil) // a nil pointer can be given to append to the end of all elements
root.AddBefore(NewTag("bar"), nil) // or prepend before all elements
bat := NewTag("bat")
bat.AddAfter(NewValue("bat value"), nil)
root.AddAfter(bat, nil)
b, err := doc.Marshal() // a simplexml document implements the Marshaler interface
if err != nil {
panic(err)
}
fmt.Println(string(b))
Output: <!--simplexml has support for comments outside of the root document--><root><bar/><foo/><bat>bat value</bat></root>
func NewDocumentFromReader ¶
NewDocumentFromReader returns a new Document that is generated from an io.Reader using encoding/xml.Decoder
BUG(kyle) Due to the design of xml.Decoder, Tags that define their namespace without a prefix will be converted to use the prefix if it was defined in a parent for use. The result will be a valid document, namespaces stay the same, just the resulting documents format is slightly different. This will be addressed once simplexml is no longer reliant on encoding/xml.
eg: <foo xmlns:urn="http://foo"><bar xmlns="http://foo"/></foo> will be converted to <foo xmlns:urn="http://foo"><urn:bar xmlns="http://foo"/></foo>
Example ¶
xmlString := `<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<!-- comment above root element -->
<root>
<!-- <comment>above foo</comment> -->
<foo>
<bar>bat</bar>
<baz/>
<fizz><![CDATA[<foo>contents</foo>]]></fizz>
</foo>
</root>
<!-- comment below root element -->`
// create a document from a reader
doc, err := NewDocumentFromReader(strings.NewReader(xmlString))
if err != nil {
panic(err)
}
// get the fizz tag and value
fizz := doc.Root().Search().ByName("foo").ByName("fizz").One()
if fizz == nil {
panic("fizz is missing")
}
fv, err := fizz.Value()
if err != nil {
panic(err)
}
fmt.Println("fizz: ", fv)
Output: fizz: <foo>contents</foo>
func (*Document) AddAfter ¶
AddAfter takes an Element pointer (add) and an optional Element pointer (after). If before == nil, the add element will be appended to the elements slice, otherwise it will be placed after the 'after' element. If 'after' != nil and is not found in the current Tags elements, an error will be returned. This method is not recursive.
func (*Document) AddBefore ¶
AddBefore takes an Element pointer (add) and an optional Element pointer (before). If before == nil, the add element will be prepended to the elements slice, otherwise it will be placed before the 'before' element. If 'before' != nil and is not found in the current Tags elements, an error will be returned. This method is not recursive.
func (Document) Marshal ¶
Marshal is a wrapper for String() but returns a []byte, error to conform to the normal Marshaler interface. An error will be returned if the doucment is malformed (returning the first result of Errors()).
type Search ¶
type Search []*Tag
Search is a slice of *Tag
type Tag ¶
type Tag struct {
// Name is the name of the current XML Element
Name string
// Prefix is the optional prefix of an XML element (eg. <prefix:name>)
Prefix string
// Attributes is a slice of *Attribute. Adding, reordering and removing Attributes may be done directly to this slice or with helper methods
Attributes []*Attribute
// contains filtered or unexported fields
}
Tag is an Element that can contain multiple child Elements
func (*Tag) AddAfter ¶
AddAfter takes an Element pointer (add) and an optional Element pointer (after). If before == nil, the add element will be appended to the elements slice, otherwise it will be placed after the 'after' element. If 'after' != nil and is not found in the current Tags elements, an error will be returned. This method is not recursive.
func (*Tag) AddAttribute ¶
AddAttribute appends a new Attribute to the Tag.
func (*Tag) AddBefore ¶
AddBefore takes an Element pointer (add) and an optional Element pointer (before). If before == nil, the add element will be prepended to the elements slice, otherwise it will be placed before the 'before' element. If 'before' != nil and is not found in the current Tags elements, an error will be returned. This method is not recursive.
func (*Tag) AddNamespace ¶
AddNamespace is a wrapper for AddAttribute, setting the prefix to 'xmlns'.
func (Tag) AvailableNamespaces ¶
AvailableNamespaces returns a slice of Attribute from the current Tag and it's parents in which IsNamespace() returns true
func (Tag) GetNamespace ¶
GetNamespace iterates through AvailableNamespaces() and returns a namespace string for the given prefix. An error is returned upon 0 or more than 1 result.
func (Tag) GetPrefix ¶
GetPrefix iterates through AvailableNamespaces() and returns a prefix string for the given namespace. An error is returned upon 0 or more than 1 result.
func (*Tag) Marshal ¶
Marshal is a wrapper for String() but returns a []byte, error to conform to the normal Marshaler interface.
func (*Tag) Remove ¶
Remove will delete an element from the Tag based on the given memory address. An error will be returned if the memory address is not an element of the Tag. This function is not recursive.
func (Tag) String ¶
String returns a string representation of the entire Tag and its inner contents. No error checking is done during String(), allowing for invalid XML to be produced.
Notes ¶
Bugs ¶
Due to the design of xml.Decoder, Tags that define their namespace without a prefix will be converted to use the prefix if it was defined in a parent for use. The result will be a valid document, namespaces stay the same, just the resulting documents format is slightly different. This will be addressed once simplexml is no longer reliant on encoding/xml.
eg: <foo xmlns:urn="http://foo"><bar xmlns="http://foo"/></foo> will be converted to <foo xmlns:urn="http://foo"><urn:bar xmlns="http://foo"/></foo>
Source Files