Xml Class

List of Functions:

As Unigine extensively uses Xml for storing different types of data, it also provides functionality for parsing and saving files of this type.

Xml Class

Members

Xml ()

Default constructor that creates an empty instance.

Xml (string node, string args = 0 = 0)

Creates an Xml tree with a given node as a root.

Arguments

string node - Name of the node that will be a root.
string args = 0 - Optional arguments to the root node. If provided, they should be in this form:
arg1=\"value1\" arg2=\"value2\" …
If values do not contain spaces, escaped quotes can be omitted.

Xml addChild (variable v, string args = 0)

Appends a new Xml node to the current Xml node as a child.

Arguments

variable v - Argument of one of the following types:
- Xml xml - Xml node.
- string name - Name of the Xml node.
string args - Arguments of the Xml node. The default value is 0.
Notice
This value should be passed if the first argument is a string

Return value

Created Xml node.

void clearChildren ()

Clears all children of the current Xml node.

void clearChilds ()

Clears all children of the current Xml node.

Warning

The function is deprecated. It is provided to keep your code working until the next release. Please, replace it with clearChildren().

void clearUnusedData ()

Clears all unused data.

void clear ()

Clears all data associated with the node.

void copy (Xml xml)

Copies all data (name, arguments, data, flags and a child hierarchy) from the source Xml node to the current one.

Arguments

Xml xml - Source Xml node.

int findArg (string name)

Find a Xml argument by its name.

Arguments

string name - Xml argument name.

Return value

Xml argument number.

int findChild (string name)

Find the number of the Xml node child by its name.

Arguments

string name - Name of the child of the current Xml node.

Return value

The number of the Xml node child.

Xml find (string path)

Searches for a node given its absolute or relative path.

Notice
							You cannot search for a root node, neither by name nor by specifying "/". In any of these cases, 0 will be returned.
						

Arguments

string path - Path to the node. The path should be in this form:
/node_a arg1=\"value1\"…/node_b arg1=\"value1\"…/…

Here, node_a and node_b a names of successive nodes down the tree. You can specify an asterisk (*) instead of a node name; that will mean "any node name". Also, node names can contain question marks (?), which means "any character". In addition, on each level, several nodes can be specified, if they are separated with a pipe (|). For example:
Source code (UnigineScript)
```
// load Xml
Xml tree = new Xml();
tree.load("tree.xml");

// find any child of the element or item node, the child must have the id
// argument with a value "1"
Xml node = tree.find("element|item/* id=1");
```
If the first slash (/) is omitted, the path is relative, and any sub-path matching this one, suits. Otherwise, the path is absolute, and the search is made strictly from the root node.

Return value

Target node, if it is found; otherwise, 0.

string getArgName (int num)

Returns argument name by its number.

Arguments

int num - Argument number.

Return value

Argument name.

string getArgValue (int num)

Returns the Xml argument value.

Arguments

int num - Argument number.

Return value

Argument value.

string getArg (string name)

Returns the value of a given argument by its name.

Arguments

string name - Name of a target argument.

Return value

Argument name.

variable getArg (string name, variable value)

Returns the argument value by its name if exists, otherwise returns a variable default value and transforms function into the default value type.

Arguments

string name - Name of the target argument.
variable value - Variable default value.

Return value

Argument value or a variable default value.

int getBoolArg (string name)

Returns a value of a given boolean argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

1 if the argument has a value 1, true or TRUE; 0, if the argument has a value 0, false or FALSE; otherwise, 0.

int getBoolArg (string name, int value)

Returns a value of a given boolean argument, if it is found; otherwise, returns the default argument value passed as the second argument.

Arguments

string name - Name of the target argument.
int value - Default value of the argument.

Return value

1 if the argument has a value 1, true or TRUE;
0 if the argument has a value 0, false or FALSE;
if the argument value is not a boolean value, the function returns 0 and shows the corresponding error message;
if the given argument name is not found, the function will return the default value passed as the second argument.

int getBoolData ()

Returns a boolean interpretation of data stored in the node.

Return value

1 if a value equals to 1, true or TRUE; 0, if the value equals to 0, false or FALSE; otherwise, 0.

variable getChildData (string name, variable value)

Allows to get the data from the Xml child node.

Arguments

string name - Name of the child node.
variable value - Type of the child (int, float, vec3, vec4, dvec3, dvec4, ivec3, ivec4, mat4, dmat4, quat, string).

Return value

The value of the child node.

Xml getChild (variable id)

Returns a child node by its name or index number in the child list.

Notice

To check, if a child with a given name exists, use the isChild() method.

Arguments

variable id - Name of a node ( string ) or its index number in the child list ( int ).

Return value

Target child node, if it is found; otherwise, 0.

dmat4 getDMat4Arg (string name)

Returns a value of a given dmat4 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

dmat4 getDMat4Data ()

Returns a dmat4 matrix interpretation of data stored in the node.

Return value

Data stored in the node.

dvec3 getDVec3Arg (string name)

Returns a value of a given dvec3 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

dvec3 getDVec3Data ()

Returns a dvec3 interpretation of data stored in the node.

Return value

Data stored in the node.

dvec4 getDVec4Arg (string name)

Returns a value of a given dvec4 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

dvec4 getDVec4Data ()

Returns a dvec4 interpretation of data stored in the node.

Return value

Data stored in the node.

string getData ()

Returns literal data stored in the node.

Return value

Literal data stored in the node or an empty string.

variable getData (variable value)

Returns node data if exists, otherwise returns a variable default value and transforms function into a default value type.

Arguments

variable value - Variable default value.

Return value

Node data or a variable default value.

double getDoubleArg (string name)

Returns a value of a given double argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

double getDoubleArg (string name, double value)

Returns the value of the given double argument, if it is found.

NoticeIf the argument with the given name is not found; the function will return the default argument value passed as the second argument.

Arguments

string name - Name of the target argument.
double value - Default value of the argument.

Return value

Argument value.

int getDoubleArrayArg (string name, int dest = [])

Returns a set of double values stored in an argument and puts them in a vector.

Arguments

string name - Name of a target argument.
int dest - Reference to a vector with double components.

Return value

1 if dest contains anything; otherwise, 0.

int getDoubleArrayData (int src = [])

Returns an interpretation of data stored in the node as a vector of double components.

Arguments

int src - Reference to a vector with double components.

Return value

1 if dest contains anything; otherwise, 0.

double getDoubleData ()

Returns a double interpretation of data stored in the node.

Return value

Data stored in the node.

float getFloatArg (string name)

Returns a value of a given float argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

float getFloatArg (string name, float value)

Returns the value of the given float argument, if it is found.

NoticeIf the argument with the given name is not found; the function will return the default argument value passed as the second argument.

Arguments

string name - Name of the target argument.
float value - Default value of the argument.

Return value

Argument value.

int getFloatArrayArg (string name, int dest = [])

Returns a set of float values stored in an argument and puts them in a vector.

Arguments

string name - Name of a target argument.
int dest - Reference to a vector .

Return value

1 if dest contains anything; otherwise, 0.

int getFloatArrayData (int dest = [])

Returns an interpretation of data stored in the node as a vector of floats.

Arguments

int dest - Reference to a vector .

Return value

1 if dest contains anything; otherwise, 0.

float getFloatData ()

Returns a float interpretation of data stored in the node.

Return value

Data stored in the node.

StringStack<256> getFormattedSubTree (string path = 0 = 0)

Formats the node tree for "pretty printing". If no arguments are passed, the entire Xml tree would be output.

Arguments

string path = 0 - Path to the node. See the description of find() for more details.

Return value

Multi-line indented output of the node tree.

ivec3 getIVec3Arg (string name)

Returns a value of a given ivec3 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

ivec3 getIVec3Data ()

Returns a ivec3 interpretation of data stored in the node.

Return value

Data stored in the node.

ivec4 getIVec4Arg (string name)

Returns a value of a given ivec4 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

ivec4 getIVec4Data ()

Returns a ivec4 interpretation of data stored in the node.

Return value

Data stored in the node.

int getIntArg (string name)

Returns a value of a given int argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

int getIntArg (string name, int value)

Returns the value of the given int argument; if it is exists; otherwise, the default value passed as the second argument is returned.

Arguments

string name - Name of the target argument.
int value - Default value of the argument.

Return value

Argument value.

int getIntArrayArg (string name, int dest = [])

Returns a set of int values stored in an argument and puts them in a vector.

Arguments

string name - Name of a target argument.
int dest - Reference to a vector .

Return value

1 if values are read successfully; otherwise, 0.

int getIntArrayData (int dest = [])

Returns an interpretation of data stored in the node as a vector of integers.

Arguments

int dest - Reference to a vector .

Return value

1 if values are read successfully; otherwise, 0.

int getIntData ()

Returns an integer interpretation of data stored in the node.

Return value

Data stored in the node.

mat4 getMat4Arg (string name)

Returns a value of a given mat4 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

mat4 getMat4Data ()

Returns a mat4 matrix interpretation of data stored in the node.

Return value

Data stored in the node.

string getName ()

Returns a name of the node.

Return value

Node name.

int getNumArgs ()

Returns a number of arguments.

Return value

Number of arguments.

int getNumChildren ()

Returns a number of children contained in the node.

In the standard Xml model the child nodes can be of the following types: node, text node and comment. The data of the Xml node is considered to be an unnamed child node, resulting in correct parsing of such a code:

Source code (XML)

<text>
	text</br>text
</text>

Hence if a node has the data, it will add to the number of its children.

Return value

Number of children.

int getNumChilds ()

Returns a number of children contained in the node.

Warning

The function is deprecated. It is provided to keep your code working until the next release. Please, replace it with getNumChildren().

Source code (XML)

<text>
	text</br>text
</text>

Hence if a node has the data, it will add to the number of its children.

Return value

Number of children.

Xml getParent ()

Returns the parent of the current Xml node.

Return value

Parent node of the current Xml node.

quat getQuatArg (string name)

Returns a value of a given quat argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

quat getQuatData ()

Returns a quaternion interpretation of data stored in the node.

Return value

Data stored in the node.

int getStringArrayArg (string name, int dest = [])

Returns a set of string values stored in an argument and puts them in a vector.

Arguments

string name - Name of a target argument.
int dest - Reference to a vector .

Return value

1 if dest contains anything; otherwise, 0.

int getStringArrayData (int dest = [])

Returns an interpretation of data stored in the node as a vector of strings.

Arguments

int dest - Reference to a vector .

Return value

1 if dest contains anything; otherwise, 0.

StringStack<256> getSubTree (string path = 0)

Dumps the node tree.

Arguments

string path - Path to the node. See the description of find() for more details.

Return value

Single-line non-indented output of the node tree. If no arguments are passed, the entire Xml tree would be output.

vec3 getVec3Arg (string name)

Returns a value of a given vec3 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

vec3 getVec3Data ()

Returns a vec3 interpretation of data stored in the node.

Return value

Data stored in the node.

vec4 getVec4Arg (string name)

Returns a value of a given vec4 argument.

Notice

To check, if an argument exists, use the isArg() method.

Arguments

string name - Name of a target argument.

Return value

Argument value.

vec4 getVec4Data ()

Returns a vec4 interpretation of data stored in the node.

Return value

Data stored in the node.

int isArg (string name)

Checks whether an argument with a given name exists.

Arguments

string name - Name to check.

Return value

1 if the argument exists; otherwise, 0.

int isChild (string name)

Checks if a child element with a given name exists.

Arguments

string name - Element name to check.

Return value

1 if a child with the provided name exists; otherwise, 0.

int load (string file)

Loads an Xml document and sets the current node to be the root of the parsed tree.

Arguments

string file - Path to an Xml file.

Return value

1 if the file is read and parsed successfully; otherwise, 0.

int parse (string xml)

Parses a string with Xml mark-up and sets the current node to be the root of the parsed tree.

Arguments

string xml - String with an Xml content.

Return value

1 if a string is successfully parsed; otherwise 0.

void printUnusedData (string name)

Logs warnings of unused data for debugging.

Arguments

string name - Path to the file.

int removeArg (string name)

Removes the argument with the given name from the list of the current Xml node arguments.

Arguments

string name - Name of the target argument.

Return value

1 of the argument is removed successfully; otherwise, 0.

variable removeChild (variable v)

Removes an child node and its descendants from the current Xml node.

Arguments

variable v - Argument of one of the following types:
- Xml xml - Xml child node (and its descendants) to be removed.
- string path - Path to the Xml child node that need to be removed. The path should have the following form:
  /node_a arg1=\"value1\"…/node_b arg1=\"value1\"…/…
  
  Notice
  See also the find() function.

Return value

Removed child node and its descendants, if they are found; otherwise, NULL.

int save (string file, int binary = 0 = 0)

Formats the tree of the current node and writes is to a file.

Arguments

string file - Path to an Xml file.
int binary = 0 - Binary format flag.

Return value

1 if the file is written successfully; otherwise, 0.

void setArgName (int num, string name)

Sets the Xml argument name.

Arguments

int num - The argument number.
string name - The argument name.

void setArgValue (int num, string value)

Sets the Xml argument value.

Arguments

int num - The argument number.
string value - The argument value.

void setArg (string name, variable value)

Sets a literal value of a given argument.

Arguments

string name - Name of an argument.
variable value - Value of an argument.

int setBoolArg (string name, int value)

Sets a value of a given boolean argument.

Arguments

string name - Name of an argument.
int value - Value of an argument. Any non-zero value means true, the zero value means false.

Return value

Always 1.

int setBoolData (int data)

Sets a boolean content for the node. This can be done only for nodes with no children.

Arguments

int data - Content to set. Any non-zero value means true, the zero value means false.

Return value

1 if the content is set successfully; otherwise, 0.

void setChildData (string name, variable value)

Allows to set a value to Xml child.

Arguments

string name - Name of a child.
variable value - Type of the child (int, float, vec3, vec4, dvec3, dvec4, ivec3, ivec4, mat4, dmat4, quat, string).

int setDMat4Arg (string name, dmat4 value)

Sets a value of a given dmat4 argument.

Arguments

string name - Name of an argument.
dmat4 value - Value of an argument.

Return value

Always 1.

int setDMat4Data (dmat4 data)

Sets a dmat4 matrix content for the node. This can be done only for nodes with no children.

Arguments

dmat4 data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setDVec3Arg (string name, double value)

Sets a value of a given dvec3 argument.

Arguments

string name - Name of an argument.
double value - Value of an argument.

Return value

Always 1.

int setDVec3Data (dvec3 value)

Sets a dvec3 content for the node. This can be done only for nodes with no children.

Arguments

dvec3 value - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setDVec4Arg (string name, dvec4 value)

Sets a value of a given dvec4 argument.

Arguments

string name - Name of an argument.
dvec4 value - Value of an argument.

Return value

Always 1.

int setDVec4Data (dvec4 value)

Sets a dvec4 content for the node. This can be done only for nodes with no children.

Arguments

dvec4 value - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

void setData (variable data)

Sets a content for the node. This can be done only for nodes with no children.

Arguments

variable data - Content to set.

int setDoubleArg (string name, double value)

Sets a value of a given double argument.

Arguments

string name - Name of an argument.
double value - Value of an argument.

Return value

Always 1.

int setDoubleArrayArg (string name, int src = [])

Sets a vector of double as a value of a given argument.

Arguments

string name - Name of an argument.
int src - Reference to a vector with double components.

Return value

Always 1.

int setDoubleArrayData (int src = [])

Sets a vector of double components as a content for the node. This can be done only for nodes with no children.

Arguments

int src - Reference to a vector with double components.

Return value

1 if the content is set successfully; otherwise, 0.

int setDoubleData (double value)

Sets a double content for the node. This can be done only for nodes with no children.

Arguments

double value - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setFloatArg (string name, float value)

Sets a value of a given float argument.

Arguments

string name - Name of an argument.
float value - Value of an argument.

Return value

Always 1.

int setFloatArrayArg (string name, int value = [])

Sets a vector of floats as a value of a given argument.

Arguments

string name - Name of an argument.
int value - Reference to a vector .

Return value

Always 1.

int setFloatArrayData (int data = [])

Sets a vector of floats as a content for the node. This can be done only for nodes with no children.

Arguments

int data - Reference to a vector .

Return value

1 if the content is set successfully; otherwise, 0.

int setFloatData (float data)

Sets a float content for the node. This can be done only for nodes with no children.

Arguments

float data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setIVec3Arg (string name, ivec3 value)

Sets a value of a given ivec3 argument.

Arguments

string name - Name of an argument.
ivec3 value - Value of an argument.

Return value

Always 1.

int setIVec3Data (ivec3 value)

Sets a ivec3 content for the node. This can be done only for nodes with no children.

Arguments

ivec3 value - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setIVec4Arg (string name, ivec4 value)

Sets a value of a given ivec4 argument.

Arguments

string name - Name of an argument.
ivec4 value - Value of an argument.

Return value

Always 1.

int setIVec4Data (ivec4 value)

Sets a ivec4 content for the node. This can be done only for nodes with no children.

Arguments

ivec4 value - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setIntArg (string name, int value, int radix = 10)

Sets a value for a given int argument in a given number notation. By default, the decimal number notation is used.

Arguments

string name - Name of an argument.
int value - Value of an argument.
int radix - Radix to use when setting a value.

Return value

1 if the value is set successfully; otherwise, 0.

int setIntArrayArg (string name, int value = [], int radix = 10)

Sets a vector of integers as a value of a given argument in a given number notation. By default, the decimal number notation is used.

Arguments

string name - Name of an argument.
int value - Reference to a vector.
int radix - Radix to use when setting a value.

Return value

1 if the vector is set successfully; otherwise, 0.

int setIntArrayData (int data = [], int radix = 10)

Sets a vector of integers as a content for the Xml node in a given number notation. By default, the decimal number notation is used. This can be done only for Xml nodes with no children.

Arguments

int data - Reference to a vector.
int radix - Radix to use when setting a value.

Return value

1 if the content is set successfully; otherwise, 0.

int setIntData (int data, int radix = 10)

Sets an integer as a content for the Xml node in a given number notation. By default, the decimal number notation is used. This can be done only for Xml nodes with no children.

Arguments

int data - Content to set.
int radix - Radix to use when setting a value.

Return value

1 if the content is set successfully; otherwise, 0.

int setMat4Arg (string name, mat4 value)

Sets a value of a given mat4 argument.

Arguments

string name - Name of an argument.
mat4 value - Value of an argument.

Return value

Always 1.

int setMat4Data (mat4 data)

Sets a mat4 matrix content for the node. This can be done only for nodes with no children.

Arguments

mat4 data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

void setName (string name)

Sets a name of the node.

Arguments

string name - Node name.

int setQuatArg (string name, quat value)

Sets a value of a given quat argument.

Arguments

string name - Name of an argument.
quat value - Value of an argument.

Return value

Always 1.

int setQuatData (quat data)

Sets a quaternion content for the node. This can be done only for nodes with no children.

Arguments

quat data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setRawData (string data)

Sets a raw content for the node. Raw data will be automatically formatted as a CDATA section. This can be done only for nodes with no children.

Arguments

string data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setStringArrayArg (string name, int value = [])

Sets a vector of strings as a value of a given argument.

Arguments

string name - Name of an argument.
int value - Reference to a vector .

Return value

Always 1.

int setStringArrayData (int data = [])

Sets a vector of strings as a content for the node. This can be done only for nodes with no children.

Arguments

int data - Reference to a vector .

Return value

1 if the content is set successfully; otherwise, 0.

int setVec3Arg (string name, vec3 value)

Sets a value of a given vec3 argument.

Arguments

string name - Name of an argument.
vec3 value - Value of an argument.

Return value

Always 1.

int setVec3Data (vec3 data)

Sets a vec3 content for the node. This can be done only for nodes with no children.

Arguments

vec3 data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setVec4Arg (string name, vec4 value)

Sets a value of a given vec4 argument.

Arguments

string name - Name of an argument.
vec4 value - Value of an argument.

Return value

Always 1.

int setVec4Data (vec4 data)

Sets a vec4 content for the node. This can be done only for nodes with no children.

Arguments

vec4 data - Content to set.

Return value

1 if the content is set successfully; otherwise, 0.

int setXmlData (string data)

Sets an unquoted string to data stored in the node. This string can also contain xml sub-tree with rich text formating.

Arguments

string data - Unquoted string to set.

Return value

Returns 1 if the string is set successfully; otherwise, 0.

Last update: 03.07.2017

Помогите сделать статью лучше

Была ли эта статья полезной?

Сообщить о проблеме в этой статье

(или выберите слово/фразу и нажмите Ctrl+Enter

Xml Class

List of Functions:

See Also

Xml Class

Members

Xml ()

Xml (string node, string args = 0 = 0)

Arguments

Xml addChild (variable v, string args = 0)

Arguments

Return value

void clearChildren ()

void clearChilds ()

void clearUnusedData ()

void clear ()

void copy (Xml xml)

Arguments

int findArg (string name)

Arguments

Return value

int findChild (string name)

Arguments

Return value

Xml find (string path)

Arguments

Return value

string getArgName (int num)

Arguments

Return value

string getArgValue (int num)

Arguments

Return value

string getArg (string name)

Arguments

Return value

variable getArg (string name, variable value)

Arguments

Return value

int getBoolArg (string name)

Arguments

Return value

int getBoolArg (string name, int value)

Arguments

Return value

int getBoolData ()

Return value

variable getChildData (string name, variable value)

Arguments

Return value

Xml getChild (variable id)

Arguments

Return value

dmat4 getDMat4Arg (string name)

Arguments

Return value

dmat4 getDMat4Data ()

Return value

dvec3 getDVec3Arg (string name)

Arguments

Return value

dvec3 getDVec3Data ()

Return value

dvec4 getDVec4Arg (string name)

Arguments

Return value

dvec4 getDVec4Data ()

Return value

string getData ()

Return value

variable getData (variable value)

Arguments

Return value

double getDoubleArg (string name)

Arguments

Return value

double getDoubleArg (string name, double value)

Arguments

Return value

int getDoubleArrayArg (string name, int dest = [])

Arguments