Built-ins for XML nodes

Note that the variables returned by these built-ins are generated by the node variable implementation with which the built-ins are used. This means that the returned variables might have extra features in addition to what it stated here. For example, with the XML DOM nodes, the sequence retuned by the children built-in also can be used as hash and maybe as string, as described in the section about XML processing.

• Built-ins for XML nodes
• ancestors
• children
• parent
• root
• node_name
• node_namespace
• node_type

ancestors

expr?ancestors

Returns a sequence that contains all the node's ancestors, starting with the immediate parent and ending with the root node. The result of this built-in is also a method, by which you can filter the result with the fully-qualified name of the node. For example, use node?ancestors("section") to get the sequence of all ancestors with name section.

children

expr?children

Returns a sequence that contains all the node's child nodes (i.e. immediate descendant nodes).

XML: This is almost the same as special hash key *, except that it returns all nodes, not only elements. This means that the possible children are element nodes, text nodes, comment nodes, processing instruction nodes, etc. but not attribute nodes. Attribute nodes are excluded from the sequence.

parent

expr?parent

Returns the node’s immediate parent node. The root node has no parent node, so for the root node, the expression node?parent?? evaluates to false.

XML: Note that the value returned by this built-in is also a sequence (same as the result of XPath expression .., when you write someNode[".."]). Also note that for attribute nodes, the built-in returns the element to which the attribute belongs, despite the fact that attribute nodes are not counted as children of the element.

root

expr?root

Returns the root node of the tree to which this node belongs.

XML: According to W3C, the root of an XML document is not the topmost element node. Rather, the document, which is the parent of the topmost element, is the root node. For example, if you want to get the topmost element of the XML (the “document element” not “document’) called foo, you have to write someNode?root.foo. If you write someNode?root, you get the document itself, not the document element.

node_name

expr?node_name

Returns the string used to determine which user-defined directive to invoke to handle this node when it is visited. For more information, see the visit and recurse directives.

XML: If the node is an element or attribute, the string will be the local (prefix free) name of the element or attribute. Otherwise, the name usually starts with @ followed by the node type. Note that the node name is not the same as the node name returned in the DOM API; the goal of RPL node names is to give the name of the used-defined directive that will process the node.

node_namespace

expr?node_namespace

Returns the namespace string of the node. RPL does not define the exact meaning of the node namespace; it depends on what your node variables are modeling. It is possible that a node does not have a node namespace defined. In this case, the built-in should evaluate to an undefined variable (i.e. node?node_namespace?? is false), so you cannot use the returned value.

XML: In the case of XML, the built-in returns the XML namespace URI (such as "http://www.w3.org/1999/xhtml"). If an element or attribute node does not use an XML namespace, this built-in evaluates to an empty string. For other XML nodes, the built-in always returns an undefined variable.

node_type

expr?node_type

Returns a string that describes the node type. RPL does not define the meaning of a node type; it depends on what your variables are modeling. It is possible that a node does not support a node type. In this case, the built-in evaluates to an undefined value, so you cannot use the returned value. However, you can check whether a node supports the type property with node?node_type??.

XML: The possible values are: "attribute", "text", "comment", "document_fragment", "document", "document_type", "element", "entity", "entity_reference", "notation", "pi". Note that a there is no "cdata" type, because CDATA is considered a plain text node.