1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
|
<html>
<head>
<title>Compiled Stylesheets</title>
<style>
.comment {
font-style: italic;
}
</style>
</head>
<body>
<h1>Compiled Stylesheets</h1>
<h2>Overview</h2>
<p>
There are 5 main entities: Stylesheet-loaders, stylesheet-compiler,
stylesheet, execution-state and processor. The normal usecase is:
<ol>
<li>Set up a stylesheet-loader to read a resource.
<li>Let it feed events to the stylesheet-compiler.
<li>The compiler creates a stylesheet.
<li>Init an execution-state with stylesheet, initial node, global
parameters and an outputhandler factory.
<li>Start the processor.
</ol>
</p>
<h2>Main classes</h2>
<h3>txStylesheet</h3>
<h4>Description:</h4>
<p>
This class represents a compiled stylesheet. If the stylesheet
contains imported and/or included stylesheets they are all compiled
into a single <code>txStylesheet</code>-object.
</p>
<p>
The stylesheet contains functions for getting the different top-level
entities that exist in a stylesheet, such as attribute-sets, templates
and global variables. The <code>txStylesheet</code> owns all objects
in the stylesheet, including the instructions in templates and
variables.
</p>
<p>
A single <code>txStylesheet</code>-object can be used for multiple
transformations, even running concurrently. Once a stylesheet is
compiled it is never changed, nor does it carry any state.
</p>
<h4>Typical functions:</h4>
<pre>
txInstruction* findTemplate(Node* aNode,
const txExpandedName& aMode,
txIMatchContext* aContext,
ImportFrame* aImportedBy,
ImportFrame** aImportFrame);
txDecimalFormat* getDecimalFormat(const txExpandedName& aName);
txInstruction* getAttributeSet(const txExpandedName& aName);
txOutputFormat* getOutputFormat();
</pre>
<h3>txStylesheetCompiler</h3>
<h4>Description:</h4>
<p>
This class gets "events" from a stylesheet loader and creates a
compiled stylesheet. The class calls back through a callback interface
to the stylesheet-loader to load included and imported stylesheets.
</p>
<p>
The output from the <code>txStylesheetCompiler</code> is a
ready-to-use <code>txStylesheet</code> object.
</p>
<p>
To load included and imported stylesheets the
<code>txStylesheetCompiler</code> calls the loader through a
<code>txIIncludeLoaderCallback</code> interface suppling the url to
load, and the <code>txStylesheetCompiler</code>-object that the loader
should use to notify its events to. There is a separate
<code>txStylesheetCompiler</code>-object for each sub-stylesheet,
however only the initial <code>txStylesheetCompiler</code> will create
a <code>txStylesheet</code>-object.
</p>
<p class="comment">
Do we want to refcount txIIncludeLoaderCallback? It might otherwise
be hairy to deal with loads being cancled or failing.
</p>
<h4>Typical functions:</h4>
<pre>
nsresult startElement(PRInt32 aNamespaceID, txAtom* aLocalName,
txAtom* aPrefix, txStylesheetAttr* aAttributes,
PRInt32 aAttrCount);
nsresult endElement();
nsresult characters(const String& aStr);
nsresult doneLoading();
void cancel(nsresult aError);
</pre>
<h3>txHandlerTable</h3>
<h4>Description:</h4>
<p>
To process the elements and textnodes in the stylesheet the
<code>txStylesheetCompiler</code> calls different
stylesheet-compile-handlers. Which handler to call is decided by two
things:
<ol>
<li>The "mode" of the compiler, i.e. is it processing a top-level
element? Is it processing the contents of a template? Is it
processing the children of a xsl:attribute-set element?
<li>The name and namespace of the element. (Of course, this doesn't
apply to textnodes).
</ol>
The handlers are global static C-style functions. The handlers
processes the elements and textnodes in the stylesheet and
creates instructions and toplevel-items.
</p>
<p>
To find which handler to call the compiler uses
<code>txHandlerTable</code>-objects. The <code>txHandlerTable</code>
contains a list of these stylesheet-compile-handlers keyed on
element-name. It also contains a handler for text and a handler for
LRE-elements.
</p>
<p>
There are different <code>txHandlerTable</code>-objects for different
"modes" of the compiler. There is one for handling top-level elements,
one for handling template-parameters, one for handling the contents of
a xsl:attribte-set element, one for handling the contents of
unsupported extension-elements etc. The
<code>txStylesheetCompiler</code> always has a current
<code>txHandlerTable</code> which is used to find the handler to call.
</p>
<p>
The <code>txHandlerTable</code>s are initialized from static structs.
This is to avoid having large pieces of code containing very similar
code.
</p>
<h4>Typical functions:</h4>
<pre>
nsresult init(txHandlerTableData* aTableData);
txElementHandler* find(PRInt32 aNamespaceID, txAtom* aLocalName);
</pre>
<h3>txStylesheetCompilerState</h3>
<p class="comment">
Do we want to rename this txStylesheetCompilerInternal?
</p>
<h4>Description:</h4>
<p>
This class manages the internal state of the
<code>txStylesheetCompiler</code>. The reason that this is a separate
class is so that the <code>txStylesheetCompiler</code> can keep a clean
interface towards the stylesheet-loaders.
</p>
<p>
The <code>txStylesheetCompilerState</code>-class is used both by the
<code>txStylesheetCompiler</code>-class and by the
stylesheet-compile-handlers.
</p>
<p>
The class has three main purposes:
<ul>
<li>
Keep track of the current context. Such as:
<ul>
<li>Namespace mappings.
<li>Base-URI.
<li>Extension-element namespaces.
<li>Whitespace preservation mode.
</ul>
</li>
<li>
Store the state that the stylesheet-compile-handlers need. For
example the current xsl:for-each loop to add xsl:sort-elements to.
</li>
<li>
Keep track of the current <code>txHandlerTable</code>, so that the
right stylesheet-compile-handler is called for elements and text.
</li>
</ul>
</p>
<p>
This is the class that implements <code>txIParseContext</code> during
all stylesheet-compilation.
</p>
<h4>Typical functions:</h4>
<pre>
nsresult pushHandlerTable(txHandlerTable* aTable);
nsresult parsePattern(const String& aPattern, txPattern** aResult);
nsresult parseExpr(const String& aExpr, Expr** aResult);
nsresult addToplevelItem(txToplevelItem* aItem);
nsresult openInstructionContainer(txInstructionContainer* aContainer);
nsresult addInstruction(txInstruction* aInstruction);
</pre>
<h3>txExecutionState</h3>
<h4>Description:</h4>
<p>
This class manages all state during the execution of a stylesheet.
This includes
<ul>
<li>The current <code>txIEvalContext</code>.
<li>The next <code>txInstruction</code> to be executed.
<li>Variables that are in scope.
<li>Values of global variables and keys.
<li>Current result-handler.
<li>Stylesheet being executed.
</ul>
</p>
<p>
The <code>txExecutionState</code> also acts as a general-purpose stack
that instructions can use to communicate between each other. The class
is the owner of this data and will delete it as appropriate if the
execution aborts.
</p>
<h4>Typical functions:</h4>
<pre>
nsresult pushEvalContext(txIEvalContext* aContext);
txIEvalContext* popEvalContext();
nsresult pushString(const nsAString& aStr);
void popString(nsAString& aStr);
txInstruction* getNextInstruction();
nsresult runTemplate(txInstruction* aInstruction);
void gotoInstruction(txInstruction* aNext);
</pre>
<h3>txXSLTProcessor</h3>
<h4>Description:</h4>
<p>
This is a fully static class that contains the main loop for executing
a stylsheet.
</p>
<h4>Typical functions:</h4>
<pre>
nsresult execute(txExecutionState& aEs);
</pre>
</body>
</html>
|
