---
name: "xmerl_scan"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/xmerl_scan"
---

# xmerl\_scan(3erl)

This module is the interface to the XML parser, it handles XML 1.0.

## NAME

xmerl\_scan - This module is the interface to the XML parser, it handles XML 1.0.

## DESCRIPTION

This module is the interface to the XML parser, it handles XML 1.0. The XML parser is activated through *xmerl\_scan:string/\[1,2\]* or *xmerl\_scan:file/\[1,2\]*. It returns records of the type defined in xmerl.hrl. See also tutorial on customization functions.

## DATA TYPES

- **document() = xmlElement() \| xmlDocument():**

  The document returned by *xmerl\_scan:string/\[1,2\]* and *xmerl\_scan:file/\[1,2\]*. The type of the returned record depends on the value of the document option passed to the function.

- **global\_state():**

  The global state of the scanner, represented by the #xmerl\_scanner{} record.

- **option\_list():**

  Options allow to customize the behaviour of the scanner. See also tutorial on customization functions.

  Possible options are:

  - ***{acc\_fun, Fun}*:**

    Call back function to accumulate contents of entity.

  - ***{continuation\_fun, Fun} \| {continuation\_fun, Fun, ContinuationState}*:**

    Call back function to decide what to do if the scanner runs into EOF before the document is complete.

  - ***{event\_fun, Fun} \| {event\_fun, Fun, EventState}*:**

    Call back function to handle scanner events.

  - ***{fetch\_fun, Fun} \| {fetch\_fun, Fun, FetchState}*:**

    Call back function to fetch an external resource.

  - ***{hook\_fun, Fun} \| {hook\_fun, Fun, HookState}*:**

    Call back function to process the document entities once identified.

  - ***{close\_fun, Fun}*:**

    Called when document has been completely parsed.

  - ***{rules, ReadFun, WriteFun, RulesState} \| {rules, Rules}*:**

    Handles storing of scanner information when parsing.

  - ***{user\_state, UserState}*:**

    Global state variable accessible from all customization functions

  - ***{fetch\_path, PathList}*:**

    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.

  - ***{space, Flag}*:**

    'preserve' (default) to preserve spaces, 'normalize' to accumulate consecutive whitespace and replace it with one space.

  - ***{line, Line}*:**

    To specify starting line for scanning in document which contains fragments of XML.

  - ***{namespace\_conformant, Flag}*:**

    Controls whether to behave as a namespace conformant XML parser, 'false' (default) to not otherwise 'true'.

  - ***{validation, Flag}*:**

    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'.

  - ***{schemaLocation, \[{Namespace,Link}\|...\]}*:**

    Tells explicitly which XML Schema documents to use to validate the XML document. Used together with the *{validation,schema}* option.

  - ***{quiet, Flag}*:**

    Set to 'true' if xmerl should behave quietly and not output any information to standard output (default 'false').

  - ***{doctype\_DTD, DTD}*:**

    Allows to specify DTD name when it isn't available in the XML document. This option has effect only together with *{validation,'dtd'* option.

  - ***{xmlbase, Dir}*:**

    XML Base directory. If using string/1 default is current directory. If using file/1 default is directory of given file.

  - ***{encoding, Enc}*:**

    Set default character set used (default UTF-8). This character set is used only if not explicitly given by the XML declaration.

  - ***{document, Flag}*:**

    Set to 'true' if xmerl should return a complete XML document as an xmlDocument record (default 'false').

  - ***{comments, Flag}*:**

    Set to 'false' if xmerl should skip comments otherwise they will be returned as xmlComment records (default 'true').

  - ***{default\_attrs, Flag}*:**

    Set to 'true' if xmerl should add to elements missing attributes with a defined default value (default 'false').

- **xmlDocument() = #xmlDocument{}:**

  The record definition is found in xmerl.hrl.

- **xmlElement() = #xmlElement{}:**

  ## EXPORTS

**accumulate\_whitespace(T::string(), S::global\_state(), X3::atom(), Acc::string()) -\> {Acc, T1, S1}**\

Function to accumulate and normalize whitespace.

**cont\_state(S::global\_state()) -\> global\_state()**\

Equivalent to cont\_state(ContinuationState, S).

**cont\_state(X::ContinuationState, S::global\_state()) -\> global\_state()**\

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.

**event\_state(S::global\_state()) -\> global\_state()**\

Equivalent to event\_state(EventState, S).

**event\_state(X::EventState, S::global\_state()) -\> global\_state()**\

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.

**fetch\_state(S::global\_state()) -\> global\_state()**\

Equivalent to fetch\_state(FetchState, S).

**fetch\_state(X::FetchState, S::global\_state()) -\> global\_state()**\

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.

**file(Filename::string()) -\> {xmlElement(), Rest}**\

Types:

Rest = list()\

Equivalent to file(Filename, \[\]).

**file(Filename::string(), Options::option\_list()) -\> {document(), Rest}**\

Types:

Rest = list()\

Parse file containing an XML document

**hook\_state(S::global\_state()) -\> global\_state()**\

Equivalent to hook\_state(HookState, S).

**hook\_state(X::HookState, S::global\_state()) -\> global\_state()**\

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.

**rules\_state(S::global\_state()) -\> global\_state()**\

Equivalent to rules\_state(RulesState, S).

**rules\_state(X::RulesState, S::global\_state()) -\> global\_state()**\

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.

**string(Text::list()) -\> {xmlElement(), Rest}**\

Types:

Rest = list()\

Equivalent to string(Text, \[\]).

**string(Text::list(), Options::option\_list()) -\> {document(), Rest}**\

Types:

Rest = list()\

Parse string containing an XML document

**user\_state(S::global\_state()) -\> global\_state()**\

Equivalent to user\_state(UserState, S).

**user\_state(X::UserState, S::global\_state()) -\> global\_state()**\

For controlling the UserState, to be used in a user function. See tutorial on customization functions.

## AUTHORS

*\<\>*