XML NSIS plugin v1.2

2005 Shengalts Aleksander aka Instructor (Shengalts@mail.ru)

Contents

	1. Introduction
	2. Features
	3. Output variables
	4. Entities
	5. XML file example
	6. Functions
	Document format
	xml::SetCondenseWhiteSpace /NOUNLOAD "[1|0]"
	xml::SetEncoding /NOUNLOAD "[encoding]"
	Document file
	xml::LoadFile /NOUNLOAD "[file]" .r0
	xml::SaveFile "[file]" .r0
	Declaration node
	xml::DeclarationVersion /NOUNLOAD .r0 .r1
	xml::DeclarationEncoding /NOUNLOAD .r0 .r1
	xml::DeclarationStandalone /NOUNLOAD .r0 .r1
	Text node
	xml::GetText /NOUNLOAD .r0 .r1
	xml::SetCDATA /NOUNLOAD "[0|1]" .r0
	xml::IsCDATA /NOUNLOAD .r0
	Node value
	xml::GetNodeValue /NOUNLOAD .r0
	xml::SetNodeValue /NOUNLOAD "[value]"
	Levels moving
	xml::RootElement /NOUNLOAD .r0 .r1
	xml::FirstChildElement /NOUNLOAD "[name]" .r0 .r1
	xml::FirstChild /NOUNLOAD "[name]" .r0 .r1
	xml::LastChild /NOUNLOAD "[name]" .r0 .r1
	xml::Parent /NOUNLOAD .r0 .r1
	xml::NoChildren /NOUNLOAD .r0
	One level moving
	xml::NextSiblingElement /NOUNLOAD "[name]" .r0 .r1
	xml::NextSibling /NOUNLOAD "[name]" .r0 .r1
	xml::PreviousSibling /NOUNLOAD "[name]" .r0 .r1
	Level modification
	xml::InsertAfterNode /NOUNLOAD "[handle]" .r0
	xml::InsertBeforeNode /NOUNLOAD "[handle]" .r0
	xml::InsertEndChild /NOUNLOAD "[handle]" .r0
	xml::ReplaceNode /NOUNLOAD "[handle]" .r0
	xml::RemoveNode /NOUNLOAD
	xml::RemoveAllChild /NOUNLOAD
	Nodes and Memory
	xml::CreateText /NOUNLOAD "[text]" .r0
	xml::CreateNode /NOUNLOAD "<a>text</a>" .r0
	xml::CloneNode /NOUNLOAD .r0
	xml::FreeNode /NOUNLOAD "[handle]" .r0
	Other node functions
	xml::NodeHandle /NOUNLOAD .r0
	xml::GotoHandle /NOUNLOAD "[handle]" .r0
	xml::NodeType /NOUNLOAD .r0
	xml::Coordinate /NOUNLOAD .r0 .r1 .r2
	Attributes
	xml::GetAttribute /NOUNLOAD "[name]" .r0 .r1
	xml::SetAttribute /NOUNLOAD "[name]" "[value]" .r0
	xml::RemoveAttribute /NOUNLOAD "[name]" .r0
	xml::FirstAttribute /NOUNLOAD .r0 .r1 .r2
	xml::LastAttribute /NOUNLOAD .r0 .r1 .r2
	xml::NextAttribute /NOUNLOAD .r0 .r1 .r2
	xml::PreviousAttribute /NOUNLOAD .r0 .r1 .r2
	xml::SetAttributeName /NOUNLOAD "[name]"
	xml::SetAttributeValue /NOUNLOAD "[value]"

---

Introduction

XML plugin parses an XML document, and builds from that a Document Object Model (DOM) that can be read, modified and saved. XML plugin and documentation are based on TinyXml (2.4.2).

Features

- Read and/or modified xml files
- Code is fast and lightweight
- Unicode UTF-8 support
- "MSXML.DLL" independent
- Support for condense and non-condense white spaces
- Row and Column tracking

Output variables

.r0-.r9 = $0-$9
.R0-.R9 = $R0-$R9

Entities

Plugin recognizes the pre-defined "character entities", meaning special characters. Namely:

	&	&
	&lt;	<
	&gt;	>
	&quot;	"
	&apos;	'

These are recognized when the XML document is read, and translated to there UTF-8 equivalents. For instance, text with the XML of:

	Far & Away

will have the value of "Far & Away" when queried and will be written back to the XML file as an ampersand.
Additionally, any character can be specified by its Unicode code point: The syntax " " or " " are both to the non-breaking space characher.

XML file example

<?xml version="1.0" encoding="utf-8" standalone="no"?>
<!-- COMMENT1 -->
<ELEMENT>
    <ELEMENT2>TEXT</ELEMENT2>
    <!-- COMMENT2 -->
    <empty_ELEMENT />
    <empty_ELEMENT2 NAME="VALUE" NAME2="VALUE2" />
</ELEMENT>

Declaration: Root: Node: Text: Comment: Attribute: Child: Parent:

<?xml version="1.0" encoding="utf-8" standalone="no"?> <ELEMENT> it is ELEMENT, TEXT, COMMENT, DECLARATION TEXT COMMENT1 and COMMENT2 NAME="VALUE" and NAME2="VALUE2" <ELEMENT2> is child for <ELEMENT> <ELEMENT> is parent for <ELEMENT2>

---

Functions

xml::SetCondenseWhiteSpace /NOUNLOAD "[1|0]" Condenses all white space into a single space or not.

"[1|0]"

"1" "0"

-condense all white space into a single space (default) -don't condense all white space into a single space

xml::SetEncoding /NOUNLOAD "[encoding]" Sets document encoding.

"[encoding]"

"" "UTF8" "LEGACY"

-auto detect encoding UTF-8 or ANSI (default) -force encoding as unicode UTF-8 -force encoding as ANSI

xml::LoadFile /NOUNLOAD "[file]" .r0 Loads document.

"[file]"	- Load this file
.r0	$0="0"  success $0="-1" error

xml::SaveFile "[file]" .r0 Saves document.

"[file]"	- Save this file, if empty save current loaded file
.r0	$0="0"  success $0="-1" error

xml::DeclarationVersion /NOUNLOAD .r0 .r1 Returns value of the version attribute of the declaration node.

.r0	$0=Version (e.g. "1.0")
.r1	$1="0"  success $1="-1" error

xml::DeclarationEncoding /NOUNLOAD .r0 .r1 Returns value of the encoding attribute of the declaration node.

.r0	$0=Encoding (e.g. "utf-8")
.r1	$1="0"  success $1="-1" error

xml::DeclarationStandalone /NOUNLOAD .r0 .r1 Returns value of the standalone attribute of the declaration node.

.r0	$0=Standalone (e.g. "yes")
.r1	$1="0"  success $1="-1" error

xml::GetText /NOUNLOAD .r0 .r1 Convenience function for easy access to the text inside current element.

.r0	$0=Element text
.r1	$1="0"  success $1="-1" error

xml::SetCDATA /NOUNLOAD "[0|1]" .r0 Turns on or off a CDATA representation of the current element text.

"[0|1]"	"0"  -turns off (default) "1"  -turns on
.r0	$0="0"  success $0="-1" error

xml::IsCDATA /NOUNLOAD .r0 Queries whether this represents text using a CDATA section.

.r0	$0="1"  current node using CDATA $0="0"  current node not using CDATA $0="-1" current node is not text

xml::GetNodeValue /NOUNLOAD .r0 Gets the value of the current node.

.r0	$0=Node value

xml::SetNodeValue /NOUNLOAD "[value]" Sets the value of the current node.

"[value]"

- Set this value

xml::RootElement /NOUNLOAD .r0 .r1 Returns the root element name and goes to it.

.r0	$0=Root element name (the only top level element)
.r1	$1="0"  success $1="-1" error

xml::FirstChildElement /NOUNLOAD "[name]" .r0 .r1 Returns the first child element name and goes to it.

"[name]"	- Find first child element specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::FirstChild /NOUNLOAD "[name]" .r0 .r1 Returns the first child node name and goes to it.

"[name]"	- Find first child node specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::LastChild /NOUNLOAD "[name]" .r0 .r1 Returns the last child node name and goes to it.

"[name]"	- Find last child node specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::Parent /NOUNLOAD .r0 .r1 Returns the parent element name and goes to it.

.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::NoChildren /NOUNLOAD .r0 Checks if the current node has any children.

.r0	$0="1" current node has no children $0="0" current node has children

xml::NextSiblingElement /NOUNLOAD "[name]" .r0 .r1 Returns the next sibling element name and goes to it.

"[name]"	- Find next sibling element specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::NextSibling /NOUNLOAD "[name]" .r0 .r1 Returns the next sibling node name and goes to it.

"[name]"	- Find next sibling node specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::PreviousSibling /NOUNLOAD "[name]" .r0 .r1 Returns the previous sibling node name and goes to it.

"[name]"	- Find previous sibling node specified by name, if empty returns first founded
.r0	$0=name
.r1	$1="0"  success $1="-1" error

xml::InsertAfterNode /NOUNLOAD "[handle]" .r0 Adds new node after current and goes to it.

"[handle]"	- Insert this node (handle returned by xml::NodeHandle, xml::CreateText, xml::CreateNode, xml::CloneNode)
.r0	$0="0"  success $0="-1" error

xml::InsertBeforeNode /NOUNLOAD "[handle]" .r0 Adds new node before current and goes to it.

"[handle]"	- Insert this node (handle returned by xml::NodeHandle, xml::CreateText, xml::CreateNode, xml::CloneNode)
.r0	$0="0"  success $0="-1" error

xml::InsertEndChild /NOUNLOAD "[handle]" .r0 Adds new node to the end of the current node children and goes to it.

"[handle]"	- Insert this node (handle returned by xml::NodeHandle, xml::CreateText, xml::CreateNode, xml::CloneNode)
.r0	$0="0"  success $0="-1" error

xml::ReplaceNode /NOUNLOAD "[handle]" .r0 Replaces the current node.

"[handle]"	- Replace with this node (handle returned by xml::NodeHandle, xml::CreateText, xml::CreateNode, xml::CloneNode)
.r0	$0="0"  success $0="-1" error

xml::RemoveNode /NOUNLOAD Deletes the current node and goes to the parent element.

xml::RemoveAllChild /NOUNLOAD Deletes all children of the current node (it will be empty).

xml::CreateText /NOUNLOAD "[text]" .r0 Creates the text node in memory and returns it handle.

"[text]"	- Create this text in memory
.r0	$0=handle to text node $0="0" error

xml::CreateNode /NOUNLOAD "<a>text</a>" .r0 Creates the node in memory and returns it handle.

"<a>text</a>"	- Create this node in memory
.r0	$0=handle to node $0="0" error

xml::CloneNode /NOUNLOAD .r0 Copies the current node to the memory and returns it handle.

.r0	$0=handle to node $0="0" error

xml::FreeNode /NOUNLOAD "[handle]" .r0 Free memory from node.

"[handle]"	- Free this node (handle returned by xml::CreateText, xml::CreateNode, xml::CloneNode)
.r0	$0="0"  success $0="-1" error

xml::NodeHandle /NOUNLOAD .r0 Returns the current node handle.

.r0	$0=current node handle $0="0" error

xml::GotoHandle /NOUNLOAD "[handle]" .r0 Goes to the specified node.

"[handle]"	- Goto this node (handle returned by xml::NodeHandle)
.r0	$0="0"  success $0="-1" error

xml::NodeType /NOUNLOAD .r0 Returns the type of the current node.

.r0	$0="ELEMENT" $0="COMMENT" $0="DOCUMENT" $0="TEXT" $0="DECLARATION" $0="UNKNOWN"

xml::Coordinate /NOUNLOAD .r0 .r1 .r2 Returns the current node coordinates in document.

.r0	$0=Row
.r1	$1=Column
.r2	$2="0"  success $2="-1" error

xml::GetAttribute /NOUNLOAD "[name]" .r0 .r1 Returns value of the attribute of the current node and goes to it.

"[name]"	- Find attribute specified by name
.r0	$0=attribute value
.r1	$1="0"  success $1="-1" error

xml::SetAttribute /NOUNLOAD "[name]" "[value]" .r0 Sets attribute of the current node.

"[name]"	- Attribute name
"[value]"	- Attribute value
.r0	$0="0"  success $0="-1" error

xml::RemoveAttribute /NOUNLOAD "[name]" .r0 Deletes attribute with the specified name of the current node.

"[name]"	- Attribute name
.r0	$0="0"  success $0="-1" error

xml::FirstAttribute /NOUNLOAD .r0 .r1 .r2 Returns name and value of the first attribute of the current node and goes to it.

.r0	$0=attribute name
.r1	$1=attribute value
.r2	$2="0"  success $2="-1" error

xml::LastAttribute /NOUNLOAD .r0 .r1 .r2 Returns name and value of the last attribute of the current node and goes to it.

.r0	$0=attribute name
.r1	$1=attribute value
.r2	$2="0"  success $2="-1" error

xml::NextAttribute /NOUNLOAD .r0 .r1 .r2 Returns name and value of the next attribute and goes to it.

.r0	$0=attribute name
.r1	$1=attribute value
.r2	$2="0"  success $2="-1" error

xml::PreviousAttribute /NOUNLOAD .r0 .r1 .r2 Returns name and value of the previous attribute and goes to it.

.r0	$0=attribute name
.r1	$1=attribute value
.r2	$2="0"  success $2="-1" error

xml::SetAttributeName /NOUNLOAD "[name]" Sets name of the current attribute.

"[name]"

- Attribute name

xml::SetAttributeValue /NOUNLOAD "[value]" Sets value of the current attribute.

"[value]"

- Attribute value

---