goxpath

package module
v1.0.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2026 License: BSD-3-Clause Imports: 16 Imported by: 3

README

Go reference documentation

XPath 2.0+ package for Go, with XPath 3.1 maps and arrays.

License: BSD-3-Clause License

Usage

myfile.xml:

<data>
    <p>hello world!</p>
    <p>hello XML!</p>
</data>

main.go:

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/speedata/goxpath"
)

func dothings() error {
	r, err := os.Open("myfile.xml")
	if err != nil {
		return err
	}
	xp, err := goxpath.NewParser(r)
	if err != nil {
		return err
	}
	seq, err := xp.Evaluate("for $i in /data/p return string($i)")
	if err != nil {
		return err
	}
	for _, itm := range seq {
		fmt.Println(itm)
	}
	return nil
}

func main() {
	if err := dothings(); err != nil {
		log.Fatal(err)
	}
}

When working with namespaces, you need to have them predefined in your query:

myfile.xml:

<a:root xmlns:a="anamespace">
  <a:sub>text</a:sub>
</a:root>

package main

import (
	"fmt"
	"log"
	"os"

	"github.com/speedata/goxpath"
)

func dothings() error {
	r, err := os.Open("myfile.xml")
	if err != nil {
		return err
	}
	xp, err := goxpath.NewParser(r)
	if err != nil {
		return err
	}
	xp.Ctx.Namespaces["a"] = "anamespace"
	seq, err := xp.Evaluate("/a:root/a:sub/text()")
	if err != nil {
		return err
	}
	fmt.Println(seq.Stringvalue())
	return nil
}

func main() {
	if err := dothings(); err != nil {
		log.Fatal(err)
	}
}

Limitations

  • No schema types
  • No collations
  • Not all functions are implemented (see list below)

Implemented functions

This list is copied from XQuery 1.0 and XPath 2.0 Functions and Operators (Second Edition)

Accessors

Function Accessor Accepts Returns
string string-value an optional item or no argument xs:string
data typed-value zero or more items a sequence of atomic values

Functions on Numeric Values

Function Meaning
abs Returns the absolute value of the argument.
ceiling Returns the smallest number with no fractional part that is greater than or equal to the argument.
floor Returns the largest number with no fractional part that is less than or equal to the argument.
round Rounds to the nearest number with no fractional part.
round-half-to-even Takes a number and a precision and returns a number rounded to the given precision. If the fractional part is exactly half, the result is the number whose least significant digit is even.

Functions to Assemble and Disassemble Strings

Function Meaning
codepoints-to-string Creates an xs:string from a sequence of Unicode code points.
string-to-codepoints Returns the sequence of Unicode code points that constitute an xs:string.

Equality and Comparison of Strings

Function Meaning
compare Returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of the second argument, according to the rules of the collation that is used.
codepoint-equal Returns true if the two arguments are equal using the Unicode code point collation.

Functions on String Values

Function Meaning
concat Concatenates two or more xs:anyAtomicType arguments cast to xs:string.
string-join Returns the xs:string produced by concatenating a sequence of xs:strings using an optional separator.
substring Returns the xs:string located at a specified place within an argument xs:string.
string-length Returns the length of the argument.
normalize-space Returns the whitespace-normalized value of the argument.
upper-case Returns the upper-cased value of the argument.
lower-case Returns the lower-cased value of the argument.
translate Returns the first xs:string argument with occurrences of characters contained in the second argument replaced by the character at the corresponding position in the third argument.
normalize-unicode Returns the normalized value of the first argument in the normalization form specified by the second argument.
encode-for-uri Returns the xs:string argument with certain characters escaped to enable the resulting string to be used as a path segment in a URI.
iri-to-uri Returns the xs:string argument with certain characters escaped to enable the resulting string to be used as (part of) a URI.
escape-html-uri Returns the xs:string argument with certain characters escaped in the manner that html user agents handle attribute values that expect URIs.

Functions Based on Substring Matching

Function Meaning
contains Indicates whether one xs:string contains another xs:string. A collation may be specified.
starts-with Indicates whether the value of one xs:string begins with the collation units of another xs:string. A collation may be specified.
ends-with Indicates whether the value of one xs:string ends with the collation units of another xs:string. A collation may be specified.
substring-before Returns the collation units of one xs:string that precede in that xs:string the collation units of another xs:string. A collation may be specified.
substring-after Returns the collation units of xs:string that follow in that xs:string the collation units of another xs:string. A collation may be specified.

String Functions that Use Pattern Matching

Function Meaning
matches Returns an xs:boolean value that indicates whether the value of the first argument is matched by the regular expression that is the value of the second argument.
replace Returns the value of the first argument with every substring matched by the regular expression that is the value of the second argument replaced by the replacement string that is the value of the third argument.
tokenize Returns a sequence of one or more xs:strings whose values are substrings of the value of the first argument separated by substrings that match the regular expression that is the value of the second argument.

Additional Boolean Constructor Functions

Function Meaning
true Constructs the xs:boolean value 'true'.
false Constructs the xs:boolean value 'false'.

Functions on Boolean Values

Function Meaning
not Inverts the xs:boolean value of the argument.

Component Extraction Functions on Durations, Dates and Times

Function Meaning
years-from-duration Returns the year component of an xs:duration value.
months-from-duration Returns the months component of an xs:duration value.
days-from-duration Returns the days component of an xs:duration value.
hours-from-duration Returns the hours component of an xs:duration value.
minutes-from-duration Returns the minutes component of an xs:duration value.
seconds-from-duration Returns the seconds component of an xs:duration value.
year-from-dateTime Returns the year from an xs:dateTime value.
month-from-dateTime Returns the month from an xs:dateTime value.
day-from-dateTime Returns the day from an xs:dateTime value.
hours-from-dateTime Returns the hours from an xs:dateTime value.
minutes-from-dateTime Returns the minutes from an xs:dateTime value.
seconds-from-dateTime Returns the seconds from an xs:dateTime value.
timezone-from-dateTime Returns the timezone from an xs:dateTime value.
year-from-date Returns the year from an xs:date value.
month-from-date Returns the month from an xs:date value.
day-from-date Returns the day from an xs:date value.
timezone-from-date Returns the timezone from an xs:date value.
hours-from-time Returns the hours from an xs:time value.
minutes-from-time Returns the minutes from an xs:time value.
seconds-from-time Returns the seconds from an xs:time value.
timezone-from-time Returns the timezone from an xs:time value.

Functions on anyURI

Function Meaning
resolve-uri Returns an xs:anyURI representing an absolute xs:anyURI given a base URI and a relative URI.

Timezone Adjustment Functions on Dates and Time Values

Function Meaning
adjust-dateTime-to-timezone Adjusts an xs:dateTime value to a specific timezone, or to no timezone at all.
adjust-date-to-timezone Adjusts an xs:date value to a specific timezone, or to no timezone at all.
adjust-time-to-timezone Adjusts an xs:time value to a specific timezone, or to no timezone at all.

Functions on Nodes

Function Meaning
name Returns the name of the context node or the specified node as an xs:string.
namespace-uri Returns the namespace URI as an xs:anyURI for the xs:QName of the argument node or the context node if the argument is omitted. This may be the URI corresponding to the zero-length string if the xs:QName is in no namespace.
local-name Returns the local name of the context node or the specified node as an xs:NCName.
lang Returns true or false, depending on whether the language of the given node, as defined using the xml:lang attribute, is the same as, or a sublanguage of, the language specified by the argument.
number Returns the value of the context item after atomization or the specified argument converted to an xs:double.
root Returns the root of the tree to which the node argument belongs.
Function Meaning
boolean Computes the effective boolean value of the argument sequence.
empty Indicates whether or not the provided sequence is empty.
exists Indicates whether or not the provided sequence is not empty.
reverse Reverses the order of items in a sequence.

Aggregate Functions

Function Meaning
avg Returns the average of a sequence of values.
count Returns the number of items in a sequence.
max Returns the maximum value from a sequence of comparable values.
min Returns the minimum value from a sequence of comparable values.
sum Returns the sum of a sequence of values.
Function Meaning
position Returns the position of the context item within the sequence of items currently being processed.
last Returns the number of items in the sequence of items currently being processed.

Context Functions

Function Meaning
current-dateTime Returns the current xs:dateTime.
current-date Returns the current xs:date.
current-time Returns the current xs:time.

Functions on Sequences

Function Meaning
distinct-values Returns a sequence with duplicate values removed.
index-of Returns the positions of items in a sequence that match a given value.
insert-before Inserts an item or sequence of items at a specified position in a sequence.
remove Removes an item from a specified position in a sequence.
unordered Returns the items in the given sequence in a non-deterministic order.
subsequence Returns the subsequence of a given sequence, identified by location.

Functions That Test the Cardinality of Sequences

Function Meaning
zero-or-one Returns the input sequence if it contains zero or one items. Raises an error otherwise.
one-or-more Returns the input sequence if it contains one or more items. Raises an error otherwise.
exactly-one Returns the input sequence if it contains exactly one item. Raises an error otherwise.

Equals, Union, Intersection and Except

Function Meaning
deep-equal Returns true if the two arguments have items that compare equal in corresponding positions.

Functions and Operators that Generate Sequences

Function Meaning
doc Returns a document node retrieved using the specified URI.
doc-available Returns true if a document node can be retrieved using the specified URI.

Formatting Functions (XPath 3.0)

Function Meaning
format-date Formats an xs:date value using a picture string.
format-number Formats a number as a string using a picture string.

Sorting (XPath 3.1)

Function Meaning
sort Returns a sorted copy of a sequence.

XPath 3.1 Map Functions

Namespace: http://www.w3.org/2005/xpath-functions/map

Function Meaning
map:get Returns the value associated with a key in a map.
map:size Returns the number of entries in a map.
map:keys Returns the keys of a map as a sequence.
map:contains Returns true if the map contains an entry with the given key.
map:put Returns a map with an added or replaced entry.
map:merge Returns a map that combines the entries from multiple maps.

XPath 3.1 Array Functions

Namespace: http://www.w3.org/2005/xpath-functions/array

Function Meaning
array:get Returns the member at a given position in an array.
array:size Returns the number of members in an array.

Constructor Functions for QNames

Function Meaning
resolve-QName Returns an xs:QName with the lexical form given in the first argument. The prefix is resolved using the in-scope namespaces for a given element.
QName Returns an xs:QName with the namespace URI given in the first argument and the local name and prefix in the second argument.
Function Meaning
prefix-from-QName Returns an xs:NCName representing the prefix of the xs:QName argument.
local-name-from-QName Returns an xs:NCName representing the local name of the xs:QName argument.
namespace-uri-from-QName Returns the namespace URI for the xs:QName argument. If the xs:QName is in no namespace, the zero-length string is returned.
namespace-uri-for-prefix Returns the namespace URI of one of the in-scope namespaces for the given element, identified by its namespace prefix.
in-scope-prefixes Returns the prefixes of the in-scope namespaces for the given element.

XML Schema Type Constructors

Function Meaning
xs:integer Cast to xs:integer.
xs:double Cast to xs:double.
xs:string Cast to xs:string.
xs:date Cast to xs:date.
xs:dateTime Cast to xs:dateTime.
xs:duration Cast to xs:duration.
xs:time Cast to xs:time.

Not yet implemented functions

Accessors

Function Accessor Accepts Returns
node-name node-name an optional node zero or one xs:QName
nilled nilled a node an optional xs:boolean
base-uri base-uri an optional node or no argument zero or one xs:anyURI
document-uri document-uri an optional node zero or one xs:anyURI

Functions and Operators that Generate Sequences

Function Meaning
id Returns the sequence of element nodes having an ID value matching the one or more of the supplied IDREF values.
idref Returns the sequence of element or attribute nodes with an IDREF value matching one or more of the supplied ID values.
collection Returns a sequence of nodes retrieved using the specified URI or the nodes in the default collection.

Context Functions

Function Meaning
implicit-timezone Returns the value of the implicit timezone property from the dynamic context.
default-collation Returns the value of the default collation property from the static context.
static-base-uri Returns the value of the Base URI property from the static context.

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrConversion is returned in case of an unsuccessful cast.
	ErrConversion = fmt.Errorf("conversion failed")
)
View Source 
var ErrSequence = fmt.Errorf("a sequence with more than one item is not allowed here")

ErrSequence is raised when a sequence of items is not allowed as an argument.

Functions

func BooleanValue 

func BooleanValue(s Sequence) (bool, error)

BooleanValue returns the effective boolean value of the sequence. XPath 2.0 §2.4.3: if the first item is a node, returns true; a single atomic value is converted to boolean; otherwise FORG0006.

func ItemStringvalue added in v1.0.6 

func ItemStringvalue(itm Item) string

ItemStringvalue returns the string value of an individual item.

func NumberValue 

func NumberValue(s Sequence) (float64, error)

NumberValue returns the sequence converted to a float.

func RegisterFunction 

func RegisterFunction(f *Function)

RegisterFunction registers an XPath function

func StringValue 

func StringValue(s Sequence) (string, error)

StringValue returns the string value of the sequence by concatenating the string values of each item.

func ToXSInteger 

func ToXSInteger(itm Item) (int, error)

ToXSInteger converts the item to an xs:integer.

Types

type Context 

type Context struct {
	Namespaces map[string]string           // Storage for (private) name spaces
	Store      map[interface{}]interface{} // Store can be used for private variables accessible in functions
	Pos        int                         // Used to determine the position() in the sequence
	// contains filtered or unexported fields
}

Context is needed for variables, namespaces and XML navigation.

func CopyContext 

func CopyContext(cur *Context) *Context

CopyContext creates a new context with the underlying xml document but can be changed without changing the original context.

func NewContext 

func NewContext(doc *goxml.XMLDocument) *Context

NewContext returns a context from the xml document

func (*Context) Attributes 

func (ctx *Context) Attributes(tf testfuncAttributes) (Sequence, error)

Attributes returns all attributes of the current node that satisfy the testfunc

func (*Context) Current 

func (ctx *Context) Current(tf testfuncChildren) (Sequence, error)

Current returns all elements in the context that satisfy the testfunc.

func (*Context) CurrentItem added in v1.0.6 

func (ctx *Context) CurrentItem() Item

CurrentItem returns the XSLT current() item.

func (*Context) Document 

func (ctx *Context) Document() goxml.XMLNode

Document moves the node navigator to the document and retuns it

func (*Context) Filter 

func (ctx *Context) Filter(filter EvalFunc) (Sequence, error)

Filter applies predicates to the context

func (*Context) GetContextSequence 

func (ctx *Context) GetContextSequence() Sequence

GetContextSequence returns the current context.

func (*Context) Root 

func (ctx *Context) Root() (Sequence, error)

Root moves the node navigator to the root node of the document.

func (*Context) SetContextSequence 

func (ctx *Context) SetContextSequence(seq Sequence) Sequence

SetContextSequence sets the context sequence and returns the previous one.

func (*Context) SetCurrentItem added in v1.0.6 

func (ctx *Context) SetCurrentItem(item Item)

SetCurrentItem sets the XSLT current() item.

func (*Context) SetSize added in v1.0.6 

func (ctx *Context) SetSize(n int)

SetSize sets the context size used by last().

func (*Context) Size added in v1.0.6 

func (ctx *Context) Size() int

Size returns the context size used by last().

type EvalFunc 

type EvalFunc func(*Context) (Sequence, error)

EvalFunc returns a sequence evaluating the XPath expression in the given context.

func ParseXPath 

func ParseXPath(tl *Tokenlist) (EvalFunc, error)

ParseXPath takes a previously created token list and returns a function that can be used to evaluate the XPath expression in different contexts.

type Function 

type Function struct {
	Name      string
	Namespace string
	F         func(*Context, []Sequence) (Sequence, error)
	MinArg    int
	MaxArg    int
}

Function represents an XPath function

type Item 

type Item interface{}

An Item can hold anything such as a number, a string or a node.

type MapEntry added in v1.0.5 

type MapEntry struct {
	Key   Item
	Value Sequence
}

MapEntry represents a key-value pair in an XPath map.

type Parser 

type Parser struct {
	Ctx *Context
}

Parser contains all necessary references to the parser

func NewParser 

func NewParser(r io.Reader) (*Parser, error)

NewParser returns a context to be filled

func (*Parser) Evaluate 

func (xp *Parser) Evaluate(xpath string) (Sequence, error)

Evaluate reads an XPath expression and evaluates it in the given context.

func (*Parser) SetVariable 

func (xp *Parser) SetVariable(name string, value Sequence)

SetVariable is used to set a variable name.

func (*Parser) XMLDocument 

func (xp *Parser) XMLDocument() *goxml.XMLDocument

XMLDocument returns the underlying XML document

type Sequence 

type Sequence []Item

A Sequence is a list of Items

func (Sequence) IntValue 

func (s Sequence) IntValue() (int, error)

IntValue returns the sequence value as an integer.

func (Sequence) String 

func (s Sequence) String() string

func (Sequence) Stringvalue 

func (s Sequence) Stringvalue() string

Stringvalue returns the concatenation of the string value of each item.

func (Sequence) StringvalueJoin added in v1.0.5 

func (s Sequence) StringvalueJoin(sep string) string

StringvalueJoin returns the string values of all items joined by sep.

type Tokenlist 

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

Tokenlist represents units of XPath language elements.

type XPathArray added in v1.0.5 

type XPathArray struct {
	Members []Sequence
}

XPathArray represents an XPath 3.1 array.

func (*XPathArray) Get added in v1.0.5 

func (a *XPathArray) Get(pos int) (Sequence, error)

Get returns the member at the given 1-based index.

func (*XPathArray) Size added in v1.0.5 

func (a *XPathArray) Size() int

Size returns the number of members in the array.

type XPathMap added in v1.0.5 

type XPathMap struct {
	Entries []MapEntry
}

XPathMap represents an XPath 3.1 map.

func (*XPathMap) Contains added in v1.0.5 

func (m *XPathMap) Contains(key Item) bool

Contains checks if a key exists in the map.

func (*XPathMap) Get added in v1.0.5 

func (m *XPathMap) Get(key Item) (Sequence, bool)

Get looks up a key in the map by comparing string values.

func (*XPathMap) Keys added in v1.0.5 

func (m *XPathMap) Keys() Sequence

Keys returns all keys in the map as a Sequence.

func (*XPathMap) Size added in v1.0.5 

func (m *XPathMap) Size() int

Size returns the number of entries in the map.

type XSDate 

type XSDate time.Time

XSDate is a date instance

func (XSDate) String 

func (d XSDate) String() string

type XSDateTime 

type XSDateTime time.Time

XSDateTime is a date time instance

func (XSDateTime) String 

func (d XSDateTime) String() string

type XSDuration added in v1.0.5 

type XSDuration struct {
	Negative bool
	Years    int
	Months   int
	Days     int
	Hours    int
	Minutes  int
	Seconds  float64
}

XSDuration represents an xs:duration value with separate date and time components.

func ParseXSDuration added in v1.0.5 

func ParseXSDuration(s string) (XSDuration, error)

ParseXSDuration parses an ISO 8601 duration string (e.g. "P1Y2M3DT4H5M6.5S", "-P1Y").

func (XSDuration) String added in v1.0.5 

func (d XSDuration) String() string

type XSQName added in v1.0.5 

type XSQName struct {
	Namespace string
	Prefix    string
	Localname string
}

XSQName represents an xs:QName value with namespace URI, prefix, and local name.

func (XSQName) String added in v1.0.5 

func (q XSQName) String() string

type XSTime 

type XSTime time.Time

XSTime is a time instance

func (XSTime) String 

func (d XSTime) String() string

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.