TopLevel
Class XML
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.
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.
children()
:
XMLList
Returns an XMLList containing the children of this XML object, maintaing the sequence in which they appear.
contains(value
:
XML)
:
boolean
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.
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.
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.
inScopeNamespaces()
:
Array
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.
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.
nodeKind()
:
String
Returns the type of the XML object, such as text, comment, processing-instruction, or attribute.
normalize()
:
XML
Merges adjacent text nodes and eliminates and eliminates empty text nodes for this XML object and all its descendents.
parent()
:
Object
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.
setName(name
:
String)
:
void
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.
static settings()
:
Object
Returns the collection of global XML properties: ignoreComments, ignoreProcessingInstructions, ignoreWhitespace, prettyPrinting, prettyIndent, and prettyPrinting.
text()
:
XMLList
Returns returns an XMLList containing all XML properties of this XML object that represent XML text nodes.
toXMLString()
:
String
Returns a XML-encoded String representation of the XML object, including tag and attributed delimiters.
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
public 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.
Method Detail
addNamespace
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
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
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
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
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
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
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
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
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.
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
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
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
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
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
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
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.