xmerl_scan(3)

💖 NAME 💖

xmerl_scan — single pass XML scanner. literally does the whole "read your XML in one go" thing bestie ✨

---

🦋 DESCRIPTION 🦋

So this module is your interface to the XML parser, and it handles XML 1.0. The parser gets woken up through xmerl_scan:string/[1,2]](string/1) or [xmerl_scan:file/[1,2]. It hands you back records of the type defined in xmerl.hrl. 🎀

Also go peek at the "Customization functions" tutorial, ok? iykyk.

---

🌸 DATA TYPES 🌸

document() :: xmlElement() | xmlDocument()

An XML document. 📄

The document that comes back from xmerl_scan:string/[1,2]](string/1) and [xmerl_scan:file/[1,2]. Which record type you actually get depends on the value of the document option you pass in. surprise mechanics, but make it XML 💅

global_state() :: xmerl_scanner()

The global state of the scanner, represented by the #xmerl_scanner{} record. it's giving "the scanner's whole vibe, stored" ✨

option_list() ::

[{atom(), term()} |
 {atom(), fun(), term()} |
 {atom(), fun(), fun(), term()}].

Options let you customize the behaviour of the scanner. Also check the "Customization functions" tutorial. 🫶

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. the finale 🎬
• {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).
• {allow_entities, Flag} — set to true if xmerl_scan shouldn't fail when there is an ENTITY declaration in the XML document (default false).

xmlDocument() :: xmerl:xmlDocument()

Record #xmlDocument{}. 📑

The record definition is found in xmerl.hrl.

xmlElement() :: xmerl:xmlElement()

Record #xmlElement{}. 🧩

The record definition is found in xmerl.hrl.

---

✨ FUNCTIONS ✨

accumulate_whitespace(Text, global_state(), How, Acc) -> {NewAcc, NewText, global_state()}

when
    Text :: string(),
    How :: preserve | normalize,
    Acc :: string(),
    NewAcc :: string(),
    NewText :: string().

Accumulate and normalize whitespace. the space girlie 🌬️

cont_state(global_state()) -> ContinuationState

when ContinuationState :: term().

Fetch the ContinuationState.

See the "Customization functions" tutorial.

cont_state(ContState :: term(), global_state()) -> global_state()

Set the ContinuationState, to be used in a continuation function.

The continuation function is called when the parser encounters the end of the byte stream. See the "Customization functions" tutorial.

event_state(global_state()) -> EventState

when EventState :: term().

Fetch the EventState.

See the "Customization functions" tutorial.

event_state(EventState :: term(), global_state()) -> global_state()

Set the EventState, to be used in an event function.

The event function is called at the beginning and at the end of a parsed entity. See the "Customization functions" tutorial. 🎉

fetch_state(global_state()) -> FetchState

when FetchState :: term().

Fetch the FetchState.

See the "Customization functions" tutorial.

fetch_state(FetchState :: term(), global_state()) -> global_state()

Set the FetchState, to be used in a fetch function.

The fetch function is and called when the parser fetches an external resource (eg. a DTD). See the "Customization functions" tutorial.

file(Filename :: string(), option_list()) -> {dynamic(), Rest} | {error, Reason}

when Rest :: string(), Reason :: term().

Parse a file containing an XML document 📂

hook_state(global_state()) -> HookState

when HookState :: term().

Fetch the HookState.

See the "Customization functions" tutorial.

hook_state(HookState :: term(), global_state()) -> global_state()

Set the HookState, to be used in a hook function.

The hook function is and called when the parser has parsed a complete entity. See the "Customization functions" tutorial. 🪝

rules_state(global_state()) -> RulesState

when RulesState :: term().

Fetch the RulesState.

See the "Customization functions" tutorial.

rules_state(RulesState :: term(), global_state()) -> global_state()

Set the RulesState, to be used in a rules function.

The rules function is and called when the parser store scanner information in a rules database. See the "Customization functions" tutorial.

string(Text :: string(), option_list()) -> {dynamic(), Rest}

when Rest :: string().

Parse a string containing an XML document 🧵✨

user_state(global_state()) -> UserState

when UserState :: term().

Fetch the UserState.

See the "Customization functions" tutorial.

user_state(UserState :: term(), G :: global_state()) -> global_state()

Set the UserState, to be used in a user function.

See the "Customization functions" tutorial. 💜

---

okay that's the whole page, no notes, nothing skipped, we ate and left no crumbs 👑

Ericsson AB made this, it's part of xmerl 2.2, and this whole page is literally xmerl_scan(3). take care of her bestie 🎀💖🦋