.TH xmerl_scan 3 "xmerl  1.1.9" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
xmerl_scan \- This module is the interface to the XML parser, it handles XML 1\&.0\&.
.SH DESCRIPTION
.LP
This module is the interface to the XML parser, it handles XML 1\&.0\&. The XML parser is activated through \fIxmerl_scan:string/[1, 2]\fR or \fIxmerl_scan:file/[1, 2]\fR\&. It returns records of the type defined in xmerl\&.hrl\&. See also tutorial <xmerl_examples\&.html> on customization functions\&.

.SH DATA TYPES
.RS 2
.TP 4
.B
\fIglobal_state()\fR:

.RS 4
.LP
The global state of the scanner, represented by the #xmerl_scanner{} record\&. 
.LP

.RE
.TP 4
.B
\fIoption_list()\fR:

.RS 4
.LP
Options allow to customize the behaviour of the scanner\&. See also tutorial <xmerl_examples\&.html> on customization functions\&. 
.LP
Possible options are: 
.RS 2
.TP 4
.B
\fI{acc_fun, Fun}\fR:
Call back function to accumulate contents of entity\&.
.TP 4
.B
\fI{continuation_fun, Fun} | {continuation_fun, Fun, ContinuationState}\fR:
Call back function to decide what to do if the scanner runs into EOF before the document is complete\&.
.TP 4
.B
\fI{event_fun, Fun} | {event_fun, Fun, EventState}\fR:
Call back function to handle scanner events\&.
.TP 4
.B
\fI{fetch_fun, Fun} | {fetch_fun, Fun, FetchState}\fR:
Call back function to fetch an external resource\&.
.TP 4
.B
\fI{hook_fun, Fun} | {hook_fun, Fun, HookState}\fR:
Call back function to process the document entities once identified\&.
.TP 4
.B
\fI{close_fun, Fun}\fR:
Called when document has been completely parsed\&.
.TP 4
.B
\fI{rules, ReadFun, WriteFun, RulesState} | {rules, Rules}\fR:
Handles storing of scanner information when parsing\&.
.TP 4
.B
\fI{user_state, UserState}\fR:
Global state variable accessible from all customization functions
.TP 4
.B
\fI{fetch_path, PathList}\fR:
PathList is a list of directories to search when fetching files\&. If the file in question is not in the fetch_path, the URI will be used as a file name\&.
.TP 4
.B
\fI{space, Flag}\fR:
\&'preserve\&' (default) to preserve spaces, \&'normalize\&' to accumulate consecutive whitespace and replace it with one space\&.
.TP 4
.B
\fI{line, Line}\fR:
To specify starting line for scanning in document which contains fragments of XML\&.
.TP 4
.B
\fI{namespace_conformant, Flag}\fR:
Controls whether to behave as a namespace conformant XML parser, \&'false\&' (default) to not otherwise \&'true\&'\&.
.TP 4
.B
\fI{validation, Flag}\fR:
Controls whether to process as a validating XML parser: \&'off\&' (default) no validation, or validation \&'dtd\&' by DTD or \&'schema\&' by XML Schema\&. \&'false\&' and \&'true\&' options are obsolete (i\&.e\&. they may be removed in a future release), if used \&'false\&' equals \&'off\&' and \&'true\&' equals \&'dtd\&'\&.
.TP 4
.B
\fI{schemaLocation, [{Namespace, Link}|\&.\&.\&.]}\fR:
Tells explicitly which XML Schema documents to use to validate the XML document\&. Used together with the \fI{validation, schema}\fR option\&.
.TP 4
.B
\fI{quiet, Flag}\fR:
Set to \&'true\&' if xmerl should behave quietly and not output any information to standard output (default \&'false\&')\&.
.TP 4
.B
\fI{doctype_DTD, DTD}\fR:
Allows to specify DTD name when it isn\&'t available in the XML document\&. This option has effect only together with \fI{validation, \&'dtd\&'\fR option\&.
.TP 4
.B
\fI{xmlbase, Dir}\fR:
XML Base directory\&. If using string/1 default is current directory\&. If using file/1 default is directory of given file\&.
.TP 4
.B
\fI{encoding, Enc}\fR:
Set default character set used (default UTF-8)\&. This character set is used only if not explicitly given by the XML declaration\&. 
.RE
.LP

.RE
.RE
.SH EXPORTS
.LP
.B
accumulate_whitespace(T::string(), S::global_state(), X3::atom(), Acc::string()) -> {Acc, T1, S1}
.br
.RS
.LP
Function to accumulate and normalize whitespace\&.
.RE
.LP
.B
cont_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to cont_state(ContinuationState, S)\&.
.RE
.LP
.B
cont_state(X::ContinuationState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the ContinuationState, to be used in a continuation function, and called when the parser encounters the end of the byte stream\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE
.LP
.B
event_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to event_state(EventState, S)\&.
.RE
.LP
.B
event_state(X::EventState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the EventState, to be used in an event function, and called at the beginning and at the end of a parsed entity\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE
.LP
.B
fetch_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to fetch_state(FetchState, S)\&.
.RE
.LP
.B
fetch_state(X::FetchState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the FetchState, to be used in a fetch function, and called when the parser fetch an external resource (eg\&. a DTD)\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE
.LP
.B
file(Filename::string()) -> {xmlElement(), Rest}
.br
.RS
.TP
Types
Rest = list()
.br
.RE
.RS
.LP
Equivalent to file(Filename, [])\&.
.RE
.LP
.B
file(Filename::string(), Options::option_list()) -> {xmlElement(), Rest}
.br
.RS
.TP
Types
Rest = list()
.br
.RE
.RS
.LP
Parse file containing an XML document
.RE
.LP
.B
hook_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to hook_state(HookState, S)\&.
.RE
.LP
.B
hook_state(X::HookState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the HookState, to be used in a hook function, and called when the parser has parsed a complete entity\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE
.LP
.B
rules_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to rules_state(RulesState, S)\&.
.RE
.LP
.B
rules_state(X::RulesState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the RulesState, to be used in a rules function, and called when the parser store scanner information in a rules database\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE
.LP
.B
string(Text::list()) -> {xmlElement(), Rest}
.br
.RS
.TP
Types
Rest = list()
.br
.RE
.RS
.LP
Equivalent to string(Test, [])\&.
.RE
.LP
.B
string(Text::list(), Options::option_list()) -> {xmlElement(), Rest}
.br
.RS
.TP
Types
Rest = list()
.br
.RE
.RS
.LP
Parse string containing an XML document
.RE
.LP
.B
user_state(S::global_state()) -> global_state()
.br
.RS
.LP
Equivalent to user_state(UserState, S)\&.
.RE
.LP
.B
user_state(X::UserState, S::global_state()) -> global_state()
.br
.RS
.LP
For controlling the UserState, to be used in a user function\&. See tutorial <xmerl_examples\&.html> on customization functions\&.
.RE