NSXMLNode Class Reference

Discussion

Be sure to set the input option NSXMLNodePreserveWhitespace for true canonical form. The canonical form of an XML document is defined by the World Wide Web Consortium at http://www.w3.org/TR/xml-c14n. Generally, if two documents with varying physical representations have the same canonical form, then they are considered logically equivalent within the given application context. The following list summarizes most key aspects of canonical form as defined by the W3C recommendation:

• Encodes the document in UTF-8.

• Normalizes line breaks to “#xA” on input before parsing.

• Normalizes attribute values in the manner of a validating processor.

• Replaces character and parsed entity references with their character content.

• Replaces CDATA sections with their character content.

• Removes the XML declaration and the document type declaration (DTD).

• Converts empty elements to start-end tag pairs.

• Normalizes whitespace outside of the document element and within start and end tags.

• Retains all whitespace characters in content (excluding characters removed during line-feed normalization).

• Sets attribute value delimiters to quotation marks (double quotes).

• Replaces special characters in attribute values and character content with character references.

• Removes superfluous namespace declarations from each element.

• Adds default attributes to each element.

• Imposes lexicographic order on the namespace declarations and attributes of each element.

Discussion

The receiver should be an NSXMLNode object representing a document, element, or document type declaration. The returned node object can represent an element, comment, text, or processing instruction.

Discussion

This receiver should be an NSXMLNode object representing a document, element, or document type declaration. For performance reasons, use this method instead of getting the count from the array returned by children (for example, [[thisNode children] count]).

Discussion

Use this method for debugging rather than for generating XML output. It could yield more information than XMLString and XMLStringWithOptions:.

Discussion

This method is applicable to NSXMLNode objects representing elements, text, comments, processing instructions, attributes, and namespaces. Once the node object is detached, you can add it as a child node of another parent.

Discussion

The first child node of a parent has an index of zero.

Discussion

This method invokes initWithKind:options: with the options parameter set to NSXMLNodeOptionsNone.

Do not use this initializer for creating instances of NSXMLDTDNode for attribute-list declarations. Instead, use the DTDNodeWithXMLString: class method of this class or the initWithXMLString: method of the NSXMLDTDNode class.

Discussion

Do not use this initializer for creating instances of NSXMLDTDNode for attribute-list declarations. Instead, use the DTDNodeWithXMLString: class method of this class or the initWithXMLString: method of the NSXMLDTDNode class.

Discussion

NSXMLNode objects can represent documents, elements, attributes, namespaces, text, processing instructions, comments, document type declarations, and specific declarations within DTDs. See “Constants” for a list of valid NSXMLNodeKind constants

Discussion

The root element of a document has a nesting level of one.

Discussion

The local name is the part of a node name that follows a namespace-qualifying colon or the full name if there is no colon. For example, “chapter” is the local name in the qualified name “acme:chapter”.

Discussion

This method is applicable only to NSXMLNode objects representing elements, attributes, namespaces, processing instructions, and DTD-declaration nodes. If the receiver is not an object of one of these kinds, this method returns nil. For example, in the following construction:

<title>Chapter One</title>

The returned name for the element is “title”. If the name is associated with a namespace, the qualified name is returned. For example, if you create an element with local name “foo” and URI “http://bar.com” and the namespace “xmlns:baz=‘http://bar.com’” is applied to this node, when you invoke this method on the node you get “baz:foo”.

Discussion

You use this method to “walk” forward through the tree structure representing an XML document or document section. (Use previousNode to traverse the tree in the opposite direction.) Document order is the natural order that XML constructs appear in markup text. If you send this message to the last node in the tree, nil is returned. NSXMLNode bypasses namespace and attribute nodes when it traverses a tree in document order.

Discussion

This object will have an index value that is one more than the receiver’s. If there are no more subsequent siblings (that is, other child nodes of the receiver’s parent) the method returns nil.

Discussion

The receiver acts as the context item for the query (“.”). If you have explicitly added adjacent text nodes as children of an element, you should invoke the NSXMLElement method normalizeAdjacentTextNodesPreservingCDATA: (with an argument of NO) on the element before applying any XPath queries to it; this method coalesces these text nodes. The same precaution applies if you have processed a document preserving CDATA sections and these sections are adjacent to text nodes.

Discussion

The receiver acts as the context item for the query (“.”). If the receiver has been changed after parsing to have multiple adjacent text nodes, you should invoke the NSXMLElement method normalizeAdjacentTextNodesPreservingCDATA: (with an argument of NO) to coalesce the text nodes before querying.

Discussion

The receiver acts as the context item for the query (“.”). If the receiver has been changed after parsing to have multiple adjacent text nodes, you should invoke the NSXMLElement method normalizeAdjacentTextNodesPreservingCDATA: (with an argument of NO) to coalesce the text nodes before querying .This convenience method invokes objectsForXQuery:constants:error: with nil for the constants dictionary.

Discussion

Document nodes and standalone nodes (that is, the root of a detached branch of a tree) have no parent, and sending this message to them returns nil. A one-to-one relationship does not always exists between a parent and its children; although a namespace or attribute node cannot be a child, it still has a parent element.

Discussion

The prefix is the part of a namespace-qualified name that precedes the colon. For example, “acme” is the prefix in the qualified name “acme:chapter”.

Discussion

You use this method to “walk” backward through the tree structure representing an XML document or document section. (Use nextNode to traverse the tree in the opposite direction.) Document order is the natural order that XML constructs appear in markup text. If you send this message to the first node in the tree (that is, the root element), nil is returned. NSXMLNode bypasses namespace and attribute nodes when it traverses a tree in document order.

Discussion

This object will have an index value that is one less than the receiver’s. If there are no more previous siblings (that is, other child nodes of the receiver’s parent) the method returns nil

Discussion

If the receiver is a standalone node (that is, a node at the head of a detached branch of the tree), this method returns nil.

Discussion

This method is effective for the following node kinds: element, attribute, namespace, processing-instruction, document type declaration, element declaration, attribute declaration, entity declaration, and notation declaration. If an NSXMLNode object that requires a name doesn’t have one, it cannot be written out as an XML string.

Discussion

This method can only be invoked on NSXMLNode objects that may have content, specifically elements, attributes, namespaces, processing instructions, text, and DTD-declaration nodes. The given object is usually a Foundation equivalent to one of the atomic types in the XQuery data model: NSNumber (integer, decimal, float, double, Boolean), NSString (string), NSCalendarDate (date), NSData (base64Binary and hexBinary), NSURL (URI), and NSArray (NMTOKENS, IDREFS, ENTITIES). However, you can also set the object value to be a custom value and register a value transformer (that is, an instance of NSValueTransformer) to convert the object value to an XML string representation when the node is asked for its string value.

Setting a node’s object value removes all existing children, including processing instructions and comments. Setting an element node’s object value creates a text node as the sole child. When an NSXMLNode object emits its object-value contents as a string, and it can determine the type of the value, it ensures that it the string is in a canonical form as defined by the W3C XML Schema Data Types specification.

Discussion

This method invokes setStringValue:resolvingEntities:, passing in an argument of NO for the second parameter. This method can only be invoked on NSXMLNode objects that may have content, specifically elements, attributes, namespaces, processing instructions, text, and DTD-declaration nodes. Setting the string value of a node object removes all existing children, including processing instructions and comments. Setting the string value of an element-node object creates a text node as the sole child.

Discussion

User-defined entities not declared in the DTD remain in their unresolved form. This method can only be invoked on NSXMLNode objects that may have content, specifically elements, attributes, namespaces, processing instructions, text, and DTD-declaration nodes. Setting the string value of a node object removes all existing children, including processing instructions and comments. Setting the string value of an element -node object creates a text node as the sole child.

Discussion

The receiver must be an NSXMLElement or NSXMLDocument document, or an attribute (that is, anNSXMLNode object of type NSXMLAttributeKind). For documents it is the URI of document origin.

Discussion

If the receiver is a node object of element kind, the content is that of any text-node children. This method recursively visits elements nodes and concatenates their text nodes in document order with no intervening spaces. If the receiver’s content is set as an object value, this method returns the string value representing the object. If the object value is one of the standard, built-in ones (NSNumber, NSCalendarDate, and so on), the string value is in canonical format as defined by the W3C XML Schema Data Types specification. If the object value is not represented by one of these classes (or if the default value transformer for a class has been overridden), the string value is generated by the NSValueTransformer registered for that object type.

Discussion

A node’s URI is derived from its namespace or a document’s URI; for documents, the URI comes either from the parsed XML or is explicitly set. You cannot change the URI for a particular node other for than a namespace or document node.

Discussion

The returned string includes the string representations of all children. This method invokes XMLStringWithOptions: with an options argument of NSXMLNodeOptionsNone.

Discussion

The returned string includes the string representations of all children.

Discussion

For example, this method might return a string such as “foo/bar[2]/baz”. The result of this method can be used directly in the nodesForXPath:error: and objectsForXQuery:constants:error: methods.