xmerl(3)

✨ xmerl — the Erlang Module Definition, bestie edition ✨

okay so real talk: this is xmerl(3), the Erlang module definition for xmerl. That's the manual name, that's the vibe, and yes we are absolutely getting into it. 🎀

🌸 NAME 🌸

xmerl — Functions for exporting XML data to an external format. That's it, that's the whole job description, and she does it beautifully. 💅

🦋 DESCRIPTION 🦋

(ngl bestie, the original leaves this one kind of empty, so we're just gonna wave at it and move on to the good stuff) ✨

💖 DATA TYPES 💖

• callback() :: module() | [module()].

A callback module, or a whole list of inherited callback modules. Yeah, she can have ancestors. It's giving family tree energy. 🌳

• element() :: xmlText() | xmlElement() | xmlPI() | xmlComment() | xmlDecl().

A normal, well-formed, no-notes XML content element. The whole squad. 👑

• simple_attribute() ::

xmlAttribute() |
{fun((_) -> _), term()} |
{Key :: atom(), Value :: term()}.

The "simple-form" XML attribute. chill mode activated 🧘

• simple_element() ::

{Tag :: atom(),
 Attributes ::
     [{Name :: atom(), Value :: iolist() | atom() |
integer()}],
 Content :: [simple_element()]} |
{Tag :: atom(), Content :: [simple_element()]} |
(Tag :: atom() | (IOString :: iolist() | element())).

The "simple-form" XML content element. Literally the low-effort-but-still-iconic version. 🍓

• xmlAttribute() :: #xmlAttribute{}.

That's record #xmlAttribute{}, periodt.

• xmlComment() :: #xmlComment{}.

Record #xmlComment{}. 🫶

• xmlDecl() :: #xmlDecl{}.

Record #xmlDecl{}. ✨

• xmlDocument() :: #xmlDocument{}.

Record #xmlDocument{}. 📄

• xmlElement() :: #xmlElement{}.

Record #xmlElement{}. 🔥

• xmlNamespace() :: #xmlNamespace{}.

Record #xmlNamespace{}. 🌈

• xmlNsNode() :: #xmlNsNode{}.

Record #xmlNsNode{}. 💜

• xmlPI() :: #xmlPI{}.

Record #xmlPI{}. 🎀

• xmlText() :: #xmlText{}.

Record #xmlText{}. 💖

---

🔥 FUNCTIONS 🔥

callbacks(Module :: module()) -> [module()].

Find the list of inherited callback modules for a given module. Basically "who's in your bloodline, bestie?" 🌳

export(Content, Callback, RootAttributes) -> ExportedFormat :: term()

with

Content :: [Element],
Element :: element(),
Callback :: callback(),
RootAttributes :: [simple_attribute()].

Export XML content. 🚀

Exports normal, well-formed XML content, using the callback module you specified.

Element is any of:

• #xmlText{}
• #xmlElement{}
• #xmlPI{}
• #xmlComment{}
• #xmlDecl{}

(Go look in xmerl.hrl for the record definitions, bestie, they're all in there.) Text inside #xmlText{} elements can be deep lists of characters and/or binaries. yes, deep, she contains multitudes. 💅

RootAttributes is a list of #xmlAttribute{} attributes for the #root# element, which implicitly becomes the parent of the Content you handed over. So the tag-handler function for #root# gets called with the complete exported data of Content. Root attributes are the move when you wanna specify encoding or other metadata of an XML or HTML document. 📝

The Callback module should contain hook functions for all tags present in the data structure. Every hook function must have this exact format:

Tag(Data, Attributes, Parents, E)

where E is the corresponding #xmlElement{}, Data is the already-exported contents of E, and Attributes is the list of #xmlAttribute{} records of E. And finally, Parents is the list of parent nodes of E, on the form [{ParentTag::atom(), ParentPosition::integer()}].

not me stressing about format — yes, that exact shape, don't freestyle it 😭

The hook function should return either the data to be exported, or a tuple {'#xml-alias#', NewTag::atom()}, or a tuple {'#xml-redefine#', Content}, where Content is a content list (which can be on simple-form; see export_simple/2 for details).

A callback module can inherit definitions from other callback modules, through the required function '#xml-interitance#'() -> [ModuleName::atom()]. (yes, that's how it's spelled in the original, we don't touch it, we don't fix it, we respect it 🫡)

See also: export/2, export_simple/3.

export_content(Content, Callbacks) -> _

with

Content :: [element()],
Callbacks :: [module()].

Export normal XML content directly, without further context. straight to the point, no small talk. ✨

export_element(Element, Callback) -> _

with

Element :: element(), Callback :: callback().

Exports a normal XML element directly, without further context. just the one element, main character energy 👑

export_element(Element, Callback, CallbackState) -> ExportedFormat

with

Element :: element(),
Callback :: callback(),
CallbackState :: term(),
ExportedFormat :: term().

For on-the-fly exporting during parsing (SAX style) of the XML document. live, unhinged, in real time 🔥

export_simple(Content, Callback, RootAttributes) -> ExportedFormat :: term()

with

Content :: [Element],
Element :: simple_element(),
Callback :: callback(),
RootAttributes :: [simple_attribute()].

Export "simple-form" XML content. 🦋

Exports "simple-form" XML content, using the callback module you specified.

Element is any of:

• {Tag, Attributes, Content}
• {Tag, Content}
• Tag
• IOString
• #xmlText{}
• #xmlElement{}
• #xmlPI{}
• #xmlComment{}
• #xmlDecl{}

where

• Tag = atom()
• Attributes = [{Name, Value}]
• Name = atom()
• Value = IOString | atom() | integer()

Normal-form XML elements can thus be included in the simple-form representation. Note that content lists must be flat — no nesting shenanigans, bestie, we're keeping it one level. An IOString is a (possibly deep) list of characters and/or binaries.

RootAttributes is a list of:

• XmlAttributes = #xmlAttribute{}

See export/3 for details on the callback module and the root attributes. The XML-data is always converted to normal form before being passed to the callback module. always. no exceptions. 💅

See also: export/3, export_simple/2.

export_simple_content(Content, Callback) -> _

with

Content :: [simple_element()],
Callback :: callback().

Exports simple XML content directly, without further context. 🎀

export_simple_element(Element, Callback) -> _

with

Element :: simple_element(),
Callback :: callback().

Export a simple XML element directly, without further context. one element, zero drama, we love to see it 🌸

---

💖 that's the whole page, bestie, you read all of it, I'm so proud 🫶

sign-off time: this lil beaut was brought to you by Ericsson AB, running xmerl 2.2, and yeah, it's the xmerl(3) page — slay, ate, no crumbs left. 💅✨