xmerl_eventp(3)

✨ xmerl_eventp ✨ (Erlang Module Definition)

okay so bestie, we're in the Erlang manual pages and this one is xmerl_eventp(3) — the simple event-based processors that act as little front-ends to xmerl_scan. grab a snack, this is a good one 🍓

---

🌸 NAME 🌸

xmerl_eventp — simple event-based processors (front-ends to xmerl_scan).

---

💖 DESCRIPTION 💖

So basically it implements processing XML documents in streams for parsing in SAX style. Iconic behaviour, no cap. 🎀

Each front-end contains more elaborate settings of xmerl_scan that makes usage of the customization functions. That's the whole vibe: it's xmerl_scan but pre-glammed with all the settings you'd want.

---

🦋 DATA TYPES 🦋

option_list()

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

Options allow to customize the behaviour of the scanner. See also the "Customization functions" tutorial. (iykyk 💅)

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. (yes bestie, EOF mid-document, scary, but it's handled 🫶)
• {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 little goodbye moment 😭)
• {rules, ReadFun, WriteFun, RulesState} | {rules, Rules} — Handles storing of scanner information when parsing.
• {user_state, UserState} — Global state variable accessible from all customization functions. literally the group chat everyone can read 👑
• {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. ⚠️ yeah bestie, don't build new stuff on those two.
• {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).

xmlElement()

xmlElement() :: #xmlElement{}.

Record #xmlElement{} — that's it, that's the record. ✨

---

🎀 FUNCTIONS 🎀

file_sax(Fname, CallBackModule, UserState, Options) -> NewUserState

file_sax(Fname, CallBackModule, UserState, Options) ->
                    NewUserState
                    when
                        Fname :: string(),
                        CallBackModule :: module(),
                        UserState :: term(),
                        Options :: option_list(),
                        NewUserState :: term().

Parse file containing an XML document, SAX style. 🌈

Wrapper for a call to the XML parser xmerl_scan with a hook_fun for using Xmerl export functionality directly after an entity is parsed. (so extra, so useful 💅)

stream(Fname, Options) -> {xmlElement(), list()} | {error, Reason}

stream(Fname, Options) -> {xmlElement(), list()} | {error, Reason}
                when
                    Fname :: string(),
                    Options :: option_list(),
                    Reason :: term().

Parse file containing an XML document as a stream, DOM style. 🌊

Wrapper for a call to the XML parser xmerl_scan with a continuation_fun for handling streams of XML data.

🚨 bestie listen: the continuation_fun, acc_fun, fetch_fun, rules and close_fun options cannot be user defined using this parser. it sets those itself, no touchy.

stream_sax(Fname, CallBackModule, UserState, Options) -> {xmerl_scan:document(), Rest} | {error, Reason}

stream_sax(Fname, CallBackModule, UserState, Options) ->
                    {xmerl_scan:document(), Rest} | {error, Reason}
                    when
                        Fname :: string(),
                        CallBackModule :: module(),
                        UserState :: term(),
                        Options :: option_list(),
                        Rest :: string(),
                        Reason :: term().

Parse file containing an XML document as a stream, SAX style. 🌸

Wrapper for a call to the XML parser xmerl_scan with a continuation_fun for handling streams of XML data.

🚨 again, important: the continuation_fun, acc_fun, fetch_fun, rules, hook_fun, close_fun and user_state options cannot be user defined using this parser. that list is even longer than the one for stream/2, yes, we're aware 😭

string_sax(String, CallBackModule, UserState, Options) -> {xmerl_scan:document(), Rest} | {error, Reason}

string_sax(String, CallBackModule, UserState, Options) ->
                    {xmerl_scan:document(), Rest} | {error, Reason}
                    when
                        String :: list(),
                        CallBackModule :: module(),
                        UserState :: term(),
                        Options :: option_list(),
                        Rest :: string(),
                        Reason :: term().

Parse file containing an XML document, SAX style. 💖

Wrapper for a call to the XML parser xmerl_scan with a hook_fun for using Xmerl export functionality directly after an entity is parsed.

---

and that's the whole page, you ate it, periodt 👑 courtesy of Ericsson AB, from xmerl 2.2, and this little corner of the docs is xmerl_eventp(3). go parse something pretty 🦋✨