matlab.io.xml.dom.Document Class

Namespace: matlab.io.xml.dom

XML Document

Since R2021a

Description

An object of the matlab.io.xml.dom.Document class represents an XML document. To create an XML document, you create a Document object. If you use a matlab.io.xml.dom.Parser object to read an XML file, the parser creates a Document object.

The matlab.io.xml.dom.Document class is a handle class.

Class Attributes

ConstructOnLoad	true
HandleCompatible	true

For information on class attributes, see Class Attributes.

Creation

Description

doc = matlab.io.xml.dom.Document() creates an empty document.

doc = matlab.io.xml.dom.Document(docElemName) creates a document with a root element that has the specified name.

The root element is a matlab.io.xml.dom.Element object with the TagName property set to docElemName.

doc = matlab.io.xml.dom.Document(docElemName,docTypeName,publicId,systemId) also specifies the document type.

The document type is a matlab.io.xml.dom.DocumentType object with the Name property set to docTypeName, the PublicID property set to publicID, and the SystemID property set to systemID.

doc = matlab.io.xml.dom.Document(docElemNSURI,docElemQName) creates a document with a root element that has the specified namespace Uniform Resource Identifier (URI) and qualified name.

doc = matlab.io.xml.dom.Document(docElemNSURI,docElemQName,docTypeName,publicId,systemId) creates a document with the specified root element and document type where the root element resides in the specified namespace.

Input Arguments

docElemName — Root element name

character vector | string scalar

Root element name, specified as a character vector or string scalar.

docTypeName — Name of DTD

character vector | string scalar

Name of Document Type Definition (DTD), specified as a character vector or string scalar.

publicId — Document type public identifier

character vector | string scalar

Document type public identifier, specified as a character vector or string scalar.

systemId — Document type system identifier

character vector | string scalar

Document type system identifier, specified as a character vector or string scalar.

docElemNSURI — Namespace URI for root element name

character vector | string scalar

Namespace Uniform Resource Identifier (URI) for root element name, specified as a character vector or string scalar.

docElemQName — Qualified root element name

character vector | string scalar

Qualified root element name, specified as a character vector or string scalar.

Properties

Children — Child node of this document

1-by-0 matlab.io.xml.dom.Node object (default) | matlab.io.xml.dom.Element object

Child node of this document, specified as a matlab.io.xml.dom.Element object.

Attributes:

GetAccess	public
SetAccess	immutable
NonCopyable	true
Transient	true

InputEncoding — Character encoding of source XML

'' (default) | character vector

Character encoding of the source XML file from which this document was parsed, specified as a character vector.

Example: 'utf-8'

Attributes:

GetAccess	public
SetAccess	immutable
Transient	true
NonCopyable	true

XMLEncoding — Character encoding defined by XML declaration

'' (default) | character vector

Character encoding defined by a XML declaration in the source XML file from which this document was parsed, specified as a character vector.

Example: 'utf-8'

Attributes:

GetAccess	public
SetAccess	immutable
Transient	true
NonCopyable	true

XMLStandalone — Whether this document is standalone

false (default) | true

Whether this document is standalone, specified as true or false. If this value is true, a parser ignores Document Type Definition (DTD) markup declarations in the XML. If this document is created from XML source that declares that the XML is standalone, the parser sets this property to true.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

XMLVersion — XML version of this document

'' (default) | character vector

XML version of this document, specified as a character vector. If this document is created from XML source that declares the XML version, the parser sets this property to the specified version.

Example: '1.0'

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

DocumentURI — URI of document source file

'' (default) | character vector

Universal Resource Identifier (URI) of the document source file, specified as a character vector. If this document is created from a file, the parser sets this property to a URI that specifies the location of the file.

Attributes:

GetAccess	public
SetAccess	public
NonCopyable	true

Configuration — Document configuration

matlab.io.xml.dom.DocumentConfiguration object

Document configuration, specified as a matlab.io.xml.dom.DocumentConfiguration object that specifies options for normalizing this document.

Attributes:

GetAccess	public
SetAccess	immutable
NonCopyable	true
Transient	true

Methods

Public Methods

appendChild	childNode = appendChild(thisDoc,childNode) appends a node to this Document node and returns the appended node.
cloneNode	docClone = cloneNode(thisDoc,deep) creates and returns a copy of this matlab.io.xml.dom.Document object. If deep is true, the copy is a deep copy. If deep is false, the copy is a shallow copy.
createAttribute	attr = createAttribute(thisDoc,attrName) returns a matlab.io.xml.dom.Attr object with the Name property set to the value of attrName. Specify attrName as a character vector or string scalar.
createAttributeNS	attr = createAttributeNS(thisDoc,namespaceURI,qualifiedName) creates and returns a matlab.io.xml.dom.Attr object with these values that are returned by these property getter functions: Getter function Returns getNodeName Value of the qualifiedName argument getNamespaceURI Value of namespaceURI argument getPrefix Prefix, extracted from the qualified name. If there is no prefix, this value is an empty string. getLocalName Local name, extracted from qualified name getName Value of the qualifiedName argument getNodeValue Empty string
createComment	comment = createComment(thisDoc,charData) creates and returns a matlab.io.xml.dom.Comment object with the TextContent property set to the value of charData. Specify charData as a character vector or string scalar.
createDocumentFragment	frag = createDocumentFragment(thisDoc) creates and returns a document fragment as a matlab.io.xml.dom.DocumentFragment object.
createElement	elem = createElement(thisDoc,elemName) creates and returns a matlab.io.xml.dom.Element object with the TagName property set to elemName. If this document has a document type that defines default attributes, this method adds the default attributes to the element that it creates. Specify elemName as a character vector or string scalar.
createElementNS	elem = createElementNS(thisDoc,namespaceURI,qualifiedName) creates and returns a matlab.io.xml.dom.Element object in the specified namespace with the TagName property set to the qualified name. If this document has a document type that defines default attributes, this method adds the default attributes to the element that it creates. Specify namespaceURI and qualifiedName as character vectors or string scalars.
createNSResolver	resolver = createNSResolver(thisDoc,resolverNode) creates and returns a matlab.io.xml.dom.XPathNSResolver object that uses the specified node to find the namespace for the prefix of a qualified element name that occurs in an XPath expression.
createProcessingInstruction	pi = createProcessingInstruction(thisDoc,target,charData) creates and returns a matlab.io.xml.dom.ProcessingInstruction object with the specified target and data. Specify target and charData as character vectors or string scalars.
createTextNode	textNode = createTextNode(thisDoc,charData) creates and returns a matlab.io.xml.dom.Text object that contains the specified character data. Specify charData as a character vector or string scalar.
getAttributes	attrs = getAttributes(thisDoc) returns an empty matlab.io.xml.dom.NamedNodeMap object because documents do not have attributes. This method provides compatibility with existing MATLAB® code that is based on the W3C XML DOM standard.
getBaseURI	name = getBaseURI(thisDoc) returns the base Universal Resource Identifier (URI) of this element as a character vector. If the base URI is not known, the method returns an empty character array. The base URI of a document is the URI of the XML file from which it was created.
getChildNodes	nodeList = getChildNodes(thisDoc) returns the children of this document as a matlab.io.xml.dom.NodeList object.
getChildren	nodes = getChildren(thisDoc) returns a 1-by-N array of objects, such as matlab.io.xml.dom.Element or matlab.io.xml.dom.Text objects, that represent the children of this document.
getDoctype	doctype = getDoctype(thisDoc) returns the matlab.io.xml.dom.DocumentType object associated with this document.
getDocumentElement	elem = getDocumentElement(thisDoc) returns the matlab.io.xml.dom.Element object that represents the root element of this document. If this document does not have a root element, the method returns an empty Element object. The root element contains the content of the document.
getDocumentURI	uri = getDocumentURI(thisDoc) returns the Uniform Resource Identifier (URI) of this document as a character vector. If the document was created from a file, this method returns the URI of the file. If the URI cannot be determined, this method returns an empty character vector. You can use the setDocumentURI method to set or change the URI of a document.
getDOMConfig	config = getDOMConfig(thisDoc) returns the matlab.io.xml.dom.DocumentConfiguration object associated with this document. The DocumentConfiguration object specifies options for normalizing the document.
getElementByID	elem = getElementByID(thisDoc,id) returns the element with the specified ID attribute or an empty element if the document does not have the attribute. An ID attribute is an attribute that is declared to be an ID attribute. An attribute with the name ID is not an ID attribute unless it is declared to be an ID attribute.
getElementsByTagName	list = getElementsByTagName(thisDoc,localName) returns a matlab.io.xml.dom.NodeList object that lists the elements in this document that match the specified tag name. The elements are listed in the order in which they occur in the document. The string scalar "*" or character vector '*' matches any URI or local name. The returned NodeList is updated immediately to reflect changes in the element content of the document.
getElementsByTagNameNS	list = getElementsByTagNameNS(thisDoc,namespaceURI,localName) returns a matlab.io.xml.dom.NodeList object that lists the elements in this document that match the specified URI and local name. The elements are listed in the order in which they occur in the document. The string scalar "*" or character vector '*' matches any URI or local name. The returned NodeList is updated immediately to reflect changes in the element content of the document.
getFirstChild	child = getFirstChild(thisNode) returns the first child of this document.
getInputEncoding	encoding = getInputEncoding(thisDoc) returns the character encoding of the source file for this document as a character vector. If the document was not created from a file, the method returns an empty character vector.
getLastChild	child = getLastChild(thisDoc) returns the last child of this document.
getLocalName	name = getLocalName(thisDoc) returns an empty character vector because documents do not have local names.
getNamespaceURI	uri = getNamespaceURI(thisDoc) returns an empty string because documents do not reside in namespaces. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getNextSibling	getNextSibling(thisDoc) returns a 0-by-0 matlab.io.xml.dom.Node object because a document does not have siblings. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getNodeName	name = getNodeName(thisDoc) returns '#document', which is the W3C XML DOM standard name for a document. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getNodeType	type = getNodeType(thisDoc) returns the integer 9, which indicates that this node is a document. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard. For new MATLAB code, use isa to determine the type of a node. For example: import matlab.io.xml.dom.* d = Document('book'); if isa(d,'matlab.io.xml.dom.Document') fprintf('This is a document.\n'); end
getNodeValue	value = getNodeValue(thisDoc) returns an empty character vector because documents do not have a node value. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getOwnerDocument	doc = getOwnerDocument(thisDoc) returns this document as a matlab.io.xml.dom.Document object.
getParentNode	parent = getParentNode(thisDoc) returns a 0-by-0 matlab.io.xml.dom.Node object because a document does not have a parent node.
getPrefix	prefix = getPrefix(thisDoc) returns an empty character vector because documents do not have a qualified name. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getPreviousSibling	getPreviousSibling(thisDoc) returns a 0-by-0 matlab.io.xml.dom.Node object because a document does not have siblings. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
getTextContent	getTextContent(thisDoc) returns an empty character array because a document does not have text.
getXmlEncoding	encoding = getXmlEncoding(thisDoc) returns the character encoding of a document, for example UTF-8, as a character vector. The character encoding can be defined by an XML declaration in the file from which a Document object is created. If the character encoding is not declared in the file or if the document is not created from a file, getXmlEncoding returns an empty character array.
getXMLStandalone	tf = getXMLStandalone(thisDoc) returns true if this document is declared to be standalone. When a document is standalone, the parser ignores markup declarations in the document Document Type Definition (DTD). You can specify that a document is standalone by using an XML declaration in the file from which a Document object is created or by using the setXMLStandalone method with the object.
getXMLVersion	version = getXMLVersion(thisDoc) returns the XML version of this document as a character vector. You can specify the XML version by using an XML declaration in the file from which a Document object is created.
hasAttributes	tf = hasAttributes(thisDoc) returns false because documents do not have attributes. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
hasChildNodes	tf = hasChildNodes(thisDoc) returns true if this document node has children.
importNode	Import node from another document into this document. See importNode.
isDefaultNamespace	tf = isDefaultNamespace(thisDoc,namespaceURI) returns true if the namespace specified by namespaceURI is the default namespace for this document. Specify namespaceURI as a character vector or string scalar. A default namespace is declared without a prefix. Child nodes of the document with names that lack a prefix belong to the default workspace. To declare a default namespace for a document, you can use the Document(namespaceURI,qualifiedName) syntax to create the document. For example: import matlab.io.xml.dom.* nsURI = "http://my.namespace.org/mybook"; d = Document(nsURI,'book'); if isDefaultNamespace(d,nsURI) fprintf(... '"%s" is the default namepace\n',nsURI); end
isEqualNode	tf = isEqualNode(thisDoc,otherNode) returns true if the node specified by otherNode is a document, has the same base URI, and has an equal subtree. This method tests for equality of documents, not whether the documents nodes are handles to the same object. To test for sameness, use isSameNode. Nodes that are the same are also equal, but node that are equal are not necessarily the same. Normalize documents before testing them for equality because normalization can affect equality.
isSameNode	tf = isSameNode(thisDoc,otherDoc) returns true if the document node specified by otherDoc is the same as this document node.
lookupNamespaceURI	uri = lookupNamespaceURI(thisDoc,prefix) returns an empty character vector because documents do not reside in namespaces. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
lookupPrefix	prefix = lookupPrefix(thisDoc,namespaceURI) returns an empty character vector because documents do not reside in namespaces. This method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
normalize	normalize(thisDoc) has no effect.
normalizeDocument	normalizeDocument(thisDoc) normalizes this document. Normalization ensures that the document structure is the same as the structure after saving and reloading the document. For example, the method removes empty text nodes, merges adjacent text nodes, adds missing namespace attributes, adds or changes prefixes, and updates the replacement trees of entity reference nodes. The normalization operations performed by this method depend on the options specified by the matlab.io.xml.dom.DocumentConfiguration object used by the document.
removeChild	child = removeChild(thisDoc,child) removes the child node specified by child from this document and returns the removed child.
replaceChild	child = replaceChild(thisDoc,newChild,oldChild) replaces the child node specified by oldChild with the node specified by newChild and returns newChild. If the new child is already in the document tree, the method removes the child from the document before it replaces the old child.
renameNode	renamedNode = renameNode(thisDoc,node,namespaceURI,name) renames and returns the specified node. The renamed node has the name specified by the name argument. Specify: node as a matlab.io.xml.dom.Element or matlab.io.xml.dom.Attr object. name as a character vector or string scalar. The value of name can include a prefix. namespaceURI as a character vector or string scalar. If the value of namespaceURI is not empty, the renamed node resides in the specified namespace.
setDocumentURI	setDocumentURI(thisDoc,locationURI) sets the DocumentURI property to the location specified by locationURI. Specify locationURI as a character vector or string character.
setNodeValue	setNodeValue has no effect. The method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
setPrefix	setPrefix has no effect. The method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
setTextContent	setTextContent has no effect. The method provides compatibility with existing MATLAB code that is based on the W3C XML DOM standard.
setXMLStandalone	setXMLStandalone(thisDoc,true) declares that this document is standalone. When a document is standalone, the parser ignores markup declarations in the document Document Type Definition (DTD). setXMLStandalone(thisDoc,false) declares that this document is not standalone.
xmlwrite	xmlwrite(thisDoc,filePath) writes this document to the file specified by filePath. Specify filePath as a character vector or string scalar.

Examples

Create a Document from an XML File

Use an XML parser to create a Document object from the file days.xml.

import matlab.io.xml.dom.*

doc = parseFile(Parser,"days.xml");

Create a Document

Create a document with a root element named weekdays. Append content to the root element.

import matlab.io.xml.dom.*
doc = Document("weekdays");
docRootNode = getDocumentElement(doc);

weekdays = ["Mon" "Tue" "Wed" "Thu" "Fri"];
for i=1:5
    dayElement = createElement(doc,"day");
    appendChild(dayElement,createTextNode(doc,weekdays(i)));
    appendChild(docRootNode,dayElement);
end

xmlFileName = "weekdays.xml";
writer = matlab.io.xml.dom.DOMWriter;
writeToFile(writer,doc,xmlFileName);

Version History

Introduced in R2021a