AllowXmlElement (XmlDoc property): Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (fix "using boolean enumerations" link)
mNo edit summary
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{Template:XmlDoc:AllowXmlElement subtitle}}
{{Template:XmlDoc:AllowXmlElement subtitle}}
The <var>AllowXmlElement </var> property indicates whether or not the method object <var>XmlDoc</var> allows the deserialization of an XML document that contains Elements that begin with the character sequence <code>xml</code> (regardless of case).
The <var>AllowXmlElement </var> property indicates whether or not the method object <var>XmlDoc</var> allows the deserialization of an XML document that contains [[XmlDoc API#XmlDoc node types|Element nodes]] that begin with the character sequence <code>xml</code> (regardless of case).
   
   
A <var>[[Boolean]]</var> value of <var>True</var> allows such deserializations. The default value, <code>False</code>, cancels the request if such a deserialization is attempted.
A <var>[[Enumerations#Using Boolean enumerations|Boolean]]</var> value of <var>True</var> allows such deserializations. The default value, <var>False</var>, cancels the request if such a deserialization is attempted.
   
   
==Syntax==
==Syntax==
{{Template:XmlDoc:AllowXmlElement syntax}}
{{Template:XmlDoc:AllowXmlElement syntax}}
===Syntax terms===
===Syntax terms===
<table class="syntaxTable">
<table class="syntaxTable">
<tr><th>%currentBoolean</th>
<tr><th>%currentBoolean</th>
<td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowXmlElement</var> property. For more information about these enumerations, see [[Enumerations#Using_Boolean_enumerations|"Using Boolean enumerations"]].</td></tr>
<td>The <var>Boolean</var> enumeration value of <var class="term">doc</var>'s <var>AllowXmlElement</var> property. </td></tr>
 
<tr><th>doc</th>
<tr><th>doc</th>
<td>An <var>XmlDoc</var> object expression.</td></tr>
<td>An <var>XmlDoc</var> object expression.</td></tr>
<tr><th>newBoolean</th>
<tr><th>newBoolean</th>
<td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowXmlElement</var> property.</td></tr>
<td>The <var>Boolean</var> value to assign to <var class="term">doc</var>'s <var>AllowXmlElement</var> property.</td></tr>
Line 24: Line 27:
Therefore, you should use care with element names: using an element name such as <code>XML</code> makes you vulnerable to a change in the standards that would leave your document incompatible with them.
Therefore, you should use care with element names: using an element name such as <code>XML</code> makes you vulnerable to a change in the standards that would leave your document incompatible with them.
   
   
'''Note:''' This property does not allow the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var> method to add an element with a name that starts with "xml".  However, as shown in the [[#Adding an element to a document|"Adding an element to a document"]] example below, it is easy to use the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> method to accomplish this.
<p class="note">'''Note:''' This property does not allow the <var>[[AddElement_(XmlDoc/XmlNode_function)|AddElement]]</var> method to add an element with a name that starts with "xml".  However, as shown in the [[#Adding an element to a document|Adding an element to a document]] example below, it is easy to use the <var>[[LoadXml_(XmlDoc/XmlNode_function)|LoadXml]]</var> method to accomplish this. </p>
<li>The <var>AllowXmlElement</var> method was introduced in <var class="product">[[Sirius Mods|"Sirius Mods"]]</var> Version 7.3, and it has also been provided by maintenance for Version 6.8 and Version 7.2.
</ul>
</ul>
   
   
Line 33: Line 35:
<p class="code">%str = %doc:AllowXmlElement:ToString
<p class="code">%str = %doc:AllowXmlElement:ToString
</p>
</p>
Taking advantage of the implicit-[[ToString]] feature, you can print this value directly by using this:
Taking advantage of the [[Enumerations#Usage Notes|implicit-ToString]] feature, you can print this value directly by using this:
<p class="code">print %doc:AllowXmlElement
<p class="code">print %doc:AllowXmlElement
</p>
</p>
===Deserializing an entire XML document===
===Deserializing an entire XML document===
The following request:
The following request:
Line 48: Line 51:
<p class="output">%d:allowXmlElement is True
<p class="output">%d:allowXmlElement is True
</p>
</p>
'''Note:''' Using the PrintText statement is described in <var>[[PrintText statement|printText]]</var>.
 
Printing an enumeration value without a <var>ToString</var> method is described in the first "Note" in [[??]] refid=crenums..
===Adding an element to a document===
===Adding an element to a document===
The following request:
The following request:
Line 67: Line 69:
</nowiki></p>
</nowiki></p>


==Request-Cancellation Errors (for set method)==
==Request-cancellation errors (for set method)==
This list is not exhaustive: it does <i>not</i> include all the errors that are request  cancelling.
<ul>
<ul>
<li><var class="term">newBoolean</var> is an invalid value (ie: not a <var>[[Boolean Enumeration|Boolean]]</var> value).
<li>The <var class="term">newBoolean</var> argument is an invalid value (that is, not a <var>Boolean</var> value).
</ul>
</ul>
 
==See also==
==See also==
{{Template:XmlDoc:AllowXmlElement footer}}
{{Template:XmlDoc:AllowXmlElement footer}}

Latest revision as of 17:20, 3 March 2014

May Element names begin with "xml"? (XmlDoc class)

The AllowXmlElement property indicates whether or not the method object XmlDoc allows the deserialization of an XML document that contains Element nodes that begin with the character sequence xml (regardless of case).

A Boolean value of True allows such deserializations. The default value, False, cancels the request if such a deserialization is attempted.

Syntax

%currentBoolean = doc:AllowXmlElement doc:AllowXmlElement = newBoolean

Syntax terms

%currentBoolean The Boolean enumeration value of doc's AllowXmlElement property.
doc An XmlDoc object expression.
newBoolean The Boolean value to assign to doc's AllowXmlElement property.

Usage notes

  • Deserializing Elements whose name begins with "xml" was restricted due to the following excerpt from the XML standard:
    • Names beginning with the string "xml", or any string which would match (('X'|'x') ('M'|'m') ('L'|'l')), are reserved for standardization in this or future versions of this specification.

    Therefore, you should use care with element names: using an element name such as XML makes you vulnerable to a change in the standards that would leave your document incompatible with them.

    Note: This property does not allow the AddElement method to add an element with a name that starts with "xml". However, as shown in the Adding an element to a document example below, it is easy to use the LoadXml method to accomplish this.

Examples

Displaying the property

The following example obtains the string value of the AllowXmlElement property:

%str = %doc:AllowXmlElement:ToString

Taking advantage of the implicit-ToString feature, you can print this value directly by using this:

print %doc:AllowXmlElement

Deserializing an entire XML document

The following request:

begin %d object xmlDoc auto new %d:AllowXmlElement = true %d:loadXml('<t>Test<xmlnode></xmlnode></t>') printText{~} is {%d:allowXmlElement} end

prints

%d:allowXmlElement is True

Adding an element to a document

The following request:

begin %d object xmlDoc auto new %n object xmlNode %n = %d:addElement('xyz') %d:allowXmlElement = true %n:LoadXml('<xmlElt/>') %d:print end

prints

<xyz> <xmlElt/> </xyz>

Request-cancellation errors (for set method)

This list is not exhaustive: it does not include all the errors that are request cancelling.

  • The newBoolean argument is an invalid value (that is, not a Boolean value).

See also