etree: github.com/beevik/etree Index | Examples | Files

package etree

import "github.com/beevik/etree"

Package etree provides XML services through an Element Tree abstraction.

Index

Examples

Package Files

etree.go helpers.go path.go

Constants

const (
    // NoIndent is used with the Document Indent function to disable all
    // indenting.
    NoIndent = -1
)

Variables

var ErrXML = errors.New("etree: invalid XML format")

ErrXML is returned when XML parsing fails due to incorrect formatting.

type Attr Uses

type Attr struct {
    Space, Key string // The attribute's namespace prefix and key
    Value      string // The attribute value string
    // contains filtered or unexported fields
}

An Attr represents a key-value attribute within an XML element.

func (*Attr) Element Uses

func (a *Attr) Element() *Element

Element returns a pointer to the element containing this attribute.

func (*Attr) FullKey Uses

func (a *Attr) FullKey() string

FullKey returns this attribute's complete key, including namespace prefix if present.

func (*Attr) NamespaceURI Uses

func (a *Attr) NamespaceURI() string

NamespaceURI returns the XML namespace URI associated with this attribute. The function returns the empty string if the attribute is unprefixed or if the attribute is part of the XML default namespace.

type CharData Uses

type CharData struct {
    Data string // the simple text or CDATA section content
    // contains filtered or unexported fields
}

CharData may be used to represent simple text data or a CDATA section within an XML document. The Data property should never be modified directly; use the SetData method instead.

func NewCData Uses

func NewCData(data string) *CharData

NewCData creates an unparented XML character CDATA section with 'data' as its content.

func NewCharData Uses

func NewCharData(data string) *CharData

NewCharData creates an unparented CharData token containing simple text data.

Deprecated: NewCharData is deprecated. Instead, use NewText, which does the same thing.

func NewText Uses

func NewText(text string) *CharData

NewText creates an unparented CharData token containing simple text data.

func (*CharData) Index Uses

func (c *CharData) Index() int

Index returns the index of this CharData token within its parent element's list of child tokens. If this CharData token has no parent, then the function returns -1.

func (*CharData) IsCData Uses

func (c *CharData) IsCData() bool

IsCData returns true if this CharData token is contains a CDATA section. It returns false if the CharData token contains simple text.

func (*CharData) IsWhitespace Uses

func (c *CharData) IsWhitespace() bool

IsWhitespace returns true if this CharData token contains only whitespace.

func (*CharData) Parent Uses

func (c *CharData) Parent() *Element

Parent returns this CharData token's parent element, or nil if it has no parent.

func (*CharData) SetData Uses

func (c *CharData) SetData(text string)

SetData modifies the content of the CharData token. In the case of a CharData token containing simple text, the simple text is modified. In the case of a CharData token containing a CDATA section, the CDATA section's content is modified.

type Comment Uses

type Comment struct {
    Data string // the comment's text
    // contains filtered or unexported fields
}

A Comment represents an XML comment.

func NewComment Uses

func NewComment(comment string) *Comment

NewComment creates an unparented comment token.

func (*Comment) Index Uses

func (c *Comment) Index() int

Index returns the index of this Comment token within its parent element's list of child tokens. If this Comment token has no parent, then the function returns -1.

func (*Comment) Parent Uses

func (c *Comment) Parent() *Element

Parent returns comment token's parent element, or nil if it has no parent.

type Directive Uses

type Directive struct {
    Data string // the directive string
    // contains filtered or unexported fields
}

A Directive represents an XML directive.

func NewDirective Uses

func NewDirective(data string) *Directive

NewDirective creates an unparented XML directive token.

func (*Directive) Index Uses

func (d *Directive) Index() int

Index returns the index of this Directive token within its parent element's list of child tokens. If this Directive token has no parent, then the function returns -1.

func (*Directive) Parent Uses

func (d *Directive) Parent() *Element

Parent returns directive token's parent element, or nil if it has no parent.

type Document Uses

type Document struct {
    Element
    ReadSettings  ReadSettings
    WriteSettings WriteSettings
}

A Document is a container holding a complete XML tree.

A document has a single embedded element, which contains zero or more child tokens, one of which is usually the root element. The embedded element may include other children such as processing instruction tokens or character data tokens. The document's embedded element is never directly serialized; only its children are.

A document also contains read and write settings, which influence the way the document is deserialized, serialized, and indented.

Create an etree Document, add XML entities to it, and serialize it to stdout.

Code:

doc := NewDocument()
doc.CreateProcInst("xml", `version="1.0" encoding="UTF-8"`)
doc.CreateProcInst("xml-stylesheet", `type="text/xsl" href="style.xsl"`)

people := doc.CreateElement("People")
people.CreateComment("These are all known people")

jon := people.CreateElement("Person")
jon.CreateAttr("name", "Jon O'Reilly")

sally := people.CreateElement("Person")
sally.CreateAttr("name", "Sally")

doc.Indent(2)
doc.WriteTo(os.Stdout)

Output:

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="style.xsl"?>
<People>
  <!--These are all known people-->
  <Person name="Jon O&apos;Reilly"/>
  <Person name="Sally"/>
</People>

Code:

doc := NewDocument()
if err := doc.ReadFromFile("document.xml"); err != nil {
    panic(err)
}

func NewDocument Uses

func NewDocument() *Document

NewDocument creates an XML document without a root element.

func NewDocumentWithRoot Uses

func NewDocumentWithRoot(e *Element) *Document

NewDocumentWithRoot creates an XML document and sets the element 'e' as its root element. If the element 'e' is already part of another document, it is first removed from its existing document.

func (*Document) Copy Uses

func (d *Document) Copy() *Document

Copy returns a recursive, deep copy of the document.

func (*Document) Indent Uses

func (d *Document) Indent(spaces int)

Indent modifies the document's element tree by inserting character data tokens containing newlines and indentation. The amount of indentation per depth level is given by the 'spaces' parameter. Pass etree.NoIndent for 'spaces' if you want no indentation at all.

func (*Document) IndentTabs Uses

func (d *Document) IndentTabs()

IndentTabs modifies the document's element tree by inserting CharData tokens containing newlines and tabs for indentation. One tab is used per indentation level.

func (*Document) ReadFrom Uses

func (d *Document) ReadFrom(r io.Reader) (n int64, err error)

ReadFrom reads XML from the reader 'r' into this document. The function returns the number of bytes read and any error encountered.

func (*Document) ReadFromBytes Uses

func (d *Document) ReadFromBytes(b []byte) error

ReadFromBytes reads XML from the byte slice 'b' into the this document.

func (*Document) ReadFromFile Uses

func (d *Document) ReadFromFile(filepath string) error

ReadFromFile reads XML from a local file at path 'filepath' into this document.

func (*Document) ReadFromString Uses

func (d *Document) ReadFromString(s string) error

ReadFromString reads XML from the string 's' into this document.

func (*Document) Root Uses

func (d *Document) Root() *Element

Root returns the root element of the document. It returns nil if there is no root element.

func (*Document) SetRoot Uses

func (d *Document) SetRoot(e *Element)

SetRoot replaces the document's root element with the element 'e'. If the document already has a root element when this function is called, then the existing root element is unbound from the document. If the element 'e' is part of another document, then it is unbound from the other document.

func (*Document) WriteTo Uses

func (d *Document) WriteTo(w io.Writer) (n int64, err error)

WriteTo serializes the document out to the writer 'w'. The function returns the number of bytes written and any error encountered.

func (*Document) WriteToBytes Uses

func (d *Document) WriteToBytes() (b []byte, err error)

WriteToBytes serializes this document into a slice of bytes.

func (*Document) WriteToFile Uses

func (d *Document) WriteToFile(filepath string) error

WriteToFile serializes the document out to the file at path 'filepath'.

func (*Document) WriteToString Uses

func (d *Document) WriteToString() (s string, err error)

WriteToString serializes this document into a string.

type Element Uses

type Element struct {
    Space, Tag string  // namespace prefix and tag
    Attr       []Attr  // key-value attribute pairs
    Child      []Token // child tokens (elements, comments, etc.)
    // contains filtered or unexported fields
}

An Element represents an XML element, its attributes, and its child tokens.

func NewElement Uses

func NewElement(tag string) *Element

NewElement creates an unparented element with the specified tag (i.e., name). The tag may include a namespace prefix followed by a colon.

func (*Element) AddChild Uses

func (e *Element) AddChild(t Token)

AddChild adds the token 't' as the last child of the element. If token 't' was already the child of another element, it is first removed from its parent element.

func (*Element) ChildElements Uses

func (e *Element) ChildElements() []*Element

ChildElements returns all elements that are children of this element.

func (*Element) Copy Uses

func (e *Element) Copy() *Element

Copy creates a recursive, deep copy of the element and all its attributes and children. The returned element has no parent but can be parented to a another element using AddChild, or added to a document with SetRoot or NewDocumentWithRoot.

func (*Element) CreateAttr Uses

func (e *Element) CreateAttr(key, value string) *Attr

CreateAttr creates an attribute with the specified 'key' and 'value' and adds it to this element. If an attribute with same key already exists on this element, then its value is replaced. The key may include a namespace prefix followed by a colon.

func (*Element) CreateCData Uses

func (e *Element) CreateCData(data string) *CharData

CreateCData creates a CharData token containing a CDATA section with 'data' as its content and adds it to the end of this element's list of child tokens.

func (*Element) CreateCharData Uses

func (e *Element) CreateCharData(data string) *CharData

CreateCharData creates a CharData token simple text data and adds it to the end of this element's list of child tokens.

Deprecated: CreateCharData is deprecated. Instead, use CreateText, which does the same thing.

func (*Element) CreateComment Uses

func (e *Element) CreateComment(comment string) *Comment

CreateComment creates a comment token using the specified 'comment' string and adds it as the last child token of this element.

func (*Element) CreateDirective Uses

func (e *Element) CreateDirective(data string) *Directive

CreateDirective creates an XML directive token with the specified 'data' value and adds it as the last child token of this element.

func (*Element) CreateElement Uses

func (e *Element) CreateElement(tag string) *Element

CreateElement creates a new element with the specified tag (i.e., name) and adds it as the last child token of this element. The tag may include a prefix followed by a colon.

func (*Element) CreateProcInst Uses

func (e *Element) CreateProcInst(target, inst string) *ProcInst

CreateProcInst creates an XML processing instruction token with the sepcified 'target' and instruction 'inst'. It is then added as the last child token of this element.

func (*Element) CreateText Uses

func (e *Element) CreateText(text string) *CharData

CreateText creates a CharData token simple text data and adds it to the end of this element's list of child tokens.

func (*Element) FindElement Uses

func (e *Element) FindElement(path string) *Element

FindElement returns the first element matched by the XPath-like 'path' string. The function returns nil if no child element is found using the path. It panics if an invalid path string is supplied.

func (*Element) FindElementPath Uses

func (e *Element) FindElementPath(path Path) *Element

FindElementPath returns the first element matched by the 'path' object. The function returns nil if no element is found using the path.

func (*Element) FindElements Uses

func (e *Element) FindElements(path string) []*Element

FindElements returns a slice of elements matched by the XPath-like 'path' string. The function returns nil if no child element is found using the path. It panics if an invalid path string is supplied.

func (*Element) FindElementsPath Uses

func (e *Element) FindElementsPath(path Path) []*Element

FindElementsPath returns a slice of elements matched by the 'path' object.

func (*Element) FullTag Uses

func (e *Element) FullTag() string

FullTag returns the element e's complete tag, including namespace prefix if present.

func (*Element) GetPath Uses

func (e *Element) GetPath() string

GetPath returns the absolute path of the element. The absolute path is the full path from the document's root.

func (*Element) GetRelativePath Uses

func (e *Element) GetRelativePath(source *Element) string

GetRelativePath returns the path of this element relative to the 'source' element. If the two elements are not part of the same element tree, then the function returns the empty string.

func (*Element) Index Uses

func (e *Element) Index() int

Index returns the index of this element within its parent element's list of child tokens. If this element has no parent, then the function returns -1.

func (*Element) InsertChild Uses

func (e *Element) InsertChild(ex Token, t Token)

InsertChild inserts the token 't' into this element's list of children just before the element's existing child token 'ex'. If the existing element 'ex' does not appear in this element's list of child tokens, then 't' is added to the end of this element's list of child tokens. If token 't' is already the child of another element, it is first removed from the other element's list of child tokens.

Deprecated: InsertChild is deprecated. Use InsertChildAt instead.

func (*Element) InsertChildAt Uses

func (e *Element) InsertChildAt(index int, t Token)

InsertChildAt inserts the token 't' into this element's list of child tokens just before the requested 'index'. If the index is greater than or equal to the length of the list of child tokens, then the token 't' is added to the end of the list of child tokens.

func (*Element) NamespaceURI Uses

func (e *Element) NamespaceURI() string

NamespaceURI returns the XML namespace URI associated with the element. If the element is part of the XML default namespace, NamespaceURI returns the empty string.

func (*Element) Parent Uses

func (e *Element) Parent() *Element

Parent returns this element's parent element. It returns nil if this element has no parent.

func (*Element) RemoveAttr Uses

func (e *Element) RemoveAttr(key string) *Attr

RemoveAttr removes the first attribute of this element whose key matches 'key'. It returns a copy of the removed attribute if a match is found. If no match is found, it returns nil. The key may include a namespace prefix followed by a colon.

func (*Element) RemoveChild Uses

func (e *Element) RemoveChild(t Token) Token

RemoveChild attempts to remove the token 't' from this element's list of child tokens. If the token 't' was a child of this element, then it is removed and returned. Otherwise, nil is returned.

func (*Element) RemoveChildAt Uses

func (e *Element) RemoveChildAt(index int) Token

RemoveChildAt removes the child token appearing in slot 'index' of this element's list of child tokens. The removed child token is then returned. If the index is out of bounds, no child is removed and nil is returned.

func (*Element) SelectAttr Uses

func (e *Element) SelectAttr(key string) *Attr

SelectAttr finds an element attribute matching the requested 'key' and, if found, returns a pointer to the matching attribute. The function returns nil if no matching attribute is found. The key may include a namespace prefix followed by a colon.

func (*Element) SelectAttrValue Uses

func (e *Element) SelectAttrValue(key, dflt string) string

SelectAttrValue finds an element attribute matching the requested 'key' and returns its value if found. If no matching attribute is found, the function returns the 'dflt' value instead. The key may include a namespace prefix followed by a colon.

func (*Element) SelectElement Uses

func (e *Element) SelectElement(tag string) *Element

SelectElement returns the first child element with the given 'tag' (i.e., name). The function returns nil if no child element matching the tag is found. The tag may include a namespace prefix followed by a colon.

func (*Element) SelectElements Uses

func (e *Element) SelectElements(tag string) []*Element

SelectElements returns a slice of all child elements with the given 'tag' (i.e., name). The tag may include a namespace prefix followed by a colon.

func (*Element) SetCData Uses

func (e *Element) SetCData(text string)

SetCData replaces all character data immediately following an element's opening tag with a CDATA section.

func (*Element) SetTail Uses

func (e *Element) SetTail(text string)

SetTail replaces all character data immediately following the element's end tag with the requested string.

func (*Element) SetText Uses

func (e *Element) SetText(text string)

SetText replaces all character data immediately following an element's opening tag with the requested string.

func (*Element) SortAttrs Uses

func (e *Element) SortAttrs()

SortAttrs sorts this element's attributes lexicographically by key.

func (*Element) Tail Uses

func (e *Element) Tail() string

Tail returns all character data immediately following the element's end tag.

func (*Element) Text Uses

func (e *Element) Text() string

Text returns all character data immediately following the element's opening tag.

type ErrPath Uses

type ErrPath string

ErrPath is returned by path functions when an invalid etree path is provided.

func (ErrPath) Error Uses

func (err ErrPath) Error() string

Error returns the string describing a path error.

type Path Uses

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

A Path is a string that represents a search path through an etree starting from the document root or an arbitrary element. Paths are used with the Element object's Find* methods to locate and return desired elements.

A Path consists of a series of slash-separated "selectors", each of which may be modified by one or more bracket-enclosed "filters". Selectors are used to traverse the etree from element to element, while filters are used to narrow the list of candidate elements at each node.

Although etree Path strings are structurally and behaviorally similar to XPath strings (https://www.w3.org/TR/1999/REC-xpath-19991116/), they have a more limited set of selectors and filtering options.

The following selectors are supported by etree paths:

.               Select the current element.
..              Select the parent of the current element.
*               Select all child elements of the current element.
/               Select the root element when used at the start of a path.
//              Select all descendants of the current element.
tag             Select all child elements with a name matching the tag.

The following basic filters are supported:

[@attrib]       Keep elements with an attribute named attrib.
[@attrib='val'] Keep elements with an attribute named attrib and value matching val.
[tag]           Keep elements with a child element named tag.
[tag='val']     Keep elements with a child element named tag and text matching val.
[n]             Keep the n-th element, where n is a numeric index starting from 1.

The following function-based filters are supported:

[text()]                    Keep elements with non-empty text.
[text()='val']              Keep elements whose text matches val.
[local-name()='val']        Keep elements whose un-prefixed tag matches val.
[name()='val']              Keep elements whose full tag exactly matches val.
[namespace-prefix()]        Keep elements with non-empty namespace prefixes.
[namespace-prefix()='val']  Keep elements whose namespace prefix matches val.
[namespace-uri()]           Keep elements with non-empty namespace URIs.
[namespace-uri()='val']     Keep elements whose namespace URI matches val.

Below are some examples of etree path strings.

Select the bookstore child element of the root element:

/bookstore

Beginning from the root element, select the title elements of all descendant book elements having a 'category' attribute of 'WEB':

//book[@category='WEB']/title

Beginning from the current element, select the first descendant book element with a title child element containing the text 'Great Expectations':

.//book[title='Great Expectations'][1]

Beginning from the current element, select all child elements of book elements with an attribute 'language' set to 'english':

./book/*[@language='english']

Beginning from the current element, select all child elements of book elements containing the text 'special':

./book/*[text()='special']

Beginning from the current element, select all descendant book elements whose title child element has a 'language' attribute of 'french':

.//book/title[@language='french']/..

Beginning from the current element, select all descendant book elements belonging to the http://www.w3.org/TR/html4/ namespace:

.//book[namespace-uri()='http://www.w3.org/TR/html4/']

Code:

xml := `
<bookstore>
	<book>
		<title>Great Expectations</title>
		<author>Charles Dickens</author>
	</book>
	<book>
		<title>Ulysses</title>
		<author>James Joyce</author>
	</book>
</bookstore>`

doc := NewDocument()
doc.ReadFromString(xml)
for _, e := range doc.FindElements(".//book[author='Charles Dickens']") {
    doc := NewDocumentWithRoot(e.Copy())
    doc.Indent(2)
    doc.WriteTo(os.Stdout)
}

Output:

<book>
  <title>Great Expectations</title>
  <author>Charles Dickens</author>
</book>

func CompilePath Uses

func CompilePath(path string) (Path, error)

CompilePath creates an optimized version of an XPath-like string that can be used to query elements in an element tree.

func MustCompilePath Uses

func MustCompilePath(path string) Path

MustCompilePath creates an optimized version of an XPath-like string that can be used to query elements in an element tree. Panics if an error occurs. Use this function to create Paths when you know the path is valid (i.e., if it's hard-coded).

type ProcInst Uses

type ProcInst struct {
    Target string // the processing instruction target
    Inst   string // the processing instruction value
    // contains filtered or unexported fields
}

A ProcInst represents an XML processing instruction.

func NewProcInst Uses

func NewProcInst(target, inst string) *ProcInst

NewProcInst creates an unparented XML processing instruction.

func (*ProcInst) Index Uses

func (p *ProcInst) Index() int

Index returns the index of this ProcInst token within its parent element's list of child tokens. If this ProcInst token has no parent, then the function returns -1.

func (*ProcInst) Parent Uses

func (p *ProcInst) Parent() *Element

Parent returns processing instruction token's parent element, or nil if it has no parent.

type ReadSettings Uses

type ReadSettings struct {
    // CharsetReader to be passed to standard xml.Decoder. Default: nil.
    CharsetReader func(charset string, input io.Reader) (io.Reader, error)

    // Permissive allows input containing common mistakes such as missing tags
    // or attribute values. Default: false.
    Permissive bool

    // Entity to be passed to standard xml.Decoder. Default: nil.
    Entity map[string]string
}

ReadSettings determine the default behavior of the Document's ReadFrom* methods.

type Token Uses

type Token interface {
    Parent() *Element
    Index() int
    // contains filtered or unexported methods
}

A Token is an interface type used to represent XML elements, character data, CDATA sections, XML comments, XML directives, and XML processing instructions.

type WriteSettings Uses

type WriteSettings struct {
    // CanonicalEndTags forces the production of XML end tags, even for
    // elements that have no child elements. Default: false.
    CanonicalEndTags bool

    // CanonicalText forces the production of XML character references for
    // text data characters &, <, and >. If false, XML character references
    // are also produced for " and '. Default: false.
    CanonicalText bool

    // CanonicalAttrVal forces the production of XML character references for
    // attribute value characters &, < and ". If false, XML character
    // references are also produced for > and '. Default: false.
    CanonicalAttrVal bool

    // UseCRLF causes the document's indentation methods to use a carriage
    // return followed by a linefeed ("\r\n") when outputting a newline. If
    // false, only a linefeed is used ("\n"). Default: false.
    UseCRLF bool
}

WriteSettings determine the behavior of the Document's WriteTo* and Indent* methods.

Package etree imports 10 packages (graph) and is imported by 238 packages. Updated 2020-08-03. Refresh now. Tools for package owners.