<?xml version="1.0" encoding="UTF-8"?> 

<!--
	description:
	
		"Gobo Eiffel XSLT extensions"

	library: "Gobo Eiffel XSLT"
	copyright: "Copyright (c) 2004, Colin Adams and others"
	license: "MIT License"
	date: "$Date: 2007-05-07 03:23:01 -0700 (Mon, 07 May 2007) $"
	revision: "$Revision: 5964 $"
-->

<chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gexslt_extensions">
  <chapterinfo>
    <copyright>
      <year>2004</year>
      <holder>Colin Adams and others</holder>
    </copyright>
    <author>
      <firstname>Colin</firstname>
      <surname>Adams</surname>
    </author>
    <email>colin@colina.demon.co.uk</email>
    <date>Wednesday, November 24th, 2004</date>
  </chapterinfo>
  <title>Extensions</title>
  <para>
    All extensions are in the namespace <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension</uri>.
  </para>
  <section>
    <title>Extension attributes</title>
    <para>
      The following extension attributes are available:
      <variablelist>
	<varlistentry>
	  <term><exmlsyntax>explain</exmlsyntax></term>
	  <listitem>
	    <para>
	      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.
	    </para>
	    <para>
	      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.)
	      <warning>This can produce a lot of output.</warning>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>memo-function</exmlsyntax></term>
	  <listitem>
	    <para>
	      <warning>
	       This attribute used to make gexslt non-compliant. It is now ignored. Use the gexslt:function extension instruction instead.
	      </warning>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <section>
       <title>Extension attributes for xsl:output</title>
       <variablelist>
	<varlistentry>
	  <term><exmlsyntax>character-representation</exmlsyntax></term>
	  <listitem>
	    <para>
	      This tells the serializer how to serialize non-ASCII characters, and characters that are not representable
	      in the selected encoding.
	      <warning>
		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.
	      </warning>
	    </para>
	    <para>
	      When the output method is "xml" or "xhtml" <warning>(Hm.maybe xhtml should follow the html behaviour)</warning>,
	      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).
	    </para>
	    <para>
	      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 "&amp;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.
	    </para>
	    <para>
	      This parameter has no meaning when the output method is "text". For <exmlsyntax>QName</exmlsyntax> output methods,
	      it's interpretation is up to the programmer of the method, but the possible values are those for the 
	      "html" method.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>indent-spaces</exmlsyntax></term>
	  <listitem>
	    <para>
	      This tells the serializer how many spaces to add for indentation when <xslt>indent="yes"</xslt> is specified.
	      It is ignored when <xslt>indent="no"</xslt> 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 <classname>XM_XSLT_OUTPUT_PROPERTIES</classname> to confirm
	      this, in case it gets changed and I forget to update the documentation).
	      <warning>
	       TODO: Change the default to indent with a single tab.
	      </warning>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><exmlsyntax>next-in-chain</exmlsyntax></term>
	  <listitem>
	    <para>
	      This is only allowed in conjunction with the <xslt>gexslt:chain</xslt> output method.
	      It's value is the URI of the next transformation to be run over the output.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      </section>
    </para>
  </section>
 <section>
    <title>User-defined data elements</title>
    <para>
     The <xpath>fn:doc(), fn:collection() and fn:document()</xpath> 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 <xpath>fn:collection()</xpath>). 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).
    </para>
    <para>
     This option is provided through an experimental user-defined data element <exmlsyntax>isolation-level</exmlsyntax>, 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)
     <exmlsyntax>isolation-level</exmlsyntax>. This takes one of the four values:
     <itemizedlist>
      <listitem><para>read-uncommitted</para></listitem>
      <listitem><para>read-committed</para></listitem>
      <listitem><para>repeatable-read</para></listitem>
      <listitem><para>serializable</para></listitem>
     </itemizedlist>
    </para>
    <para>
     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.
     <warning>
      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)).
     </warning>
    </para>
    <para>
      There is also <exmlsyntax>collation</exmlsyntax>.
      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.
    </para>
 </section>
 <section>
    <title>Extension instructions</title>
    <section>
     <title>Gexslt:function</title>
     <para>
      <xslt>gexslt:function</xslt> is identical in syntax to xsl:function. However it is implemented as a memo-function
      for performance.
     </para>
     <para>
      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.
     </para>
     <para>
      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. 
     </para>
    </section>
    <para>
      <xslt>gexslt:serialize</xslt> may be defined in the future. Or maybe not.
      Users can always use <ulink url="http://xmlportfolio.com/xml-to-string/">Evan Lenz's serializer written in XSLT 1.0</ulink>.
      (I think an XSLT 2.0 html serializer has also been written).
    </para>
 </section>
 <section>
    <title>Additional output methods</title>
    <para>
      The only supplied method is <xslt>gexslt:chain</xslt>, which delegates serialization to a further
      transformation, sepecified by the <xslt>gexslt:next-in-chain</xslt> attribute. Consquently all other
      attributes on the <xslt>xslt:output</xslt> element are ignored.
    </para>
    <para>
     There is also an example provided to show Eiffel programmers
      how to write their own output methods. This is in the namespace 
      <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension/example</uri>, and has
      a local name of <exmlsyntax>xml</exmlsyntax>. It functions identically to the standard
      <xslt>xml</xslt> method, unless the extension attribute <exmlsyntax>internal-subset</exmlsyntax> (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 <xslt>doctype-system</xslt> for this to work.
    </para>
 </section>
 <section>
    <title>Extension functions</title>
    <section>
     <title>gexslt:transformation</title>
     <para>
      This function allows you to run an XSLT transformation from within your current XSLT transformation. Syntax
      is <xpath>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()+</xpath></para>
      <para>or
      <xpath> gexslt:transformation ($trans-uri as xs:string, $initial-context as node()) as item()+</xpath>
     </para>
     <para>
      The two-argument form is equivalent to passing () for all remaining arguments.
     </para>
     <para>
      The meaning of the arguments is as follows:
     </para>
     <orderedlist>
      <listitem><para>The URI of the transformation to be run</para></listitem>
      <listitem><para>An optional initial context node</para></listitem>
      <listitem><para>An optional initial template</para></listitem>
      <listitem><para>An optional initial mode</para></listitem>
      <listitem>
       <para>
	The $parameter-names are names of global stylesheet parameters.
       </para>
       </listitem>
      <listitem>
       <para>
	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.
       </para>
       </listitem>
      <listitem>
       <para>
	The $features string consists of a white-space separated list of <xpath>xs:QName</xpath>-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.
       </para>
      </listitem>
     </orderedlist>
     <para>
      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,
     </para>
     <para>
      The result sequence has one of two forms:
      <orderedlist>
       <listitem>
	<para>
	 An <xpath>xs:QName</xpath>,  followed by an <xpath>xs:string</xpath> forllowed by <xpath>item()*</xpath>
         representing the components of the error from the transformation (see <xpath>fn:error()</xpath>).
       </para>
       </listitem>
       <listitem><para>Zero or one<xpath>document-node()</xpath>s. The document will be the implicit result document if one exists.</para></listitem>
      </orderedlist>
     </para>
     <para>
      Result documents can be serialized using the <xslt>gexslt:serialize</xslt> extension instruction (if I ever write it).
     </para>
    </section>
 </section>

</chapter>

