2004
Colin Adams and others
Colin
Adams
colin@colina.demon.co.uk Wednesday, November 24th, 2004

# 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 makes gexslt non-compliant, and support will be dropped without warning in the future. The first stage of dropping support will be to issue a warning saying the attribute is ignored. If you have used it correctly, this will only make a performance change. Later, it might be changed to issue an error message.

  This attribute may be set on any xsl:function declaration in the stylesheet. The permitted values are "yes" and "no". If the value is "yes", then the result of calling the function with a given set of parameters is cached.

  This should not be set to "yes" 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.

  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.

### 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 b e 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 "&eacute;") 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).

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.

## 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

None are provided at present. gexslt:serialize may be defined in the future. Or maybe not. Users can always use Evan Lenz's serializer written in XSLT 1.0.

## Additional output methods

The only supplied method is gexslt:chain, which delegates serialization to a further transformation, sepecified by the gexslt:next-in-chain attribute. Consquently all other attributes on the xslt:output element are ignored.

Also, there is an example provided to show Eiffel programmers how to write their own output methods. This is in the namespace `http://www.gobosoft.com/eiffel/gobo/gexslt/extension/example`, and has a local name of xml. It functions identically to the standard xml method, unless the extension attribute internal-subset (in the same namespace) is supplied. In which case, it's value is used as the text for a DTD internal subset. You must also supply doctype-system for this to work.

## 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:

1. The URI of the transformation to be run

2. An optional initial context node

3. An optional initial template

4. An optional initial mode

5. The $parameter-names are names of global stylesheet parameters.

6. 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.

7. 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:

1. An xs:QName, followed by an xs:string forllowed by item()* representing the components of the error from the transformation (see fn:error()).

2. 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.