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:
xmerl_scan:event_state/[1,2]
)
xmerl_scan:hook_state/[1,2]
)
xmerl_scan:fetch_state/[1,2]
)
xmerl_scan:cont_state/[1,2]
)
xmerl_scan:rules_state/[1,2]
)
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.
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 access the
cont_state
.)
Functions to access user state:
xmerl_scan:user_state(GlobalState)
xmerl_scan:user_state(UserState,
GlobalState)
{event_fun, fun()} | {event_fun, fun(),
EventState}
The event function is called at the beginning and at the end of a parsed entity. It has the following format and semantics:
|
{hook_fun, fun()} | {hook_fun, fun(),
HookState}
The hook function is called when the processor has parsed a complete entity. Format and semantics:
|
The relationship between the event function, the hook function and the accumulator function is as follows:
{fetch_fun, fun()} | {fetch_fun, fun(), FetchState}
The fetch function is called in order to fetch an external resource (e.g. a DTD).
The fetch function can respond with three different return values:
|
Format and semantics:
|
{continuation_fun, fun()} | {continuation_fun, fun(), ContinuationState}
The continuation function is called when the parser encounters the end of the byte stream. Format and semantics:
|
{rules, ReadFun : fun(), WriteFun : fun(), RulesState} |
{rules, Table : ets()}
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:
{rules, Table}
option, the
scanner uses this table. When the scanner is done, it does
not delete the table.The format for the read and write functions are as follows:
|
Here is a summary of the data objects currently being written by the scanner:
Context | Key Value | Definition |
---|---|---|
notation | NotationName | {system, SL} | {public, PIDL, SL} |
elem_def | ElementName | #xmlElement{content = ContentSpec} |
parameter_entity | PEName | PEDef |
entity | EntityName | EntityDef |
where
|
NOTE: When <Elem> is not wrapped with <Occurrence>, (Occurrence = once) is implied.
{acc_fun, fun()}
The accumulator function is called to accumulate the contents of an entity.When parsing very large files, it may not be desirable 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:
|
See xmerl_test.erl
for more examples.
The following sample program illustrates three ways of scanning a document:
|