XML NSIS plugin v1.6

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

	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::SetText /NOUNLOAD "[value]" .r0
	xml::SetCDATA /NOUNLOAD "[0\|1]" .r0
	xml::IsCDATA /NOUNLOAD .r0
	Node value
	xml::GetNodeValue /NOUNLOAD .r0
	xml::SetNodeValue /NOUNLOAD "[value]"
	Level searching
	xml::FindNextElement /NOUNLOAD "[name]" .r0 .r1
	xml::FindCloseElement /NOUNLOAD
	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::ElementPath /NOUNLOAD .r0
	xml::GotoPath /NOUNLOAD "[path]" .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:

	&amp;	&
	&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 &amp; 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::SetText /NOUNLOAD "[value]" .r0

Convenience function for easy set the text of the current element.

"[value]"
- Set this text

.r0
$0="0" success
$0="-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::FindNextElement /NOUNLOAD "[name]" .r0 .r1

Search for element (recursive), returns the element name and goes to it.

"[name]"
- Element specified by name, if empty returns all founded elements

.r0
$0=name

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

xml::FindCloseElement /NOUNLOAD

Closes search opened by xml::FindNextElement.

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]"
- Go to this node
(handle returned by xml::NodeHandle)
.r0
$0="0" success
$0="-1" error

xml::ElementPath /NOUNLOAD .r0

Returns the current element path.

.r0
$0=current element path (e.g. "/a/b/c[3]/d")
$0="" error

xml::GotoPath /NOUNLOAD "[path]" .r0

Goes to the specified path.

"[path]"
- Go to this path
(e.g. from root "/a/b[2]/c/d", from currect element "a/b[2]/c/d",
using last element 'b' "a/b[-1]/c/d", using any last element "a/[-1]/c/d",
go to the document beginning "")
.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 element 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 element.

"[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 element.

"[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 element 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 element 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

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

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

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

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

"[name]"	- Element specified by name, if empty returns all founded elements
.r0	$0=name
.r1	$1="0" success $1="-1" error

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

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

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

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

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

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

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

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

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

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

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

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

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

"[path]"	- Go to this path (e.g. from root "/a/b[2]/c/d", from currect element "a/b[2]/c/d", using last element 'b' "a/b[-1]/c/d", using any last element "a/[-1]/c/d", go to the document beginning "")
.r0	$0="0" success $0="-1" error

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