xslt

type BudgetedModuleResolver interface {
	ModuleResolver
	// ResolveModuleWith is ResolveModule charging against b.
	ResolveModuleWith(
		b *xdm.EntityBudget, href, base string) (*xdm.Node, string, error)
}

type Compatibility struct {
	// DropAttributesOnDocumentNode discards an attribute or namespace node
	// that reaches the content of a document node, instead of raising
	// XTDE0420.
	//
	// The specified behaviour is the error. 5.8.1 applies its rules in the
	// order listed, and the rule that unwraps a document node in the result
	// sequence unwraps document nodes only -- an attribute survives it and
	// reaches the check. The suite agrees: error-0420a exists to assert this,
	// and its own description reads "the xsl:copy is copying a document node
	// which can't have an attribute".
	//
	// Saxon nonetheless accepts it, and stylesheets are written to that.
	// DocBook xslTNG builds a temporary tree from a sequence containing an
	// attribute in its head.xsl, and every document carrying an xml:lang
	// fails against a processor that applies the rule.
	DropAttributesOnDocumentNode bool

	// PrivateFunctionsVisibleToEvaluate is retained for symmetry and is a
	// no-op: the private-visibility default is already confined to a real
	// xsl:package, which is where visibility is a meaningful property. It is
	// named here so that the behaviour is discoverable alongside the other
	// divergences rather than only in the changelog.
	PrivateFunctionsVisibleToEvaluate bool
}

type CompileOptions struct {
	// Resolver loads xsl:include and xsl:import targets. Nil disables them,
	// which is the safe default for untrusted stylesheets.
	Resolver ModuleResolver

	// BaseURI of the stylesheet, for resolving relative include paths.
	BaseURI string
	// StaticParams supplies values for static stylesheet parameters — a
	// top-level xsl:param carrying static="yes" — keyed by the parameter's
	// {uri}local name. A static parameter is bound before static analysis
	// begins, so its value has to come from the caller rather than from
	// Transform's runtime Params.
	StaticParams map[string]xdm.Sequence

	// SchemaResolver loads the schemas named by xsl:import-schema. Nil
	// disables loading by location, for the same reason a nil Resolver
	// disables xsl:include: following a location means fetching whatever
	// the stylesheet names. An inline <xs:schema> child needs no resolver.
	SchemaResolver xsd.Resolver

	// SchemaParseOptions are passed to the XML parser for each schema
	// document xsl:import-schema loads, including the ones those documents
	// import in turn.
	//
	// The zero value refuses a DOCTYPE, which is the right default for the
	// same reason it is in xsd.Options: a schema has no use for one, and it
	// is the entry point for entity expansion attacks. A host that must
	// read a schema carrying one -- the W3C's own schema for schemas
	// declares its entities that way -- sets AllowDOCTYPE here, and thereby
	// says so deliberately rather than having it decided for it.
	SchemaParseOptions xdm.ParseOptions

	// PackageResolver loads the packages named by xsl:use-package. Nil
	// disables package composition, for the same reason a nil Resolver
	// disables xsl:include: resolving a package name means fetching whatever
	// the stylesheet asks for, and a host running an untrusted stylesheet
	// should decide what that can reach.
	PackageResolver PackageResolver

	// XPathVersion pins the version of XPath every expression in the
	// stylesheet is compiled in, overriding what the stylesheet declares.
	//
	// Nil, the default, derives it from the version attribute the way the
	// specification requires: 1.0 and 2.0 are XPath 2.0, 3.0 is XPath 3.1,
	// since XSLT 3.0 section 2.2 requires an XPath 3.1 processor.
	//
	// Setting it is for a host that must decide the language itself rather
	// than let the document decide — pinning XPath20 to run an untrusted
	// stylesheet under a smaller surface, or raising a stylesheet that
	// declares 2.0 but is known to want the later functions. It is a
	// deliberate departure from conformance in both directions, which is why
	// nothing sets it implicitly.
	XPathVersion *xpath.Version

	// Compat relaxes rules this engine is right to enforce, for stylesheets
	// written against a processor that does not. The zero value enforces
	// them all; see Compatibility.
	Compat Compatibility

	// MaxVersion caps the XSLT version whose constructs the compiler will
	// accept, whatever the stylesheet's own @version says.
	//
	// It exists for the constructs a later version *adds* to the language
	// rather than changes in it. xsl:package is the case that forces it: a
	// package written to XSLT 3.0 routinely carries version="2.0", because
	// the version attribute states the XSLT version of the *expressions*, not
	// of the packaging — so the attribute cannot tell an XSLT 2.0 processor,
	// for which xsl:package is XTSE0010, apart from a 3.0 one for which it is
	// the module element. Only the host knows which it is running as.
	//
	// Zero, the default, imposes no cap and accepts everything implemented.
	MaxVersion float64
	// contains filtered or unexported fields
}

type DecimalFormat = xpath.DecimalFormat

type FileResolver struct {
	// Roots are the directories a relative or absolute path may resolve
	// inside. A path escaping all of them is refused.
	Roots []string

	// AllowDOCTYPE permits a DOCTYPE declaration in the documents this
	// resolver parses. It is off by default, which is what keeps a
	// stylesheet from reaching a document that expands entities or names an
	// external one — the XXE entry point. A caller whose inputs are trusted,
	// a conformance suite among them, can turn it on.
	AllowDOCTYPE bool

	// ExternalEntities permits the documents this resolver parses to read
	// external entities and an external DTD subset, using this same resolver
	// — so they are confined to Roots on exactly the terms everything else
	// is, with the same scheme rejection and the same symlink handling.
	//
	// It is separate from AllowDOCTYPE and off by default. AllowDOCTYPE
	// admits declarations that cost nothing outside the document; this
	// admits reads of other files, which is the XXE surface proper. A caller
	// that wants DTD-declared entities does not thereby want file reads, and
	// making one imply the other would silently widen every existing caller.
	ExternalEntities bool

	// UnparsedText permits fn:unparsed-text to read files through this
	// resolver, confined to Roots on the same terms as everything else.
	//
	// It is separate from every other flag here and off by default, because
	// it is the widest of them. ResolveDocument hands the stylesheet a
	// parsed XML document, so a file that is not well-formed XML discloses
	// nothing; unparsed-text hands back the raw bytes of any file inside
	// Roots, so a root containing one XML data file and one private key
	// leaks the key. A caller who wants fn:doc does not thereby want that,
	// and folding the two together would silently widen every existing
	// caller of NewFileResolver.
	UnparsedText bool

	// MaxBytes bounds a single file this resolver reads, whichever way the
	// stylesheet asks for it: fn:doc and xsl:import, an external entity,
	// fn:unparsed-text, and XInclude parse="text" all go through one read.
	// Zero means DefaultMaxResourceBytes; a negative value means no limit,
	// for a caller reading files it produced itself.
	//
	// It is one field rather than one per call path on purpose. The confinement
	// above is a property of the *file*, not of the function that names it —
	// every root is readable by every path, so a stylesheet refused a 200 MB
	// file through unparsed-text would simply ask for it through doc(), and two
	// numbers would only mean the effective limit is the larger of them while
	// looking like it were the smaller. One number is the honest statement of
	// what a resolver will put in memory for one resource.
	//
	// The bound is needed here and not only downstream. xdm.ParseOptions.MaxBytes
	// bounds the *parse*, but readConfined has the whole file in memory before
	// the parser is handed anything, and fn:unparsed-text and XInclude
	// parse="text" never reach a parser at all. Once a caller enables a
	// FileResolver the stylesheet chooses which permitted file is read, so an
	// unbounded read makes any large readable file a memory-exhaustion
	// primitive.
	MaxBytes int64
	// contains filtered or unexported fields
}

type Instruction interface {
	// Execute runs the instruction, appending to out.
	Execute(rt *runtime, out *outputBuilder) error
}

type ModuleResolver interface {
	ResolveModule(href, base string) (*xdm.Node, string, error)
}

type OutputSettings struct {
	Method        string // "xml", "html", "text"
	Indent        bool
	OmitXMLDecl   bool
	Encoding      string
	DocTypePublic string
	DocTypeSystem string
	CDataElements []xdm.QName
	// SuppressIndentation names the elements whose content is written with
	// no added whitespace even when indent is yes. It is separate from
	// CDataElements despite taking the same kind of list, because the two
	// name elements for opposite reasons: one because their text needs no
	// escaping, the other because their text must not be disturbed.
	SuppressIndentation []xdm.QName
	Standalone          string
	// Version is xsl:output/@version. For the html method it selects the
	// HTML version; for xml and xhtml it is the XML version.
	Version string
	// HTMLVersion is xsl:output/@html-version, new in XSLT 3.0.
	//
	// It exists because @version cannot answer the question for XHTML: there
	// it states the version of XML, so an XHTML5 document is still
	// version="1.0" and the HTML version had nowhere to go. Section 9.1: if
	// html-version is absent "the html output method uses the value of the
	// version parameter in its place", so it overrides for html and is the
	// only source for xhtml.
	HTMLVersion string
	// UseCharacterMaps names the xsl:character-map declarations applied at
	// serialisation.
	UseCharacterMaps []xdm.QName
	// ByteOrderMark writes a BOM at the start of the output. It is "no" by
	// default for every method, which is what makes UTF-8 output usable by
	// readers that do not expect one.
	ByteOrderMark bool
	// IncludeContentType controls whether the HTML and XHTML methods insert
	// the content-type meta element. It defaults to true, which is why it is
	// stored as a pointer: an explicit "no" has to be distinguishable from
	// the attribute being absent.
	IncludeContentType *bool
	// EscapeURIAttributes controls percent-escaping of URI-valued attributes
	// in the HTML and XHTML methods. It defaults to true, and is a pointer
	// for the same reason.
	EscapeURIAttributes *bool
	// UndeclarePrefixes emits namespace undeclarations, which only XML 1.1
	// permits. This parser implements XML 1.0, so it is recorded and ignored.
	UndeclarePrefixes bool
	// ItemSeparator is xsl:output/@item-separator: the string inserted
	// between adjacent items of the result sequence during sequence
	// normalisation (XSLT 3.0 section 5.7.1 step 3).
	//
	// It is a pointer because an explicit zero-length separator is not the
	// same as the attribute being absent: absent means the default rule
	// (adjacent atomic values separated by a single space, nodes not
	// separated at all), while item-separator="" means every adjacency gets
	// nothing, including between two atomic values.
	ItemSeparator *string

	// BuildTree says whether the raw result is normalised into a final
	// result tree before it is delivered or serialised (XSLT 3.0 section
	// 2.3.6). Nil is the default, which depends on the method: yes for xml,
	// html, xhtml and text, no for json and adaptive.
	//
	// With build-tree="no" the raw sequence is serialised as it stands, so
	// item-separator has something to separate -- normalisation would have
	// merged the whole sequence into one tree first, which is why the note
	// in 27.1 says the separator "has no effect ... if the effective value
	// of build-tree is yes".
	BuildTree *bool
	// ParameterDocument is the URI of an external
	// output:serialization-parameters document whose parameters override the
	// ones written here. It is kept as a URI rather than resolved at compile
	// time because 25.1 says the document "should be read during run-time
	// evaluation of the stylesheet", so that a stylesheet deployed away from
	// where it was written still finds its own parameters.
	ParameterDocument string
	// ParameterDocumentBase is the base URI of the element that wrote
	// ParameterDocument, which is what a relative URI there resolves
	// against. It has to travel with the URI rather than be taken from the
	// principal module: an <xsl:output name="f" parameter-document="p.xml"/>
	// in a module reached by xsl:include names a document beside *that*
	// module, and output-0722 puts the included module and its parameter
	// document in a subdirectory to make the difference visible.
	ParameterDocumentBase string
	// InlineCharMap is a character map given by value rather than by name:
	// the output:use-character-maps element of a parameter document spells
	// its entries out, having no xsl:character-map declaration to point at.
	// It overrides UseCharacterMaps entirely, being the higher-precedence
	// source of the same parameter.
	InlineCharMap map[rune]string
	// AllowDuplicateNames is the JSON output method's parameter of that name:
	// with it unset, two map keys that render to the same JSON string are
	// SERE0022 rather than two entries in one object.
	AllowDuplicateNames bool
	// JSONNodeOutputMethod is the method a node nested inside a JSON value is
	// serialised with, JSON having no node type of its own. Empty is the
	// default, "xml".
	JSONNodeOutputMethod string
	// MediaType is the media type of the output. It is metadata a caller
	// passes on, with one exception: the html and xhtml methods write it
	// into the content attribute of the meta element they inject, where it
	// is escaped like any other attribute value.
	MediaType string
	// NormalizationForm names a Unicode normalisation applied to the output.
	// NFC, NFD, NFKC and NFKD are implemented, as is "none"; see
	// normalizerFor in serialize.go. Any other value -- "fully-normalized"
	// among them -- is a serialization error rather than something to ignore,
	// because output that was silently left unnormalised would be accepted
	// by a consumer that then compares it against a normalised form and
	// finds a spurious difference.
	NormalizationForm string
	// Version10Implicit records that the principal module declares version
	// "1.0" and this is the implicitly-created final result tree.
	//
	// It changes only the *default* output method. Under backwards
	// compatibility an XSLT 1.0 stylesheet has no xhtml method to select —
	// the method did not exist — so a result whose document element is html
	// in the XHTML namespace serialises as xml, not xhtml: URI-valued
	// attributes are left unescaped and no content-type meta element is
	// added. An explicit xsl:output/@method overrides this like any other
	// default, and xsl:result-document clears the flag, because the tree it
	// creates is not the implicit one.
	Version10Implicit bool
}

type PackageResolver interface {
	ResolvePackage(name, versionMatch string) (*xdm.Node, error)
}

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

type Result struct {

	// Nodes is the result sequence, which for a typical stylesheet is a
	// single element.
	Nodes xdm.Sequence
	// Messages holds xsl:message output, in the order produced.
	Messages []string
	// Warnings holds the warnings the transform raised, in the order
	// produced. They report conditions the spec asks a processor to notice —
	// currently the two xsl:mode warning attributes — and never affect the
	// result.
	Warnings []string
	// Secondary holds the documents produced by xsl:result-document, in the
	// order produced. It is empty for the great majority of stylesheets,
	// which produce a single result.
	Secondary []SecondaryResult
	// BaseURI is the URI this result tree is identified by, which Tree()
	// puts on the document node it manufactures. It is empty for the
	// principal result, whose document node has no URI of its own; a caller
	// assembling a Result from a SecondaryResult sets it from that
	// document's BaseURI so that base-uri(/) answers inside it.
	BaseURI string
	// contains filtered or unexported fields
}

type SecondaryResult struct {
	// Href is the resolved @href value, as written by the stylesheet. It is
	// the caller's choice what to do with it — this engine never writes to
	// the filesystem on a stylesheet's behalf, since a transform that can
	// create files anywhere the process can write is a hazard the caller
	// should be the one to opt into.
	Href string
	// BaseURI is Href resolved against the base output URI, which is the
	// base URI of every node in this document that does not override it with
	// xml:base.
	//
	// Section 19.1 makes the base output URI implementation-defined when the
	// caller does not supply one, and the stylesheet's own location is the
	// only URI this engine has: an @href of "out/second.xml" written in a
	// stylesheet read from .../foo.xsl means .../out/second.xml, which is
	// also where a caller honouring the href would write it. Leaving it
	// empty made base-uri() answer "" for every node in a secondary result,
	// and made a relative xml:base inside one resolve against nothing.
	BaseURI string
	// Nodes is the result sequence for this document.
	Nodes xdm.Sequence
	// Output holds the serialisation settings that apply to this document,
	// taken from @format and any serialisation attributes on the instruction.
	Output OutputSettings
	// contains filtered or unexported fields
}

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

type Template struct {
	Match    *Pattern
	Name     xdm.QName
	HasName  bool
	Mode     []string // empty means the default (unnamed) mode
	Priority float64
	Params   []*Variable
	Body     []Instruction
	// contains filtered or unexported fields
}

type TransformOptions struct {
	// Params supplies values for top-level xsl:param, keyed by Clark name
	// ("{uri}local", or just "local" for a no-namespace parameter).
	Params map[string]xdm.Sequence

	// Documents resolves fn:doc and fn:document. Nil disables them, which is
	// the default: a stylesheet that can open arbitrary URIs is an SSRF and
	// file-disclosure vector, and validation rule sets need at most the code
	// lists shipped beside them.
	Documents xpath.DocumentResolver

	// Collections resolves fn:collection. Nil disables it, which is the
	// default, and setting Documents does not set this: enabling fn:doc for
	// a known code list should not also let a stylesheet enumerate whatever
	// a collection URI happens to name.
	Collections xpath.CollectionResolver

	// Texts resolves fn:unparsed-text. Nil disables it, which is the
	// default, and setting Documents does not set this: fn:doc hands back a
	// parsed XML document, while fn:unparsed-text hands back the raw bytes
	// of whatever the resolver will open. See xpath.TextResolver.
	Texts xpath.TextResolver

	// Environment answers fn:environment-variable and
	// fn:available-environment-variables. Nil withholds the process
	// environment from both, which is the default: a stylesheet that can
	// read the environment can read whatever credentials the process was
	// started with, and no resolver root bounds that. Setting Documents or
	// Texts does not set this. See xpath.EnvironmentResolver, and
	// xpath.OSEnvironment for the widest grant.
	Environment xpath.EnvironmentResolver

	// MaxDepth bounds template recursion. Zero means DefaultMaxDepth; a
	// negative value means no limit.
	//
	// "No limit" is not the safe end of the range. Recursion runs on the Go
	// stack, and exhausting it is a fatal error the runtime does not deliver
	// as a panic, so recover cannot turn it back into a failed request: the
	// process dies and every other request in flight dies with it. The bound
	// is what converts that into an error value. Remove it only for input
	// you produced yourself.
	//
	// The bound catches a stylesheet that recurses without a base case,
	// which is the common authoring mistake. But it also counts the ordinary
	// descent of an identity transform, so a limit below the parser's left
	// this refusing documents it had just accepted: at the old fixed 300, a
	// legal 500-deep document could be parsed and not transformed.
	MaxDepth int

	// DisableAssertions turns off xsl:assert checking for the whole
	// transformation. The zero value leaves assertions enabled, which is what
	// XSLT 3.0 section 22.2 requires: "By default, assertions are enabled."
	//
	// The same section asks for this switch: "An implementation should provide
	// an external mechanism to disable assertion checking for the stylesheet
	// as a whole (either statically or dynamically). The detail of such
	// mechanisms is implementation-defined." It lives here rather than on
	// CompileOptions because dynamic is the more useful of the two readings —
	// one compiled stylesheet can then be run with assertions on in test and
	// off in production, without recompiling — and because a caller who wants
	// the static reading already has use-when, which 22.2 names first.
	//
	// A disabled assertion is skipped before its @test is evaluated, so it
	// cannot fail and costs nothing. Note that this is the only thing that may
	// skip one: the section closes by asking implementations to "avoid
	// optimizing xsl:assert instructions away".
	DisableAssertions bool

	// InitialMode names the mode for the initial apply-templates.
	InitialMode string

	// InitialMatchSelection is what the initial apply-templates selects from.
	//
	// Section 2.3.2 makes the initial match selection an arbitrary sequence,
	// not a node: a caller may start the transform at a set of nodes, or —
	// since XSLT 3.0 gave patterns the power to match one — at atomic values
	// with no source document behind them at all. Leaving it nil defaults the
	// selection to the source document, which is the ordinary invocation.
	//
	// Setting it is also what satisfies XTDE0044: naming an initial mode
	// obliges the caller to say what to apply it to, and the source document
	// is only the usual way of saying it.
	InitialMatchSelection xdm.Sequence

	// InitialTemplate names a template to invoke instead of matching the
	// document root, which is how a stylesheet with only named templates is
	// entered.
	InitialTemplate string
	// InitialTemplateURI is the namespace URI of InitialTemplate, for a
	// caller that has already resolved the prefix in its own namespace
	// context. Empty means resolve any prefix in InitialTemplate against the
	// stylesheet's own declarations instead.
	//
	// The two are not interchangeable. A caller naming the template from
	// outside the stylesheet — a test catalog, a command line with its own
	// bindings — binds the prefix itself, and resolving it a second time
	// against the stylesheet can silently select a DIFFERENT template that
	// happens to spell another namespace with the same prefix.
	InitialTemplateURI string

	// InitialFunction names a stylesheet function to invoke as the entry
	// point, which is the third way into a stylesheet beside a template and
	// an apply-templates. Section 2.3.5 calls it the initial function.
	//
	// The name is expanded: a caller naming a function from outside the
	// stylesheet has already bound its own prefixes, and resolving a second
	// time against the stylesheet's declarations could select a different
	// function that spells another namespace with the same prefix. This is
	// the same hazard InitialTemplateURI exists for, and the QName form
	// avoids it outright rather than needing a companion field.
	//
	// Leave it zero to use one of the other entry points. It is mutually
	// exclusive with InitialTemplate and with an initial mode.
	InitialFunction xdm.QName

	// InitialFunctionParams are the arguments of the initial function call,
	// in order. Section 2.3.5 makes the arity of the entry point the LENGTH
	// OF THIS LIST -- "in the design of a concrete API, the arity may be
	// inferred from the length of the parameter list" -- so this is not
	// merely the values but also the half of the function's identity that
	// InitialFunction does not carry.
	//
	// A nil list therefore selects arity zero rather than meaning "unset":
	// the spec gives no way to name an initial function without also fixing
	// its arity, so a caller naming a function and supplying no parameters is
	// asking for the nullary one, and gets XTDE0041 if none exists.
	InitialFunctionParams []xdm.Sequence

	// InitialTemplateParams are the values supplied for the initial
	// template's non-tunnel parameters, keyed by the parameter name in Clark
	// notation. InitialTemplateTunnelParams are its tunnel parameters, which
	// pass through to whatever the template calls in turn.
	//
	// They are separate from Params, which binds the stylesheet's global
	// parameters. Section 2.3.2 makes those two different acts of priming: a
	// global parameter belongs to the stylesheet and is set once, while these
	// are the arguments of one call, and a template parameter and a global
	// parameter may share a name without either standing for the other.
	InitialTemplateParams       map[string]xdm.Sequence
	InitialTemplateTunnelParams map[string]xdm.Sequence

	// InitialModeParams and InitialModeTunnelParams are the same thing for an
	// apply-templates invocation: section 2.3.3 gives that entry point "two
	// sets of (QName, value) pairs, one set for tunnel parameters and one for
	// non-tunnel parameters", with "the same [effect] as when a template is
	// invoked using xsl:apply-templates with an xsl:with-param child".
	//
	// They are kept apart from the initial-template pair rather than shared
	// with it because the two entry points are mutually exclusive (XTDE0047)
	// but the names would still mislead a caller reading the API.
	InitialModeParams       map[string]xdm.Sequence
	InitialModeTunnelParams map[string]xdm.Sequence

	// Now fixes the value fn:current-dateTime returns. Leave it zero to use
	// the wall clock; set it to make a transform reproducible, which is what
	// a golden-file test needs.
	Now time.Time

	// ImplicitTimezone is the offset in minutes for date values with no
	// timezone. Defaults to UTC so that results are reproducible across
	// machines.
	ImplicitTimezone int

	// BaseOutputURI is the URI the principal result tree is destined for.
	// Section 19.1 makes it implementation-defined when the caller supplies
	// none, and this engine never writes files itself, so the default is to
	// have none at all: fn:current-output-uri then answers the empty
	// sequence everywhere, and a relative @href on xsl:result-document
	// resolves against the stylesheet's own location instead.
	BaseOutputURI string
	// contains filtered or unexported fields
}

type Variable struct {
	Name xdm.QName
	// Select is the value expression, or nil when the value comes from the
	// element's content.
	Select *xpath.Compiled
	// Body is the sequence constructor used when Select is absent. A variable
	// with content builds a temporary tree, which is why the two forms are
	// not interchangeable: "select" yields whatever the expression yields,
	// while content always yields a document node.
	Body []Instruction
	// Required marks a parameter that must be supplied.
	Required bool
	// IsParam distinguishes an xsl:param from an xsl:variable. The two are
	// compiled to the same structure because they evaluate identically, but
	// only a parameter can be supplied from outside, and section 10.1.1
	// gives the two different error codes when a declared "as" type rejects
	// the value: a parameter left unsupplied whose required type excludes
	// the empty sequence is XTDE0610, while a variable is only ever the
	// plain type error.
	IsParam bool
	// Tunnel marks a tunnel parameter, which passes through templates that do
	// not declare it.
	Tunnel bool
	// contains filtered or unexported fields
}