XML commands

Introduction

The following describes the "XML commands" that both "xmlproc" and "xmlcmd" can take and what they do.

An XML session consists of memory for an XML file and a "variable store" that consists of "variables" containing string data ore pointers to "nodes" in the XML file.

Summary of commands:

File commands
xparsefile Loads an XML file into the program's memory for manipulation and/or enquiry.
xsavefile Writes an XML file from memory to disk.
Match/Find commands
xmatch Finds an element (and children) of a particular name and/or value.
xmatchnext Finds an element (and children) of a particular name and/or value, useful if more than one exists.
xfind Same as "xmatch" but searches the XML tree recursively.
xfindnext Same as "xmatchnext" but searches the XML tree recursively.
Element Commands
xname Retrieve the name of an element
xgetprop Retrieve a particular property (or attribute) of an element
xsetprop Set's a particular property (or attribute) of an element
xgettext Get the text portion(s) od an element
xsettext Set the text portion of an element
xnext Obtain the next element
xchild Obtain the first child element
xparent Obtain the parent element
xwalk Walks" the tree, obtains first child if it exists, the next node if it does not, and the next element after the parent if at end of list.
xmove Moves an element from one part of the tree to another.
xaddchild Adds a child element
xaddnext Inserts an element after
xaddprev Inserts an element before
Node commands
xnodenext Obtain next node
xnodeprev Obtain previous node
xnodechild Obtain first child node
xnodelast Obtain last child node
xnodeparent Obtain parent of node
xnodewalk Walks" the tree, obtains first child if it exists, the next node if it does not, and the next element after the parent if at end of list.
xnodetype Obtain type of node
Namespace
xnewns Creates a new namespace
xsetns Sets a namespace to a node
xusens Tells the system to use a namespace for elements
Miscellaneous
xcopy Copies one variable to another, or outputs contents
xifexists Sees if a variabl;e exists and has a node in it
xdelete Delete an element (and a variable)
xlevel Gets the level (how far down the tree) of one element compared to another.

General syntax

Commands take a number of parameters. The start of a new command signifies the end of the preceding one. For this reason command names can be escaped by prefixing them with the .\. character (in real life this is .\\. to escape the LINUX/UNIX shell).

For instance: 

#!/bin/bash

HANDLE=`xmlopen test.xml`

xmlcmd $HANDLE xcopy destvar xcopy    # Will see this as 2 xcopys
                                      # xcopy destvar
                                      # and
                                      # xcopy
                                      

xmlcmd $HANDLE xcopy destvar \\xcopy  # Copies the string "xcopy"
                                      # into variable "destvar"

xmlclose $HANDLE

Variables

An XML session contains an unlimited number of "variables". These are indepentant of the XML document itself. These are created when they are "set", and can contain nothing, string data or a pointer to a "node" on the XML document.

When a document is created it sets a variable called "/" to the root element.

Names of variables are case insensitive.

Command arguments

A command argument takes either a string or a variable, which is defined in this documentation. However, for both these "indirect" access can be initiated by pre-fixing the argument with the "@" character.

For instance: 

xcopy vara "string"

will populate the variable "varto" with the value "string". However.. 

xcopy varb @vara

will populate the variable "varb" with a variable "vara" - that is that will put the value "string" into barb.

Also, the command 

xcopy @vara another_string

will place (in this example) the value "another_string" into a variable called "string".

More than one @ can be placed in front of the variable.. 

xcopy vara dvara            # Places "dvara" into "vara"
xcopy dvara evara           # Places "evara" into "dvara"

xcopy @@vara string         # Places string into a variable called "evara"
                            # First @        Retrieves dvara from vara
                            # Second @        Retrieves  evara from dvara

It is possible to escape this behaviour by prefixing the @ character with a "\" (which in real life will probably need to be "\\" to escape the LINUX/UNIX shell interpretation).

File comannds

xparsefile

Syntax:

xparsefile file_name

Description

This loads an XML file into the session.s memory. It removes any existing file.s data that was in there at the time. Usually this is not used because the first parameter of .xmlproc. or the parameter of .xmlopen. achieves the same more intuitively.

xsavefile

Syntax:

xsavefile file_name

Description

This saves the XML data in the session's memory to a file, overwriting it if it already exists. It places a pointer to the root node in a variable called "/".

Match/Find Commands

xmatch

Syntax

xmatch root [{xmatch_lines}...]

Where "xmatch_lines" are: 

[variable_name] level|detail_args

Where "details_args" consist of at least one of the following 

element element_name [namespace element_name]
attribute property_name [namespace element_name]
property property_name [namespace element_name] property_value
text text_value

Note: The "attribute" and "property" arguments are mutually exclusive for each "xmatch_line".

The process will examine the XML file using the node stored in the "root" variable as a base. It will examine all elements that are "children" of this comparing them with the first "match_line", where it will perform the following operations.

  • If there is only one "match_line" then the variable is set (if it is defined) and the routine finishes.
  • If the element.s details matches those described by the .match_line. arguments then the children of that are compared to the second .match_line. details, and if a match occurs there then the process is repeated for the it.s children and the third .match_line. if it exists and so on.
  • If a match does not occur then control is passed to the parent level and the previous .match_line. and the search continues from there.
  • If an element is found then all the variables (defined) are set to the appropriate element, otherwise they are all set to NULL.

The values to compare the individual elements properties are described as follows:

Match_line description
variable If this is supplied then the variable is set on a succesful match.
level If this is defined then the matches any element. Nothing else should be defined here.
element element_name An element with the name element_name matches.
attribute propery_name An element who has a property (or attribute) of property_name matches. The value of this property is ignored. Only one of these can be defined per .match_line. and it is mutiually exclusive with the .property. keyword below.
property property_name property_value An element that has a property or attribute property_name set to property_value matches. Only one of these can be defined per .match_line. and it is mutiually exclusive with the .attribute. keyword above
text text_value The text portion of the element needs to match the text_value. It is worth noting that blank characters (spaces, new lines etc) are stripped off the top and tail (but not middle) of the element.s text value and the argument here. Please note it is a single argument so it is more than likely it needs to be enclosed in quotes.

To use an example:

Using the following XML file.. 

<web_app>
        <description>Libra Web Application</description>
        <context_param>
                <param_name>httpPort</param_name>
                <param_value>80</param_value>
        </context_param>
        <context_param>
                <param_name>swapFlag</param_name>
                <param_value>all_https</param_value>
        </context_param>
	...
</web_app>

The following command is processed: 

xmatch / va element context_param 
            element param_name text "swapFlag"

The above will use the root of the document, or the "web_app" element, to base it.s search on. It consists of 2 "match_lines", so it will search for two levels.

It first looks for the higher level. The process will scan all children of "web_app" until it finds a match for that, which it does when it comes across a "context_param" element above.

When the first level "matches" then the children of that are compared to the second "match_line": 

element param_name text "swapFlag"

This would fail for the first .context_param. as although it has a child element named "param_name" it.s text property is "httpPort", not "swapFlag".

The process will then continue searching the "<web_app>" list until it comes to the next "context_param" (the next element there), and it would search that children for am element named "param_name" with a text value of "swapFlag", which would be a hit.

The process would then set the "va" variable to be the second "context_param" node. If a variable was defined prior to the second "element" keyword then the above node's "<param_name>" child would be set to that.

Return Value

The value returns 0 (SUCCESS) if a match is found. It returns 1 if not.

xmatchnext

Syntax

As per xmatch

Desription

This works the same as "xmatch", but it finds the lowest level (last match_line) needs to have a variable defined. If this is initially set to "NULL" (or does not exist) then the first match is found. If that variable is set to a valid "match" then the subsequent one is found.

The upshot of this is that should this be continuously invoked with the same arguments then a list of elements can be processed.

For example, a shellscript that does the same as above can be written as... 

#!/bin/bash

export HANDLE=`xmlopen web.xml`

export FOUND=1 # FAIL - not fount

while true
do
        if ! xmlcmd $HANDLE xmathcnext /          \
                va element copntext_param        \
                vc element  param_name
        then
                break
        fi
        if test `xmlgettext vc` = "swapFlag"
        then
                FOUND=0 # SUCCESS - found
                break
        fi
done

xmlclose $HANDLE

exit $FOUND

Return Value:

This returns 0 (SUCCESS) if it finds a match, else 1 (FAIL) if it does not or there is an error condition.

xfind

Syntax

As per xmatch

Description

This works the same as xmatch with the following differences:

  1. It does a "recursive" search down the XML tree - similar to the UNIX/LINUX "find" command does to directories and files.
  2. It starts by comparing the root of the command itself, not the children.

Therefore the following will all set "va" to be the same element (for the above example) 

xfind /                                               \
        va element "context_menu"                     \
           element "param_name" text "swapFlag"


xfind /                                               \
           element "web_app"                          \
        va element "context_menu"                     \
           element "param_name" text "swapFlag"


xfind /                                               \
        vt element "param_name" text "swapFlag"       \
xparent va vt

Please note though, the last of the above is not a good way of doing it.

Return Value:

This returns 0 (SUCCESS) if it finds a match, else 1 (FAIL) if it does not or there is an error condition.

xfindnext

Syntax

Same as matchnext

Description

xfindnext is to xmatchnext as xfind is to xmatch.

Element Commands

xnext xchild xparent xwalk

Syntax

x**** [variable_to] variable_name

where (x****) is the appropriate command.

Description

This examines the node pointed to in variable_name and obtains the new element. It then sets variable_to if it exists, or overwrites variable_name with it if not.

The new element is:

Command Description
xnext The next element in the list
xchild The element's first element child
xparent The element's parent
xwalk This "walks" the tree. If there are children it returns the element.s first child, otherwise it returns the next element in the list. Failing both these it returns the parent's next element.

Please note these commands return elements, not all nodes. It excludes text nodes. These are usually extracted using the "xgettext" command, but can be navigated to using the "Node Commands" below.

Return Value:

This returns 0 (SUCCESS) if it can get the next element, else 1 (FAIL) if it does not or there is an error condition.

xmove

Syntax

xmove variable_to variable

Description

This moves a node to a new parent. This moves the SECOND variable to be a child of the FIRST (opposite to LINUX/UNIX "mv" command). I do not know what happens if you try and move a node to be a descendant of itself, probably something horrible, so care should be taken here.

Return Value:

This returns 0 (SUCCESS) on a succesful move, or 1 (FAIL) on an error condition.

xgettext

Syntax

xgettext [variable_to] variable_name

Description

This obtains the element pointed to by variable_name and extracts the text content of it. If variable_to exists It places that as a string into it. If it does not then it outputs the content to the standard output.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval, or 1 (FAIL) on an error condition.

xsettext

Syntax

xsettext variable text_data

Description

This sets the variable's element's text property to Text data. It is worth noting that "text_data" is a single argument so probably need to be enclosed in quotes.

Return Value:

This returns 0 (SUCCESS) on a succesful placement, or 1 (FAIL) on an error condition.

xgetprop

Syntax

xgetprop [variable_to] variable_element string_property [namespace namespace_name]

Description

This obtains the element pointed to by variable_element and extracts the value of the property whose name is stored in the variable string_property. If variable_to exists It places that as a string into it. If it does not then it outputs the value to the standard output.

Return Value:

This returns 0 (SUCCESS) on a succesful retrrieval, or 1 (FAIL) on an error condition.

xsetprop

Syntax

xsetprop variable_element string_property [namespace namespace_name] string_value

Description

This obtains the element pointed to by variable_element and sets the value of the property whose name is stored in the variable string_property to string_value.

Return Value:

This returns 0 (SUCCESS) on a succesful placement, or 1 (FAIL) on an error condition.

Node Commands

xnodenext xnodeprev xnodechild xnodelast xnodeparent xnodewalk

Syntax

xnode**** [variable_to] variable_name

where (xnode****) is the appropriate command.

Description

This examines the node pointed to in variable_name and obtains the new node. Nodes include all elements, as well as the text between them.

The new node is:

Command Description
xnodenext The next node in the list
xnodeprev The previous node in the list
xnodechild The element's first node child
xnodelast The element's last node child
xnodeparent The node's parent
xnodewalk This "walks" the tree. If there are children it returns the element's first child, otherwise it returns the next node in the list. Failing both these it returns the parent's next node.

Please note these commands return nodes, not all elements. Should just elements be used then either the equivalent "Element Commands" should be used, or the "xnodetype" should be invoked after retrieval.

Return Value:

This returns 0 (SUCCESS) if it can get the next node, else 1 (FAIL) if it does not or there is an error condition.

xnodetype

Syntax

xnodetype [variable_to] variable_name

Description

This obtains the type of the node pointed to by variable_name. If variable_to exists It places that as a string into it. If it does not then it outputs the content to the standard output.

The output is one of the following:

null The node is invalid or does not exist
element The node is an element
text The node is a text type
comment The node is a comment

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval, or 1 (FAIL) on an error condition.

xsettext

Syntax

xsettext variable text_data

Description

This sets the variable's element's text property to Text data. It is worth noting that "text_data" is a single argument so probably need to be enclosed in quotes.

Return Value:

This returns 0 (SUCCESS) on a succesful placement, or 1 (FAIL) on an error condition.

Namespace Commands

xnewns

Syntax

xnewns variable_node variable_href variable_prefix

Description

This creates a namespace on node, which is usually the root one. The variable_href is the URI of the namespace, and the variable_prefix is the prefix to use.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval. It returns 1 (FAIL) on an error condition.

xsetns

Syntax

xsetns variable_node variable_namespace

Description

This allocates a namespace to an element node. The variable_namespace can either be the URI or the prefix of the namespace.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval. It returns 1 (FAIL) on an error condition.

xusens

Syntax

xusens [variable_node variable_namespace]

Description

This "remembers" the namespace and applies it to elements in the "xmatch*", "xfind*" and "xadd*" commands. The command with no parameters "forgets" it.

The namespace used is defined at the node supplied, or a parent, and can be referred to by either the prefix or the URI.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval. It returns 1 (FAIL) on an error condition.

Miscellaneous Commands

xcopy

Syntax

xcopy [variable_to] string_from

Description

This command copies a string to a variable. If the variable_to is missing then it outputs the string_from to the standard output.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval, or 1 (FAIL) on an error condition.

xifexists

Syntax

xifexists variable_name

Description

This is used to see if a variable exists.

Return Value:

This returns 0 (SUCCESS) if the variable exists and is a node, otherwise it returns 1 (FAIL).

xlevel

Syntax

xlevel [variable_dest] variable_parent variable_child

Description

This outputs the level of the child compared to the parent. A direct child outputs "1", grandchild "2" and so on.

If variable_dest is defined then the number goes in there instead of the standard output.

Should the variable_child not be a descendant of variable then an error condition is raised.

Return Value:

This returns 0 (SUCCESS) on a succesful retrieval. It returns 1 (FAIL) on an error condition.