Class XML

• TopLevel.Object
  • TopLevel.XML

The XML object contains functions and properties for working with XML instances. The XML object implements the powerful XML-handling standards defined in the ECMA-357 specification (known as “E4X”).

Use the toXMLString() method to return a string representation of the XML object regardless of whether the XML object has simple content or complex content.

Do not create large XML objects in memory to avoid out-of-memory conditions. When dealing with XML streams use XMLStreamReader and XMLStreamWriter. The following example shows how:

1var id : String = "p42";
2var pname : String = "a product";
3
4// use E4X syntax
5var product : XML =
6  <product id={id}>
7    <name>{pname}</name>
8    <shortdesc></shortdesc>
9  </product>;
10
11product.shortdesc = "a fine product";
12product.longdesc = "this is a fine product";
13
14var xmlString = product.toXMLString();
15
16fileWriter.write(xmlString);

The code above will write the following to file:

1<product id="p42">
2  <name>a product</name>
3  <shortdesc>a fine product</shortdesc>
4  <longdesc>this is a fine product</longdesc>
5</product>

Do not create large XML objects in memory to avoid out-of-memory conditions. When dealing with XML streams use XMLStreamReader and XMLStreamWriter.

assign, create, create, defineProperties, defineProperty, entries, freeze, fromEntries, getOwnPropertyDescriptor, getOwnPropertyNames, getOwnPropertySymbols, getPrototypeOf, hasOwnProperty, is, isExtensible, isFrozen, isPrototypeOf, isSealed, keys, preventExtensions, propertyIsEnumerable, seal, setPrototypeOf, toLocaleString, toString, valueOf, values

ignoreComments: Boolean

The ignoreComments property determines whether or not XML comments are ignored when XML objects parse the source XML data.

ignoreProcessingInstructions: Boolean

The ignoreProcessingInstructions property determines whether or not XML processing instructions are ignored when XML objects parse the source XML data.

ignoreWhitespace: Boolean

The ignoreWhitespace property determines whether or not white space characters at the beginning and end of text nodes are ignored during parsing.

prettyIndent: Number

The prettyIndent property determines the amount of indentation applied by the toString() and toXMLString() methods when the XML.prettyPrinting property is set to true.

prettyPrinting: Boolean

The prettyPrinting property determines whether the toString() and toXMLString() methods normalize white space characters between some tags.

XML()

Creates a new XML object.

XML(value: Object)

Creates a new XML object. You must use the constructor to create an XML object before you call any of the methods of the XML class. Use the toXMLString() method to return a string representation of the XML object regardless of whether the XML object has simple content or complex content.

Parameters:

• value - any Object that can be converted to XML via the top-level XML() function.

addNamespace(ns: Object): XML

Adds a namespace to the set of in-scope namespaces for the XML object. If the namespace already exists in the in-scope namespaces for the XML object, then the prefix of the existing namespace is set to undefined. If ns is a Namespace instance, it is used directly. However, if ns is a QName instance, the input parameter's URI is used to create a new namespace. If ns is not a Namespace or QName instance, ns is converted to a String and a namespace is created from the String.

Parameters:

• ns - the namespace to add to the XML object.

Returns:

• a new XML object, with the namespace added.

appendChild(child: Object): XML

Appends the specified child to the end of the object's properties. child should be a XML object, an XMLList object or any other data type that will then be converted to a String.

Parameters:

• child - the object to append to this XML object.

Returns:

• the XML object with the child appended.

attribute(attributeName: String): XMLList

Returns the attribute associated with this XML object that is identified by the specified name.

Parameters:

• attributeName - the name of the attribute.

Returns:

• the value of the attribute as either an XMLList or an empty XMLList

attributes(): XMLList

Returns an XMList of the attributes in this XML Object.

Returns:

• an XMList of the attributes in this XML Object.

child(propertyName: Object): XMLList

Returns the children of the XML object based on the specified property name.

Parameters:

• propertyName - the property name representing the children of this XML object.

Returns:

• an XMLList of children that match the property name parameter.

childIndex(): Number

Identifies the zero-based index of this XML object within the context of its parent, or -1 if this object has no parent.

Returns:

• the index of this XML object in the context of its parent, or -1 if this object has no parent.

children(): XMLList

Returns an XMLList containing the children of this XML object, maintaing the sequence in which they appear.

Returns:

• an XMLList containing the children of this XML object.

comments(): XMLList

Returns the properties of the XML object that contain comments.

Returns:

• properties of the XML object that contain comments.

contains(value: XML): Boolean

Returns true if this XML object contains the specified XML object, false otherwise.

Parameters:

• value - the object to locate in this XML object.

Returns:

• true if this XML object contains the specified XML object, false otherwise.

copy(): XML

Returns a copy of the this XML object including duplicate copies of the entire tree of nodes. The copied XML object has no parent.

Returns:

• the copy of the object.

static defaultSettings(): Object

Returns a new Object with the following properties set to the default values: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent, and prettyPrinting. The default values are as follows:

• ignoreComments = true
• ignoreProcessingInstructions = true
• ignoreWhitespace = true
• prettyIndent = 2
• prettyPrinting = true

Be aware that this method does not apply the settings to an existing instance of an XML object. Instead, this method returns an Object containing the default settings.

Returns:

• an Object with properties set to the default settings.

descendants(): XMLList

Returns all descendents of the XML object.

Returns:

• a list of all descendents of the XML object.

descendants(name: String): XMLList

Returns all descendents of the XML object that have the specified name parameter. To return all descendents, use * as the name parameter.

Parameters:

• name - the name of the element to match. To return all descendents, use * as the name parameter.

Returns:

• a list of all descendents constrained by the name parameter.

elements(): XMLList

Returns a list of all of the elements of the XML object.

elements(name: Object): XMLList

Returns a list of the elements of the XML object using the specified name to constrain the list. name can be a QName, String, or any other data type that will be converted to a string prior to performing the search for elements of that name.

To list all objects use * for the value of name.

Parameters:

• name - the name of the elements to return or an * to return all elements.

Returns:

• a list of the elements of the XML object using the specified name to constrain the list.

hasComplexContent(): Boolean

Returns a Boolean value indicating whether this XML object contains complex content. An XML object is considered to contain complex content if it represents an XML element that has child elements. XML objects representing attributes, comments, processing instructions and text nodes do not have complex content. The existence of attributes, comments, processing instructions and text nodes within an XML object is not significant in determining if it has complex content.

Returns:

• a Boolean value indicating whether this XML object contains complex content.

hasOwnProperty(prop: String): Boolean

Returns a Boolean value indicating whether this object has the property specified by prop.

Parameters:

• prop - the property to locate.

Returns:

• true if the property exists, false otherwise.

hasSimpleContent(): Boolean

Returns a Boolean value indicating whether this XML object contains simple content. An XML object is considered to contain simple content if it represents a text node, represents an attribute node or if it represents an XML element that has no child elements. XML objects representing comments and processing instructions do not have simple content. The existence of attributes, comments, processing instructions and text nodes within an XML object is not significant in determining if it has simple content.

Returns:

• a Boolean value indicating whether this XML object contains simple content.

inScopeNamespaces(): Array

Returns an Array of Namespace objects representing the namespaces in scope for this XML object in the context of its parent. If the parent of this XML object is modified, the associated namespace declarations may change. The set of namespaces returned by this method may be a super set of the namespaces used by this value

Returns:

• an Array of Namespace objects representing the namespaces in scope for this XML object in the context of its parent.

insertChildAfter(child1: Object, child2: Object): XML

Inserts the specified child2 after the specified child1 in this XML object and returns this XML object. If child1 is null, inserts child2 before all children of this XML object. If child1 does not exist in this XML object, it returns without modifying this XML object.

Parameters:

• child1 - the child after which child2 is inserted.
• child2 - the child to insert into this XML object.

Returns:

• the updated XML object.

insertChildBefore(child1: Object, child2: Object): XML

Inserts the specified child2 before the specified child1 in this XML object and returns this XML object. If child1 is null, inserts child2 after all children of this XML object. If child1 does not exist in this XML object, it returns without modifying this XML object.

Parameters:

• child1 - the child before which child2 is inserted.
• child2 - the child to insert into this XML object.

Returns:

• the updated XML object.

length(): Number

Returns a value of 1 for XML objects.

Returns:

• the value of 1.

localName(): Object

Returns the local name portion of the qualified name of the XML object.

Returns:

• the local name as either a String or null.

name(): Object

Returns the qualified name for the XML object.

Returns:

• the qualified name as either a QName or null.

namespace(): Object

Returns the namespace associated with the qualified name of this XML object.

Returns:

• the namespace associated with the qualified name of this XML object.

namespace(prefix: String): Object

Returns the namespace that matches the specified prefix and that is in scope for the XML object. if there is no such namespace, the method returns undefined.

Parameters:

• prefix - the prefix to use when attempting to locate a namespace.

Returns:

• the namespace that matches the specified prefix and that is in scope for the XML object. If specified namespace does not exist, the method returns undefined.

namespaceDeclarations(): Array

Returns an Array of namespace declarations associated with the XML Obnject in the context of its parent.

Returns:

• an Array of namespace declarations associated with the XML Obnject in the context of its parent.

nodeKind(): String

Returns the type of the XML object, such as text, comment, processing-instruction, or attribute.

Returns:

• the type of the XML object.

normalize(): XML

Merges adjacent text nodes and eliminates and eliminates empty text nodes for this XML object and all its descendents.

Returns:

• the normalized XML object.

parent(): Object

Returns the parent of the XML object or null if the XML object does not have a parent.

Returns:

• the parent of the XML object of null if the XML object does not have a parent.

prependChild(value: Object): XML

Inserts the specified child into this XML object prior to its existing XML properties and then returns this XML object.

Parameters:

• value - the child to prepend to this XML object.

Returns:

• the XML object updated with the prepended child.

processingInstructions(): XMLList

Returns an XMLList containing all the children of this XML object that are processing-instructions.

Returns:

• an XMLList containing all the children of this XML object that are processing-instructions.

processingInstructions(name: String): XMLList

Returns an XMLList containing all the children of this XML object that are processing-instructions with the specified name. If you use * for the name, all processing-instructions are returned.

Parameters:

• name - the name representing the processing-instructions you want to retreive.

Returns:

• an XMLList containing all the children of this XML object that are processing-instructions with the specified name.

propertyIsEnumerable(property: String): Boolean

Returns a Boolean indicating whether the specified property will be included in the set of properties iterated over when this XML object is used in a for..in statement.

Parameters:

• property - the property to test.

Returns:

• true when the property can be iterated in a for..in statement, false otherwise.

removeNamespace(ns: Namespace): XML

Removes the specified namespace from the in scope namespaces of this object and all its descendents, then returns a copy of this XML object. This method will not remove a namespace from an object when it is referenced by that object's QName or the ONames of that object's attributes.

Parameters:

• ns - the namespace to remove.

Returns:

• a copy of this XML object with the namespace removed.

replace(propertyName: String, value: Object): XML

Replaces the XML properties of this XML object specified by propertyName with value and returns this updated XML object. If this XML object contains no properties that match propertyName, the replace method returns without modifying this XML object.

The propertyName parameter may be a numeric property name, an unqualified name for a set of XML elements, a qualified name for a set of XML elements or the properties wildcard *.

When the propertyName parameter is an unqualified name, it identifies XML elements in the default namespace. The value parameter may be an XML object, XMLList object or any value that may be converted to a String.

Parameters:

• propertyName - a numeric property name, an unqualified name for a set of XML elements, a qualified name for a set of XML elements or the properties wildcard *.
• value - an XML object, XMLList object or any value that may be converted to a String.

Returns:

• the updated XML object.

setChildren(value: Object): XML

Replaces the XML properties of this XML object with a new set of XML properties from value.

Parameters:

• value - a single XML object or an XMLList.

Returns:

• the updated XML object.

setLocalName(name: String): void

Replaces the local name of this XML object with a string constructed from the specified name.

Parameters:

• name - the new local name.

setName(name: String): void

Replaces the name of this XML object with a QName or AttributeName constructed from the specified name.

Parameters:

• name - the new name of this XML object.

setNamespace(ns: Namespace): void

Replaces the namespace associated with the name of this XML object with the specified namespace.

Parameters:

• ns - the namespace to associated with the name of thix XML object.

static setSettings(): void

Restores the default settings for the following XML properties:

• XML.ignoreComments = true
• XML.ignoreProcessingInstructions = true
• XML.ignoreWhitespace = true
• XML.prettyIndent = 2
• XML.prettyPrinting = true

static setSettings(settings: Object): void

Updates the collection of global XML properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyPrinting, prettyIndent, and prettyPrinting.

Parameters:

• settings - an object with each of the following properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent, and prettyPrinting.

static settings(): Object

Returns the collection of global XML properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyPrinting, prettyIndent, and prettyPrinting.

Returns:

• an object with each of the following properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent, and prettyPrinting.

text(): XMLList

Returns an XMLList containing all XML properties of this XML object that represent XML text nodes.

Returns:

• an XMLList containing all XML properties of this XML object that represent XML text nodes.

toString(): String

Returns the String representation of the XML object. If the object contains simple content, this method returns a String with tag, attributes, and namespace declarations removed. However, if the object contains complex content, this method returns an XML encoded String representing the entire XML object. If you want to return the entire XML object regardless of content complexity, use the toXMLString() method.

Returns:

• the String representation of the XML object.

toXMLString(): String

Returns a XML-encoded String representation of the XML object, including tag and attributed delimiters.

Returns:

• the string representation of the XML object.

valueOf(): XML

Returns this XML object.

Returns:

• this XML object.