xpath

README

XPath

XPath is Go package provides selecting nodes from XML, HTML or other documents using XPath expression.

Implementation

• htmlquery - an XPath query package for HTML document

• xmlquery - an XPath query package for XML document.

• jsonquery - an XPath query package for JSON document

Supported Features

The basic XPath patterns.

The basic XPath patterns cover 90% of the cases that most stylesheets will need.

• node : Selects all child elements with nodeName of node.

• * : Selects all child elements.

• @attr : Selects the attribute attr.

• @* : Selects all attributes.

• node() : Matches an org.w3c.dom.Node.

• text() : Matches a org.w3c.dom.Text node.

• comment() : Matches a comment.

• . : Selects the current node.

• .. : Selects the parent of current node.

• / : Selects the document node.

• a[expr] : Select only those nodes matching a which also satisfy the expression expr.

• a[n] : Selects the nth matching node matching a When a filter's expression is a number, XPath selects based on position.

• a/b : For each node matching a, add the nodes matching b to the result.

• a//b : For each node matching a, add the descendant nodes matching b to the result.

• //b : Returns elements in the entire document matching b.

• a|b : All nodes matching a or b, union operation(not boolean or).

• (a, b, c) : Evaluates each of its operands and concatenates the resulting sequences, in order, into a single result sequence

Node Axes

• child::* : The child axis selects children of the current node.

• descendant::* : The descendant axis selects descendants of the current node. It is equivalent to '//'.

• descendant-or-self::* : Selects descendants including the current node.

• attribute::* : Selects attributes of the current element. It is equivalent to @*

• following-sibling::* : Selects nodes after the current node.

• preceding-sibling::* : Selects nodes before the current node.

• following::* : Selects the first matching node following in document order, excluding descendants.

• preceding::* : Selects the first matching node preceding in document order, excluding ancestors.

• parent::* : Selects the parent if it matches. The '..' pattern from the core is equivalent to 'parent::node()'.

• ancestor::* : Selects matching ancestors.

• ancestor-or-self::* : Selects ancestors including the current node.

• self::* : Selects the current node. '.' is equivalent to 'self::node()'.

Expressions

The gxpath supported three types: number, boolean, string.

• path : Selects nodes based on the path.

• a = b : Standard comparisons.

  • a = b True if a equals b.
  • a != b True if a is not equal to b.
  • a < b True if a is less than b.
  • a <= b True if a is less than or equal to b.
  • a > b True if a is greater than b.
  • a >= b True if a is greater than or equal to b.

• a + b : Arithmetic expressions.

  • - a Unary minus
  • a + b Add
  • a - b Substract
  • a * b Multiply
  • a div b Divide
  • a mod b Floating point mod, like Java.

• a or b : Boolean or operation.

• a and b : Boolean and operation.

• (expr) : Parenthesized expressions.

• fun(arg1, ..., argn) : Function calls:

Function	Supported
boolean()	✓
ceiling()	✓
choose()	✗
concat()	✓
contains()	✓
count()	✓
current()	✗
document()	✗
element-available()	✗
ends-with()	✓
false()	✓
floor()	✓
format-number()	✗
function-available()	✗
generate-id()	✗
id()	✗
key()	✗
lang()	✗
last()	✓
local-name()	✓
name()	✓
namespace-uri()	✓
normalize-space()	✓
not()	✓
number()	✓
position()	✓
replace()	✓
reverse()	✓
round()	✓
starts-with()	✓
string()	✓
string-length()	✓
substring()	✓
substring-after()	✓
substring-before()	✓
sum()	✓
system-property()	✗
translate()	✓
true()	✓
unparsed-entity-url()	✗

Changelogs

2019-03-19

• optimize XPath | operation performance. #33. Tips: suggest split into multiple subquery if you have a lot of | operations.

2019-01-29

• improvement normalize-space function. #32

2018-12-07

• supports XPath 2.0 Sequence expressions. #30 by @minherz.

Documentation

Overview

Example

XPath package example.

package main

import (
	"fmt"

	"github.com/antchfx/xpath"
)

func main() {
	expr, err := xpath.Compile("count(//book)")
	if err != nil {
		panic(err)
	}
	var root xpath.NodeNavigator
	// using Evaluate() method
	val := expr.Evaluate(root) // it returns float64 type
	fmt.Println(val.(float64))

	// using Evaluate() method
	expr = xpath.MustCompile("//book")
	val = expr.Evaluate(root) // it returns NodeIterator type.
	iter := val.(*xpath.NodeIterator)
	for iter.MoveNext() {
		fmt.Println(iter.Current().Value())
	}

	// using Select() method
	iter = expr.Select(root) // it always returns NodeIterator object.
	for iter.MoveNext() {
		fmt.Println(iter.Current().Value())
	}
}

Index

• type Expr
  • func Compile(expr string) (*Expr, error)
  • func MustCompile(expr string) *Expr
  • func (expr *Expr) Evaluate(root NodeNavigator) interface{}
  • func (expr *Expr) Select(root NodeNavigator) *NodeIterator
  • func (expr *Expr) String() string
• type NodeIterator
  • func Select(root NodeNavigator, expr string) *NodeIterator
  • func (t *NodeIterator) Current() NodeNavigator
  • func (t *NodeIterator) MoveNext() bool
• type NodeNavigator
• type NodeType

Examples

• Package

Types

type Expr

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

Expr is an XPath expression for query.

func Compile

func Compile(expr string) (*Expr, error)

Compile compiles an XPath expression string.

func MustCompile

func MustCompile(expr string) *Expr

MustCompile compiles an XPath expression string and ignored error.

func (*Expr) Evaluate

func (expr *Expr) Evaluate(root NodeNavigator) interface{}

Evaluate returns the result of the expression. The result type of the expression is one of the follow: bool,float64,string,NodeIterator).

func (*Expr) Select

func (expr *Expr) Select(root NodeNavigator) *NodeIterator

Select selects a node set using the specified XPath expression.

func (*Expr) String

func (expr *Expr) String() string

String returns XPath expression string.

type NodeIterator

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

NodeIterator holds all matched Node object.

func Select

func Select(root NodeNavigator, expr string) *NodeIterator

Select selects a node set using the specified XPath expression. This method is deprecated, recommend using Expr.Select() method instead.

func (*NodeIterator) Current

func (t *NodeIterator) Current() NodeNavigator

Current returns current node which matched.

func (*NodeIterator) MoveNext

func (t *NodeIterator) MoveNext() bool

MoveNext moves Navigator to the next match node.

type NodeNavigator

type NodeNavigator interface {
	// NodeType returns the XPathNodeType of the current node.
	NodeType() NodeType

	// LocalName gets the Name of the current node.
	LocalName() string

	// Prefix returns namespace prefix associated with the current node.
	Prefix() string

	// Value gets the value of current node.
	Value() string

	// Copy does a deep copy of the NodeNavigator and all its components.
	Copy() NodeNavigator

	// MoveToRoot moves the NodeNavigator to the root node of the current node.
	MoveToRoot()

	// MoveToParent moves the NodeNavigator to the parent node of the current node.
	MoveToParent() bool

	// MoveToNextAttribute moves the NodeNavigator to the next attribute on current node.
	MoveToNextAttribute() bool

	// MoveToChild moves the NodeNavigator to the first child node of the current node.
	MoveToChild() bool

	// MoveToFirst moves the NodeNavigator to the first sibling node of the current node.
	MoveToFirst() bool

	// MoveToNext moves the NodeNavigator to the next sibling node of the current node.
	MoveToNext() bool

	// MoveToPrevious moves the NodeNavigator to the previous sibling node of the current node.
	MoveToPrevious() bool

	// MoveTo moves the NodeNavigator to the same position as the specified NodeNavigator.
	MoveTo(NodeNavigator) bool
}

NodeNavigator provides cursor model for navigating XML data.

type NodeType

type NodeType int

NodeType represents a type of XPath node.

const (
	// RootNode is a root node of the XML document or node tree.
	RootNode NodeType = iota

	// ElementNode is an element, such as <element>.
	ElementNode

	// AttributeNode is an attribute, such as id='123'.
	AttributeNode

	// TextNode is the text content of a node.
	TextNode

	// CommentNode is a comment node, such as <!-- my comment -->
	CommentNode
)