.TH xmerl_scan 3erl "xmerl 1.3.12" "" "Erlang Module Definition"
.SH NAME
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 on customization functions\&.
.SH "DATA TYPES"

.RS 2
.TP 2
.B
document() = \fBxmlElement()\fR\& | \fBxmlDocument()\fR\&:

.RS 2
.LP
The document returned by \fIxmerl_scan:string/[1,2]\fR\& and \fIxmerl_scan:file/[1,2]\fR\&\&. The type of the returned record depends on the value of the document option passed to the function\&.
.RE

.TP 2
.B
global_state():

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

.TP 2
.B
option_list():

.RS 2
.LP
Options allow to customize the behaviour of the scanner\&. See also tutorial on customization functions\&.
.RE

.RS 2
.LP
Possible options are:
.RE

.RS 2
.TP 2
.B
\fI{acc_fun, Fun}\fR\&:
Call back function to accumulate contents of entity\&.
.TP 2
.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 2
.B
\fI{event_fun, Fun} | {event_fun, Fun, EventState}\fR\&:
Call back function to handle scanner events\&.
.TP 2
.B
\fI{fetch_fun, Fun} | {fetch_fun, Fun, FetchState}\fR\&:
Call back function to fetch an external resource\&.
.TP 2
.B
\fI{hook_fun, Fun} | {hook_fun, Fun, HookState}\fR\&:
Call back function to process the document entities once identified\&.
.TP 2
.B
\fI{close_fun, Fun}\fR\&:
Called when document has been completely parsed\&.
.TP 2
.B
\fI{rules, ReadFun, WriteFun, RulesState} | {rules, Rules}\fR\&:
Handles storing of scanner information when parsing\&.
.TP 2
.B
\fI{user_state, UserState}\fR\&:
Global state variable accessible from all customization functions
.TP 2
.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 2
.B
\fI{space, Flag}\fR\&:
\&'preserve\&' (default) to preserve spaces, \&'normalize\&' to accumulate consecutive whitespace and replace it with one space\&.
.TP 2
.B
\fI{line, Line}\fR\&:
To specify starting line for scanning in document which contains fragments of XML\&.
.TP 2
.B
\fI{namespace_conformant, Flag}\fR\&:
Controls whether to behave as a namespace conformant XML parser, \&'false\&' (default) to not otherwise \&'true\&'\&.
.TP 2
.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 2
.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 2
.B
\fI{quiet, Flag}\fR\&:
Set to \&'true\&' if xmerl should behave quietly and not output any information to standard output (default \&'false\&')\&.
.TP 2
.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 2
.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 2
.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\&.
.TP 2
.B
\fI{document, Flag}\fR\&:
Set to \&'true\&' if xmerl should return a complete XML document as an xmlDocument record (default \&'false\&')\&.
.TP 2
.B
\fI{comments, Flag}\fR\&:
Set to \&'false\&' if xmerl should skip comments otherwise they will be returned as xmlComment records (default \&'true\&')\&.
.TP 2
.B
\fI{default_attrs, Flag}\fR\&:
Set to \&'true\&' if xmerl should add to elements missing attributes with a defined default value (default \&'false\&')\&.
.RE
.TP 2
.B
xmlDocument() = #xmlDocument{}:

.RS 2
.LP
The record definition is found in xmerl\&.hrl\&.
.RE

.TP 2
.B
xmlElement() = #xmlElement{}:

.RS 2
.LP
The record definition is found in xmerl\&.hrl\&.
.RE

.RE
.SH EXPORTS
.LP
.B
accumulate_whitespace(T::string(), S::\fBglobal_state()\fR\&, X3::atom(), Acc::string()) -> {Acc, T1, S1}
.br
.RS
.LP
Function to accumulate and normalize whitespace\&.
.RE

.LP
.B
cont_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBcont_state(ContinuationState, S)\fR\&\&.
.RE

.LP
.B
cont_state(X::ContinuationState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.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 on customization functions\&.
.RE

.LP
.B
event_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBevent_state(EventState, S)\fR\&\&.
.RE

.LP
.B
event_state(X::EventState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.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 on customization functions\&.
.RE

.LP
.B
fetch_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBfetch_state(FetchState, S)\fR\&\&.
.RE

.LP
.B
fetch_state(X::FetchState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.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 on customization functions\&.
.RE

.LP
.B
file(Filename::string()) -> {\fBxmlElement()\fR\&, Rest}
.br
.RS
.LP
Types:

.RS 3
Rest = list()
.br
.RE
.RE
.RS
.LP
Equivalent to \fBfile(Filename, [])\fR\&\&.
.RE

.LP
.B
file(Filename::string(), Options::\fBoption_list()\fR\&) -> {\fBdocument()\fR\&, Rest}
.br
.RS
.LP
Types:

.RS 3
Rest = list()
.br
.RE
.RE
.RS
.LP
Parse file containing an XML document
.RE

.LP
.B
hook_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBhook_state(HookState, S)\fR\&\&.
.RE

.LP
.B
hook_state(X::HookState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.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 on customization functions\&.
.RE

.LP
.B
rules_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBrules_state(RulesState, S)\fR\&\&.
.RE

.LP
.B
rules_state(X::RulesState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.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 on customization functions\&.
.RE

.LP
.B
string(Text::list()) -> {\fBxmlElement()\fR\&, Rest}
.br
.RS
.LP
Types:

.RS 3
Rest = list()
.br
.RE
.RE
.RS
.LP
Equivalent to \fBstring(Test, [])\fR\&\&.
.RE

.LP
.B
string(Text::list(), Options::\fBoption_list()\fR\&) -> {\fBdocument()\fR\&, Rest}
.br
.RS
.LP
Types:

.RS 3
Rest = list()
.br
.RE
.RE
.RS
.LP
Parse string containing an XML document
.RE

.LP
.B
user_state(S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
Equivalent to \fBuser_state(UserState, S)\fR\&\&.
.RE

.LP
.B
user_state(X::UserState, S::\fBglobal_state()\fR\&) -> \fBglobal_state()\fR\&
.br
.RS
.LP
For controlling the UserState, to be used in a user function\&. See tutorial on customization functions\&.
.RE

.SH AUTHORS
.LP

.I
<>