Extensions

All extensions are in the namespace http://www.gobosoft.com/eiffel/gobo/gexslt/extension.

Extension attributes

The following extension attributes are available:

explain

This attribute may be set on any instruction in the stylesheet, or on a literal result element. The permitted values are "yes", "no" and "all". If the value is "yes", then at compile time an analysis of all XPath expressions appearing as attributes of that element is written to the standard error stream. The analysis includes the static type of the expression, and a representation of the expression tree that results from parsing and optimization. The tree structure is represented by indentation.

The value of "all" only takes effect on xsl:stylesheet and xsl:transform elements. It is treated as if "yes" was coded. Additionally, if this is the prinicpal stylesheet, then the instructions themselves, when compiled to an expression, have their compiled form displayed. (Only xsl:templates, top-level xsl:variables and xsl:params, and xsl:function definitions are displayed.)

This can produce a lot of output.

memo-function

This attribute used to make gexslt non-compliant. It is now ignored. Use the gexslt:function extension instruction instead.

Extension attributes for xsl:output

character-representation

This tells the serializer how to serialize non-ASCII characters, and characters that are not representable in the selected encoding.

This may need to be dropped - I have to check the serialization specs, but I think they have been tightened to disallow some of this.

When the output method is "xml" or "xhtml"

(Hm.maybe xhtml should follow the html behaviour)

, this parameter only effects characters that are not representable in the selected encoding. It can take on the value "hex" or "decimal", and it determines whether the character is written out with a decimal character reference, or a hexadecimal character reference (the default).

When the output method is "html", then the value may hold two strings, separated by a semicolon. The first string defines how non-ASCII characters within the character encoding will be represented, the values being "native", "entity", "decimal", or "hex". The second string defines how characters outside the encoding will be represented, the values being "entity", "decimal", or "hex". Here "native" means output the character as itself; "entity" means use a defined entity reference (such as "é") if known; "decimal" and "hex" refer to numeric character references. For example "entity;decimal" (the default) means that with encoding="iso-8859-1", characters in the range 160-255 will be represented using standard HTML entity references, while Unicode characters above 255 will be represented as decimal character references.

This parameter has no meaning when the output method is "text". For QName output methods, it's interpretation is up to the programmer of the method, but the possible values are those for the "html" method.

indent-spaces

This tells the serializer how many spaces to add for indentation when indent="yes" is specified. It is ignored when indent="no" is specified, or is omitted and the default for the serialization method is "no". If you omit this parameter, then three spaces are used (but check the creation procedure for XM_XSLT_OUTPUT_PROPERTIES to confirm this, in case it gets changed and I forget to update the documentation).

TODO: Change the default to indent with a single tab.

next-in-chain

This is only allowed in conjunction with the gexslt:chain output method. It's value is the URI of the next transformation to be run over the output.

method

This is only allowed on xsl:result-document, and it specifies the method used to store the resource. For HTTP, only PUT and POST are permitted. PUT is the default. Other schemes allow any value and ignore it.

User-defined data elements

The fn:doc(), fn:collection() and fn:document() functions are defined to be stable by default. That is, repeated use of one of these functions on the same URI will result in the identical document node (or collection of document nodes in the case of fn:collection()). But to implement this the library is forced to lock the documents in memory for the duration of the transformation. This can cause severe performance problems, especially with large collections. For that reason, an implementation is allowed to provide options that allow other isolation levels (in the SQL sense - the default behaviour corresponds to SERIALIZABLE).

This option is provided through an experimental user-defined data element isolation-level, which is ignored unless it is a top-level element in the principal stylesheet module. This has a compulsory attribute (in the per-element partition, not in the gexslt namespace) isolation-level. This takes one of the four values:

read-uncommitted
read-committed
repeatable-read
serializable

The effect of this implementation, is that documents or collections specified as read-committed (or read-uncommitted) will not be locked in memory. If the same URI is passed to one of these functions a second time, then the document(s) will be read and parsed by the XML parser a second time. This will break the usual guarantee of node identity.

This user-defined data element is experimental. I intend to eventually move towards a more transaction-oriented solution. Support for this user-defined data element may then be dropped (note that this will not cause errors in stylesheets that use it - it will then have no effect (other than to issue a warning)).

There is also collation. This is intended for declaring collation-URI names, but as the only collation supported is the default one at the moment, it is not much use (I use it for binding additional URIs to the default collation, to test the collation-naming mechanism). When a tailorable collation based on the Unicode Collation Algorithm is available, then this will be used to bind URI names to tailored collations.

Extension instructions

Gexslt:function

gexslt:function is identical in syntax to xsl:function. However it is implemented as a memo-function for performance.

If the function has any side effects (which can only occur if it uses user-written extension functions with side-effects), or if it access context information, such as position(), last() or the context item, then you may not get what you expect.

If the function constructs and returns a temporary tree, the same tree will be returned each time. The only consequence of this is if you compare node identities on that tree.

gexslt:serialize may be defined in the future. Or maybe not. Users can always use Evan Lenz's serializer written in XSLT 1.0. (I think an XSLT 2.0 html serializer has also been written).

Extension functions

gexslt:transformation

This function allows you to run an XSLT transformation from within your current XSLT transformation. Syntax is gexslt:transformation ($trans-uri as xs:string, $initial-context as node()?, $initial-template as xs:QName?, $initial-mode as xs:QName?, $parameter-names as xs:QName*, $parameter-values as item()*, $features as xs:string?) as item()+

or gexslt:transformation ($trans-uri as xs:string, $initial-context as node()) as item()+

The two-argument form is equivalent to passing () for all remaining arguments.

The meaning of the arguments is as follows:

The URI of the transformation to be run
An optional initial context node
An optional initial template
An optional initial mode
The $parameter-names are names of global stylesheet parameters.
The $parameter-values lists must be of the same length as the $parameter-names list. It contains values of the stylesheet parameter named in the corresponding position in the $parameter-names list.
The $features string consists of a white-space separated list of xs:QName-valued features. No features are defined at this stage. I have various stylesheet-caching control features in mind, and general options such as which tree-model to use.

If the stylesheet fails to compile, then the error return value will be COMPILE_FAILED in the gexslt namespace. If there is no initial template, and no initial context node, then the error return value will be NO_INITIAL_TEMPLATE in the gexslt namespace. If the number of parameter names and values are unequal, then the error return value will be PARAMETER_MISMATCH in the gexslt namespace. If an unrecognized feature name is supplied, then the error return value will be UNRECOGNIZED_FEATURE in the gexslt namespace. Otherwise, the error return value will be a standard XPath or XSLT error code, or a normal gexslt error code,

The result sequence has one of two forms:

An xs:QName, followed by an xs:string forllowed by item()* representing the components of the error from the transformation (see fn:error()).
Zero or onedocument-node()s. The document will be the implicit result document if one exists.

Result documents can be serialized using the gexslt:serialize extension instruction (if I ever write it).

gexslt:response-body

This function returns any available response data, as a single string, as a result of storing an xsl:result-document. It takes a single string argument (required), whose value must be the same as the (resolved) value of the href attribute on the xsl:result-document. If no such response data is available then the error return value will be NO_RESPONSE in the gexslt namespace.

This is principally intended for use with http URIs, but any scheme that supports responses to store requests can use it. Database requests spring to mind.