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
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
|
<meta http-equiv="Context-Type" content="text/html; charset=iso-8859-1">
<?xml version="1.0" encoding="iso-8859-1"?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd ">
<html xmlns="http://www.w3.org/1999/xhtml" ><head>
<title>Customization functions</title>
<link rel="stylesheet" type="text/css" href="stylesheet.css">
</head>
<body>
<h1>Customization functions</h1>
<h3 id="sect_1.1">1 Description</h3>
<p>The XML processor offers a number of hooks for
customization. These hooks are defined as function objects, and
can be provided by the caller.</p>
<p>The following customization functions are available. If
they also have access to their own state variable, the access
function for this state is identified within parentheses:</p>
<ul>
<li>event function (<tt>
xmerl_scan:event_state/[1,2]
</tt>)</li>
<li>hook function (<tt>
xmerl_scan:hook_state/[1,2]
</tt>)</li>
<li>fetch function (<tt>
xmerl_scan:fetch_state/[1,2] </tt>)
</li>
<li>continuation function (<tt>
xmerl_scan:cont_state/[1,2] </tt>)
</li>
<li>rules function (<tt>
xmerl_scan:rules_state/[1,2] </tt>)
</li>
<li>accumulator function</li>
<li>close function</li>
</ul>
<p>For all of the above state access functions, the function
with one argument
(e.g. <tt>event_state(GlobalState)</tt>)
will read the state variable, while the function with two
arguments (e.g.: <tt>event_state(NewEventState,
GlobalState)</tt>) will modify it.</p>
<p>For each function, the description starts with the syntax
for specifying the function in the
<a href="xmerl_scan.html#type-option_list"><tt>Option_list</tt></a>.
The general forms are <tt>{Tag, Fun}</tt>, or
<tt>{Tag, Fun, LocalState}</tt>. The
second form can be used to initialize the state variable in
question.</p>
<h4 id="sect_1.1.1">1.1 User State</h4>
<p>All customization functions are free to access a
"User state" variable. Care must of course be taken
to coordinate the use of this state. It is recommended that
functions, which do not really have anything to contribute to
the "global" user state, use their own state
variable instead. Another option (used in
e.g. <tt>xmerl_eventp.erl</tt>) is for
customization functions to share one of the local states (in
<tt>xmerl_eventp.erl</tt>, the
continuation function and the fetch function both acces the
<tt>cont_state</tt>.)</p>
<p>Functions to access user state:</p>
<ul>
<li><tt>
xmerl_scan:user_state(GlobalState) </tt>
</li>
<li><tt>xmerl_scan:user_state(UserState,
GlobalState) </tt></li>
</ul>
<h4 id="sect_1.1.2">1.2 Event Function</h4>
<p><tt>{event_fun, fun()} | {event_fun, fun(),
EventState}</tt></p>
<p>The event function is called at the beginning and at the
end of a parsed entity. It has the following format and
semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
fun(Event, GlobalState) ->
EventState = xmerl_scan:event_state(GlobalState),
EventState2 = foo(Event, EventState),
GlobalState2 = xmerl_scan:event_state(EventState2, GlobalState)
end.
</code></pre></td></tr></table>
<h4 id="sect_1.1.3">1.3 Hook Function</h4>
<p> <tt>{hook_fun, fun()} | {hook_fun, fun(),
HookState}</tt></p>
<p>The hook function is called when the processor has parsed a complete
entity. Format and semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
fun(Entity, GlobalState) ->
HookState = xmerl_scan:hook_state(GlobalState),
{TransformedEntity, HookState2} = foo(Entity, HookState),
GlobalState2 = xmerl_scan:hook_state(HookState2, GlobalState),
{TransformedEntity, GlobalState2}
end.
</code></pre></td></tr></table>
<p>The relationship between the event function, the hook
function and the accumulator function is as follows:</p>
<ol>
<li>The event function is first called with an
'ended' event for the parsed entity.</li>
<li>The hook function is called, possibly
re-formatting the entity.</li>
<li>The acc function is called in order to
(optionally) add the re-formatted entity to the contents of
its parent element.</li>
</ol>
<h4 id="sect_1.1.4">1.4 Fetch Function</h4>
<p>
<tt>{fetch_fun, fun()} | {fetch_fun, fun(), FetchState}</tt>
</p>
<p>The fetch function is called in order to fetch an external resource
(e.g. a DTD).</p>
<p>The fetch function can respond with three different return values:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
Result ::=
{ok, {file, Filename}, NewGlobalState} |
{ok, {string, String}, NewGlobalState} |
{ok, not_fetched, NewGlobalState}
</code></pre></td></tr></table>
<p>Format and semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
fun(URI, GlobalState) ->
FetchState = xmerl_scan:fetch_state(GlobalState),
Result = foo(URI, FetchState). % Result being one of the above
end.
</code></pre></td></tr></table>
<h4 id="sect_1.1.5">1.5 Continuation Function</h4>
<p>
<tt>{continuation_fun, fun()} | {continuation_fun, fun(), ContinuationState}</tt>
</p>
<p>The continuation function is called when the parser encounters the end
of the byte stream. Format and semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
fun(Continue, Exception, GlobalState) ->
ContState = xmerl_scan:cont_state(GlobalState),
{Result, ContState2} = get_more_bytes(ContState),
case Result of
[] ->
GlobalState2 = xmerl_scan:cont_state(ContState2, GlobalState),
Exception(GlobalState2);
MoreBytes ->
{MoreBytes2, Rest} = end_on_whitespace_char(MoreBytes),
ContState3 = update_cont_state(Rest, ContState2),
GlobalState3 = xmerl_scan:cont_state(ContState3, GlobalState),
Continue(MoreBytes2, GlobalState3)
end
end.
</code></pre></td></tr></table>
<h4 id="sect_1.1.6">1.6 Rules Functions</h4>
<p>
<tt>
{rules, ReadFun : fun(), WriteFun : fun(), RulesState} |
{rules, Table : ets()}</tt>
</p>
<p>The rules functions take care of storing scanner
information in a rules database. User-provided rules functions
may opt to store the information in mnesia, or perhaps in the
user_state(RulesState).</p>
<p>The following modes exist:</p>
<ul>
<li>If the user doesn't specify an option, the
scanner creates an ets table, and uses built-in functions to
read and write data to it. When the scanner is done, the ets
table is deleted.</li>
<li>If the user specifies an ets table via the
<tt>{rules, Table}</tt> option, the
scanner uses this table. When the scanner is done, it does
<em>not</em> delete the table.</li>
<li>If the user specifies read and write
functions, the scanner will use them instead.</li>
</ul>
<p>The format for the read and write functions are as
follows:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
WriteFun(Context, Name, Definition, ScannerState) -> NewScannerState.
ReadFun(Context, Name, ScannerState) -> Definition | undefined.
</code></pre></td></tr></table>
<p>Here is a summary of the data objects currently being
written by the scanner:</p>
<table border="1" cellspacing="0" cellpadding="4" >
<colgroup cols="3">
<thead>
<tr>
<th>Context</th>
<th>Key Value</th>
<th>Definition</th>
</tr>
</thead>
<tbody>
<tr>
<td>notation</td>
<td>NotationName</td>
<td><tt>{system, SL} | {public, PIDL, SL}</tt></td>
</tr>
<tr>
<td>elem_def</td>
<td>ElementName</td>
<td><tt>#xmlElement{content = ContentSpec}</tt></td>
</tr>
<tr>
<td>parameter_entity</td>
<td>PEName</td>
<td><tt>PEDef</tt></td>
</tr>
<tr>
<td>entity</td>
<td>EntityName</td>
<td><tt>EntityDef</tt></td>
</tr>
</tbody>
</colgroup>
<caption>Table 1 - 1 Scanner data objects</caption>
</table>
<p>where</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
ContentSpec ::= empty | any | ElemContent
ElemContent ::= {Mode, Elems}
Mode ::= seq | choice
Elems ::= [Elem]
Elem ::= '#PCDATA' | Name | ElemContent | {Occurrence, Elems}
Occurrence ::= '*' | '?' | '+'
</code></pre></td></tr></table>
<table border="1" cellspacing="0" cellpadding="5" width="80%"
bgcolor="#CCCCCC">
</table>
<p>
NOTE: <i>When <Elem> is not wrapped with
<Occurrence>, (Occurrence = once) is implied.</i></p>
<h4 id="sect_1.1.7">1.7 Accumulator Function</h4>
<p><tt>{acc_fun, fun()}</tt></p>
<p>The accumulator function is called to accumulate the
contents of an entity.When parsing very large files, it may
not be desireable to do so.In this case, an acc function can
be provided that simply doesn't accumulate.</p>
<p>Note that it is possible to even modify the parsed
entity before accumulating it, but this must be done with
care. <tt>xmerl_scan</tt> performs
post-processing of the element for namespace management. Thus,
the element must keep its original structure for this to
work.</p>
<p>The acc function has the following format and
semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
%% default accumulating acc fun
fun(ParsedEntity, Acc, GlobalState) ->
{[ParsedEntity|Acc], GlobalState}.
%% non-accumulating acc fun
fun(ParsedEntity, Acc, GlobalState) ->
{Acc, GlobalState}.
</code></pre></td></tr></table>
<h4 id="sect_1.1.8">1.8 Close Function</h4>
<p>The close function is called when a document (either the
main document or an external DTD) has been completely
parsed. When xmerl_scan was started using
<tt>xmerl_scan:file/[1,2]</tt>, the
file will be read in full, and closed immediately, before the
parsing starts, so when the close function is called, it will
not need to actually close the file. In this case, the close
function will be a good place to modify the state
variables.</p>
<p>Format and semantics:</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
fun(GlobalState) ->
GlobalState1 = .... % state variables may be altered
</code></pre></td></tr></table>
<h3 id="sect_2.1">2 Examples</h3>
<p>
See <code>xmerl_test.erl</code> for more examples.
</p>
<h4 id="sect_2.1.1">2.1 Handling spaces</h3>
<p>
The following sample program illustrates three ways of
scanning a document:
<ol>
<li> the default scan, which leaves whitespace untouched
<li> normalizing spaces
<li> normalizing spaces, then removing text elements that only
contain one space.
</ol>
</p>
<table border="1" cellspacing="0" cellpadding="5" width="100%"
bgcolor="#CCCCCC"><tr><td><pre><code>
-module(tmp).
-include("xmerl.hrl").
-export([file1/1,
file2/1,
file3/1]).
file1(F) ->
xmerl_scan:file(F).
file2(F) ->
xmerl_scan:file(F, [{space,normalize}]).
file3(F) ->
Acc = fun(#xmlText{value = " ", pos = P}, Acc, S) ->
{Acc, P, S}; % new return format
(X, Acc, S) ->
{[X|Acc], S}
end,
xmerl_scan:file(F, [{space,normalize}, {acc_fun, Acc}]).
</code></pre></td></tr></table>
</body>
</html>
|
