The XML processor offers a number of hooks for
+ customization. These hooks are defined as function objects, and
+ can be provided by the caller.
+
+
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:
+
+
+
+
event function (
+ xmerl_scan:event_state/[1,2]
+ )
+
+
hook function (
+ xmerl_scan:hook_state/[1,2]
+ )
+
+
fetch function (
+ xmerl_scan:fetch_state/[1,2] )
+
+
+
continuation function (
+ xmerl_scan:cont_state/[1,2] )
+
+
+
rules function (
+ xmerl_scan:rules_state/[1,2] )
+
+
+
accumulator function
+
+
close function
+
+
+
+
For all of the above state access functions, the function
+ with one argument
+ (e.g. event_state(GlobalState))
+ will read the state variable, while the function with two
+ arguments (e.g.: event_state(NewEventState,
+ GlobalState)) will modify it.
+
+
For each function, the description starts with the syntax
+ for specifying the function in the
+ Option_list.
+ The general forms are {Tag, Fun}, or
+ {Tag, Fun, LocalState}. The
+ second form can be used to initialize the state variable in
+ question.
+
+
+
1.1 User State
+
+
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. xmerl_eventp.erl) is for
+ customization functions to share one of the local states (in
+ xmerl_eventp.erl, the
+ continuation function and the fetch function both acces the
+ cont_state.)
+
+ fun(URI, GlobalState) ->
+ FetchState = xmerl_scan:fetch_state(GlobalState),
+ Result = foo(URI, FetchState). % Result being one of the above
+ end.
+
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).
+
+
The following modes exist:
+
+
+
+
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.
+
+
If the user specifies an ets table via the
+ {rules, Table} option, the
+ scanner uses this table. When the scanner is done, it does
+ not delete the table.
+
+
If the user specifies read and write
+ functions, the scanner will use them instead.
+
+
+
+
The format for the read and write functions are as
+ follows:
+ NOTE: When <Elem> is not wrapped with
+ <Occurrence>, (Occurrence = once) is implied.
+
+
+
+
1.7 Accumulator Function
+
{acc_fun, fun()}
+
+
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.
+
+
Note that it is possible to even modify the parsed
+ entity before accumulating it, but this must be done with
+ care. xmerl_scan performs
+ post-processing of the element for namespace management. Thus,
+ the element must keep its original structure for this to
+ work.
+
+
The acc function has the following format and
+ semantics:
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
+ xmerl_scan:file/[1,2], 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.
+
+
Format and semantics:
+
+
+
+ fun(GlobalState) ->
+ GlobalState1 = .... % state variables may be altered
+
+
+
+
2 Examples
+
+See xmerl_test.erl for more examples.
+
+
+
2.1 Handling spaces
+
+The following sample program illustrates three ways of
+scanning a document:
+
+
the default scan, which leaves whitespace untouched
+
normalizing spaces
+
normalizing spaces, then removing text elements that only
+ contain one space.
+