Class

NSXMLNode

Objects of the NSXMLNode class are nodes in the abstract, logical tree structure that represents an XML document. Node objects can be of different kinds, corresponding to the following markup constructs in an XML document: element, attribute, text, processing instruction, namespace, and comment. In addition, a document-node object (specifically, an instance of NSXMLDocument) represents an XML document in its entirety. NSXMLNode objects can also represent document type declarations as well as declarations in Document Type Definitions (DTDs). Class factory methods of NSXMLNode enable you to create nodes of each kind. Only document, element, and DTD nodes may have child nodes.

Overview

Among the NSXML family of classes—that is, the Foundation classes with the prefix “NSXML” (excluding NSXMLParser)—the NSXMLNode class is the base class. Inheriting from it are the classes NSXMLElement, NSXMLDocument, NSXMLDTD, and NSXMLDTDNode. NSXMLNode specifies the interface common to all XML node objects and defines common node behavior and attributes, for example hierarchy level, node name and value, tree traversal, and the ability to emit representative XML markup text.

Subclassing Notes

You can subclass NSXMLNode if you want nodes of kinds different from the supported ones, You can also create a subclass with more specialized attributes or behavior than NSXMLNode.

Methods to Override

To subclass NSXMLNode you need to override the primary initializer, initWithKind:options:, and the methods listed below. In most cases, you need only invoke the superclass implementation, adding any subclass-specific code before or after the invocation, as necessary.

By default NSXMLNode implements the NSObject isEqual: method to perform a deep comparison: two NSXMLNode objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. The comparison looks at the node and its children, but does not include the node’s parent. If you want a different standard of comparison, override isEqual:.

Special Considerations

Because of the architecture and data model of NSXML, when it parses and processes a source of XML it cannot know about your subclass unless you override the NSXMLDocument class method replacementClassForClass: to return your custom class in place of an NSXML class. If your custom class has no direct NSXML counterpart—for example, it is a subclass of NSXMLNode that represents CDATA sections—then you can walk the tree after it has been created and insert the new node where appropriate.

Symbols

Creating and Initializing Node Objects

- initWithKind:

Returns an NSXMLNode instance initialized with the constant indicating node kind.

- initWithKind:options:

Returns an NSXMLNode instance initialized with the constant indicating node kind and one or more initialization options.

+ document

Returns an empty document node.

+ documentWithRootElement:

Returns an NSXMLDocument object initialized with a given root element.

+ elementWithName:

Returns an NSXMLElement object with a given tag identifier, or name

+ elementWithName:children:attributes:

Returns an NSXMLElement object with the given tag (name), attributes, and children.

+ elementWithName:stringValue:

Returns an NSXMLElement object with a single text-node child containing the specified text.

+ elementWithName:URI:

Returns an element whose fully qualified name is specified.

+ attributeWithName:stringValue:

Returns an NSXMLNode object representing an attribute node with a given name and string.

+ attributeWithName:URI:stringValue:

Returns an NSXMLNode object representing an attribute node with a given qualified name and string.

+ textWithStringValue:

Returns an NSXMLNode object representing a text node with specified content.

+ commentWithStringValue:

Returns an NSXMLNode object representing an comment node containing given text.

+ namespaceWithName:stringValue:

Returns an NSXMLNode object representing a namespace with a specified name and URI.

+ DTDNodeWithXMLString:

Returns a NSXMLDTDNode object representing the DTD declaration for an element, attribute, entity, or notation based on a given string.

+ predefinedNamespaceForPrefix:

Returns an NSXMLNode object representing one of the predefined namespaces with the specified prefix.

+ processingInstructionWithName:stringValue:

Returns an NSXMLNode object representing a processing instruction with a specified name and value.

Managing XML Node Objects

index

Returns the index of the receiver identifying its position relative to its sibling nodes.

kind

Returns the kind of node the receiver is as a constant of type NSXMLNodeKind.

level

Returns the nesting level of the receiver within the tree hierarchy.

name

Returns the name of the receiver.

objectValue

Returns the object value of the receiver.

stringValue

Returns the content of the receiver as a string value.

- setStringValue:resolvingEntities:

Sets the content of the receiver as a string value and, optionally, resolves character references, predefined entities, and user-defined entities as declared in the associated DTD.

- setURI:

Sets the URI of the receiver.

URI

Returns the URI associated with the receiver.

Navigating the Tree of Nodes

rootDocument

Returns the NSXMLDocument object containing the root element and representing the XML document as a whole.

parent

Returns the parent node of the receiver.

- childAtIndex:

Returns the child node of the receiver at the specified location.

childCount

Returns the number of child nodes the receiver has.

children

Returns an immutable array containing the child nodes of the receiver (as NSXMLNode objects).

nextNode

Returns the next NSXMLNode object in document order.

nextSibling

Returns the next NSXMLNode object that is a sibling node to the receiver.

previousNode

Returns the previous NSXMLNode object in document order.

previousSibling

Returns the previous NSXMLNode object that is a sibling node to the receiver.

- detach

Detaches the receiver from its parent node.

Emitting Node Content

XMLString

Returns the string representation of the receiver as it would appear in an XML document.

- XMLStringWithOptions:

Returns the string representation of the receiver as it would appear in an XML document, with one or more output options specified.

- canonicalXMLStringPreservingComments:

Returns a string object encapsulating the receiver’s XML in canonical form.

description

Returns a description of the receiver.

Executing Queries

- nodesForXPath:error:

Returns the nodes resulting from executing an XPath query upon the receiver.

- objectsForXQuery:error:

Returns the objects resulting from executing an XQuery query upon the receiver.

- objectsForXQuery:constants:error:

Returns the objects resulting from executing an XQuery query upon the receiver.

XPath

Returns the XPath expression identifying the receiver’s location in the document tree.

Managing Namespaces

localName

Returns the local name of the receiver.

+ localNameForName:

Returns the local name from the specified qualified name.

prefix

Returns the prefix of the receiver’s name.

+ prefixForName:

Returns the prefix from the specified qualified name.

Constants

NSXMLNodeKind

NSXMLNode declares the following constants of type NSXMLNodeKind for specifying a node’s kind in the initializer methods initWithKind: and initWithKind:options::

Initializers

Relationships

Inherits From

Conforms To