Mac Developer Library

Developer

Foundation Framework Reference NSXMLDocument Class Reference

Options
Deployment Target:

On This Page
Language:

NSXMLDocument

An instance of NSXMLDocument represents an XML document as internalized into a logical tree structure. An NSXMLDocument object can have multiple child nodes but only one element, the root element. Any other node must be a NSXMLNode object representing a comment or a processing instruction. If you attempt to add any other kind of child node to an NSXMLDocument object, such as an attribute, namespace, another document object, or an element other than the root, NSXMLDocument raises an exception. If you add a valid child node and that object already has a parent, NSXMLDocument raises an exception. An NSXMLDocument object may also have document-global attributes, such as XML version, character encoding, referenced DTD, and MIME type.

The initializers of the NSXMLDocument class read an external source of XML, whether it be a local file or remote website, parse it, and process it into the tree representation. You can also construct an NSXMLDocument programmatically. There are accessor methods for getting and setting document attributes, methods for transforming documents using XSLT, a method for dynamically validating a document, and methods for printing out the content of an NSXMLDocument as XML, XHTML, HTML, or plain text.

The NSXMLDocument class is thread-safe as long as any given instance is used only in one thread.

Subclassing Notes

Methods to Override

To subclass NSXMLDocument you need to override the primary initializer, initWithData:options:error:, 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 NSXMLDocument implements the NSObject isEqual: method to perform a deep comparison: two NSXMLDocument objects are not considered equal unless they have the same name, same child nodes, same attributes, and so on. The comparison does not consider the parent node (and hence the node’s location). 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 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.

  • Returns the character encoding used for the XML.

    Declaration

    Swift

    var characterEncoding: String?

    Objective-C

    @property(copy) NSString *characterEncoding

    Return Value

    The character encoding used for the XML, or nil if no encoding is specified.

    Discussion

    Typically the encoding is specified in the XML declaration of a document that is processed, but it can be set at any time. If the specified encoding does not match the actual encoding, parsing of the document may fail.

    Availability

    Available in OS X v10.4 and later.

  • Sets the character encoding of the receiver to encoding,

    Declaration

    Swift

    var characterEncoding: String?

    Objective-C

    @property(copy) NSString *characterEncoding

    Parameters

    encoding

    A string that specifies an encoding; it must match the name of an IANA character set. See http://www.iana.org/assignments/character-sets for a list of valid encoding specifiers.

    Discussion

    Typically the encoding is specified in the XML declaration of a document that is processed, but it can be set at any time. If the specified encoding does not match the actual encoding, parsing of the document might fail.

    Availability

    Available in OS X v10.4 and later.

  • Returns the kind of document content for output.

    Declaration

    Swift

    var documentContentKind: NSXMLDocumentContentKind

    Objective-C

    @property NSXMLDocumentContentKind documentContentKind

    Discussion

    Most of the differences among content kind have to do with the handling of content-less tags such as <br>. The valid NSXMLDocumentContentKind constants are NSXMLDocumentXMLKind, NSXMLDocumentXHTMLKind, NSXMLDocumentHTMLKind, and NSXMLDocumentTextKind.

    Availability

    Available in OS X v10.4 and later.

  • Sets the kind of output content for the receiver.

    Declaration

    Swift

    var documentContentKind: NSXMLDocumentContentKind

    Objective-C

    @property NSXMLDocumentContentKind documentContentKind

    Parameters

    kind

    An enum constant identifying a kind of document content. The valid NSXMLDocumentContentKind constants are NSXMLDocumentXMLKind, NSXMLDocumentXHTMLKind, NSXMLDocumentHTMLKind, and NSXMLDocumentTextKind.

    Discussion

    Most of the differences among document-content kind have to do with the handling of content-less tags such as <br>.

    Availability

    Available in OS X v10.4 and later.

  • Returns an NSXMLDTD object representing the internal DTD associated with the receiver.

    Declaration

    Swift

    @NSCopying var DTD: NSXMLDTD?

    Objective-C

    @property(copy) NSXMLDTD *DTD

    Return Value

    An NSXMLDTD object representing the internal DTD associated with the receiver or nil if no DTD has been associated.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setDTD:

  • - setDTD: Available in OS X v10.4 through OS X v10.9

    Sets the internal DTD to be associated with the receiver.

    Declaration

    Objective-C

    - (void)setDTD:(NSXMLDTD *)documentTypeDeclaration

    Parameters

    documentTypeDeclaration

    An NSXMLDTD object representing the internal DTD to be associated with the receiver.

    Discussion

    When the receiver is written out, this document type declaration appears in the output, just after the XML declaration.

    Availability

    Available in OS X v10.4 through OS X v10.9.

    See Also

    – DTD

  • - isStandalone Available in OS X v10.4 through OS X v10.9

    Returns whether the receiver represents a standalone XML document—that is, one without an external DTD.

    Declaration

    Objective-C

    - (BOOL)isStandalone

    Return Value

    YEStrue if the receiver represents a standalone XML document, NOfalse if the “standalone” declaration was not present in the original document and hasn’t been set since.

    Availability

    Available in OS X v10.4 through OS X v10.9.

  • Sets a Boolean value that specifies whether the receiver represents a standalone XML document.

    Declaration

    Swift

    var standalone: Bool

    Objective-C

    @property(getter=isStandalone) BOOL standalone

    Parameters

    standalone

    YEStrue if the receiver represents a standalone XML document, NOfalse otherwise.

    Discussion

    A standalone document does not have an external DTD associated with it.

    Availability

    Available in OS X v10.4 and later.

  • Returns the MIME type for the receiver.

    Declaration

    Swift

    var MIMEType: String?

    Objective-C

    @property(copy) NSString *MIMEType

    Return Value

    The MIME type for the receiver (for example, “text/xml”).

    Discussion

    MIME types are assigned by IANA (see http://www.iana.org/assignments/media-types/index.html).

    Availability

    Available in OS X v10.4 and later.

  • - setMIMEType: Available in OS X v10.4 through OS X v10.9

    Sets the MIME type of the receiver.

    Declaration

    Objective-C

    - (void)setMIMEType:(NSString *)MIMEType

    Parameters

    MIMEType

    A string object identifying a MIME type, for example, “text/xml”. MIME types are assigned by IANA (see http://www.iana.org/assignments/media-types/index.html).

    Availability

    Available in OS X v10.4 through OS X v10.9.

    See Also

    – MIMEType

  • Returns the URI identifying the source of this document.

    Declaration

    Objective-C

    - (NSString *)URI

    Return Value

    The URI identifying the source of this document or nil if this attribute has not been set.

    See Also

    – setURI:

  • Sets the URI identifying the source of this document.

    Declaration

    Objective-C

    - (void)setURI:(NSString *)URI

    Parameters

    URI

    A string object representing a URI source, or nil to remove the current URI.

    Discussion

    This attribute is automatically set when the receiver is initialized using initWithContentsOfURL:options:error:.

    See Also

    – URI

  • Returns the version of the receiver’s XML.

    Declaration

    Swift

    var version: String?

    Objective-C

    @property(copy) NSString *version

    Return Value

    The version of the receiver’s XML or nil if the version has not be set.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setVersion:

  • Sets the version of the receiver’s XML.

    Declaration

    Swift

    var version: String?

    Objective-C

    @property(copy) NSString *version

    Parameters

    version

    A string object identifying the version of the XML.

    Discussion

    Currently, the version should be either “1.0 “or “1.1”.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – version

  • Returns the XML string representation of the receiver—that is, the entire document—encapsulated in a data object.

    Declaration

    Swift

    @NSCopying var XMLData: NSData { get }

    Objective-C

    @property(readonly, copy) NSData *XMLData

    Discussion

    This method invokes XMLDataWithOptions: with an option of NSXMLNodeOptionsNone. The encoding used is based on the value returned from characterEncoding or UTF-8 if no valid encoding is returned by that method.

    Availability

    Available in OS X v10.4 and later.

  • Returns the XML string representation of the receiver—that is, the entire document—encapsulated in a data object.

    Declaration

    Swift

    func XMLDataWithOptions(_ options: Int) -> NSData

    Objective-C

    - (NSData *)XMLDataWithOptions:(NSUInteger)options

    Parameters

    options

    One or more options (bit-OR'd if multiple) to affect the output of the document; see Constants for the valid output options.

    Discussion

    The encoding used is based on the value returned from characterEncoding.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – XMLData

  • Validates the document against the governing schema and returns whether the document conforms to the schema.

    Declaration

    Swift

    func validate() throws

    Objective-C

    - (BOOL)validateAndReturnError:(NSError * _Nullable *)error

    Parameters

    error

    If validation fails, on return contains an NSError object describing the reason or reasons for failure.

    Return Value

    YEStrue if the validation operation succeeded, otherwise NOfalse.

    Discussion

    The constants indicating the kind of validation errors are emitted by the underlying parser; see NSXMLParser.h for most of these constants. If the schema is defined with a DTD, this method uses the NSXMLDTD object set for the receiver for validation. If the schema is based on XML Schema, the method uses the URL specified as the value of the xsi:schemaLocation attribute of the root element.

    You can validate an XML document when it is first processed by specifying the NSXMLDocumentValidate option when you initialize an NSXMLDocument object with the initWithContentsOfURL:options:error:, initWithData:options:error:, or initWithXMLString:options:error: methods.

    Availability

    Available in OS X v10.4 and later.

    See Also

    – setDTD:

Data Types

  • Type used to define the kind of document content.

    Declaration

    Swift

    enum NSXMLDocumentContentKind : UInt { case XMLKind case XHTMLKind case HTMLKind case TextKind }

    Objective-C

    typedef NSUInteger NSXMLDocumentContentKind;

    Discussion

    For possible values, see Document Content Types.

    Import Statement

    Objective-C

    @import Foundation;

    Swift

    import Foundation

    Availability

    Available in OS X v10.4 and later.

  • Input and output options specifically intended for NSXMLDocument objects.

    Declaration

    Swift

    var NSXMLDocumentTidyHTML: Int { get } var NSXMLDocumentTidyXML: Int { get } var NSXMLDocumentValidate: Int { get } var NSXMLDocumentXInclude: Int { get } var NSXMLDocumentIncludeContentTypeDeclaration: Int { get }

    Objective-C

    NSXMLDocumentTidyHTML = 1 << 9, NSXMLDocumentTidyXML = 1 << 10, NSXMLDocumentValidate = 1 << 13, NSXMLDocumentXInclude = 1 << 16, NSXMLDocumentIncludeContentTypeDeclaration = 1 << 18,

    Constants

    • NSXMLDocumentTidyHTML

      NSXMLDocumentTidyHTML

      Formats HTML into valid XHTML during processing of the document.

      When tidying, NSXMLDocument adds a line break before the close tag of a block-level element (<p>, <div>, <h1>, and so on); it also makes the string value of <br> or <hr> a line break. These operations make the string value of the HTML <body> more readable. After using this option, avoid outputting the document as anything other than the default kind, NSXMLDocumentXHTMLKind.

      (Input)

      Available in OS X v10.4 and later.

    • NSXMLDocumentTidyXML

      NSXMLDocumentTidyXML

      Changes malformed XML into valid XML during processing of the document.

      It also eliminates “pretty-printing” formatting, such as leading tab characters. It does respect the xml:space="preserve" attribute.

      (Input)

      Available in OS X v10.4 and later.

    • NSXMLDocumentValidate

      NSXMLDocumentValidate

      Validates this document against its DTD (internal or external) or XML Schema.

      (Input)

      Available in OS X v10.4 and later.

    • NSXMLDocumentXInclude

      NSXMLDocumentXInclude

      Replaces all XInclude nodes in the document with the nodes referred to.

      XInclude allows clients to include parts of another XML document within a document.

      (Input)

      Available in OS X v10.4 and later.

    • NSXMLDocumentIncludeContentTypeDeclaration

      NSXMLDocumentIncludeContentTypeDeclaration

      Includes a content type declaration for HTML or XHTML in the output of the document.

      (Output)

      Available in OS X v10.4 and later.

    Discussion

    Because NSXMLDocument is a subclass of NSXMLNode, you can also use the relevant input and output options described in Constants in the NSXMLNode class reference. You can specify input options in the NSXMLDocument methods initWithContentsOfURL:options:error:, initWithData:options:error:, initWithXMLString:options:error:. The XMLDataWithOptions: method takes output options.

  • Define document types.

    Declaration

    Swift

    case XMLKind case XHTMLKind case HTMLKind case TextKind

    Objective-C

    enum { NSXMLDocumentXMLKind = 0, NSXMLDocumentXHTMLKind, NSXMLDocumentHTMLKind, NSXMLDocumentTextKind };

    Constants

    • XMLKind

      NSXMLDocumentXMLKind

      The default type of document content type, which is XML.

      Available in OS X v10.4 and later.

    • XHTMLKind

      NSXMLDocumentXHTMLKind

      The document output is XHTML.

      This is set automatically if the NSXMLDocumentTidyHTML option is set and NSXML detects HTML.

      Available in OS X v10.4 and later.

    • HTMLKind

      NSXMLDocumentHTMLKind

      Outputs empty tags in HTML without a close tag, such as <br>.

      Available in OS X v10.4 and later.

    • TextKind

      NSXMLDocumentTextKind

      Outputs the string value of the document by extracting the string values from all text nodes.

      Available in OS X v10.4 and later.

    Discussion

    You specify one of the NSXMLDocumentContentKind constants in setDocumentContentKind: to indicate the kind of content required for document output.