XML NSIS plugin v2.0

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

Contents

	1. Introduction
	2. Features
	3. Entities
	4. XML file example
	5. Functions
	Document format
	${xml::SetCondenseWhiteSpace} "[1|0]"
	${xml::SetEncoding} "[encoding]"
	Document file
	${xml::LoadFile} "[file]" $var
	${xml::SaveFile} "[file]" $var
	Declaration node
	${xml::DeclarationVersion} $var1 $var2
	${xml::DeclarationEncoding} $var1 $var2
	${xml::DeclarationStandalone} $var1 $var2
	Text node
	${xml::GetText} $var1 $var2
	${xml::SetText} "[value]" $var
	${xml::SetCDATA} "[0|1]" $var
	${xml::IsCDATA} $var
	Node value
	${xml::GetNodeValue} $var
	${xml::SetNodeValue} "[value]"
	Level searching
	${xml::FindNextElement} "[name]" $var1 $var2
	${xml::FindCloseElement}
	Levels moving
	${xml::RootElement} $var1 $var2
	${xml::FirstChildElement} "[name]" $var1 $var2
	${xml::FirstChild} "[name]" $var1 $var2
	${xml::LastChild} "[name]" $var1 $var2
	${xml::Parent} $var1 $var2
	${xml::NoChildren} $var
	One level moving
	${xml::NextSiblingElement} "[name]" $var1 $var2
	${xml::NextSibling} "[name]" $var1 $var2
	${xml::PreviousSibling} "[name]" $var1 $var2
	Level modification
	${xml::InsertAfterNode} "[handle]" $var
	${xml::InsertBeforeNode} "[handle]" $var
	${xml::InsertEndChild} "[handle]" $var
	${xml::ReplaceNode} "[handle]" $var
	${xml::RemoveNode} $var
	${xml::RemoveAllChild}
	Nodes and Memory
	${xml::CreateText} "[text]" $var
	${xml::CreateNode} "<a>text</a>" $var
	${xml::CloneNode} $var
	${xml::FreeNode} "[handle]" $var
	XPath
	${xml::XPathString} "[expression]" $var1 $var2
	${xml::XPathNode} "[expression]" $var
	${xml::XPathAttribute} "[expression]" $var
	Other node functions
	${xml::NodeHandle} $var
	${xml::GotoHandle} "[handle]" $var
	${xml::ElementPath} $var
	${xml::GotoPath} "[path]" $var
	${xml::NodeType} $var
	${xml::Coordinate} $var1 $var2 $var3
	Attributes
	${xml::GetAttribute} "[name]" $var1 $var2
	${xml::SetAttribute} "[name]" "[value]" $var
	${xml::RemoveAttribute} "[name]" $var
	${xml::FirstAttribute} $var1 $var2 $var3
	${xml::LastAttribute} $var1 $var2 $var3
	${xml::NextAttribute} $var1 $var2 $var3
	${xml::PreviousAttribute} $var1 $var2 $var3
	${xml::CurrentAttribute} $var1 $var2 $var3
	${xml::SetAttributeName} "[name]"
	${xml::SetAttributeValue} "[value]"
	Unload plugin
	${xml::Unload}

---

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.5.3) and TinyXPath (1.3.1).

Features

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

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} "[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} "[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} "[file]" $var Loads document.

"[file]"	- Load this file
$var	"0"  success "-1" error

${xml::SaveFile} "[file]" $var Saves document.

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

${xml::DeclarationVersion} $var1 $var2 Returns value of the version attribute of the declaration node.

$var1	Version (e.g. "1.0")
$var2	"0"  success "-1" error

${xml::DeclarationEncoding} $var1 $var2 Returns value of the encoding attribute of the declaration node.

$var1	Encoding (e.g. "utf-8")
$var2	"0"  success "-1" error

${xml::DeclarationStandalone} $var1 $var2 Returns value of the standalone attribute of the declaration node.

$var1	Standalone (e.g. "yes")
$var2	"0"  success "-1" error

${xml::GetText} $var1 $var2 Convenience function for easy access to the text inside current element.

$var1	Element text
$var2	"0"  success "-1" error

${xml::SetText} "[value]" $var Convenience function for easy set the text of the current element.

"[value]"	- Set this text
$var	"0"  success "-1" error

${xml::SetCDATA} "[0|1]" $var Turns on or off a CDATA representation of the current element text.

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

${xml::IsCDATA} $var Queries whether this represents text using a CDATA section.

$var	"1"  current node using CDATA "0"  current node not using CDATA "-1" current node is not text

${xml::GetNodeValue} $var Gets the value of the current node.

$var	Node value

${xml::SetNodeValue} "[value]" Sets the value of the current node.

"[value]"

- Set this value

${xml::FindNextElement} "[name]" $var1 $var2 Search for element (recursive), returns the element name and goes to it.

"[name]"	- Element specified by name, if empty returns all founded elements
$var1	name
$var2	"0"  success "-1" error

${xml::FindCloseElement} Closes search opened by xml::FindNextElement.

${xml::RootElement} $var1 $var2 Returns the root element name and goes to it.

$var1	Root element name (the only top level element)
$var2	"0"  success "-1" error

${xml::FirstChildElement} "[name]" $var1 $var2 Returns the first child element name and goes to it.

"[name]"	- Find first child element specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::FirstChild} "[name]" $var1 $var2 Returns the first child node name and goes to it.

"[name]"	- Find first child node specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::LastChild} "[name]" $var1 $var2 Returns the last child node name and goes to it.

"[name]"	- Find last child node specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::Parent} $var1 $var2 Returns the parent element name and goes to it.

$var1	name
$var2	"0"  success "-1" error

${xml::NoChildren} $var Checks if the current node has any children.

$var	"1" current node has no children "0" current node has children

${xml::NextSiblingElement} "[name]" $var1 $var2 Returns the next sibling element name and goes to it.

"[name]"	- Find next sibling element specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::NextSibling} "[name]" $var1 $var2 Returns the next sibling node name and goes to it.

"[name]"	- Find next sibling node specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::PreviousSibling} "[name]" $var1 $var2 Returns the previous sibling node name and goes to it.

"[name]"	- Find previous sibling node specified by name, if empty returns first founded
$var1	name
$var2	"0"  success "-1" error

${xml::InsertAfterNode} "[handle]" $var Adds new node after current and goes to it.

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

${xml::InsertBeforeNode} "[handle]" $var Adds new node before current and goes to it.

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

${xml::InsertEndChild} "[handle]" $var 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)
$var	"0"  success "-1" error

${xml::ReplaceNode} "[handle]" $var Replaces the current node.

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

${xml::RemoveNode} $var Deletes the current node and goes to the parent element.

$var	"0"  success "-1" error

${xml::RemoveAllChild} Deletes all children of the current node (it will be empty).

${xml::CreateText} "[text]" $var Creates the text node in memory and returns it handle.

"[text]"	- Create this text in memory
$var	handle to text node "0" error

${xml::CreateNode} "<a>text</a>" $var Creates the node in memory and returns it handle.

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

${xml::CloneNode} $var Copies the current node to the memory and returns it handle.

$var	handle to node "0" error

${xml::FreeNode} "[handle]" $var Free memory from node.

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

${xml::XPathString} "[expression]" $var1 $var2 Compute a string XPath expression.

"[expression]"	- XPath expression (e.g. "count(//@*)")
$var1	result string
$var2	"0"  success "-1" error

${xml::XPathNode} "[expression]" $var Compute a node XPath expression and goes to it.

"[expression]"	- XPath expression (e.g. "/a/b")
$var	"0"  success "-1" error

${xml::XPathAttribute} "[expression]" $var Compute an attribute XPath expression and goes to it.

"[expression]"	- XPath expression (e.g. "/a/b/@attr")
$var	"0"  success "-1" error

${xml::NodeHandle} $var Returns the current node handle.

$var	current node handle "0" error

${xml::GotoHandle} "[handle]" $var Goes to the specified node.

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

${xml::ElementPath} $var Returns the current element path.

$var	current element path (e.g. "/a/b/c[3]/d")

${xml::GotoPath} "[path]" $var 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 "")
$var	"0"  success "-1" error

${xml::NodeType} $var Returns the type of the current node.

$var	"ELEMENT" "COMMENT" "DOCUMENT" "TEXT" "DECLARATION" "UNKNOWN"

${xml::Coordinate} $var1 $var2 $var3 Returns the current node coordinates in document.

$var1	Row
$var2	Column
$var3	"0"  success "-1" error

${xml::GetAttribute} "[name]" $var1 $var2 Returns value of the attribute of the current element and goes to it.

"[name]"	- Find attribute specified by name
$var1	attribute value
$var2	"0"  success "-1" error

${xml::SetAttribute} "[name]" "[value]" $var Sets attribute of the current element.

"[name]"	- Attribute name
"[value]"	- Attribute value
$var	"0"  success "-1" error

${xml::RemoveAttribute} "[name]" $var Deletes attribute with the specified name of the current element.

"[name]"	- Attribute name
$var	"0"  success "-1" error

${xml::FirstAttribute} $var1 $var2 $var3 Returns name and value of the first attribute of the current element and goes to it.

$var1	attribute name
$var2	attribute value
$var3	"0"  success "-1" error

${xml::LastAttribute} $var1 $var2 $var3 Returns name and value of the last attribute of the current element and goes to it.

$var1	attribute name
$var2	attribute value
$var3	"0"  success "-1" error

${xml::NextAttribute} $var1 $var2 $var3 Returns name and value of the next attribute and goes to it.

$var1	attribute name
$var2	attribute value
$var3	"0"  success "-1" error

${xml::PreviousAttribute} $var1 $var2 $var3 Returns name and value of the previous attribute and goes to it.

$var1	attribute name
$var2	attribute value
$var3	"0"  success "-1" error

${xml::CurrentAttribute} $var1 $var2 $var3 Returns name and value of the current attribute.

$var1	attribute name
$var2	attribute value
$var3	"0"  success "-1" error

${xml::SetAttributeName} "[name]" Sets name of the current attribute.

"[name]"

- Attribute name

${xml::SetAttributeValue} "[value]" Sets value of the current attribute.

"[value]"

- Attribute value

${xml::Unload} Unload plugin.

---