From 829ad8643354de2c1f0a998e75132f9a15d0ebd1 Mon Sep 17 00:00:00 2001 From: MewPurPur Date: Fri, 25 Aug 2023 17:55:57 +0300 Subject: [PATCH] Improve XMLParser's documentation --- doc/classes/XMLParser.xml | 80 +++++++++++++++++++++++++++------------ 1 file changed, 56 insertions(+), 24 deletions(-) diff --git a/doc/classes/XMLParser.xml b/doc/classes/XMLParser.xml index 9b960f66fed..36795852e07 100644 --- a/doc/classes/XMLParser.xml +++ b/doc/classes/XMLParser.xml @@ -2,10 +2,41 @@ Provides a low-level interface for creating parsers for XML files. - Low-level class for creating parsers for [url=https://en.wikipedia.org/wiki/XML]XML[/url] files. 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 < parser.GetAttributeCount(); idx++) + { + attributesDict[parser.GetAttributeName(idx)] = parser.GetAttributeValue(idx); + } + GD.Print($"The {nodeName} element has the following attributes: {attributesDict}"); + } + } + [/csharp] + [/codeblocks] @@ -13,111 +44,112 @@ - Gets the number of attributes in the current element. + 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. - Gets the name of the attribute specified by the [param idx] index. + Returns the name of an attribute of the currently parsed element, specified by the [param idx] index. - Gets the value of the attribute specified by the [param idx] index. + Returns the value of an attribute of the currently parsed element, specified by the [param idx] index. - Gets the current line in the parsed file, counting from 0. + Returns the current line in the parsed file, counting from 0. - Gets the value of a certain attribute of the current element by [param name]. This will raise an error if the element has no such attribute. + 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. - Gets the value of a certain attribute of the current element by [param name]. This will return an empty [String] if the attribute is not found. + 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. - Gets the contents of a text node. This will raise an error in any other type of node. + Returns the contents of a text node. This method will raise an error if the current parsed node is of any other type. - Gets the name of the current element node. This will raise an error if the current node type is neither [constant NODE_ELEMENT] nor [constant NODE_ELEMENT_END]. + 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. - Gets the byte offset of the current node since the beginning of the file or buffer. + 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. - Gets the type of the current node. Compare with [enum NodeType] constants. + Returns the type of the current node. Compare with [enum NodeType] constants. - Check whether the current element has a certain attribute. + Returns [code]true[/code] if the currently parsed element has an attribute with the [param name]. - Check whether the current element is empty (this only works for completely empty tags, e.g. [code]<element />[/code]). + Returns [code]true[/code] if the currently parsed element is empty, e.g. [code]<element />[/code]. - Opens an XML [param file] for parsing. This returns an error code. + Opens an XML [param file] for parsing. This method returns an error code. - Opens an XML raw [param buffer] for parsing. This returns an error code. + Opens an XML raw [param buffer] for parsing. This method returns an error code. - Reads the next node of the file. This returns an error code. + Parses the next node in the file. This method returns an error code. - Moves the buffer cursor to a certain offset (since the beginning) and read the next node there. This returns an error code. + Moves the buffer cursor to a certain offset (since the beginning) and reads the next node there. This method returns an error code. - Skips the current section. If the node contains other elements, they will be ignored and the cursor will go to the closing of the current element. + 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. @@ -126,22 +158,22 @@ There's no node (no file or buffer opened). - Element (tag). + An element node type, also known as a tag, e.g. [code]<title>[/code]. - End of element. + An end of element node type, e.g. [code]</title>[/code]. - Text node. + A text node type, i.e. text that is not inside an element. This includes whitespace. - Comment node. + A comment node type, e.g. [code]<!--A comment-->[/code]. - CDATA content. + A node type for CDATA (Character Data) sections, e.g. [code]<![CDATA[CDATA section]]>[/code]. - Unknown node. + An unknown node type.