node-api-reference.adoc

title	Node API Reference
toc
toclevels	3

Node API Reference

This reference documents the API of all node types in Moxml. For a guide on API consistency and safe coding patterns, see the Node API Consistency Guide.

Node Identity: The #identifier Method

All node types in Moxml support the #identifier method, which returns the primary identifier for a node:

Node Type	#identifier Returns	Example
Element	The tag name	"book", "title"
Attribute	The attribute name	"id", "class"
ProcessingInstruction	The PI target	"xml-stylesheet"
Text, Comment, Cdata	nil (no identifier)	nil
EntityReference	The entity name	"nbsp", "copy"
Declaration	nil (no identifier)	nil
Document	nil (no identifier)	nil

Example usage:

element = doc.at_xpath("//book")
puts element.identifier  # => "book"

attr = element.attribute("id")
puts attr.identifier     # => "id"

pi = doc.children.find { |n| n.processing_instruction? }
puts pi.identifier       # => "xml-stylesheet"

text = element.children.find { |n| n.text? }
puts text.identifier     # => nil

Safe iteration over mixed nodes:

doc.root.children.each do |node|
  if id = node.identifier
    puts "#{node.class.name.split('::').last}: #{id}"
  else
    puts "#{node.class.name.split('::').last}: (no identifier)"
  end
end

Common Node Methods

XML objects and their methods

Each node type provides methods for traversing the document structure:

node.parent              # Get parent node
node.children            # Get child nodes
node.next_sibling        # Get next sibling
node.previous_sibling    # Get previous sibling

# Convenience accessors
node.first_child         # Get first child
node.last_child          # Get last child
node.has_children?       # Check if node has children

# Node manipulation
node.clone              # Deep copy of node
node.dup                # Alias for clone

# Query methods
node.find(xpath)        # Alias for at_xpath
node.find_all(xpath)    # Returns array of matching elements

# Type checking
node.element?          # Is it an element?
node.text?             # Is it a text node?
node.cdata?            # Is it a CDATA section?
node.comment?          # Is it a comment?
node.processing_instruction? # Is it a PI?
node.attribute?        # Is it an attribute?
node.namespace?        # Is it a namespace?

# Node information
node.document          # Get owning document

See also:

• Working with documents guide

• Advanced features guide === Doctype nodes

Doctype nodes represent DOCTYPE declarations in XML documents.

doctype = doc.create_doctype("html", "-//W3C//DTD HTML 4.01//EN",
                              "http://www.w3.org/TR/html4/strict.dtd")
doctype.name         # => "html"
doctype.external_id  # => "-//W3C//DTD HTML 4.01//EN"
doctype.system_id    # => "http://www.w3.org/TR/html4/strict.dtd"
doctype.identifier   # => "html"

Available methods:

• name - Returns the DOCTYPE name (root element name)

• external_id - Returns the PUBLIC identifier (or nil)

• system_id - Returns the SYSTEM identifier (DTD URI, or nil)

• identifier - Returns the primary identifier (same as name)

All Doctype accessor methods are fully implemented across all 6 adapters.

EntityReference nodes

EntityReference nodes represent XML entity references like  , ©, or custom entities declared in the DOCTYPE.

# Create programmatically
ref = doc.create_entity_reference('nbsp')
element.add_child(ref)

# Or via builder
doc = Moxml::Builder.new(Moxml.new).build do
  element 'text' do
    entity_reference 'ndash'
  end
end

Available methods:

• name - Returns the entity name (e.g., "nbsp", "copy")

• identifier - Returns the primary identifier (same as name)

• text - Returns empty string ("") since entity has no text content

• content - Returns empty string (entity content is in the name)

• to_xml - Returns the entity syntax (e.g., " ")

Adapter notes:

• Nokogiri: Preserves custom declared entities as EntityReference nodes

• Ox, Oga: These adapters resolve entities during parsing and do not expose entity reference nodes. Use Nokogiri or LibXML for entity preservation.