xpath

type ArgumentPlaceholder struct{}

type ArrayConstructor struct {
	Members []Expr
	// Curly marks the "array { ... }" spelling.
	Curly bool
}

type Axis int

type BinaryOp struct {
	Op          string
	Left, Right Expr
	// ResolveQName binds a prefix in the static context of this operator, for
	// the one conversion that needs it. A general comparison casts an
	// untypedAtomic operand to the *other* operand's type, and when that type
	// is xs:QName the lexical form carries a prefix whose namespace lives in
	// the static context -- which the runtime Context deliberately does not
	// carry, since namespaces are a static property. Capturing the resolver
	// on the node is what makes the binding available where the cast happens.
	// Nil for every operator other than a comparison, and for a comparison
	// parsed without a namespace resolver.
	ResolveQName func(prefix string) (string, bool)
}

type Binding struct {
	Var xdm.QName
	Seq Expr
}

type CastExpr struct {
	Operand  Expr
	Type     SequenceType
	Castable bool // true for "castable as", which yields a boolean
}

type Collation interface {
	Compare(a, b string) int
	Contains(s, sub string) bool
	StartsWith(s, prefix string) bool
	EndsWith(s, suffix string) bool
	IndexOf(s, sub string) int
}

type CollectionResolver interface {
	// ResolveCollection returns the documents in uri, resolved against base.
	//
	// The result is a sequence rather than a []*xdm.Tree because a collection
	// is permitted to contain items that are not document nodes.
	ResolveCollection(uri, base string) (xdm.Sequence, error)
}

type CompileOptions struct {
	// Namespaces resolves the prefixes in src. Nil admits none, which is
	// what passing a nil NamespaceResolver does.
	Namespaces NamespaceResolver

	// Version is the language version. The zero value is XPath20.
	Version Version

	// RefFloor raises the version at which a named function reference is
	// admitted, for a host whose own version outruns the expression's. Zero
	// means Version; see refversion.go.
	RefFloor Version

	// XQuery parses src by the rule an expression embedded in an XQuery
	// module follows; see ParseXQuery for the one difference.
	XQuery bool

	// Context bounds the compile. Nil means no deadline.
	//
	// Cancellation is observed before parsing, between parsing and
	// optimisation, and periodically inside the optimiser -- so a deadline
	// is honoured at a granularity rather than instantly, and an expression
	// compiling in microseconds (the ordinary case: the median is ~3µs)
	// never observes it at all.
	//
	// Parsing has no cancellation of its own and is roughly two thirds of
	// the cost on a large expression, so a deadline set to expire mid-compile
	// is observed when parsing finishes rather than during it. MaxBytes is
	// the bound that covers parsing.
	Context context.Context

	// MaxBytes bounds len(src). Zero means unbounded. It is checked before
	// parsing, so an over-large expression costs the comparison and nothing
	// else.
	//
	// This is the deterministic half of the protection Context gives: it
	// refuses the same input every time, where a deadline depends on how
	// loaded the machine is. A host compiling expressions taken from
	// document data -- xsl:evaluate does exactly that, at transform time --
	// should set it.
	MaxBytes int
}

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

type Context struct {
	// Item is the context item. It is nil where there is no context item,
	// which is an error to reference rather than an empty sequence.
	Item xdm.Item
	// Position is the context position, 1-based. Zero means "no focus".
	Position int
	// Size is the context size.
	Size int

	// Vars holds in-scope variable bindings, keyed by expanded name.
	// Lookups walk to Parent, so a nested scope does not copy the map.
	Vars   map[string]xdm.Sequence
	Parent *Context

	// Funcs resolves function calls. Supplied by the caller so that XSLT can
	// add xsl:function declarations and extension functions without this
	// package knowing about them.
	Funcs FunctionLibrary

	// Version is the language version the expression was compiled under.
	//
	// It reaches the function library because a few functions differ between
	// versions in ways the parser cannot settle: fn:matches and its siblings
	// accept the "q" flag and the 3.0 regular expression constructs only
	// under 3.0, and must raise the same errors as any other processor when
	// asked to be 2.0. The zero value is XPath20, so a Context built by an
	// existing caller behaves exactly as it did before.
	Version Version

	// RegexVersion raises the version of the *regular expression* dialect
	// above Version, without admitting any other 3.0 construct.
	//
	// The two are separable because the regex language is not part of the
	// XPath grammar: a pattern is a string, read by fn:matches and its
	// siblings at the point of call rather than by the parser. So a host may
	// legitimately want a 2.0 expression to accept a 3.0 pattern, which is
	// exactly what XSLT needs -- the XSLT suite runs version="2.0"
	// stylesheets under a 3.0 processor and expects "(?:...)" to compile,
	// because the dialect follows the processor while the syntax follows the
	// module.
	//
	// The zero value adds nothing: the effective dialect is the larger of
	// this and Version, so an existing caller is unaffected.
	RegexVersion Version

	// LibraryVersion raises the version of the *function library* above
	// Version, without admitting any new syntax.
	//
	// Which functions exist is a property of the processor rather than of the
	// module, in the same way the regular-expression dialect is: calling a
	// function is ordinary syntax at every version, and only the name has to
	// resolve. The XSLT suite requires the separation — accessor-050 and
	// fifteen others are version="2.0" stylesheets scoped XSLT30+ that call
	// fn:path, and a 3.0 processor must find it for them.
	//
	// Raising Version instead would also hand those modules inline functions
	// and map constructors, which the XSLT 2.0 grammar must refuse.
	//
	// The zero value adds nothing: the effective floor is the larger of this
	// and Version, so an existing caller is unaffected.
	LibraryVersion Version

	// StaticBaseURI is the base URI of the expression itself — the stylesheet
	// or query it was written in — which is what fn:static-base-uri returns
	// and what fn:resolve-uri resolves against by default.
	//
	// It is distinct from a *node's* base URI, which comes from the document
	// the node was parsed from. Returning the context node's was the nearest
	// thing available before this existed, and it is a different value: a
	// stylesheet in one place can perfectly well be applied to a document
	// from another.
	StaticBaseURI string

	// QualifyVar lets the host language redirect a variable reference to a
	// different name; see VarQualifier. Nil for the flat scoping XPath's own
	// grammar implies.
	QualifyVar VarQualifier

	// MissingVar lets the host language say what an unresolved reference
	// means. Returning nil leaves the ordinary XPST0008. It exists because a
	// host may decline to bind a variable whose evaluation failed, and owe
	// the failure to whoever refers to it -- an XSLT 3.0 abstract variable
	// is the case.
	MissingVar func(ctx *Context, name xdm.QName) error

	// StaticHost is an opaque value the host language attached to the
	// expression being evaluated; see Compiled.WithStaticHost. This package
	// never interprets it, only carries it.
	StaticHost any

	// StaticNamespaces is the statically known namespaces of the expression,
	// carried from compile time so that a function can expand a prefix that
	// reaches it as a *string* rather than as syntax.
	//
	// Almost every prefix in an expression is resolved by the parser, which is
	// why NamespaceResolver is a compile-time interface. The exception is a
	// prefixed name that arrives as an argument value: F&O 9.8.4.3 says the
	// $calendar argument of the date formatting functions "must be a valid
	// EQName ... if it is a lexical QName then it is expanded into an expanded
	// QName using the statically known namespaces", and the functions' own
	// Properties section lists them as depending on "namespaces" for exactly
	// this reason. The argument need not be a literal, so the expansion cannot
	// be done at parse time; the resolver has to survive into evaluation.
	//
	// Nil means the caller compiled without one, and a prefixed calendar is
	// then unresolvable — which is the same answer an empty resolver gives.
	StaticNamespaces NamespaceResolver

	// ImplicitTimezone is the offset in minutes applied to date/time values
	// that carry no timezone. The spec requires the dynamic context to supply
	// one; defaulting to UTC keeps results reproducible across machines,
	// which matters more for a validator than matching local time.
	ImplicitTimezone int

	// Ctx carries cancellation. A stylesheet can loop for a long time on
	// pathological input, and the caller needs a way out that does not
	// involve killing the process.
	Ctx context.Context

	// Docs resolves fn:doc and fn:document URIs. Nil disables them, which is
	// the safe default: a stylesheet that can open arbitrary URIs is an SSRF
	// and file-disclosure vector.
	Docs DocumentResolver

	// Collections resolves fn:collection URIs. Nil disables it, for the same
	// reason nil disables Docs, and setting Docs does not set this: see
	// CollectionResolver.
	Collections CollectionResolver

	// Texts resolves fn:unparsed-text URIs. Nil disables it, and setting
	// Docs does not set this: reading a file as raw text is a wider grant
	// than reading it as a parsed document. See TextResolver.
	Texts TextResolver

	// Entities resolves the external entities and external DTD subset that a
	// document handed to fn:parse-xml declares. Nil refuses every one of
	// them, which is the safe default and the one nearly every caller wants:
	// parse-xml is handed a string that came from somewhere, and honouring
	// <!ENTITY e SYSTEM "..."> inside it is XXE by definition. Setting Docs
	// or Texts does not set this — those grant reads of URIs the expression
	// itself named, while this grants reads of URIs the *parsed data* names,
	// which is a different and wider trust decision.
	//
	// Confinement is entirely the resolver's; see xdm.EntityResolver.
	Entities xdm.EntityResolver

	// Environment answers fn:environment-variable and
	// fn:available-environment-variables. Nil withholds the process
	// environment from both, which is the default and the safe one: the
	// environment of a server process routinely holds credentials, and
	// nothing about evaluating an expression implies consent to read them.
	//
	// Setting Docs or Texts does not set this, and this does not set those:
	// those grant reads of a URI space the caller has confined, while this
	// grants reads of the process's own state, which no resolver root
	// bounds. Withholding costs no conformance — see EnvironmentResolver.
	Environment EnvironmentResolver

	// Validator validates a tree fn:json-to-xml has just built, when the
	// call asked for validate=true. Nil means the processor cannot do it,
	// which is FOJS0004 rather than a silent untyped result; see
	// TreeValidator.
	Validator TreeValidator

	// Compat is XPath 1.0 compatibility mode, which XSLT 3.8 puts in force for
	// expressions written on an element whose effective [xsl:]version is below
	// 2.0. Under it the coercion rules of XPath 2.0 appendix B.1 apply: a
	// multi-item argument to a parameter expecting a string, a number or a
	// node is truncated to its first item instead of raising XPTY0004,
	// arithmetic on a non-numeric operand yields NaN rather than a type error,
	// and a general comparison converts its operands the way XPath 1.0 did.
	//
	// It defaults to false and is set only by a Compiled that was given it, so
	// ordinary 2.0 evaluation never sees it.
	Compat bool

	// MapDuplicateCode overrides the error code raised when a map constructor
	// names the same key twice.
	//
	// The construct is one expression with two spellings of the same failure,
	// because the code is the host language's rather than XPath's. XQuery 3.1
	// section 3.11.1 calls it XQDY0137, which is the default and what the QT3
	// suite requires. XSLT 3.0 section 17.4 says of the very same MapExpr that
	// "if two or more entries have the same key then a dynamic error occurs
	// [see ERR XTDE3365]", so an XSLT host sets this to XTDE3365 -- matching
	// the code xsl:map already raises for a duplicate, which is the point: in
	// XSLT the two ways of writing a map agree on how they fail.
	//
	// The zero value keeps XQDY0137, so a host that does not set it behaves
	// exactly as it did.
	MapDuplicateCode string

	// Depth guards against unbounded recursion in user-defined functions and
	// named templates, which the spec does not bound.
	Depth int

	// MaxDepth is the bound Depth is checked against. Zero means the package
	// default, MaxDepth.
	//
	// It is settable because the default is a guard against untrusted input
	// rather than a limit the language imposes: a query that recurses five
	// thousand deep is perfectly legal, and fn-format-number's numberformat121
	// and 122 do exactly that on purpose. A caller evaluating an expression it
	// trusts can raise the bound; one evaluating an expression from outside
	// should leave it alone.
	MaxDepth int

	// Now is the value fn:current-dateTime and its siblings return.
	//
	// The spec requires these to be stable for the whole of one evaluation:
	// calling current-dateTime() twice must give the same answer, or a
	// stylesheet that stamps a document and then checks the stamp against
	// "now" can disagree with itself. Reading the clock here once, rather
	// than per call, is what guarantees that. A zero value means the caller
	// did not set one and the functions are unavailable.
	Now time.Time
	// HasNow distinguishes an unset clock from a legitimately zero time.
	HasNow bool
	// contains filtered or unexported fields
}

type ContextCollectionResolver interface {
	CollectionResolver
	ResolveCollectionIn(ctx *Context, uri, base string) (xdm.Sequence, error)
}

type ContextDocumentResolver interface {
	DocumentResolver
	// ResolveDocumentIn is ResolveDocument for a call made from ctx.
	ResolveDocumentIn(ctx *Context, uri, base string) (*xdm.Tree, error)
}

type ContextItem struct{}

type DecimalFormat struct {
	Name              xdm.QName
	DecimalSeparator  rune
	GroupingSeparator rune
	Percent           rune
	PerMille          rune
	ZeroDigit         rune
	Digit             rune
	PatternSeparator  rune
	MinusSign         rune
	Infinity          string
	NaN               string
	// ExponentSeparator is the character that introduces the exponent part of
	// a picture, which XPath 3.1 added along with scientific notation itself.
	// It is a declared symbol like every other one here because a locale that
	// writes 1,2346E4 needs to say so; the default "e" is what an undeclared
	// format uses.
	ExponentSeparator rune
}

type DocumentResolver interface {
	// ResolveDocument returns the tree for uri, resolved against base.
	ResolveDocument(uri, base string) (*xdm.Tree, error)
}

type DynamicCall struct {
	Target Expr
	Args   []Expr
}

type DynamicFunctionLibrary interface {
	FunctionLibrary
	// LookupDynamic returns the function a dynamic reference to this name and
	// arity resolves to.
	LookupDynamic(ctx *Context, name xdm.QName, arity int) (Function, bool)
}

type EnvironmentResolver interface {
	// LookupEnvironment returns the value of name and whether it is
	// available. A resolver that hides a variable returns ok false, which is
	// the same answer an unset variable gives.
	LookupEnvironment(name string) (value string, ok bool)

	// EnvironmentNames returns the names LookupEnvironment will answer, in
	// any order. An empty result is legal and means no variable is exposed.
	EnvironmentNames() []string
}

type Expr interface {
	// Eval evaluates the expression in ctx and returns a sequence.
	Eval(ctx *Context) (xdm.Sequence, error)
	// String returns a source-like rendering, used in error messages and to
	// make test failures readable.
	String() string
}

type FilterExpr struct {
	Base       Expr
	Predicates []Expr
}

type ForExpr struct {
	Bindings []Binding
	Return   Expr
}

type FuncCall struct {
	Name xdm.QName
	Args []Expr
}

type Function struct {
	Name  xdm.QName
	Arity int
	// Call receives the already-evaluated arguments. Functions that need the
	// context item (fn:string with no argument, fn:position) read it from ctx.
	Call func(ctx *Context, args []xdm.Sequence) (xdm.Sequence, error)
	// Since is the first language version in which this function exists. The
	// zero value is XPath20, so every function that predates versioning is
	// available everywhere, and a 3.0 addition is invisible to a 2.0
	// expression rather than being quietly callable from one.
	//
	// The check belongs at lookup rather than in each function body: a 2.0
	// expression calling fn:head must get "unknown function", the same static
	// error every other processor raises, not a working answer or a distinct
	// complaint from inside a function it should not have found.
	//
	// It applies only to the fn: namespace in practice. The math: functions
	// are gated by their namespace instead — see registerMathFuncs.
	Since Version

	// Signature is the declared return type followed by the parameter types,
	// in source spelling. It is what a typed function test — "f#1 instance of
	// function(element(A)) as xs:string" — is judged against.
	//
	// applyBuiltinSignatures fills this from specSignatures for every
	// function in the four namespaces the F&O manifest covers, so it is nil
	// only for a function with no declared type to read: a host or EXSLT
	// extension, or a stylesheet's own. Such a function is matched on arity
	// alone, which is the right answer there rather than merely the
	// permissive one -- its declared type is whatever declared it, not
	// "nothing".
	Signature []string

	// VariadicSignature carries a variadic function's declared type without
	// repeating its one parameter, and mirrors the field of the same name on
	// xdm.FunctionItem -- see the commentary there for why the materialised
	// form is a liability rather than a convenience. Nil for every
	// fixed-arity function, which leaves Signature the ordinary path.
	VariadicSignature *xdm.VariadicSignature
}

type FunctionCall = func(ctx *Context, args []xdm.Sequence) (xdm.Sequence, error)

type FunctionLibrary interface {
	// Lookup returns the function with the given name and arity.
	Lookup(name xdm.QName, arity int) (Function, bool)
}

type FunctionSpec struct {
	Name   xdm.QName
	Arity  int
	Params []SequenceType
	Result SequenceType
	// Since is the first language version in which the function exists, with
	// the same meaning as Function.Since.
	Since Version
	// Extension marks an entry that is not an F&O function — a host-language
	// addition such as fn:stream-available, which XSLT 3.0 defines for
	// streaming and F&O does not define at all. Extensions are excluded from
	// F&O completeness counts and are the documented exception to manifest
	// coverage.
	Extension bool
	// Invoke is the implementation, with the signature of Function.Call.
	Invoke FunctionCall
}

type IfExpr struct {
	Cond, Then, Else Expr
}

type InlineFunctionExpr struct {
	Params []InlineParam
	// Result is the declared return type, or nil if none was written.
	Result *SequenceType
	Body   Expr
}

type InlineParam struct {
	Name xdm.QName
	// Type is the declared parameter type, or nil if none was written, in
	// which case it is item()*.
	Type *SequenceType
}

type InstanceOfExpr struct {
	Operand Expr
	Type    SequenceType
}

type KindTest struct {
	Kind xdm.NodeKind
	// Any matches every kind: the node() test.
	Any bool
	// Name constrains element()/attribute()/processing-instruction() tests
	// that name a target.
	Name    *xdm.QName
	HasName bool
	// Content constrains the root element of a document-node() test:
	// document-node(element(invoice)) matches only a document whose element
	// child satisfies the inner test. Nil means the document's content is
	// unconstrained.
	Content NodeTest
	// TypeName is the second argument of element(name, type) and its
	// attribute() counterpart, resolved to the key the data model records
	// type annotations under: a namespace-qualified {uri}local for a schema
	// type, the bare local name for a built-in. The empty string means the
	// test carried no type argument and constrains only the name.
	//
	// It is resolved at parse time because the prefix binding lives in the
	// static context, which is gone by the time the test runs. Comparing the
	// lexical form instead forced the comparison down to local parts, and two
	// types sharing a local name in different namespaces then matched each
	// other.
	TypeName string
	// TypeNameLexical is TypeName as the author wrote it, kept only so that
	// String() renders the test back in the syntax it was parsed from.
	TypeNameLexical string
	// TypeUnionMembers are the annotation keys of TypeName's member types,
	// transitively, when TypeName is a union type.
	//
	// XPath 3.1 2.5.5 makes union membership a clause of derives-from in its
	// own right, and a node validated against a union is annotated with the
	// MEMBER that accepted it rather than with the union. So an attribute
	// declared as a union of my:partNumberType and xs:integer whose value is
	// "44" is annotated "integer", and attribute(*, my:partIntegerUnion)
	// matches it only by knowing the members. match-232 asserts exactly that.
	//
	// The relation runs one way only. These names admit a MEMBER-annotated
	// node to the UNION's test; they say nothing about the reverse, and a
	// node annotated with the union does not match a test naming one member.
	//
	// Resolved at parse time, while the schema is still reachable, for the
	// same reason SubstitutionGroup is. nil when TypeName is not a union.
	TypeUnionMembers []string
	// TypeNillable records the "?" of element(name, type?), which lets a
	// nilled element match even though its content is absent.
	TypeNillable bool
	// SchemaDeclared marks a schema-element() or schema-attribute() test,
	// which names a global declaration rather than an element name. It
	// matches the named declaration and, for an element, the members of its
	// substitution group.
	SchemaDeclared bool
	// SubstitutionGroup holds the other names schema-element(E) admits: the
	// members of E's substitution group, resolved from the imported schema
	// when the test was parsed.
	//
	// It is resolved at parse time because nothing carries a schema into the
	// evaluator, and the group is fixed once the schema is imported. Nil for
	// every test that is not a schema-element(), and for a declaration that
	// heads no group.
	SubstitutionGroup []xdm.QName
	// DeclaredType is the local name of the type the schema-element() or
	// schema-attribute() declaration names, resolved at parse time for the
	// same reason SubstitutionGroup is. A node whose annotation is neither
	// that type nor derived from it was validated against some *other*
	// declaration of the same name — a local one — and does not match.
	//
	// Empty when the declaration's type is anonymous, in which case there is
	// no name to compare and the test checks only that the node was
	// validated.
	DeclaredType string
}

type LetExpr struct {
	Bindings []Binding
	Return   Expr
}

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

type Library struct {

	// Parent is consulted when a name is not found locally, so a stylesheet's
	// own functions can shadow and extend the builtins without copying them.
	Parent FunctionLibrary
	// contains filtered or unexported fields
}

type Literal struct{ Val *xdm.Atomic }

type LookupExpr struct {
	Base Expr
	// Name, Index and Wildcard are the three shapes a key specifier takes;
	// exactly one is set. Expr is the parenthesised form, "?($k)".
	Name    string
	HasName bool
	// Index is the literal position of "?3", held as the atomic the parser
	// already built rather than re-encoded as a machine int. An integer
	// literal is arbitrary-precision, so "?100000000000000000000000000000000"
	// has to survive to evaluation intact and fail there as FOAY0001 with its
	// own digits; narrowing it here saturated it to maxint.
	Index    *xdm.Atomic
	HasIndex bool
	Wildcard bool
	Expr     Expr
}

type MapConstructor struct {
	Keys   []Expr
	Values []Expr
}

type NameTest struct {
	// Name is the expanded name to match. Wildcards leave one or both parts
	// unconstrained; see AnyURI and AnyLocal.
	Name xdm.QName
	// AnyURI matches any namespace ("*" and "*:local").
	AnyURI bool
	// AnyLocal matches any local name ("*" and "prefix:*").
	AnyLocal bool
}

type NamedFunctionRef struct {
	Name  xdm.QName
	Arity int
	// Cast is the cast a reference to the CONSTRUCTOR FUNCTION of an imported
	// schema type stands for, with the argument reachable as
	// ConstructorArgVar. Nothing registers such a function in the library --
	// the set of them is not known until a schema is imported -- so the
	// reference is resolved here, while the parser's schema hook is still in
	// reach, exactly as foldSchemaConstructor resolves an ordinary call.
	// nil for every other reference.
	Cast Expr
}

type NamespaceResolver interface {
	// ResolvePrefix returns the URI bound to prefix, or false if unbound.
	ResolvePrefix(prefix string) (string, bool)
	// DefaultElementNamespace returns the namespace applied to unprefixed
	// element name tests. XSLT sets this from xpath-default-namespace; it is
	// empty by default, and it never applies to attribute names or function
	// names.
	DefaultElementNamespace() string
	// DefaultFunctionNamespace returns the namespace for unprefixed function
	// names, which is the fn: namespace in XPath and XSLT.
	DefaultFunctionNamespace() string
}

type NodeTest interface {
	// Matches reports whether n is selected on an axis whose principal node
	// kind is principal.
	Matches(n *xdm.Node, principal xdm.NodeKind) bool
	String() string
}

type OSEnvironment struct{}

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

type PathExpr struct {
	// Root marks a path that starts at the document root ("/foo" rather
	// than "foo").
	Root  bool
	Steps []Expr // Step, or an arbitrary expression in "(...)/foo" form
}

type QuantifiedExpr struct {
	Every    bool
	Bindings []Binding
	Test     Expr
}

type Regexp interface {
	MatchString(s string) bool
	FindAllStringSubmatchIndex(s string, n int) [][]int
	NumSubexp() int
}

type SchemaImpureUnionTypes interface {
	// SchemaUnionAtomicMemberTypes returns the built-in atomic types the named
	// union admits directly, transitively through member unions, skipping any
	// list member. ok is false when the name is not a union at all.
	SchemaUnionAtomicMemberTypes(name xdm.QName) ([]xdm.TypeCode, bool)
}

type SchemaListTypes interface {
	// SchemaTypeIsList reports whether name is a simple type of variety list,
	// and the name of its item type when it is.
	SchemaTypeIsList(name xdm.QName) (itemType xdm.QName, ok bool)
}

type SchemaTypes interface {
	// LookupSchemaType reports whether name is a type in the static context,
	// and which primitive an atomic value of it erases to.
	//
	// The primitive is what the type *system* needs: "instance of" and "treat
	// as" compare against the type hierarchy, and a value of a derived atomic
	// type is a value of its primitive with facets applied. A complex type,
	// or a list or union with no single primitive, returns ok with a zero
	// code and false for atomic — enough to stop XPST0051 without claiming
	// the value is comparable as an atomic.
	LookupSchemaType(name xdm.QName) (prim xdm.TypeCode, atomic, ok bool)

	// LookupSchemaDeclaration reports whether name is a global element or
	// attribute declaration in the static context.
	//
	// It is what schema-element() and schema-attribute() need: both name a
	// *declaration* rather than a type, and both are XPST0008 when no schema
	// declares the name.
	LookupSchemaDeclaration(name xdm.QName, attribute bool) bool

	// SubstitutionGroupMembers returns the global element declarations that
	// may substitute for name, transitively and not including name itself.
	//
	// schema-element(E) matches E and every member of E's substitution
	// group, so a schema that declares "surname" as substitutable for "last"
	// makes schema-element(z:last) match a z:surname element. Resolving the
	// members here rather than at match time is what keeps the node test
	// self-contained: nothing carries a schema into the evaluator, and the
	// group is fixed once the schema is imported.
	//
	// An implementation with no schema, or a name with no members, returns
	// nil.
	SubstitutionGroupMembers(name xdm.QName) []xdm.QName

	// SchemaDeclarationType returns the local name of the type a global
	// element or attribute declaration names, and whether there is one.
	//
	// It is a LOCAL name, unlike the type name in an element() test, which is
	// resolved to a namespace-qualified annotation key at parse time. The
	// difference is deliberate: this string is produced by an implementation
	// of this interface, which has no obligation to know about annotation
	// keys, so the comparison against it (in nodeTypeMatches, reached through
	// KindTest.DeclaredType) accepts a bare name as a local-part match. That
	// is narrower ground than it sounds: the check exists only to tell a
	// global declaration from a LOCAL declaration of the same name in the
	// same schema, where the namespace is not in question.
	//
	// schema-element(E) matches a node only when it was validated against
	// E's *declaration*, and a node may carry E's name while having been
	// validated against a local declaration of a different type — which is
	// the case the suite draws the line on. The evaluator sees only the
	// compiled test, so the declared type is resolved here, while the schema
	// is still reachable, and compared against the node's annotation at
	// match time.
	//
	// An anonymous type has no name to return, so a declaration using one
	// returns false and the test falls back to checking only that the node
	// was validated at all.
	SchemaDeclarationType(name xdm.QName, attribute bool) (string, bool)

	// ValidateSchemaValue checks a lexical value against a named simple type
	// in the static context, reporting whether the name is a simple type at
	// all and, if so, whether the value is in its value space.
	//
	// "castable as my:hatsize" is that question. The engine can cast to the
	// built-in the type derives from, but the facets the schema author wrote
	// live only in the schema — so without asking, a cast to a restriction of
	// xs:integer accepted every integer and the restriction meant nothing.
	ValidateSchemaValue(name xdm.QName, value string) (known bool, err error)
}

type SchemaUnionListMembers interface {
	// SchemaUnionListMemberNames returns the names of the named union's list
	// members, in declaration order and transitively through member unions.
	// ok is false when the name is not a union at all.
	SchemaUnionListMemberNames(name xdm.QName) ([]xdm.QName, bool)
}

type SchemaUnionMemberFacets interface {
	// SchemaUnionMemberFacetNames returns one name per entry of
	// SchemaUnionMemberTypes: a built-in member's bare local name
	// ("NCName"), and the empty string for a member with no built-in name to
	// apply. ok is false when the name is not a pure union.
	SchemaUnionMemberFacetNames(name xdm.QName) ([]string, bool)

	// SchemaUnionAtomicMemberFacetNames is the same, one name per entry of
	// SchemaUnionAtomicMemberTypes: an IMPURE union's atomic members, which a
	// cast reaches by the same rule and which lose the same information.
	// CastAs-UnionType-34 casts to a pattern-restricted union over xs:date and
	// three Gregorian types and requires an xs:date back.
	SchemaUnionAtomicMemberFacetNames(name xdm.QName) ([]string, bool)
}

type SchemaUnionNames interface {
	SchemaUnionMemberNames(name xdm.QName) ([]string, bool)
}

type SchemaUnionTypes interface {
	// SchemaUnionMemberTypes returns the built-in atomic types a pure union
	// type admits, transitively, and whether name is a pure union type at
	// all.
	//
	// "Pure" is XPath 3.1 2.5's term and its constraints are the caller's to
	// enforce: variety union, no facets, no list type in the transitive
	// membership, and no member union carrying facets. A union failing any of
	// them returns false — XSD 1.1 fixed a 1.0 error here, and matching such
	// a type is unsafe rather than merely unsupported.
	SchemaUnionMemberTypes(name xdm.QName) ([]xdm.TypeCode, bool)
}

type ScopedFunctionLibrary interface {
	FunctionLibrary
	// LookupFrom returns the function a call written in ctx's package resolves
	// to, or false where that package may not see it.
	LookupFrom(ctx *Context, name xdm.QName, arity int) (Function, bool)
}

type SequenceExpr struct{ Items []Expr }

type SequenceType struct {
	// Empty is the empty-sequence() type.
	Empty bool
	// ItemType is nil for item(), which matches anything.
	ItemType NodeTest
	// AtomicType names an atomic type when the item type is one.
	AtomicType    xdm.TypeCode
	HasAtomicType bool
	// IsFunctionTest marks a function(*) or function(...) as ... item type,
	// which matches a function item. A typed test additionally fixes the
	// arity and, where the function item records a signature of its own, the
	// parameter and return types it must be compatible with.
	IsFunctionTest   bool
	FunctionArity    int
	HasFunctionArity bool
	// FunctionParams and FunctionReturn are the typed test's declared
	// parameter and return types. They are matched only against a function
	// item that records its own signature; one that does not is judged on
	// arity alone. Every standard function now carries its manifest
	// signature, so that path is reached only by a function with no declared
	// type to read -- an untyped inline function, or a host extension.
	FunctionParams []SequenceType
	FunctionReturn *SequenceType
	// IsArrayTest marks an "array(*)" or "array(T)" item type, added in 3.1.
	//
	// An array is also a function item, so a function test can match one too;
	// the reverse does not hold, which is why this is a flag of its own rather
	// than a shape of IsFunctionTest. ArrayMember is the declared member type
	// of "array(T)", against which *every* member sequence is checked —
	// members are sequences, so "array(xs:string)" admits only arrays whose
	// members are each exactly one string.
	IsArrayTest bool
	ArrayMember *SequenceType
	// IsMapTest marks a "map(*)" or "map(K, V)" item type, added in 3.1, on
	// the same reasoning as IsArrayTest: a map is also a function item, so a
	// function test matches one, but a map test matches only a map.
	//
	// MapKey is the declared key type, an atomic type with no occurrence
	// indicator, and MapValue the declared value type, checked against every
	// entry's value sequence.
	IsMapTest bool
	MapKey    *SequenceType
	MapValue  *SequenceType
	// IsErrorType marks xs:error, the empty type. Nothing is an instance of
	// it, so it matches only the empty sequence — and only then because the
	// occurrence indicator permits it, never because an item conformed.
	IsErrorType bool
	// IsNumericType marks xs:numeric, the union of xs:double, xs:float and
	// xs:decimal that XPath 3.1 adds.
	//
	// It is a union rather than an atomic type, so it has no TypeCode of its
	// own: an item is an instance of it when its type is any of the three or
	// derived from one, which is what makes xs:short an xs:numeric. A cast to
	// it is the identity on a value that already is one and a cast to
	// xs:double on anything else, so the written name has to survive to the
	// cast rather than collapsing to a type code here.
	IsNumericType bool
	// ListItemFacet is the item type's facet name when the written type is
	// one of the built-in list types -- "NMTOKEN" for xs:NMTOKENS. A list
	// type's value is a sequence, so no TypeCode stands for it and the name
	// has to survive to the cast; see listtype.go.
	ListItemFacet string
	// FacetName is the derived type actually written, when it differs from
	// AtomicType — "byte" for xs:byte, which is an xs:integer with a range.
	// The code alone cannot express the bound, and dropping it made
	// "128 castable as xs:byte" answer true.
	FacetName string
	// SchemaType is the lexical name of a type that came from an imported
	// schema rather than from the built-in table.
	//
	// It is kept as written because that is what the schema's own type table
	// is keyed by: matching a value against it means asking the schema, not
	// the type codes here, and a derived type's identity is exactly its name.
	SchemaType string

	// SchemaValueValid checks a lexical value against the imported schema
	// type SchemaType names, when that name is a simple type. It is captured
	// at parse time, while the schema is still reachable through the
	// resolver, for the same reason a schema-element() test's substitution
	// group is: nothing carries a schema into the evaluator.
	//
	// nil when the type is not an imported simple type, in which case a cast
	// is decided entirely by the built-in the type derives from.
	SchemaValueValid func(value string) error

	// SchemaExpandQName resolves a lexical QName against the namespace
	// bindings in scope where the type name was written, when the type's
	// value space is the QName one.
	//
	// A cast to xs:QName or to a type derived from xs:NOTATION cannot be
	// completed without it: the namespace comes from the static context, and
	// by evaluation time that context is gone -- CastToDerived produces a
	// QName with no URI, which is why the parser folds the literal case. A
	// computed operand has no literal to fold, so the bindings are captured
	// here instead, alongside SchemaValueValid and for the same reason.
	//
	// nil unless the type is QName-valued.
	SchemaExpandQName func(lexical string) (xdm.QName, bool)

	// SchemaUnionMembers are the built-in atomic types a *pure union type*
	// from an imported schema admits, transitively.
	//
	// XPath 3.1 2.5.5 writes union membership as its own clause of
	// derives-from — "ET is a pure union type of which AT is a member type" —
	// so a value is an instance of the union whenever its actual type is one
	// of the members. No validation and no annotation are involved: the
	// xs:date that fn:current-date returns is an instance of a union over
	// xs:date, xs:time and xs:dateTime purely because xs:date is a member.
	//
	// Resolved at parse time, while the schema is still reachable, for the
	// same reason SchemaValueValid is. nil for anything that is not a pure
	// union, which is what keeps the impure cases 2.5 excludes — a union
	// carrying facets, or one with a list type anywhere in its transitive
	// membership — matching nothing rather than matching too much.
	SchemaUnionMembers []xdm.TypeCode

	// SchemaUnionMemberFacets are the member type NAMES of the same union, one
	// per entry of SchemaUnionMembers and in the same order, or nil when the
	// resolver cannot supply them.
	//
	// A CAST to a union produces an instance of the member that accepted the
	// value, and the erased code cannot say which derived type that was: a
	// union over xs:NCName and xs:QName reports xs:string for the first, so
	// the cast returned a bare string and "instance of xs:NCName" was false.
	// The name is what CastToDerived needs to apply the facet and annotate the
	// result. See SchemaUnionMemberFacets.
	SchemaUnionMemberFacets []string

	// SchemaListType marks a schema-defined simple type of variety list
	// written in type position.
	//
	// It is the schema-defined counterpart of ListItemFacet, which covers
	// only the three built-in list types the engine knows by name. Both say
	// the same thing -- the value is a sequence of whitespace-separated
	// tokens, not one atomic item -- and both exist so that a cast to such a
	// type is not rejected by the atomic-target rule. The difference is how
	// the tokens are checked: a built-in list applies a known item facet,
	// while a schema-defined one is validated in full by the schema through
	// SchemaValueValid, which already applies the item type AND the list's
	// own facets.
	SchemaListType bool

	// SchemaListItemType is the built-in atomic type each whitespace-
	// separated token of a SchemaListType value is cast to, or the zero code
	// when the item type is itself schema-defined and has no built-in code.
	// Castability does not depend on it -- the schema decides that through
	// SchemaValueValid -- but the cast's result sequence does.
	SchemaListItemType xdm.TypeCode

	// SchemaListItem is the item type of the same list, resolved as a cast
	// target in its own right, or nil when the resolver cannot supply it.
	//
	// SchemaListItemType is lossy in the way a cast cares about. XPath erases
	// every derived string type to xs:string, so a list of xs:IDREF built
	// three bare strings where F&O 3.0 18.3.6 owes three values "each of
	// which is an instance of the item type"; and a list whose item type is
	// a union has no code at all, so its tokens stayed the strings they were
	// handed in as. CastAs-UnionType-27 asks for xs:IDREF* and
	// CastAs-ListType-21 for an xs:NCName that is also an instance of the
	// union. Each token is cast to THIS type, through the same rules as a
	// cast written against it, so the facet is applied, the member chosen and
	// the annotation recorded. The code stays as the fallback for a resolver
	// that answers only the older question.
	SchemaListItem *SequenceType

	// SchemaSimpleType marks a named schema simple type that is a legal cast
	// target but has no shape any of the fields above can describe: an
	// *impure* union -- one carrying facets, or one holding a list type
	// anywhere in its transitive membership -- and a union derived by
	// restriction.
	//
	// The distinction from SchemaUnionMembers is which question is being
	// asked, not which types exist. XPath 3.1 2.5 admits only a *pure* union
	// as an ItemType, because "instance of" has to answer from a value's own
	// annotation and a faceted union's members do not necessarily satisfy its
	// facets -- the XSD 1.0 error 1.1 3.16.6.3 corrected. But 3.14.2 admits
	// any simple type in the in-scope schema types as a cast target, and a
	// cast has a lexical form in hand to validate, so the objection does not
	// arise: castability is the schema's own ValidateValue answer.
	// cbcl-castable-impure-001 asserts that
	// "xs:date('2001-01-01') castable as s:impureUnionType" is true, not an
	// error, and the purity rule still governs every ItemType position.
	//
	// SchemaValueValid is what decides a value; this field only says that the
	// name denotes such a type, so the atomic-target rule lets it through.
	SchemaSimpleType bool

	// SchemaSimpleListMembers are the LIST members of the impure union
	// SchemaSimpleType marks, in declaration order, each resolved as a cast
	// target of its own: SchemaListType set, SchemaListItem carrying the item
	// type, SchemaValueValid the member's own validity.
	//
	// A cast to a list type produces a SEQUENCE, one value per whitespace-
	// separated token (F&O 3.0 18.3.6). A union holding a list member is
	// impure, so such a cast arrives here rather than in the list-type branch
	// above, and without this the result was the single string handed in.
	// cbcl-castable-impure-010 is what that cost: the constructor
	// "s:impureUnionType('1 2 3')" owes three xs:decimal values, and a
	// three-item sequence is not castable to anything -- so the outer
	// "castable as s:impureUnionType" is false, where one string made it true.
	//
	// The members are whole types rather than one item code because the code
	// could not say which list admitted the value, nor what its items are
	// beyond a built-in primitive. A union over xs:IDREFS and a list of a
	// union (CastAs-UnionType-27 and -28) owes xs:IDREF values from the first
	// and union-member values from the second, and which one applies is
	// decided by trying them in order -- the rule for every union.
	//
	// Only a string-like source reaches a list member at all; an atomic
	// source is confined to SchemaSimpleAtomicMembers, which is the rule that
	// separates -005 from -009. nil when the union has no list member.
	SchemaSimpleListMembers []SequenceType

	// SchemaSimpleAtomicMembers are the built-in atomic types an impure union
	// admits directly, ignoring any list member.
	//
	// It is what separates cbcl-castable-impure-001 from -009. impureUnionType
	// is a union of xs:date and a list of xs:decimal, and the suite asks for
	// true from an xs:date and FALSE from an xs:decimal -- even though "1" is
	// a perfectly good one-item list of decimals. The difference is the SOURCE
	// type: F&O defines a cast to a list type from xs:string and
	// xs:untypedAtomic only, so a non-string source can reach a union's ATOMIC
	// members and nothing else. A string-like source may reach every member,
	// which is why "1 2 3" as an xs:untypedAtomic is castable (-005) and the
	// same value already typed as the union is not (-010).
	//
	// nil when the type has no atomic member, which refuses every non-string
	// source -- the right answer for a union over list types alone.
	SchemaSimpleAtomicMembers []xdm.TypeCode

	// SchemaSimpleAtomicFacets are those members' NAMES, one per entry and in
	// the same order, or nil when the resolver cannot supply them. It is
	// SchemaUnionMemberFacets for the impure case, and exists for the same
	// reason: the cast's result is an instance of the member that accepted the
	// value, and the erased code cannot say which derived type that was.
	SchemaSimpleAtomicFacets []string

	// Occurrence is "", "?", "*" or "+".
	Occurrence string
}

type SerializeParams struct {
	// AllowDuplicateNames permits a JSON object to be written with two keys
	// that render to the same string; without it that is SERE0022.
	AllowDuplicateNames bool
	// Indent asks for whitespace around the JSON structural tokens.
	//
	// Serialization 3.1 section 9.1.4 makes this the one parameter of the two
	// that is optional in a direction: for indent=yes the serializer MAY add
	// whitespace, and for indent=no it MUST NOT. So compact output was always
	// conformant, and remains exactly what is written when this is false.
	Indent bool
	// JSONNodeOutputMethod is the method a node nested inside a JSON value is
	// serialised with, since JSON itself has no node type. Empty means the
	// default, "xml".
	JSONNodeOutputMethod string
	// ItemSeparator, when HasItemSeparator is set, goes between the items of
	// an adaptive result in place of the newline the method otherwise writes.
	ItemSeparator    string
	HasItemSeparator bool
	// CharMap maps a character to the string that replaces it on output, as
	// xsl:character-map defines.
	CharMap map[rune]string
	// Normalize applies the requested Unicode normalization form, or is nil
	// when the normalization-form parameter was "none". The caller supplies
	// the function rather than the form's name because normalisation cannot
	// be left until the document is finished: a character map's replacement
	// is exempt from it, so the two have to be interleaved here, where the
	// map is applied.
	Normalize func(string) string
	// Encoding is the output encoding. Nothing is transcoded -- both methods
	// return a string -- but the JSON method escapes a character the named
	// encoding could not have held, and only the caller knows which was
	// asked for.
	Encoding string
	// Budget is the evaluation whose MaxBytes allowance the serialized bytes
	// are charged against. These two entry points are a host boundary --
	// xslt's own serializer reaches the JSON and adaptive methods through
	// them, carrying no Context of its own -- so without it the bytes a
	// transform serializes are the one string production nothing charges.
	//
	// Nil is unbounded, which is what a caller who does not set it gets and
	// what both functions did before the field existed.
	Budget *Context
}

type SimpleMap struct {
	Left  Expr
	Right Expr
}

type StaticCall struct {
	Name  xdm.QName
	Arity int
	// Ref marks a "name#arity" reference rather than a call. The two differ
	// in what a missing function means to the host language, so the caller is
	// told which it found.
	Ref bool
	// StringArgs holds the arguments of a call that are string literals, one
	// entry per argument position, nil wherever the argument is anything
	// else. It is empty for a Ref, which has no arguments.
	//
	// A host language whose error is about the *value* of a literal argument
	// can decide it without waiting for the call to be reached: XSLT's
	// XTDE3490 asks whether the name written in current-merge-group('x')
	// is one of the merge sources, and says the error "may be reported
	// statically if it can be detected statically". Only literals are
	// reported, because an argument that has to be evaluated has no static
	// value -- which is the same line checkMergeKeyCompatibility draws.
	StringArgs []*string
}

type Step struct {
	Axis       Axis
	Test       NodeTest
	Predicates []Expr

	// Explicit records that the axis was written out ("child::x") rather
	// than abbreviated ("x"). Section 5.5.3 gives the abbreviated child axis
	// in a pattern a wider reach than the written one — it is evaluated on
	// the child-or-top axis, so "document-node()" alone matches the document
	// node while "child::document-node()" is legal but matches nothing,
	// since a document node is never a child.
	Explicit bool
}

type StringConcat struct {
	Left  Expr
	Right Expr
}

type TextResolver interface {
	// ResolveText returns the text of uri, resolved against base, decoded
	// using encoding when one is named and as UTF-8 when it is empty.
	ResolveText(uri, base, encoding string) (string, error)
}

type Token struct {
	Kind TokenKind
	Val  string
	Pos  int

	// Num holds the parsed numeric value and NumType its XPath type, so the
	// parser does not re-parse the literal. A numeric literal's type is fixed
	// by its lexical form: no dot or E means integer, a dot means decimal, an
	// E means double.
	Num float64
	// contains filtered or unexported fields
}

type TokenKind int

type TreatExpr struct {
	Operand Expr
	Type    SequenceType
}

type TreeValidator interface {
	// ValidateJSONTree assesses a document node holding the XML
	// representation of JSON against the schema of F&O 3.1 §C.2, annotating
	// the tree in place.
	//
	// The tree was constructed by this package a moment ago and is reachable
	// from nowhere else, so mutating it is safe in a way that annotating a
	// source document would not be.
	//
	// An implementation that has the schema but finds the tree invalid
	// returns the error. That should not happen for a tree fn:json-to-xml
	// built — the construction rules of §17.4.2 produce a valid instance by
	// construction, and duplicates="retain", the one option that does not,
	// is already refused alongside validate=true — but a wrong answer is
	// worth a diagnosis rather than a silently untyped tree.
	ValidateJSONTree(doc *xdm.Node) error
}

type UnaryOp struct {
	Op      string
	Operand Expr
}

type VarQualifier func(ctx *Context, name xdm.QName) xdm.QName

type VarRef struct{ Name xdm.QName }

type Version int