ViewVC logotype

Contents of /vendor/gobosoft.com/gobo/current/doc/gexslt/extension/index.xml

Parent Directory Parent Directory | Revision Log Revision Log

Revision 90767 - (show annotations)
Tue Jan 22 00:56:30 2013 UTC (6 years, 8 months ago) by manus
File MIME type: text/xml
File size: 15045 byte(s)
Updated svn:eol-style to be native and svn:mime-style to be text/xml

1 <?xml version="1.0" encoding="UTF-8"?>
3 <!--
4 description:
6 "Gobo Eiffel XSLT extensions"
8 library: "Gobo Eiffel XSLT"
9 copyright: "Copyright (c) 2004, Colin Adams and others"
10 license: "MIT License"
11 date: "$Date$"
12 revision: "$Revision$"
13 -->
15 <chapter xmlns="http://www.gobosoft.com/eiffel/gobo/documentation" id="gexslt_extensions">
16 <chapterinfo>
17 <copyright>
18 <year>2004</year>
19 <holder>Colin Adams and others</holder>
20 </copyright>
21 <author>
22 <firstname>Colin</firstname>
23 <surname>Adams</surname>
24 </author>
25 <email>colin@colina.demon.co.uk</email>
26 <date>Wednesday, November 24th, 2004</date>
27 </chapterinfo>
28 <title>Extensions</title>
29 <para>
30 All extensions are in the namespace <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension</uri>.
31 </para>
32 <section>
33 <title>Extension attributes</title>
34 <para>
35 The following extension attributes are available:
36 <variablelist>
37 <varlistentry>
38 <term><exmlsyntax>explain</exmlsyntax></term>
39 <listitem>
40 <para>
41 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".
42 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
43 error stream. The analysis includes the static type of the expression, and a representation of the expression tree that results from parsing and optimization.
44 The tree structure is represented by indentation.
45 </para>
46 <para>
47 The value of "all" only takes effect on xsl:stylesheet and xsl:transform elements. It is treated as if "yes" was coded.
48 Additionally, if this is the prinicpal stylesheet, then the instructions themselves, when compiled to an expression,
49 have their compiled form displayed. (Only xsl:templates, top-level xsl:variables and xsl:params, and xsl:function definitions
50 are displayed.)
51 <warning>This can produce a lot of output.</warning>
52 </para>
53 </listitem>
54 </varlistentry>
55 <varlistentry>
56 <term><exmlsyntax>memo-function</exmlsyntax></term>
57 <listitem>
58 <para>
59 <warning>
60 This attribute used to make gexslt non-compliant. It is now ignored. Use the gexslt:function extension instruction instead.
61 </warning>
62 </para>
63 </listitem>
64 </varlistentry>
65 </variablelist>
66 <section>
67 <title>Extension attributes for xsl:output</title>
68 <variablelist>
69 <varlistentry>
70 <term><exmlsyntax>character-representation</exmlsyntax></term>
71 <listitem>
72 <para>
73 This tells the serializer how to serialize non-ASCII characters, and characters that are not representable
74 in the selected encoding.
75 <warning>
76 This may need to be dropped - I have to check the serialization specs, but I think they have been tightened to disallow
77 some of this.
78 </warning>
79 </para>
80 <para>
81 When the output method is "xml" or "xhtml" <warning>(Hm.maybe xhtml should follow the html behaviour)</warning>,
82 this parameter only effects characters that are not representable
83 in the selected encoding. It can take on the value "hex" or "decimal", and it determines whether
84 the character is written out with a decimal character reference, or a hexadecimal
85 character reference (the default).
86 </para>
87 <para>
88 When the output method is "html", then the value may hold two strings, separated by a semicolon.
89 The first string defines how non-ASCII characters within the character encoding will be represented,
90 the values being "native", "entity", "decimal", or "hex".
91 The second string defines how characters outside the encoding will be represented, the values being
92 "entity", "decimal", or "hex". Here "native" means output the character as itself; "entity" means
93 use a defined entity reference (such as "&amp;eacute;") if known; "decimal" and "hex" refer to numeric
94 character references. For example "entity;decimal" (the default) means that with encoding="iso-8859-1",
95 characters in the range 160-255 will be represented using standard HTML entity references, while
96 Unicode characters above 255 will be represented as decimal character references.
97 </para>
98 <para>
99 This parameter has no meaning when the output method is "text". For <exmlsyntax>QName</exmlsyntax> output methods,
100 it's interpretation is up to the programmer of the method, but the possible values are those for the
101 "html" method.
102 </para>
103 </listitem>
104 </varlistentry>
105 <varlistentry>
106 <term><exmlsyntax>indent-spaces</exmlsyntax></term>
107 <listitem>
108 <para>
109 This tells the serializer how many spaces to add for indentation when <xslt>indent="yes"</xslt> is specified.
110 It is ignored when <xslt>indent="no"</xslt> is specified, or is omitted and the default
111 for the serialization method is "no". If you omit this parameter, then three spaces are used
112 (but check the creation procedure for <classname>XM_XSLT_OUTPUT_PROPERTIES</classname> to confirm
113 this, in case it gets changed and I forget to update the documentation).
114 <warning>
115 TODO: Change the default to indent with a single tab.
116 </warning>
117 </para>
118 </listitem>
119 </varlistentry>
120 <varlistentry>
121 <term><exmlsyntax>next-in-chain</exmlsyntax></term>
122 <listitem>
123 <para>
124 This is only allowed in conjunction with the <xslt>gexslt:chain</xslt> output method.
125 It's value is the URI of the next transformation to be run over the output.
126 </para>
127 </listitem>
128 </varlistentry>
129 <varlistentry>
130 <term><exmlsyntax>method</exmlsyntax></term>
131 <listitem>
132 <para>
133 This is only allowed on <xslt>xsl:result-document</xslt>, and it specifies the method used
134 to store the resource. For HTTP, only PUT and POST are permitted. PUT is the default. Other schemes
135 allow any value and ignore it.
136 </para>
137 </listitem>
138 </varlistentry>
139 </variablelist>
140 </section>
141 </para>
142 </section>
143 <section>
144 <title>User-defined data elements</title>
145 <para>
146 The <xpath>fn:doc(), fn:collection() and fn:document()</xpath> functions are defined to be stable by default.
147 That is, repeated use of one of these functions on the same URI will result in the identical document node (or
148 collection of document nodes in the case of <xpath>fn:collection()</xpath>). But to implement this the library
149 is forced to lock the documents in memory for the duration of the transformation.
150 This can cause severe performance problems, especially with large
151 collections. For that reason, an implementation is allowed to provide options that allow other isolation levels
152 (in the SQL sense - the default behaviour corresponds to SERIALIZABLE).
153 </para>
154 <para>
155 This option is provided through an experimental user-defined data element <exmlsyntax>isolation-level</exmlsyntax>, which is ignored
156 unless it is a top-level element in the principal stylesheet module.
157 This has a compulsory attribute (in the per-element partition, not in the gexslt namespace)
158 <exmlsyntax>isolation-level</exmlsyntax>. This takes one of the four values:
159 <itemizedlist>
160 <listitem><para>read-uncommitted</para></listitem>
161 <listitem><para>read-committed</para></listitem>
162 <listitem><para>repeatable-read</para></listitem>
163 <listitem><para>serializable</para></listitem>
164 </itemizedlist>
165 </para>
166 <para>
167 The effect of this implementation, is that documents or collections specified as read-committed (or read-uncommitted) will
168 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
169 and parsed by the XML parser a second time. This will break the usual guarantee of node identity.
170 <warning>
171 This user-defined data element is experimental. I intend to eventually move towards a more transaction-oriented solution.
172 Support for this user-defined data element may then be dropped (note that this will not cause errors in stylesheets that
173 use it - it will then have no effect (other than to issue a warning)).
174 </warning>
175 </para>
176 <para>
177 There is also <exmlsyntax>collation</exmlsyntax>.
178 This is intended for declaring collation-URI names, but as the only collation supported is
179 the default one at the moment, it is not much use (I use it for binding additional URIs to the default collation,
180 to test the collation-naming mechanism). When a tailorable collation based on the Unicode Collation Algorithm is
181 available, then this will be used to bind URI names to tailored collations.
182 </para>
183 </section>
184 <section>
185 <title>Extension instructions</title>
186 <section>
187 <title>Gexslt:function</title>
188 <para>
189 <xslt>gexslt:function</xslt> is identical in syntax to xsl:function. However it is implemented as a memo-function
190 for performance.
191 </para>
192 <para>
193 If the function has any side effects (which can only occur if it uses
194 user-written extension functions with side-effects), or if it access context information, such as position(),
195 last() or the context item, then you may not get what you expect.
196 </para>
197 <para>
198 If the function constructs and returns a temporary tree, the same tree will be returned each time. The only consequence
199 of this is if you compare node identities on that tree.
200 </para>
201 </section>
202 <para>
203 <xslt>gexslt:serialize</xslt> may be defined in the future. Or maybe not.
204 Users can always use <ulink url="http://xmlportfolio.com/xml-to-string/">Evan Lenz's serializer written in XSLT 1.0</ulink>.
205 (I think an XSLT 2.0 html serializer has also been written).
206 </para>
207 </section>
208 <section>
209 <title>Additional output methods</title>
210 <para>
211 The only supplied method is <xslt>gexslt:chain</xslt>, which delegates serialization to a further
212 transformation, sepecified by the <xslt>gexslt:next-in-chain</xslt> attribute. Consquently all other
213 attributes on the <xslt>xslt:output</xslt> element are ignored.
214 </para>
215 <para>
216 There is also an example provided to show Eiffel programmers
217 how to write their own output methods. This is in the namespace
218 <uri>http://www.gobosoft.com/eiffel/gobo/gexslt/extension/example</uri>, and has
219 a local name of <exmlsyntax>xml</exmlsyntax>. It functions identically to the standard
220 <xslt>xml</xslt> method, unless the extension attribute <exmlsyntax>internal-subset</exmlsyntax> (in the same
221 namespace) is supplied. In which case, it's value is used as the text for a DTD internal subset. You
222 must also supply <xslt>doctype-system</xslt> for this to work.
223 </para>
224 </section>
225 <section>
226 <title>Extension functions</title>
227 <section>
228 <title>gexslt:transformation</title>
229 <para>
230 This function allows you to run an XSLT transformation from within your current XSLT transformation. Syntax
231 is <xpath>gexslt:transformation ($trans-uri as xs:string,
232 $initial-context as node()?,
233 $initial-template as xs:QName?,
234 $initial-mode as xs:QName?,
235 $parameter-names as xs:QName*,
236 $parameter-values as item()*,
237 $features as xs:string?) as item()+</xpath></para>
238 <para>or
239 <xpath> gexslt:transformation ($trans-uri as xs:string, $initial-context as node()) as item()+</xpath>
240 </para>
241 <para>
242 The two-argument form is equivalent to passing () for all remaining arguments.
243 </para>
244 <para>
245 The meaning of the arguments is as follows:
246 </para>
247 <orderedlist>
248 <listitem><para>The URI of the transformation to be run</para></listitem>
249 <listitem><para>An optional initial context node</para></listitem>
250 <listitem><para>An optional initial template</para></listitem>
251 <listitem><para>An optional initial mode</para></listitem>
252 <listitem>
253 <para>
254 The $parameter-names are names of global stylesheet parameters.
255 </para>
256 </listitem>
257 <listitem>
258 <para>
259 The $parameter-values lists must be of the same length as the $parameter-names list.
260 It contains values of the stylesheet parameter named in the corresponding position in the $parameter-names list.
261 </para>
262 </listitem>
263 <listitem>
264 <para>
265 The $features string consists of a white-space separated list of <xpath>xs:QName</xpath>-valued features.
266 No features are defined at this stage. I have various stylesheet-caching control features in mind, and general
267 options such as which tree-model to use.
268 </para>
269 </listitem>
270 </orderedlist>
271 <para>
272 If the stylesheet fails to compile, then the error return value will be COMPILE_FAILED in the gexslt namespace.
273 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.
274 If the number of parameter names and values are unequal, then the error return value will be PARAMETER_MISMATCH in the gexslt namespace.
275 If an unrecognized feature name is supplied, then the error return value will be UNRECOGNIZED_FEATURE in the gexslt namespace.
276 Otherwise, the error return value will be a standard XPath or XSLT error code, or a normal gexslt error code,
277 </para>
278 <para>
279 The result sequence has one of two forms:
280 <orderedlist>
281 <listitem>
282 <para>
283 An <xpath>xs:QName</xpath>, followed by an <xpath>xs:string</xpath> forllowed by <xpath>item()*</xpath>
284 representing the components of the error from the transformation (see <xpath>fn:error()</xpath>).
285 </para>
286 </listitem>
287 <listitem><para>Zero or one<xpath>document-node()</xpath>s. The document will be the implicit result document if one exists.</para></listitem>
288 </orderedlist>
289 </para>
290 <para>
291 Result documents can be serialized using the <xslt>gexslt:serialize</xslt> extension instruction (if I ever write it).
292 </para>
293 </section>
294 <section>
295 <title>gexslt:response-body</title>
296 <para>
297 This function returns any available response data, as a single string, as a result
298 of storing an <xslt>xsl:result-document</xslt>. It takes a single string argument (required), whose
299 value must be the same as the (resolved) value of the <xslt>href</xslt> attribute on the <xslt>xsl:result-document</xslt>.
300 If no such response data is available then the error return value will be NO_RESPONSE in the gexslt namespace.
301 </para>
302 <para>
303 This is principally intended for use with <uri>http</uri> URIs, but any scheme that supports responses to store requests
304 can use it. Database requests spring to mind.
305 </para>
306 </section>
307 </section>
309 </chapter>


Name Value
svn:mime-type text/xml

  ViewVC Help
Powered by ViewVC 1.1.23