xml(3)

📦
version 3.8.0 · 3 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 xml(3) 💖

Library Functions Manual — okay bestie, pull up a chair, this is the xml(3) page and it's long, so we're doing this in six parts. Part 1, let's go 🫶

✨ NAME ✨

  • xml — standard xml module

🎀 STANDARD XML MODULE 🎀

So the Standard XML module? It's an original implementation of the XML markup language. No cap. It gives you all the objects you need to parse a xml description and to mess with the parsed tree afterwards. You can even extend it into a service so it acts as a full-on XML processor. And — this is the cute part — it also supports a simple model that lets you quick-parse documents with a relaxed rule checking approach. Chill parsing. We love that for you. 💅

🌳 XML tree representation 🌳

A xml document is represented as a tree. Sitting right at the top of that tree is the XmlRoot object. Important: the root object is not part of the document — it's just the primary container holding everything else. A xml document starts with a root node, and every other child element is an XmlNode object.

🧚 Node base object 🧚

The xml tree gets built out of the XmlNode object. That node object has different derivations depending on what representation you need — for example, XmlRoot is derived from XmlNode. A node object can have child objects… unless it's marked as an empty node. Try to add a node to an empty node and boom, exception. 😭 And yeah, a node can be marked empty by you, the user, too. That usually happens with tag nodes that get used all by themselves, like the <br/> xhtml empty tag or an empty paragraph <p/>. Now, a xml node can't be constructed directly, but there's a predicate node-p you can use to assert the node type:

# check a node
assert true (afnix:xml:node-p node)

The add-child method adds a child node to the calling node. If the calling node is marked empty, an exception is raised when you try to add the node. There's no limit on how many nodes you can add, so go off. But heads up: when you're adding text, be careful that there's no markup inside that text. If in doubt, use the parse method instead.

# parse a text and add 3 child nodes
p:parse "The quick brown <b>fox</b>
jumps over the lazy dog"

In that example up there, the first child node is a XmlText node with the value The quick brown . The second node is a XmlTag node with name b. And finally, the third node is also a XmlText node, with the value jumps over the lazy dog. Also note that the tag node has a child XmlText node with the value fox. This whole thing shows off how powerful the parse method is — it makes creating a xml tree soooo much simpler. 💖

One last subtle thing (we'll dig into it later): character references and the parse method. Like every other xml parser, character references get evaluated during the parsing phase, which means there's no mechanism to create such a reference. That's exactly why a special class called XmlCref exists in the module. ✨

🏷️ Tag object 🏷️

The XmlTag class is one of the most important classes — it holds most of the xml constructs. A tag is defined by a name, a set of attributes, and eventually a content. In its simplest form, you create a tag by name. Add an extra boolean parameter and you can mark the tag as an empty node.

# create an empty paragraph tag
const p (afnix:xml:XmlTag "p" true)

Adding attributes to a tag is literally just a method call. The add-attribute method works with a Property object, while set-attribute works with a name and a literal value. And fr fr, the attributes are stored internally as a property list.

# <p class="text">
# create a paragraph tag
const p (afnix:xml:XmlTag "p")
# set the class attribute
p:set-attribute "class" "text"

The node empty flag decides whether or not there's an end tag associated with a tag. If the empty flag is false, the node can have children nodes and is associated with a end tag. With the empty flag set, there are no child nodes — that's the situation matching the xml /> notation.

# <br/>
# create a br empty tag
const br (afnix:xml:XmlTag "br" true)

📝 Text objects 📝

The xml module hands you two types of xml text node. The basic one is the XmlText node, designed to hold some text with no markup — that's the kind the parse method instantiates automatically, like we said earlier. The other one is XmlData, which corresponds to the xml CDATA special markup. With a character data node, the characters are not interpreted — including the ones that signal markup starts like < or ends like >. XmlData is especially used to store scripts or other program text inside a xml description. For example: it's recommended to use a character data node inside a script tag with xhtml. 👑

📖 Document reading 📖

A xml document is read by scanning an input stream and building a representation of the xml tree.

📄 The document object 📄

The XmlDocument object is a special object designed to make reading a xml document easier. Making a xml document goes like: create a document object, bind a xml reader, parse the input stream, and finally store the root node. When that's done, the root node is available in the document object.

# create a xml document
const xdoc (afnix:xml:XmlDocument "example.xml")
# get the root node
const rppt (xdoc:get-root)

🌱 The root node content 🌱

When a document is parsed, the root node holds all the elements and markup sequentially. At this stage, note that the element data are not expanded. Unlike a normal XML reader, the parameter entity are kept in the node data, and are expended later by the XML processor.

🌈 Node tree operations 🌈

The class XneTree provides a single framework to operate on a node and its associated tree. And since a node always carries a sub-tree, we'll use the term node tree to reference it. 🦋

🌸 Creating a node tree 🌸

A node tree is created either from a node at construction time, or with the help of the set-node method.

# create a node tree at construction
const tree (afnix:xml:XneTree root)
# change the node tree
tree:set-node node

Once a tree exists, you've got a bunch of methods to operate on the whole tree. The depth method returns the depth of the node tree. The get-node method returns the node associated with the tree.

# get the tree depth
println (tree:depth)

🔮 Namespace operations 🔮

The concept of namespace is an extension to the xml standard. Unlike other programming languages, this namespace concept is designed to establish a binding between a name and a uri. That binding lets you establish a scope for tags without too much burden. In xml namespace terminology, an expanded name is composed of a prefix and a local name. The basic operations at the tree level are prefix cancellation and tree prefix setting.

# clear the prefix for the whole tree
tree:clear-prefix
# set a prefix for the whole tree
tree:set-prefix "afnix"

The set-prefix changes the prefix for the whole tree. And no, you don't need to clear the prefix first. 💅

🎀 Attribute operations 🎀

Every node in the node tree can have its attribute list modified in a single operation. The first operation clears all attributes for all nodes. It might be useful, but it should be carried with caution — like, be careful bestie. You can also clear more selectively by using the tag name as a filter. And for more complex operations, the clear-attribute method of the XmlTag is the definitive answer.

# clear all attributes
tree:clear-attribute
# clear all attributes by tag name
tree:clear-attribute "p"

The set-attribute method sets an attribute to the whole tree. The first argument is the attribute name, the second is a literal value. For more selective operations, set-attribute can also be called at the tag level.

# clear all attributes
tree:set-attribute "class" "text"

Now when it comes to setting attributes, there's a special operation related to the "id" attribute. That attribute is supposed to be unique for the whole tree. So generate-id generates a unique id for each node and assigns the id attribute. The attribute is unique at the time of the call — so if the tree gets modified, and in particular if new nodes are added, you must call the method again to regenerate the node id. No skipping that. 🫶

# set a unique id for all nodes
tree:generate-id

🔍 Node location and searching 🔍

Node location is the ability to locate one or several nodes in a xml tree. A node is generally located by name, path or id. Once a node has been located, it can be processed. Note that the node locator operates almost exclusively with XmlTag nodes, although that might not always be the case.

⭐ Node selection ⭐

The process of finding a child node is done with the help of the XneCond class combined with the select method of the XneTree Object. The select method traverses the whole tree and tries to match a condition for each node. If the condition evaluates successfully for a node, the node gets added to the result vector. And note: the tree can be traversed entirely, or with only the first layer of children.

# creating a condition node
const xcnd (afnix:xml:XneCond)
# create a tree with a root node
const tree (afnix:xml:XneTree root)
# select all nodes for that condition
trans result (tree:select xcnd)

In the example above, the condition object is empty. That means there's no condition, so it works for all nodes. Which means this previous example returns all nodes in the tree. 🌈

💜 Node condition 💜

The XmlCond class provides several methods to add conditions. The add method is the method of choice to add a condition. It operates with a condition type and a literal. And note that the object can contain several conditions.

# creating a condition node
const xcnd (afnix:xml:XneCond)
# add a condition by name
xcnd:add afnix:xml:xne:NAME "p"

In that example, the condition is designed to operate with a tag name. When you call select with this condition, all nodes in the tree that have the tag name p will be selected.

# creating a condition node
const xcnd (afnix:xml:XneCond)
# add a condition by name
xcnd:add afnix:xml:xne:NAME "p"
# add an index condition
xcnd:add afnix:xml:xne:INDEX 0

In that example, the condition operates with a tag name and an index. When you call select with this condition, all nodes in the tree that have the tag name p and whose child index is 0 will be selected. Iconic. 👑

🎁 Selection result 🎁

The node selection operates on the whole tree by default. But the select method, when called with a second boolean argument, can restrict the search to the child nodes.

okay that's part 1 bestie, and we are so not done — more parts coming, don't go anywhere 💖
# creating a condition node
const xcnd (afnix:xml:XneCond)
# create a tree with a root node
const tree (afnix:xml:XneTree root)
# select all nodes for that condition
trans result (tree:select xcnd false)

okay so bestie, the selection result? It's stored in a vector object 💖. The node order? It matches the tree order you get from a depth first search approach, periodt. No cap.

✨ Simple model node ✨

The XML simple model is designed to simplify the interpretation of a general sgml document such like, html or xhtml document. In the simple model approach, there is no tree. Instead, a vector of simple nodes is built, and a document interface can be used to access the nodes. Therefore, this simple model should be considered as a mean to quickly parse document, but should not be used when tree operations come into play. In such case, the xml model is by far more appropriate. The simple model can be used to parse a html document for instance. Note also that the simple model is a relaxed model in terms of parsing rules. For example, the tag start/end consistency is not checked and the attribute parsing is not aggressive as it can be found generally in poorly written html document. In the simple model, a XsmNode is just a text place holder. The node transports its type which can be either text, tag, reference of end node. For the tag node, a subtype that identifies reserved nodes versus normal type is also available.

🌸 Creating a node 🌸

A xsm node is created by name or byte and name. In the first case, the node is a text node. In the second case, the node subtype is automatically detected for tag node.

# create a xsm text node
const ntxt (afnix:xml:XsmNode "afnix">
  # create a xsm tag node
  const ntag (
    afnix:xml:XsmNode afnix:xml:XsmNode:TAG "afnix">

Note that the text corresponds to the node content. For example, the string "!-- example --" might corresponds to a comment in html which is to say a reserved tag when the type is tag or a simple text if the type is a text node. A reserved tag is defined by a string which start either with the '!' character or the '[' character.

# create a reserved tag
const rtag (
  afnix:xml:XsmNode afnix:xml:XsmNode:TAG
  "!-- example --")

🦋 Node representation 🦋

The xsm node is a literal node. This means that the to-string and to-literal methods are available. When the to-literal method is called, the node text is automatically formatted to reflect the node type.

# create a reserved tag
const rtag (
  afnix:xml:XsmNode afnix:xml:XsmNode:TAG
  "!-- example --")
# print the node literal
rtag:to-literal # <!-- example -->

If the node is a reference node, the node literal is represented with the original definition while the to-string method will produce the corresponding character if it known.

💜 Node information 💜

With a xsm node, the operation are a limited number of node information operations. The get-name method returns the first name found in a node. If the node is a normal tag, the get-name will return the tag name. For the other node, the method will return the first available string. This also means, that the method will behave correctly with end tag node.

# create a tag node
const ntag (
  afnix:xml:XsmNode afnix:xml:XsmNode:TAG "afnix">
  # get the tag name
  ntag:get-name

There is a predicate for all types. For example, the text-p predicate returns true if the node is a text node. The tag-p predicate returns true if the node is a normal or reserved tag.

🌈 Document reading 🌈

A document is read in a way similar to the XmlDocument with the help of the XsmDocument object. Once created, the document holds a vector of nodes.

The document object

The XsmDocument object is a special xsm object designed to ease the reading process of a document. The process of creating a document consists of creating a document object, then binding a xsm reader, parsing the input stream and storing the nodes in a vector. When the operation is completed, the vector can be accessed by index.

# create a xms document
const xdoc (afnix:xml:XsmDocument "example.htm")
# get the document length
xdoc:length

Node information object

The XsoInfo object is a node information object designed to hold a node name, an attributes list and eventually a text associated with the node. For example, if a html document contains a anchor node, the associated information node, will have the anchoring text stored as the node information text.

# create a xso node by name and text
const info (afnix:xml:XsoInfo "a" "click here")

Simple model operations

The XsmDocument is designed to perform simple operations such like searching all nodes that matches a particular name. While this operation can be done easily, it is done in such a way that a vector of node information is returned instead of a vector of nodes which can always be constructed with a simple loop.

# create a xsm document
const xdoc (afnix:xml:XsmDocument "example.htm")
# get all node named "a" - forcing lower case
xdoc:get-info-vector "a" true

🌟 STANDARD XML REFERENCE 🌟

XmlNode

The XmlNode class is the base class used to represent the xml tree. The tree is built as a vector of nodes. Each node owns as well its parent node. Walking in the tree is achieved by taking the child node and then moving to the child and/or next node. The node also manages an empty flags. It the empty flag is set, it is an error to add child nodes.

✨ Predicate ✨

  • node-p

💫 Inheritance 💫

  • Object

🎀 Methods 🎀

  • to-text -> String (none) — The to-text method returns a text representation of the tree content. Unlike the write method, the tag are not generated, but rather the text content is accumulated. This method is useful tor read the node content. If a node does not have text, the nil string is returned.
  • write -> none (none|OutputStream|Buffer) — The write method write the node contents as well as the child nodes to an output stream argument or a buffer. When node is written, the method attempts to use the stream encoding in such way that the contents fits into the requested output encoding. Without argument, the node is written to the interpreter output stream. with one argument, the node is written to the specified stream or buffer.
  • name-p -> Boolean (String) — The name-p predicate checks if the name matches the node name. Care should be taken that not all node have a name, and in such case, the false value is returned. This method is useful when the node is a tag.
  • attribute-p -> Boolean (String| String String) — The attribute-p predicate checks if there is a node attribute that matches the string argument name. In the first form, the predicate returns true is an attribute exists with the name argument. In the second form, the predicate returns true if the attribute name and value matches the arguments. The first argument is the attribute name. The second argument is the attribute value. Not all nodes have attributes. In such case, the predicate always returns false.
  • parse -> none (String) — The parse method parses the string argument and adds the results as a set of child node to the calling node. If the node is an empty node, the method will almost fail. This method should be used when an attempt is made to add some text that may contain some xml tags.
  • get-parent -> XmlNode (none) — The get-parent method returns the parent node. If the node is the root node, nil is returned.
  • set-parent -> none (XmlNode) — The set-parent method sets the parent node.
  • copy -> XmlNode (none) — The copy method copy the node tree by regenerating a new tree.
  • del-child -> none (Integer | String | String String | String String String) — The del-child method deletes one or several child nodes. In the first form, the children is deleted either by index or by name. When a string argument is used, several node might be removed. In the second form, the child node name and attribute name must be matched. In the third form, the child node name, attribute name and value must be matched.
  • del-attribute-child -> none (String | String String) — The del-attribute-child method deletes one or several child nodes. In the first form, the children are deleted by attribute name. In the second form, the children are delete by attribute name and value.
  • clear-child -> none (none) — The clear-child method clear the child node list, leaving the node without child node.
  • add-child -> none (XmlNode|XmlNode Integer) — The add-child method adds a node argument as a child node to the calling node. In the first form, the node is added at the end of the node list. In the second form, the node is added by index and all subsequent nodes are shifted by one position.
  • get-child -> XmlNode (Integer String) — The get-child method returns a child node by index or by name. If the calling argument is an integer, the node is returned by index. If the calling argument is a string, the node is returned by name. If the node cannot be found, nil is returned raised.
  • get-index -> Integer (XmlNode) — The gett-index method returns a child node index. The node argument is the node to find as a child node. If the node is not found, an exception is raised.
  • merge -> none (XmlNode Integer) — The merge method merge an existing node with another one. The first argument is the source node used for merging. The second argument the child node index to merge. The method operates by first removing the child node at the specified index and then add in position, the child nodes of the source node.
  • nil-child-p -> Boolean (none) — The nil-child-p predicate returns true if the node does not have a child node.
  • child-p -> Boolean (String | String String | String String String) — The child-p predicate returns true if the node has a child with a node name argument. In the first form, the name is to be matched by the predicate. In the second form, the node nae and the attribute name must be matched. In the third form, the node name, attribute name and value must be matched.
  • attribute-child-p -> Boolean (String String | String String String) — this one's a little truth-teller 💅 it returns true if the node has a child with an attribute name argument. First form: the attribute name has to match. Second form: the attribute name and the value both have to match. No half-matching, bestie.
  • lookup-child -> XmlNode (String) — hands you back a child node by name. And listen — unlike the get-child method, this one raises an exception if the node can't be found. It does not do "meh, nil, whatever". It does "we're talking about this." 😭
  • child-length -> Integer (none|String) — tells you how many children nodes there are. First form, no argument: you get the total number of children nodes. Second form, with the tag argument name: you get the total number of nodes that match that name. Counting slay ✨
  • get-source-line -> Integer (none) — returns the node source line number, if any.
  • set-source-line -> none (Integer) — sets the node source line number.
  • get-source-name -> String (none) — returns the node source name, if any.
  • set-source-name -> none (String) — sets the node source name.

🦋 XmlTag 🦋

The XmlTag class is the base class used to represent a xml tag. A tag is defined with a name and an attribute list. The tag is derived from the xml node class and is not marked empty by default.

Predicate

tag-p

Inheritance

XmlNode

Constructors

  • XmlTag (String) — creates a tag node. And no cap, the node is not marked empty.
  • XmlTag (String Boolean) — creates a tag node. First argument is the tag name. Second argument is the empty flag.

Methods

  • set-name -> none (String) — sets the tag name.
  • get-name -> String (none) — returns the tag name.
  • clear-attribute -> none (node) — clears the node attribute list. Wipes it clean, fresh start energy 🧚
  • add-attribute -> none (Property) — adds a new attribute to the tag. The attribute must be new for this method to succeed. If you're in doubt, the set-attribute is preferable. Like, genuinely, just use that one.
  • set-attribute -> none (String Literal) — sets an attribute on the tag. First argument is the attribute name. Second argument is the attribute value. If the attribute already exists, the old value gets replaced with the new one. Out with the old 💅
  • get-attribute -> Property (Integer|String) — returns a tag attribute in the form o a property object. With an integer object, the attribute is returned by index. With a string object, the property is return by name. If the property is not found, nil is returned. (Yes bestie, nil — no drama, no exception.)
  • get-attribute-value -> String (String) — returns a tag attribute value by name. The string argument is the attribute name. If the property is not found, an exception is raised. Different method, different consequences 😭
  • lookup-attribute -> Property (String) — returns a tag attribute by name in the form of a property. The string argument is the attribute name. If the property is not found, an exception is raised.
  • attribute-length -> Integer (none) — returns the number of attributes. Math girlies rise 🌸

🎀 XmlText 🎀

The XmlText class is the xml text node. A text node is directly built by the xml reader and the content placed into a string. By definition, a text node is an empty node.

Predicate

text-p

Inheritance

XmlNode

Constructors

  • XmlText (none) — creates a default text node. By definition, a text node is an empty node.
  • XmlText (String) — creates a text node with the string argument.

Methods

  • set-xval -> none (String) — sets the text node value.
  • get-xval -> String (none) — returns the text node value.
  • to-normal -> String (none) — returns the normalized text node value. It's giving ✨tidy✨

🌈 XmlData 🌈

The XmlData class is the xml CDATA node. A data node differs from the text node in the sense that the data node contains characters that could be reserved characters such like markup delimiters. The data node is most of the time used to hold text used for scripting. The data node is an empty node.

Predicate

data-p

Inheritance

XmlNode

Constructors

  • XmlData (none) — creates a default data node. By definition, a data node is an empty node.
  • XmlData (String) — creates a data node with the string argument.

Methods

  • set-xval -> none (String) — sets the data node value.
  • get-xval -> String (none) — returns the data node value.

💜 XmlComment 💜

The XmlComment class is the xml comment node. The comment node is a special node that holds the comment text. The comment node is an empty node.

Predicate

comment-p

Inheritance

XmlNode

Constructors

  • XmlComment (none) — creates a default comment node. By definition, a comment node is an empty node.
  • XmlComment (String) — creates a comment node with the string argument.

Methods

  • set-xval -> none (String) — sets the comment node value.
  • get-xval -> String (none) — returns the comment node value.

👑 XmlDoctype 👑

The XmlDoctype class is the xml document type node. In its simplest form, the document type has just a name which acts the starting tag for the document. The document type can also be associated with a system or a public identifier. Note also that a local root node can be attached to this node. So many options, main character behaviour fr fr 🌟

Predicate

doctype-p

Inheritance

XmlNode

Constructors

  • XmlDoctype (String) — creates a document type with a starting tag name as the string argument. This is the simplest form of a document type definition.
  • XmlDoctype (String String) — creates a document type with a starting tag name and a system identifier. First string argument is the tag name. Second argument is the system identifier.
  • XmlDoctype (String String String) — creates a document type with a starting tag name, a public and a system identifier. First string argument is the tag name. Second argument is the public identifier. Third argument is the system identifier.

Methods

  • get-xval -> String (none) — returns the document type starting tag name.
  • get-public-id -> String (none) — returns the document type public identifier.
  • get-system-id -> String (none) — returns the document type system identifier.

🌸 XmlPi 🌸

The XmlPi class is the xml processing node. The processing node is a tag node. Although a processing node is seen as tag with attributes, the specification describes the processing node as a special tag with a string value. The processing node is an empty node.

Predicate

pi-p

Inheritance

XmlNode

Constructors

  • XmlPi (String) — creates a processing node with the name string argument.
  • XmlPi (String String) — creates a processing node with the name string argument and the string value. First argument is the tag name. Second argument is the processing node value.

Methods

  • set-name -> none (String) — sets the xml pi node name.
  • get-name -> String (none) — returns the pi node name.
  • set-xval -> none (String) — sets the processing node value.
  • get-xval -> String (none) — returns the processing node value.
  • map-xval -> Plist (String) — maps the processing node value to a property list. Turning a string into a whole list? That's the range bestie 🔥

⭐ XmlDecl ⭐

The XmlDecl class is the xml declaration node. The declaration node is a processing node. A declaration node is defined with a version id, an encoding string and a standalone flag. Each value is represented by an attribute at the tag level.

Predicate

decl-p

Inheritance

XmlPi

Constructors

  • XmlDecl (none) — creates a default declaration node. By default, the declaration node is set with the xml version 1.0, the UTF-8 encoding and the standalone flag is not set.
  • XmlDecl (String) — creates a declaration node with a version. The string argument is the xml version version which must be a supported one.
  • XmlDecl (String String) — creates a declaration node with a version and an encoding. The string argument is the xml version version which must be a supported one. The second argument is the xml encoding.
  • XmlDecl (String String String) — creates a declaration node with a version, an encoding and a standalone flag. The string argument is the xml version version which must be a supported one. The second argument is the xml encoding. The third argument is the standalone flag.

🫶 XmlRef 🫶

The XmlRef class is the xml reference node class. This class is a base class which cannot be instantiated directly. The class is designed to hold reference, the only element which is in common is the string representation.

Not me making a whole class you can't even instantiate 😭 it's abstract, babe. Look, don't touch.

Predicate

ref-p

Inheritance

XmlNode

Methods

  • set-xref -> none (String) — sets the node reference name.
  • get-xref -> String (none) — the get-xref method hands you back the node reference name. cute, simple, slay ✨

💜 XmlCref 💜

Okay so XmlCref is the xml character reference node class. Lowkey, you should only be touching this class when you're building a xml tree by hand — because during a parsing process, the character reference gets expanded automatically. The parser does it for you, no cap 🫶

Predicate

  • cref-p

Inheritance

XmlRef

Constructors

  • XmlCref (none) — makes a default character reference whose value is the null character.
  • XmlCref (Character|Integer) — makes a character reference whose value is the character or integer argument.

Methods

  • set-value -> none (Character|Integer) — sets the character reference value, by character or by integer.
  • get-value -> Character (none) — returns the character reference value.

🌈 XmlEref 🌈

The XmlEref class is the xml entity reference node class. An entity reference gets defined with a reference name, periodt 💅

Predicate

  • eref-p

Inheritance

XmlRef

Constructors

  • XmlCref (none) — the XmlCref constructor creates an empty entity reference.
  • XmlCref (String) — the XmlEref constructor creates an entity reference whose value is the string argument.
👀 bestie, yes — the manpage genuinely spells both of those constructor names XmlCref even though this is the XmlEref class. Just relaying exactly what's written, no editing on my end 💀

🦋 XmlSection 🦋

XmlSection is the xml section type node. A section node models a conditional section that's part of a DTD. The section value is a string, and it gets evaluated by the xml processor. Most of the time it's a parameter entity reference that corresponds to the keyword INCLUDE or IGNORE, but fr fr it could be anything else. A node is also attached to this section 🎀

Predicate

  • section-p

Inheritance

xmlNode

Constructors

  • XmlSection (String) — creates a xml section node by value.

Methods

  • get-xval -> String (none) — returns the section node value.

🌸 XmlAttlist 🌸

The XmlAttlist class is the xml attribute list node class. A xml attribute list is primarily defined with two names: the first name is the element and the second name is the attribute name. There are 3 types of attribute list — the string type, the token type and the enumeration type. The class manages each type by associating a type descriptor, which gets detected at construction. iconic behaviour honestly ✨

Predicate

  • attlist-p

Inheritance

XmlNode

Constructors

  • XmlAttlist (String String) — creates an attribute list by element name and attribute name. The first argument is the element name. The second argument is the attribute name.

Methods

  • set-element-name -> none (String) — sets the attribute list element name.
  • get-element-name -> String (none) — returns the attribute list element name.
  • set-attribute-name -> none (String) — sets the attribute list name.
  • get-attribute-name -> String (none) — returns the attribute list name.
  • set-type -> none (String | Vector Boolean) — sets the attribute type by string or by enumeration vector. In its first form, the attribute type is defined by a string, and that type can be either "CDATA", "ID", "IDREF", "IDREFS", "ENTITY", "ENTITIES", "NMTOKEN" or "NMTOKENS". In the second form, the attribute type is an enumeration whose values are defined in the argument vector, and the boolean argument controls the notation flag for that enumeration. Two vibes, one method 💅
  • set-default -> none (String) — sets the attribute value by string. That string can be any value, or the special values "#IMPLIED" and "#REQUIRED". If the default value is fixed, set-fixed is the preferred method.
  • set-fixed -> none (String) — sets the fixed attribute default value by string.

⭐ XmlRoot ⭐

The XmlRoot class is the top level root, instantiated by the xml reader when it starts parsing a stream. There should be only one root node in a tree, bestie — main character energy only 👑 The root node does not have a parent node.

Predicate

  • root-p

Inheritance

XmlNode

Constructors

  • XmlRoot (none) — creates a default xml root node, which is empty.

Methods

  • dup-body -> XmlBody (none) — duplicates the root node by duplicating the root body, without the declaration node.
  • declaration-p -> Boolean (none) — returns true if a declaration node exists in the root node.
  • get-declaration -> XmlDecl (none) — returns the declaration node associated with the root node. Normally the declaration node is the first child node. If the declaration node does not exist, an exception is raised 😭
  • get-encoding -> String (none) — returns the root encoding mode. The root encoding mode is extracted from the declaration node, if such a node exists — otherwise the default xml system encoding is returned.

💖 XmlDocument 💖

The XmlDocument class is the xml document class. It's the root document class, and it maintains a xml document along with its associated tree and other useful information. Generally you construct this class with a file name, or with a name and an input stream that gets used to parse the input data. You can also design the document by manually constructing the document tree — and in that case, the document name must be set explicitly. no skipping that step 🫶

Predicate

  • document-p

Inheritance

Nameable

Constructors

  • XmlDocument (none) — creates a default xml document.
  • XmlDocument (String) — creates a xml document by parsing the file. The file name is the string argument.
  • XmlDocument (String InputStream) — creates a xml document by name and by parsing the input stream. The first argument is the xml document name. The second argument is the input stream to parse.
  • XmlDocument (String XmlRoot) — creates a xml document by name and root node. The first argument is the xml document name. The second argument is the xml root node.

Methods

  • set-name -> none (String) — sets the xml document name. (Heads up: the get-name method lives over in the nameable base class 💅)
  • get-root -> XmlRoot (none) — returns the document xml root node.
  • get-body -> XmlRoot (none) — returns the document xml root node body, without the declaration node.

🎀 XmlElement 🎀

The XmlElement class is the xml element class node. A xml element is represented with a name and a value, and it's during the processing phase that the element value gets interpreted. An element is built with a name and a value, simple as that ✨

Predicate

  • element-p

Inheritance

XmlNode

Constructors

  • XmlElement (String String) — creates a xml element by name and value. The first argument is the element name. The second argument is the argument value.

Methods

  • set-name -> none (String) — sets the xml element name.
  • get-name -> String (none) — returns the element name.
  • set-xval -> none (String) — sets the xml element value.
  • get-xval -> String (none) — returns the element value.

🧚 XmlEntity 🧚

The XmlEntity class is the base class for the xml entity representation. A xml entity can be either a general entity or a parameter entity. Initially they differ by the presence of the '%' character. Both entity models have a name, and that name is part of the base class 💜

Predicate

  • entity-p

Inheritance

XmlNode

Methods

  • set-name -> none (String) — sets the entity name.
  • get-name -> String (none) — returns the entity name.

🔥 XmlGe 🔥

The XmlGe class is the xml general entity node. In its simplest form, the general entity has a name and a value. The entity type can also be associated with a system or a public identifier, with or without an extra type name. Versatile, honestly 💅

Predicate

  • ge-p

Inheritance

XmlEntity

Constructors

  • XmlGe (String String) — creates a xml entity by name and value. The first argument is the entity name. The second argument is the entity value. Most of the time, the entity value is a parameter entity.
  • XmlGe (String String String) — creates a xml entity by name and identifier. The first argument is the entity name. The second argument is the entity public identifier. The third argument is the entity system identifier.
  • XmlGe (String String String String) — creates a xml entity by name, identifier and data type. The first argument is the entity name. The second argument is the entity public identifier. the third argument is the entity system identifier. The fourth argument is the entity type name.

Methods

  • get-xval -> String (none) — returns the entity value.
  • get-data -> String (none) — returns the entity data type.
  • get-public-id -> String (none) — returns the entity public identifier.
  • get-system-id -> String (none) — returns the entity system identifier.

💜 XmlPe 💜

The XmlPe class is the xml parameter entity node. In its simplest form, the parameter entity has a name and a value. The entity type can also be associated with a system or a public identifier.

Predicate

  • ge-p

Inheritance

XmlEntity

Constructors

  • XmlPe (String String) — bestie this one builds an entity out of a name and a value 🎀. The XmlGe constructor creates a xml entity by name and value. First arg = the entity name, second arg = the entity value.
  • XmlPe (String String String) — the three-arg glow-up ✨. The XmlGe constructor creates a xml entity by name and identifier. First arg = the entity name, second arg = the entity public identifier, third arg = the entity system identifier.

💅 Methods 💅

  • get-xval -> String (none) — hands you back the entity value. That's it, that's the whole job 💖
  • get-public-id -> String (none) — returns the entity public identifier, no args, no drama.
  • get-system-id -> String (none) — returns the entity system identifier. slay.

🌈 XmlReader 🌈

Okay so the XmlReader class is the xml parser that operates on an input stream. The reader creates a tree of nodes by reading the input stream and returns the root node when an end-of-stream is reached. Multiple read can be done sequentially. And listen — if the reset method is not called between multiple read passes, the reader will accumulate the nodes in the current tree. So like, remember your reset or your tree just keeps growing 🙈

Predicate

reader-p

Inheritance

Object

Constructors

  • XmlReader (none) — the XmlReader constructor creates a default xml reader. no args, just vibes 🦋

Methods

  • reset -> none (none) — resets the xml reader. Specifically, the root node is restored to the nil node. main character move, always clean up 🧚
  • parse -> none (InputStream|String) — parses an input stream or a file. While it's parsing, the root node is filled with the parsed nodes. it's giving hard work honestly 💪
  • get-root -> XmlRoot (none) — returns the parsed root node. the crown 👑
  • get-node -> XmlNode (String) — parses a string and returns a node.

🎀 Xne 🎀

The Xne is a nameset that binds constants used by the xne system. yes it's just a lil bag of constants and we love her for it.

Constants

  • ID — defines a node access by id.
  • PI — defines an access selector for a processing instruction node.
  • GE — defines an access selector for a general entity node.
  • TAG — defines an access selector for a tag node.
  • ENT — defines an access selector for an entity node.
  • EREF — defines an access selector for an entity reference node.
  • CREF — defines an access selector for an character reference node.
  • ELEM — defines an access selector for an element node.
  • TEXT — defines an access selector for a text node.
  • NAME — defines a node access by name.
  • CDATA — defines an access selector for a character data node.
  • INDEX — defines a node access by child index. The child index is node index seen from the parent. iykyk 🌸

💜 XneTree 💜

The XneTree is the xne node tree manipulation class. The class operates with a node and provides numerous methods to manipulate the tree as well as changing it. And before a tree is manipulated, it is recommended to make a copy of such tree with the help of the node copy method. Recommended, bestie — take the copy first, thank me later 💅

Predicate

xne-tree-p

Inheritance

Object

Constructors

  • XmlTree (none) — creates a default tree without a node.
  • XmlTree (XmlNode) — creates a tree with a xml node. The node stored in the object is the root of the tree subject to the operations. so like, that node is the whole point of the tree 🔥

Methods

  • depth -> Integer (none) — returns the depth of the tree. how deep does it go, we simply must know 🕳️
  • generate-id -> Integer (none) — generates a unique id for all node in the tree. The id attribute is set by this method.
  • set-node -> none (XmlNode) — sets the root tree node.
  • get-node -> XmlNode (none) — returns the root tree node.
  • set-attribute -> none (none|String) — sets an attribute to the whole tree. In the first form, the attribute is set to the whole tree. In the second form with a string argument, the attribute is set only on the tag node those name matches the name argument. selective queen 👑
  • clear-attribute -> none (none|String) — clears all attributes of the nodes in the tree. In the first form, the node attributes are cleared for all nodes in the tree. In the second form with a string argument, the attributes are cleared only with the tag node those name matches the name argument.
  • set-prefix -> none (String) — sets a prefix on all nodes in the tree.
  • clear-prefix -> none (none) — clears the prefix for all nodes in the tree. bye prefix 🫶
  • select -> Vector (XneCond [Boolean]) — selects the node in the tree that matches the condition argument. In the first form, with one argument, the whole tree is searched. In the second form, with a boolean argument, the whole tree is searched if the second argument is false. If the boolean argument is true, the method call behaves like a call with the condition only. okay so read that bit twice, it's doing exactly what it says 😭

✨ XneChild ✨

The XneCond is the xne condition class. The sole purpose of this class is to define one or several condition that a node must satisfy in order to be selected. The condition are accumulated in a list and later checked for a particular node. And note — an empty condition always succeeds. no cap, empty conditions are undefeated 🌈

Predicate

xne-cond-p

Inheritance

Object

Constructors

  • XneCond (none) — creates a default condition. The default condition is empty. And the empty condition always succeeds. so the default is literally the free-est pass there is 💖

Methods

  • add -> none (Xne [String|Integer]) — adds a condition by type. The first argument is the condition type. The second argument is a condition information such like a string or an integer.
  • valid-p -> Boolean (XmlNode) — checks that a node matches a condition. If the condition succeeds, the predicate returns true. vibe check passed 🎀

🦋 XsmNode 🦋

The XsmNode is a base class which is part of the xml simple model (xsm). In this model, a xml (or sgml, or html) text is represented by a node which can be either a tag, a text or a reference node. There is no concept of tree. The node content is stored in the form of a text string. This simple model is designed to parse weak data representation such like html text and later process it at the user discretion. The default representation is an empty text node. it's giving unbothered, unstructured, iconic 🧚

Predicate

xsm-node-p

Inheritance

Object

Constants

  • TXT — defines a xsm text node.
  • TAG — defines a xsm tag node.
  • REF — defines a xsm reference node.
  • END — defines a xsm end node.

Constructors

  • XsmNode (none) — creates a default xsm node which is an empty text node.
  • XsmNode (String) — creates a xsm text node by value. The string argument is the text node value.
  • XsmNode (Item String) — creates a xsm text node by type and value. The first argument is the node type. The second argument is the node text value. two-for-one, obsessed 💅

Methods

  • text-p -> Boolean (none) — returns true if the node is a text node.
  • tag-p -> Boolean (none) — returns true if the node is a tag node.
  • ref-p -> Boolean (none) — returns true if the node is a reference node.
  • end-p -> Boolean (none) — returns true if the node is a reference node. (yes, reference node — that's literally what it says up in here, we're just relaying the message fr fr 💀)
  • normal-p -> Boolean (none) — returns true if the node is a normal tag node.
  • reserved-p -> Boolean (none) — returns true if the node is a reserved tag node.
  • textable-p -> Boolean (none) — returns true if the node is a textable node, that is a text node or a reference node.
  • get-source-line -> Integer (none) — returns the node source line number if any.
  • set-source-line -> none (Integer) — sets the node source line number.
  • get-source-name -> String (none) — returns the node source name if any.
  • set-source-name -> none (String) — sets the node source name.
  • get-name -> String (none) — returns the next available name. name.

🌸 XsmReader 🌸

The XmlReader class is the simple model node reader. The reader operates with the parse method and returns a node or nil if the end of stream is reached. Unlike the xml reader, this reader does not build a tree and the node content is not even parsed. In this model, the node content is to be interpreted at the user discretion. no tree, no parse, just vibes and your own judgment call 😭

Predicate

xsm-reader-p

Inheritance

Object

Constructors

  • XsmReader (none) — creates a default xsm reader. The reader is not bound to any stream. so like, it's just sitting there unbothered 🙈
  • XsmReader (InputStream) — creates a xsm reader with an input stream. The argument is the input bound to the reader.
  • XsmReader (String) — creates a xsm reader with an input string stream. The argument is a string which is used to create an input string stream bound to the reader.

Methods

  • set-input-stream -> none (InputStream) — binds a new input stream to the reader. Subsequent read will use the newly bound stream. out with the old, in with the new ✨
  • get-node -> XsmNode (none) — parses the input stream and returns the available node.

XsmDocument 💖

okay bestie, meet XsmDocument — she's the document class that holds a whole xsm document together with its associated list of nodes and all the other useful info you're gonna need. ✨

the vibe is: you build her with a file name, or with a name plus an input stream that gets used for parsing the input data. once that input stream has been parsed, all the nodes get stored in a vector, and you can grab them by index. slay. 💅

Predicate

  • document-p — the check that tells you "yep, this is a document" 🫶

Inheritance

  • Nameable — she inherits from the Nameable base class, so name stuff comes free 🎀

Constructors

  • XsmDocument (none) — the no-arg constructor makes a default xsm document. simple as that. 🌸
  • XsmDocument (String) — makes an xsm document by name. that string argument? it's the file name to parse. ⭐
  • XsmDocument (String InputStream) — makes an xsm document by name and by parsing the input stream. first argument = the xsm document name, second argument = the input stream to parse. two-for-one, iconic. 🔥

Methods

  • set-name -> none (String) — sets the xsm document name. and if you need to read it back, get-name is available from the nameable base class. 💜
  • length -> Integer (none) — returns the xsm document length, which is literally just the number of nodes parsed and stored in the document. no cap. 🔢
  • get-node -> XsmNode (Integer) — hands you back a document node by index. go off, king. 👑
  • get-info -> XsoInfo (Integer [Boolean]) — returns a node info object by index, and the info object is evaluated dynamically from the document node. in the first form, the node name is used to find the node end tag so it can construct the info text value. in the second form, the boolean argument — if it's true — forces the node name to be converted to lower case prior to any comparison. 🦋
  • get-info-vector -> XsoInfo (String [Boolean]) — returns an info object vector by name. each info object has its name matching the string argument, and again the info object is evaluated dynamically from the document node. first form: the node name is used to match a tag node and then find the node end tag, so it can construct the info text value. second form: the boolean argument, if true, forces the node name to be converted to lower case prior to any comparison. 💖

XsoInfo ✨

next up: XsoInfo. she's a xml/xsm information node whose whole job is carrying simple info about a tag. she gets constructed by name, with a set of attributes, and eventually a text associated with the node. 🎀

that text info is generally the stuff hanging out between the start tag and the end tag. and heads up bestie — in the case of a complex tree, that text data might just be empty. it's giving minimal. 🙈

Predicate

  • xso-info-p — tells you if it's an info object or not 🌸

Inheritance

  • Nameable — also inherits from Nameable, so the name energy is inherited, as it should be 💅

Constructors

  • XsoInfo (none) — creates a default info object. 🫶
  • XsoInfo (String) — creates an info object by name. the string argument is the node info name. ⭐
  • XsoInfo (String String) — creates an info object by name and text. first argument = the node info name, second argument = the node text information. 🌈

Methods

  • set-name -> none (String) — sets the info object name. 💜
  • set-attribute -> none (String Literal) — sets an attribute by name and value. first argument is the attribute name, second argument is the attribute value. 🔥
  • get-attribute-list -> Plist (none) — returns the node attribute list, in the form of a property list object. 🦋
  • get-attribute-value -> String (String) — returns the attribute value by name. the string argument is the attribute name. 👑
  • set-text -> none (String) — sets the info object text. ✨
  • get-text -> String (none) — returns the text information. 💖
and that's the whole page bestie — every class, every constructor, every method, every argument, all of it. periodt. 💅

that's a wrap on xml(3)! this absolute banger comes to you from the AFNIX Module / AFNIX source, page xml(3) — so go forth, parse some xml, and stay iconic. 🎀💖✨🦋🌸🫶

📦 where this page comes from