godot/doc/classes/XMLParser.xml
2023-08-28 16:39:26 +03:00

180 lines
7.7 KiB
XML

<?xml version="1.0" encoding="UTF-8" ?>
<class name="XMLParser" inherits="RefCounted" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd">
<brief_description>
Provides a low-level interface for creating parsers for XML files.
</brief_description>
<description>
Provides a low-level interface for creating parsers for [url=https://en.wikipedia.org/wiki/XML]XML[/url] files. This class can serve as base to make custom XML parsers.
To parse XML, you must open a file with the [method open] method or a buffer with the [method open_buffer] method. Then, the [method read] method must be called to parse the next nodes. Most of the methods take into consideration the currently parsed node.
Here is an example of using [XMLParser] to parse a SVG file (which is based on XML), printing each element and its attributes as a dictionary:
[codeblocks]
[gdscript]
var parser = XMLParser.new()
parser.open("path/to/file.svg")
while parser.read() != ERR_FILE_EOF:
if parser.get_node_type() == XMLParser.NODE_ELEMENT:
var node_name = parser.get_node_name()
var attributes_dict = {}
for idx in range(parser.get_attribute_count()):
attributes_dict[parser.get_attribute_name(idx)] = parser.get_attribute_value(idx)
print("The ", node_name, " element has the following attributes: ", attributes_dict)
[/gdscript]
[csharp]
var parser = new XmlParser();
parser.Open("path/to/file.svg");
while (parser.Read() != Error.FileEof)
{
if (parser.GetNodeType() == XmlParser.NodeType.Element)
{
var nodeName = parser.GetNodeName();
var attributesDict = new Godot.Collections.Dictionary();
for (int idx = 0; idx &lt; parser.GetAttributeCount(); idx++)
{
attributesDict[parser.GetAttributeName(idx)] = parser.GetAttributeValue(idx);
}
GD.Print($"The {nodeName} element has the following attributes: {attributesDict}");
}
}
[/csharp]
[/codeblocks]
</description>
<tutorials>
</tutorials>
<methods>
<method name="get_attribute_count" qualifiers="const">
<return type="int" />
<description>
Returns the number of attributes in the currently parsed element.
[b]Note:[/b] If this method is used while the currently parsed node is not [constant NODE_ELEMENT] or [constant NODE_ELEMENT_END], this count will not be updated and will still reflect the last element.
</description>
</method>
<method name="get_attribute_name" qualifiers="const">
<return type="String" />
<param index="0" name="idx" type="int" />
<description>
Returns the name of an attribute of the currently parsed element, specified by the [param idx] index.
</description>
</method>
<method name="get_attribute_value" qualifiers="const">
<return type="String" />
<param index="0" name="idx" type="int" />
<description>
Returns the value of an attribute of the currently parsed element, specified by the [param idx] index.
</description>
</method>
<method name="get_current_line" qualifiers="const">
<return type="int" />
<description>
Returns the current line in the parsed file, counting from 0.
</description>
</method>
<method name="get_named_attribute_value" qualifiers="const">
<return type="String" />
<param index="0" name="name" type="String" />
<description>
Returns the value of an attribute of the currently parsed element, specified by its [param name]. This method will raise an error if the element has no such attribute.
</description>
</method>
<method name="get_named_attribute_value_safe" qualifiers="const">
<return type="String" />
<param index="0" name="name" type="String" />
<description>
Returns the value of an attribute of the currently parsed element, specified by its [param name]. This method will return an empty string if the element has no such attribute.
</description>
</method>
<method name="get_node_data" qualifiers="const">
<return type="String" />
<description>
Returns the contents of a text node. This method will raise an error if the current parsed node is of any other type.
</description>
</method>
<method name="get_node_name" qualifiers="const">
<return type="String" />
<description>
Returns the name of an element node. This method will raise an error if the currently parsed node is not of [constant NODE_ELEMENT] or [constant NODE_ELEMENT_END] type.
</description>
</method>
<method name="get_node_offset" qualifiers="const">
<return type="int" />
<description>
Returns the byte offset of the currently parsed node since the beginning of the file or buffer. This is usually equivalent to the number of characters before the read position.
</description>
</method>
<method name="get_node_type">
<return type="int" enum="XMLParser.NodeType" />
<description>
Returns the type of the current node. Compare with [enum NodeType] constants.
</description>
</method>
<method name="has_attribute" qualifiers="const">
<return type="bool" />
<param index="0" name="name" type="String" />
<description>
Returns [code]true[/code] if the currently parsed element has an attribute with the [param name].
</description>
</method>
<method name="is_empty" qualifiers="const">
<return type="bool" />
<description>
Returns [code]true[/code] if the currently parsed element is empty, e.g. [code]&lt;element /&gt;[/code].
</description>
</method>
<method name="open">
<return type="int" enum="Error" />
<param index="0" name="file" type="String" />
<description>
Opens an XML [param file] for parsing. This method returns an error code.
</description>
</method>
<method name="open_buffer">
<return type="int" enum="Error" />
<param index="0" name="buffer" type="PackedByteArray" />
<description>
Opens an XML raw [param buffer] for parsing. This method returns an error code.
</description>
</method>
<method name="read">
<return type="int" enum="Error" />
<description>
Parses the next node in the file. This method returns an error code.
</description>
</method>
<method name="seek">
<return type="int" enum="Error" />
<param index="0" name="position" type="int" />
<description>
Moves the buffer cursor to a certain offset (since the beginning) and reads the next node there. This method returns an error code.
</description>
</method>
<method name="skip_section">
<return type="void" />
<description>
Skips the current section. If the currently parsed node contains more inner nodes, they will be ignored and the cursor will go to the closing of the current element.
</description>
</method>
</methods>
<constants>
<constant name="NODE_NONE" value="0" enum="NodeType">
There's no node (no file or buffer opened).
</constant>
<constant name="NODE_ELEMENT" value="1" enum="NodeType">
An element node type, also known as a tag, e.g. [code]&lt;title&gt;[/code].
</constant>
<constant name="NODE_ELEMENT_END" value="2" enum="NodeType">
An end of element node type, e.g. [code]&lt;/title&gt;[/code].
</constant>
<constant name="NODE_TEXT" value="3" enum="NodeType">
A text node type, i.e. text that is not inside an element. This includes whitespace.
</constant>
<constant name="NODE_COMMENT" value="4" enum="NodeType">
A comment node type, e.g. [code]&lt;!--A comment--&gt;[/code].
</constant>
<constant name="NODE_CDATA" value="5" enum="NodeType">
A node type for CDATA (Character Data) sections, e.g. [code]&lt;![CDATA[CDATA section]]&gt;[/code].
</constant>
<constant name="NODE_UNKNOWN" value="6" enum="NodeType">
An unknown node type.
</constant>
</constants>
</class>