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.

example

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

expand all

`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

expand all

`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

expand all

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

collapse all

Create a Document from an XML File

Open Live Script

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

Open Live Script

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

matlab.io.xml.dom.Document Class

Description

Class Attributes

Creation

Description

Input Arguments

docElemName — Root element name character vector | string scalar

docTypeName — Name of DTD character vector | string scalar

publicId — Document type public identifier character vector | string scalar

systemId — Document type system identifier character vector | string scalar

docElemNSURI — Namespace URI for root element name character vector | string scalar

docElemQName — Qualified root element name character vector | 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

Attributes:

InputEncoding — Character encoding of source XML '' (default) | character vector

Attributes:

XMLEncoding — Character encoding defined by XML declaration '' (default) | character vector

Attributes:

XMLStandalone — Whether this document is standalone false (default) | true

Attributes:

XMLVersion — XML version of this document '' (default) | character vector

Attributes:

DocumentURI — URI of document source file '' (default) | character vector

Attributes:

Configuration — Document configuration matlab.io.xml.dom.DocumentConfiguration object

Attributes:

Methods

Public Methods

Examples

Create a Document from an XML File

Create a Document

Version History

See Also

`docElemName` — Root element name
character vector | string scalar

`docTypeName` — Name of DTD
character vector | string scalar

`publicId` — Document type public identifier
character vector | string scalar

`systemId` — Document type system identifier
character vector | string scalar

`docElemNSURI` — Namespace URI for root element name
character vector | string scalar

`docElemQName` — Qualified root element name
character vector | string scalar

`Children` — Child node of this document
1-by-0 `matlab.io.xml.dom.Node` object (default) | `matlab.io.xml.dom.Element` object

`InputEncoding` — Character encoding of source XML
`''` (default) | character vector

`XMLEncoding` — Character encoding defined by XML declaration
`''` (default) | character vector

`XMLStandalone` — Whether this document is standalone
`false` (default) | `true`

`XMLVersion` — XML version of this document
`''` (default) | character vector

`DocumentURI` — URI of document source file
`''` (default) | character vector

`Configuration` — Document configuration
`matlab.io.xml.dom.DocumentConfiguration` object