xquery

type BoundarySpace ¶

type BoundarySpace int

BoundarySpace is the boundary-space policy of §4.3: whether whitespace that only separates markup survives into the constructed element.

const (
	// StripSpace discards boundary whitespace. It is the default, and the
	// value a query gets when it says nothing.
	StripSpace BoundarySpace = iota
	// PreserveSpace keeps it, as "declare boundary-space preserve" asks.
	PreserveSpace
)

type Construction ¶

type Construction int

Construction is the construction mode of §4.10: whether a copied node keeps the type annotation it was validated with.

const (
	// PreserveTypes keeps annotations. It is the default.
	PreserveTypes Construction = iota
	// StripTypes replaces them with xs:untyped and xs:untypedAtomic.
	StripTypes
)

type EmptyOrder ¶

type EmptyOrder int

EmptyOrder decides where the empty sequence sorts in an "order by" that does not say (§4.7).

const (
	// EmptyGreatest sorts the empty sequence last ascending. It is this
	// implementation's default, which the specification leaves open.
	EmptyGreatest EmptyOrder = iota
	// EmptyLeast sorts it first.
	EmptyLeast
)

type Options ¶

type Options struct {
	// BaseURI is the static base URI. It is stamped on constructed elements
	// and is what a relative reference resolves against.
	BaseURI string

	// DeclarationBaseURI is the URI of the resource the query text was read
	// from. It is used for one thing only: resolving a relative
	// "declare base-uri" against it, as §4.5 requires.
	//
	// It is deliberately separate from BaseURI. The two answer different
	// questions -- "what does a prolog declaration resolve against" and "what
	// does the query run under" -- and conflating them is what made every
	// earlier attempt at K2-BaseURIProlog-4 a net loss: one value for both
	// also stamped that value on constructed elements and on
	// fn:static-base-uri when the query declared nothing, which the suite's
	// base-URI-12/14/23/24 and K2-BaseURIFunc-30 all detect. Kept apart,
	// setting this one changes nothing except the resolution a declaration
	// asks for: a query with no "declare base-uri" is unaffected by it.
	DeclarationBaseURI string

	// BoundarySpace decides whether whitespace that only separates markup
	// survives into a constructed element. The zero value strips it, which is
	// what a query with no "declare boundary-space" gets.
	BoundarySpace BoundarySpace

	// Construction decides whether a copied node keeps its type annotation.
	// The zero value preserves it.
	Construction Construction

	// DefaultElementNamespace is applied to an unprefixed element name. It is
	// never applied to an attribute name.
	DefaultElementNamespace string

	// Namespaces are prefix bindings available to the query, as though its
	// prolog had declared them. The eight predeclared prefixes of §4.1 —
	// xml, xs, xsi, fn, local, math, map and array — are bound already, as is
	// err, which §3.16 binds so that "catch err:FODC0002" works with no
	// declaration. None of them need to appear here.
	Namespaces map[string]string
}

Options configure how a query is compiled.

The zero value is the specification's defaults: boundary whitespace is stripped, construction preserves types, an unprefixed element name is in no namespace, and an unprefixed function name is in the fn: namespace.

type Ordering ¶

type Ordering int

Ordering is the ordering mode of §4.6.

const (
	// Ordered requires the document order a path expression would give. It
	// is the default.
	Ordered Ordering = iota
	// Unordered permits any order.
	Unordered
)

type Query ¶

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

A Query is a compiled query, safe for concurrent use.

Compiling separates what can be decided from the text — namespaces, the shape of every constructor, and every expression in it — from what depends on the input. Nothing about a Query changes when it runs, so one may be evaluated from several goroutines at once.

func Compile(src string, opts Options) (*Query, error)

package main

import (
	"os"

	"github.com/knroy/go-xml/xpath"
	"github.com/knroy/go-xml/xquery"
	"github.com/knroy/go-xml/xslt"
)

func main() {
	q, err := xquery.Compile(`<sum>{ 1 + 2 }</sum>`, xquery.Options{})
	if err != nil {
		panic(err)
	}
	seq, err := q.Eval(xpath.NewContext(nil, xpath.Builtins()))
	if err != nil {
		panic(err)
	}
	// A query returns a sequence; serialising it is a separate step.
	if err := xslt.Serialize(os.Stdout, seq,
		xslt.OutputSettings{OmitXMLDecl: true}, nil); err != nil {
		panic(err)
	}
}

Output:
<sum>3</sum>

func (q *Query) Eval(ctx *xpath.Context) (xdm.Sequence, error)

package main

import (
	"fmt"

	"github.com/knroy/go-xml/xdm"
	"github.com/knroy/go-xml/xpath"
	"github.com/knroy/go-xml/xquery"
)

func main() {
	q, err := xquery.Compile(
		`declare variable $who external; concat("hello ", $who)`,
		xquery.Options{})
	if err != nil {
		panic(err)
	}
	ctx := xpath.NewContext(nil, xpath.Builtins())
	ctx.Vars = map[string]xdm.Sequence{"who": {xdm.NewString("world")}}

	seq, err := q.Eval(ctx)
	if err != nil {
		panic(err)
	}
	fmt.Println(seq)
}

Output:
[hello world]

func (q *Query) SerializationOptions() map[string]string

package main

import (
	"fmt"

	"github.com/knroy/go-xml/xquery"
)

func main() {
	// "output" is not a predeclared prefix, so it must be bound first.
	q, err := xquery.Compile(`
		declare namespace output =
			"http://www.w3.org/2010/xslt-xquery-serialization";
		declare option output:method "json";
		1`, xquery.Options{})
	if err != nil {
		panic(err)
	}
	fmt.Println(q.SerializationOptions()["method"])
}

Output:
json

func (q *Query) String() string

type XQVersion ¶ added in v1.2.1

type XQVersion int

XQVersion is the version of the XQuery language a module is written in, as named by its version declaration (§4.1 VersionDecl).

This is not the same thing as xpath.Version, and the two cannot be collapsed into one. xpath.Version selects a version of the *expression* language, and XQuery's expression language is XPath's: XQuery 1.0's is XPath 2.0's, 3.0's is XPath 3.0's, 3.1's is XPath 3.1's. But XQuery has rules of its own that XPath has no counterpart for -- the prolog, the module system, node construction -- and those changed on XQuery's own schedule. An unprefixed "declare option" name is the clearest case: it is XPST0081 in XQuery 1.0 and legal from 3.0, and XPath has no option declaration at all, so no value of xpath.Version can carry that distinction. Keeping the two types separate is what lets a decision point say which language's rule it is applying.

The constants are in version order, so that "later than" is a comparison and the predicates below are the only place that knows which comparison. The zero value is therefore XQuery10 and is never what a module gets: newStaticContext sets the default explicitly, because the default is a policy decision about undeclared modules and not an accident of ordering.

const (
	// XQuery10 is XQuery 1.0, the 2007 Recommendation.
	XQuery10 XQVersion = iota
	// XQuery30 is XQuery 3.0, the 2014 Recommendation. It admits everything
	// in 1.0, and changes the answer to a handful of questions 1.0 had
	// already answered -- see the callers of atLeast30.
	XQuery30
	// XQuery31 is XQuery 3.1, the 2017 Recommendation. It is what this engine
	// implements, and what a module with no version declaration is compiled
	// as: §4.1 leaves the version of such a module implementation-defined.
	XQuery31
)

func (v XQVersion) String() string