Script: Class Top Level XML
Class XML
- Object
- 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:
var id : String = "p42"; var pname : String = "a product";
// use E4X syntax var product : XML = <product id={id}> <name>{pname}</name> <shortdesc></shortdesc> </product>;
product.shortdesc = "a fine product"; product.longdesc = "this is a fine product";
var xmlString = product.toXMLString();
fileWriter.write(xmlString);
The code above will write the following to file:
<product id="p42"> <name>a product</name> <shortdesc>a fine product</shortdesc> <longdesc>this is a fine product</longdesc> </product>
Do not create large XML objects in memory to avoid out-of-memory conditions. When dealing with XML streams use XMLStreamReader and XMLStreamWriter.
Properties
static ignoreComments : boolean
The ignoreComments property determines whether or not XML comments are ignored when XML objects parse the source XML data.
static ignoreProcessingInstructions : boolean
The ignoreProcessingInstructions property determines whether or not XML processing instructions are ignored when XML objects parse the source XML data.
static ignoreWhitespace : boolean
The ignoreWhitespace property determines whether or not white space characters at the beginning and end of text nodes are ignored during parsing.
static 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.
static prettyPrinting : boolean
The prettyPrinting property determines whether the toString() and toXMLString() methods normalize white space characters between some tags.
Constructor Summary
XML()
Creates a new XML object.
Creates a new XML object.
Method Summary
addNamespace(ns : Object) : XML
Adds a namespace to the set of in-scope namespaces for the XML object.
appendChild(child : Object) : XML
Appends the specified child to the end of the object's properties.
attribute(attributeName : String) : XMLList
Returns the attribute associated with this XML object that is identified by the specified name.
attributes() : XMLList
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.
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 an XMLList containing the children of this XML object, maintaing the sequence in which they appear.
Returns the 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.
Returns a copy of the this XML object including duplicate copies of the entire tree of nodes.
static defaultSettings() : Object
Returns a new Object with the following properties set to the default values: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyIndent, and prettyPrinting.
descendants() : XMLList
Returns all descendents of the XML object.
descendants(name : String) : XMLList
Returns all descendents of the XML object that have the specified name parameter.
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.
hasComplexContent() : boolean
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.
hasSimpleContent() : boolean
Returns a Boolean value indicating whether this XML object contains simple content.
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.
insertChildBefore(child1 : Object, child2 : Object) : XML
Inserts the specified child2 before the specified child1 in this XML object and returns this XML object.
Returns a value of 1 for XML objects.
Returns the local name portion of the qualified name of the XML object.
Returns the qualified name for the 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.
namespaceDeclarations() : Array
Returns an Array of namespace declarations associated with the XML Obnject in the context of its parent.
Returns the type of the XML object, such as text, comment, processing-instruction, or attribute.
Merges adjacent text nodes and eliminates and eliminates empty text nodes for this XML object and all its descendents.
Returns the parent of the XML object or 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.
processingInstructions() : XMLList
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.
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.
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.
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.
setChildren(value : Object) : XML
Replaces the XML properties of this XML object with a new set of XML properties from value.
setLocalName(name : String) : void
Replaces the local name of this XML object with a string constructed from the specified name.
Replaces the name of this XML object with a QName or AttributeName constructed from the specified name.
setNamespace(ns : Namespace) : void
Replaces the namespace associated with the name of this XML object with the specified namespace.
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.
Returns the collection of global XML properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyPrinting, prettyIndent, and prettyPrinting.
Returns returns an XMLList containing all XML properties of this XML object that represent XML text nodes.
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 this XML object.
Methods inherited from class Object
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
Constructor Detail
XML
publicXML()
Creates a new XML object.
XML
publicXML(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.
Method Detail
addNamespace
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
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
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
attributes() : XMLList
Returns an XMList of the attributes in this XML Object.
Returns:
an XMList of the attributes in this XML Object.
child
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
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
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
comments() : XMLList
Returns the properties of the XML object that contain comments.
Returns:
properties of the XML object that contain comments.
contains
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
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.
defaultSettings
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
descendants() : XMLList
Returns all descendents of the XML object.
Returns:
a list of all descendents of the XML object.
descendants
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
elements() : XMLList
Returns a list of all of the elements of the XML object.
elements
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
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
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
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
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
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
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
length() : Number
Returns a value of 1 for XML objects.
Returns:
the value of 1.
localName
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
name() : Object
Returns the qualified name for the XML object.
Returns:
the qualified name as either a QName or null.
namespace
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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.
setSettings
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
setSettings
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.
settings
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
text() : XMLList
Returns 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
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
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
valueOf() : XML
Returns this XML object.
Returns:
this XML object.