[[xmlCreate Talk Page|Discuss this page]]

=== xmlCreate ===

^ Syntax | (xmlCreate xml) -> xml |
^ Arguments | xml: The XML or string to use |
^ Returns | A new XML pointer |
^ Category | [[XML functions | XML]]|
^ Description | Creates a new XML pointer from existing XML or converts a string into XML data. String must be properly formatted XML data. |

XML data cannot be treated like a string despite appearing to be one when printed. However, it can be used to create a string using **[[cat]]**, though the result does not have the pointer.

=== XML Pointers ===
This function can be used to create a copy of an XML pointer variable. Consider the following code, where &unidHugoSandoval; is defined as shown below and its XML is then modified.

<code>
	<Type UNID="&unidHugoSandoval;">
		<StaticData>
			<Data id="MissionAttribute">"hugoSandovalMission"</Data>
			<Data id="Name">"Hugo Sandoval"</Data>
			<Data id="Sovereign">&svCommonwealth;</Data>
		</StaticData>

		<Events>
			<OnCharacterCanBeMet>
				True
			</OnCharacterCanBeMet>

			<OnGlobalSystemStopped>
				(rpgCharacterAscend &unidHugoSandoval;)
			</OnGlobalSystemStopped>
		</Events>
	</Type>
</code>
Here is the code that we will apply to this XML
<code>
	(block (xml1 xml2)						;Line 1
		(setq xml1 (typGetXML &unidHugoSandoval;))		;Line 2
		(xmlDeleteSubElement xml1 0)				;Line 3
		(setq xml2 (xmlCreate xml1))				;Line 4
		(xmlDeleteSubElement xml1 0)				;Line 5
		)
</code>

After Line 3, <StaticData> (the first subelement of &unidHugoSandoval;) has been removed and the value of **xml1** looks like this:
<code>
	<Type UNID="&unidHugoSandoval;">
		<Events>
			<OnCharacterCanBeMet>
				True
			</OnCharacterCanBeMet>

			<OnGlobalSystemStopped>
				(rpgCharacterAscend &unidHugoSandoval;)
			</OnGlobalSystemStopped>
		</Events>
	</Type>
</code>
At Line 4, a new copy for the XML data in **xml1** has been created and stored in **xml2**. The two variables have identical values. However, they are separate, so a change to **xml1** will not affect the value of **xml2**. At Line 5, the <Events> element has been deleted from **xml1**, which now looks like this:
<code>
	<Type UNID="&unidHugoSandoval;">
	</Type>
</code>
While **xml2** still looks like this:
<code>
	<Type UNID="&unidHugoSandoval;">
		<Events>
			<OnCharacterCanBeMet>
				True
			</OnCharacterCanBeMet>

			<OnGlobalSystemStopped>
				(rpgCharacterAscend &unidHugoSandoval;)
			</OnGlobalSystemStopped>
		</Events>
	</Type>
</code>


=== XML From Strings ===
The following code creates XML from a string and stores it in the variable **theXML**. Attempting to use **xml**-prefixed functions with a string will lead to an "invalid XML element" error. Note that the angle brackets **<** and **>** need to be escaped with **&lt;** and **&gt;** (respectively) when used outside of the in-game console or the TLisp Shell from TransData, as they are evaluated as part of the string. Furthermore, the quotation marks are also escaped as **\"**.

<code>
	(block (theXML)
		(setq theXML (xmlCreate "<Element attribute=\"5\"/>"))
		)
</code>

In file code, the working equivalent is this:
<code>
	(block (theXML)
		(setq theXML (xmlCreate "&lt;Element attribute=\"5\"/&gt;"))
		)
</code>

This sets the **theXML** to a valid XML data pointer that can be used with other functions.

The following code will not work:
<code>
	;Quotation marks have not been escaped, so this code will be interpreted incorrectly
	(xmlCreate "<Element attribute="5"/>")

	;XML element is not closed. Furthermore, it lacks content
	(xmlCreate "<Element attribute=\"5\">"))

	;XML element is closed, but it still lacks content
	(xmlCreate "<Element attribute=\"5\"></Element>")

	;XML element is closed, but it still lacks content
	(xmlCreate "<Element attribute=\"5\"></Element>")

	;Due to a typo, the end tag has a different name from the open tag
	(xmlCreate "<Element attribute=\"5\"></Elemenf>")

	;Additionally, this code will not work if used in an extension.
	(xmlCreate "<Element attribute=\"5\">")
</code>

The following examples will work:
<code>
	(xmlCreate "<Element/>")
	(xmlCreate "<Element>5</Element>")
	(xmlCreate "<Element>Text</Element>")
	(xmlCreate "<Element attribute=\"5\">Text</Element>")
</code>

[[modding:xml|XML]]

Return to [[modding:function:xml_functions|XML Functions]] list

Return to [[:Functions]] list