Description
The PBDOM_PROCESSINGINSTRUCTION class defines behavior for an XML processing instruction. Methods allow you to obtain the target of the processing instruction object as well as its data. You can always access the data as a string, and, where appropriate, as name/value pairs.
Note that the actual processing instruction of a processing instruction object is a string, even if the instruction is divided into separate name="value" pairs. PBDOM does support such a processing instruction object format. If the processing instruction object data does contain pairs, as is commonly the case, then PBDOM_PROCESSINGINSTRUCTION parses them into an internal list of name/value pairs.
Methods
Some of the inherited methods from PBDOM_OBJECT serve no meaningful objective, and only default or trivial functionalities result. These are described in the following table:
|
Method |
Always returns |
|---|---|
|
AddContent |
Current PBDOM_PROCESSINGINSTRUCTION. Use AddValue instead. |
|
GetContent |
false. Use GetName and GetValue instead. |
|
HasChildren |
false. |
|
InsertContent |
Current PBDOM_PROCESSINGINSTRUCTION. |
|
IsAncestorObjectOf |
false. |
|
RemoveContent |
false. Use RemoveValue instead. |
|
SetContent |
Current PBDOM_PROCESSINGINSTRUCTION. Use SetData instead. |
PBDOM_PROCESSINGINSTRUCTION has the following methods:
Description
Creates and returns a clone of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.Clone(boolean bDeep)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object. |
|
bDeep |
A boolean specifying whether a deep or shallow clone is returned. Values are true for a deep clone and false for a shallow clone. This argument is currently ignored. |
Return value
PBDOM_OBJECT. A clone of the current PBDOM_PROCESSINGINSTRUCTION object returned as a PBDOM_OBJECT.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the internal implementation of this PBDOM_PROCESSINGINSTRUCTION object is null. The occurrence of this exception is rare, but it can take place if severe memory corruption occurs.
Usage
The Clone method creates a new PBDOM_PROCESSINGINSTRUCTION object that is a duplicate of, and a separate object from, the original. The clone of a PBDOM_PROCESSINGINSTRUCTION object is always identical to its original whether bDeep is true or false, because a PBDOM_PROCESSINGINSTRUCTION object contains no subtree of child PBDOM_OBJECTs.
A PBDOM_PROCESSINGINSTRUCTION clone has no parent, but it resides in the same PBDOM_DOCUMENT as its original, and if the original PBDOM_PROCESSINGINSTRUCTION object is standalone, so is the clone.
Description
Detaches a PBDOM_PROCESSINGINSTRUCTION object from its parent PBDOM_OBJECT.
Syntax
pbdom_pi_name.Detach()
Return value
PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object detached from its parent object. This method does nothing if this PBDOM_PROCESSINGINSTRUCTION object has no parent.
Description
Tests for the equality of the current PBDOM_PROCESSINGINSTRUCTION object with the supplied PBDOM_OBJECT.
Syntax
pbdom_pi_name.Equals(pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
pbdom_object_ref |
A PBDOM_OBJECT for testing for equality with the current PBDOM_PROCESSINGINSTRUCTION object |
Return value
Boolean.
Returns true if the current PBDOM_PROCESSINGINSTRUCTION object is equivalent to the input PBDOM_OBJECT, and false otherwise.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
Description
Returns the raw data of the PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetData()
Return value
String.
The data of the PBDOM_PROCESSINGINSTRUCTION object.
Usage
The processing instruction data is fundamentally a string and not a set of name="value" pairs.
Description
Obtains the name of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetName()
Return value
String.
Examples
Calling the GetName method on the following processing instruction returns works:
<?works document="hello.doc" data="hello.wks" ?>
Usage
This method is similar to the GetTarget method. To PBDOM, the processing instruction target is synonymous with its name.
Description
Retrieves a list of names taken from the part of the PBDOM_PROCESSINGINSTRUCTION object's data that is factored into name="value" pairs. This method can be used in conjunction with the GetValue method.
Syntax
pbdom_pi_name.GetNames(string name_array[ ])
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
name_array |
An unbounded string array filled with names |
Return value
Boolean.
Returns true if a list of names is retrieved, and false otherwise. If there are no name/value pairs, this method returns false.
Examples
Given the following PBDOM_PROCESSINGINSTRUCTION object, GetNames returns three strings, a, b, and c, even though a occurs more than once:
<? dw-set_values a="1" b="2" c="3" a="4" ?>
When the GetValue method is called on a, the value 4 is returned, because it is the last value set for a.
Usage
If a name is used more than once as the name of a name/value pair in a PBDOM_PROCESSINGINSTRUCTION object, then the value set in the last occurrence of the name is used, and values declared in all previous occurrences of the name are discarded.
Description
Returns a long integer code that indicates the class of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetObjectClass()
Return value
Long.
GetObjectClass returns a long integer code that indicates the class of the current PBDOM_OBJECT. If pbdom_pi_name is a PBDOM_PROCESSINGINSTRUCTION object, the returned value is 10.
Description
Returns a string form of the class of the PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetObjectClassString()
Return value
String.
GetObjectClassString returns a string that indicates the class of the current PBDOM_OBJECT. If pbdom_pi_name is a PBDOM_PROCESSINGINSTRUCTION, the returned string is "pbdom_processinginstruction".
Description
Returns the owning PBDOM_DOCUMENT of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetOwnerDocumentObject()
Return value
PBDOM_DOCUMENT. If there is no owning PBDOM_DOCUMENT, null is returned.
Description
Returns the parent PBDOM_OBJECT of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetParentObject()
Return value
PBDOM_OBJECT. The parent of the PBDOM_PROCESSINGINSTRUCTION object. If there is no parent, null is returned.
Description
Returns the target of the PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetTarget()
Return value
String.
The target of the PBDOM_PROCESSINGINSTRUCTION object.
Examples
Given the following PBDOM_PROCESSINGINSTRUCTION object, calling the GetTarget method returns the string "xml-stylesheet":
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Calling the GetName method returns the same string.
See also
Description
Obtains text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.GetText()
Return value
String.
Usage
The GetText method returns the text data of the current PBDOM_PROCESSINGINSTRUCTION object. GetText is similar to GetData. However, the textual content of a processing instruction object is not a text node.
See also
Description
Obtains the text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object with all surrounding whitespace characters removed and internal whitespace characters normalized to a single space.
Syntax
pbdom_pi_name.GetTextNormalize()
Return value
String.
The normalized text content of the PBDOM_PROCESSINGINSTRUCTION object. If no textual value exists for the current PBDOM_OBJECT, or if only whitespace characters exist, an empty string is returned.
See also
Description
Obtains the text data that is contained within the current PBDOM_PROCESSINGINSTRUCTION object with all surrounding whitespaces removed.
Syntax
pbdom_pi_name.GetTextTrim()
Return value
String.
The trimmed text content of the PBDOM_PROCESSINGINSTRUCTION object. If no textual value exists for the current PBDOM_PROCESSINGINSTRUCTION object, or if only whitespace characters exist, an empty string is returned.
See also
Description
Returns the value for a specific name/value pair on the PBDOM_PROCESSINGINSTRUCTION object. If no such pair is found for the PBDOM_PROCESSINGINSTRUCTION object, an empty string is returned.
Syntax
pbdom_pi_name.GetValue(string strName)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
strName |
String name of name/value pair |
Return value
String.
String name of the name/value pair to search for value.
Examples
Given the following PBDOM_PROCESSINGINSTRUCTION object, GetValue("href") returns the string "simple-ie5.xsl":
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
See also
Description
Removes the specified name/value pair.
Syntax
pbdom_pi_name.RemoveValue(string strName)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
strName |
String name of name/value pair to be removed |
Return value
Boolean.
Returns true if the requested name/value pair is removed and false otherwise.
Examples
Suppose the following PBDOM_PROCESSINGINSTRUCTION object is given:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Then, RemoveValue("href") results in the PBDOM_PROCESSINGINSTRUCTION object being transformed into the following:
<?xml-stylesheet type="text/xsl" ?>
Description
Sets the raw data for the PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.SetData(string strData)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
strData |
New data for the PBDOM_PROCESSINGINSTRUCTION object |
Return value
PBDOM_PROCESSINGINSTRUCTION. The PBDOM_PROCESSINGINSTRUCTION object modified with the new data.
Throws
EXCEPTION_INVALID_STRING -- The input data is invalid. This can happen in the following circumstances:
-
The input data contains the sub-string "?>". This violates the requirements for the data of a processing instruction.
-
If the processing instruction target name is xml, making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing instruction, this exception is thrown if the input data string does not conform to the following criteria:
-
The data must contain a name/value pair for the name version.
-
The data can contain a name/value pair for the name encoding.
-
The data can contain a name/value pair for the name standalone. If it does, the value for standalone must either be yes or no.
-
The data must not contain any other data in the form of name/value pairs or in any other form.
-
Lowercase
The strings xml, version, encoding, standalone, yes, and no are all case sensitive and must be in lowercase.
Examples
Suppose there is a PBDOM_PROCESSINGINSTRUCTION object as follows:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
Then, SetData("href=new.xsl") results in the PBDOM_PROCESSINGINSTRUCTION object being transformed into the following:
<?xml-stylesheet href=new.xsl" ?>
The entire data for the PBDOM_PROCESSINGINSTRUCTION object is now reset.
Usage
Special processing is performed when the name of the processing instruction's target is xml, which indicates that it is an XML declaration. The valid instructions allowed in the input Data as part of the name in the name/value pairs are version, encoding, and standalone. The version instruction is mandatory before the processing instruction can be added to a document.
The XML specification expects the instructions to be in the specific order version , encoding , standalone. This function reorders the input data to conform to the specification, for example:
<? xml version="1.0" encoding="utf-8" standalone="yes"?>
Description
Sets the name of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.SetName(string strName)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
strName |
The new name you want to set for the current PBDOM_PROCESSINGINSTRUCTION object |
Return value
Boolean.
Returns true if the name of the current PBDOM_PROCESSINGINSTRUCTION object was changed, and false otherwise.
Throws
EXCEPTION_INVALID_NAME -- This exception is thrown if the name is invalid. The name can be xml, making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing instruction. However, in this case, the name xml must be in lowercase, or the EXCEPTION_INVALID_NAME exception will be thrown.
EXCEPTION_INVALID_STRING -- This exception is thrown if the name is xml and the current data of this PBDOM_PROCESSINGINSTRUCTION object is not valid. The data is valid only under the following circumstances:
-
It is an empty string.
-
If it is not an empty string, it must contain a name/value pair for the name version.
-
If it is not an empty string and it contains a name/value pair for the name version, it can also contain a name/value pair for the name encoding.
-
If it is not an empty string and it contains a name/value pair for the name version, it can also contain a name/value pair for the name standalone. If it does, the value for standalone must be either yes or no (both are case sensitive).
-
If it is not an empty string and it contains a name/value pair for the name version, it must not contain any other data (in name/value pair format or otherwise) except for encoding and standalone.
Usage
This method is equivalent to setting the target of the processing instruction object. See the list of exceptions for information about the restrictions on the use of xml as the target.
Description
Sets the referenced PBDOM_OBJECT to be the parent of the current PBDOM_PROCESSINGINSTRUCTION object.
Syntax
pbdom_pi_name.SetParentObject(pbdom_object pbdom_object_ref)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
pbdom_object_ref |
A PBDOM_OBJECT to be set as the parent of the current PBDOM_PROCESSINGINSTRUCTION object |
Return value
PBDOM_OBJECT. This PBDOM_PROCESSINGINSTRUCTION object modified.
Throws
EXCEPTION_PBDOM_OBJECT_INVALID_FOR_USE -- If the input PBDOM_OBJECT is not a reference to an object derived from PBDOM_OBJECT.
EXCEPTION_HIERARCHY_ERROR -- If setting the input PBDOM_OBJECT to be the parent of this PBDOM_PROCESSINGINSTRUCTION object will cause the parent PBDOM_OBJECT to be no longer well formed. For example, if this PBDOM_PROCESSINGINSTRUCTION object is an XML declaration and the parent to be set is a PBDOM_ELEMENT.
Usage
The PBDOM_OBJECT that you set as the parent and the current PBDOM_PROCESSINGINSTRUCTION object must have a legal parent-child relationship. Currently, only a PBDOM_ELEMENT and a PBDOM_DOCUMENT can be set as the parent of a PBDOM_PROCESSINGINSTRUCTION object.
Description
Sets the value for the specified name/value pair.
Syntax
pbdom_pi_name.SetValue(string strName, stringstrValue)
|
Argument |
Description |
|---|---|
|
pbdom_pi_name |
The name of a PBDOM_PROCESSINGINSTRUCTION object |
|
strName |
String name of a name/value pair |
|
strValue |
String value of a name/value pair |
Return value
PBDOM_PROCESSINGINSTRUCTION.
Throws
EXCEPTION_INVALID_STRING -- The input strName/strValue is invalid. This can happen in the following circumstances:
-
The input strName/strValue data contains the sub-string ?>. This violates the requirements for the data of a processing instruction.
-
If the target name is xml, making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing instruction, this exception is thrown if the input data string does not conform to the following criterion: the data can contain a name/value pair for the name standalone. If it does, the value for standalone must either be yes or no. The strings xml, standalone, yes, and no are case sensitive and must be lowercase.
EXCEPTION_INVALID_NAME -- The input strName is invalid. This can happen if the target name is xml, making this PBDOM_PROCESSINGINSTRUCTION object an XML declaration processing instruction, and either of the following is true:
-
The strName value is other than version, standalone or encoding.
-
Either standalone or encoding is set without the version first being set.
Examples
Consider the following PBDOM_PROCESSINGINSTRUCTION object:
<?xml-stylesheet href="simple-ie5.xsl" type="text/xsl" ?>
SetValue("href","new.xsl")
transforms this processing instruction to the following, modifying the value for href:
<?xml-stylesheet href="new.xsl" type="text/xsl"?>
SetValue("extra_info","xalan")
transforms the processing instruction to the following, adding a new name/value pair for extra_info:
<?xml-stylesheet href=new.xsl" type="text/xsl" extra_info "xalan" ?>
Then SetValue("extra_info_2","") transforms the processing instruction to the following, adding a new name/value pair for extra_info_2 with an empty string as the value:
<?xml-stylesheet href=new.xsl" type="text/xsl" extra_info="xalan" extra_info_2="" ?>
Usage
If no value is found, the supplied pair is added to the processing instruction data. The appearance of name/value pairs in a PBDOM_PROCESSINGINSTRUCTION object is not subject to any order. In this way, name/value pairs in a PBDOM_PROCESSINGINSTRUCTION object are similar to attributes in an element. Attributes are specifically not ordered.
Special processing is performed when the name of the processing instruction's target is xml, which indicates that it is an XML declaration. The valid instructions allowed in the input Data as part of the name in the name/value pairs are version, encoding, and standalone. The version instruction is mandatory before the processing instruction can be added to a document.
The XML specification expects the instructions to be in this specific order: version , encoding , standalone. This function reorders the input data to conform to the specification, for example:
<? xml version="1.0" encoding="utf-8" standalone="yes"?>
