XmlParser — C# API

class XmlParserReckfellSharpInherits RefCounted

Open a file or buffer and check every Read result. Error.FileEof ends reading. Actual SDK names are GetNodeType/GetNodeName: Node here means an XML token, not a gameplay Entity.

Not a strict XML validator, DOM, schema or automatic namespace resolver. The reader can pass mismatched closing tags without failure. Successful reading does not replace your format structural/field checks.

The current reader can return Error.Ok on a short whitespace-only tail while retaining the previous type and attributes. The example checks the current-step start in the original buffer to avoid adding a repeated element.

The example collects attribute values on exact-name elements at any depth. Missing attributes are skipped; existing empty values are included. It extracts rather than validates the whole document. Pass System.Text.Encoding.UTF8.GetBytes(text) and keep the input array unchanged during the call.

C#
using System;
using System.Collections.Generic;
using Reckfell;

public static class XmlAttributeExample
{
    public static Error Collect(byte[] utf8, string elementName, string attributeName,
        out string[] values)
    {
        values = Array.Empty<string>();
        if (utf8.Length == 0)
            return Error.InvalidData;
        using var parser = new XmlParser();
        Error error = parser.OpenBuffer(utf8);
        if (error != Error.Ok)
            return error;
        var found = new List<string>();
        while (true)
        {
            error = parser.Read();
            if (error == Error.FileEof)
            {
                values = found.ToArray();
                return Error.Ok;
            }
            if (error != Error.Ok)
                return error;
            if (parser.GetNodeType() == XmlParser.NodeType.Element
                && parser.GetNodeName() == elementName
                && parser.HasAttribute(attributeName))
            {
                // A short whitespace-only read can retain the preceding token.
                int start = (int)parser.GetNodeOffset();
                while (start < utf8.Length && utf8[start] is 9 or 10 or 13 or 32)
                    start++;
                if (start < utf8.Length && utf8[start] == (byte)'<')
                    found.Add(parser.GetNamedAttributeValue(attributeName));
            }
        }
    }
}

XmlParser offsets are UTF-8 bytes; do not use them with C# Substring. Seek already reads a token, SkipSection changes position and fields after EOF can remain from a previous read.

Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.

Constructors1

XmlParserConstructor

# XmlParser

C#
public XmlParser();

Creates a low-level reader with no open input or current token. Call Open/OpenBuffer, then Read and check Error. Not a DOM or XML-schema validator.

Methods18

GetAttributeCountint

# GetAttributeCount

C#
public int GetAttributeCount();

Reads the current attribute-list size. Check GetNodeType()==Element first: Text/Comment can retain a previous element attribute list. Closing tags clear the list.

Returns int

Attribute-list size; can be stale outside Element.

GetAttributeNamestring

# GetAttributeName

C#
public string GetAttributeName(int idx);

Reads an attribute name by index in the current list. Use on Element after checking bounds, not a text token with stale attributes.

Parameters
Name	Type	Default
`idx`	`int`	—

idx

Index 0 <= idx < GetAttributeCount() on current Element. An invalid index produces native diagnostics and an empty result.

Returns string

String from the current attribute list. Check presence and valid index/name separately.

GetAttributeValuestring

# GetAttributeValue

C#
public string GetAttributeValue(int idx);

Reads an attribute string value by index. Supported character references are already decoded; for example a&b reads as a&b. Does not automatically convert to a number.

Parameters
Name	Type	Default
`idx`	`int`	—

idx

Index 0 <= idx < GetAttributeCount() on current Element. An invalid index produces native diagnostics and an empty result.

Returns string

String from the current attribute list. Check presence and valid index/name separately.

GetCurrentLineint

# GetCurrentLine

C#
public int GetCurrentLine();

Returns the current zero-based count of consumed LF (\n) characters. Seek does not recompute it for the new position, so arbitrary seeking makes it unreliable as a target-token line number.

Returns int

Current zero-based line counter; can disagree with position after Seek.

GetNamedAttributeValuestring

# GetNamedAttributeValue

C#
public string GetNamedAttributeValue(string name);

Reads an attribute by exact name. Missing attributes log a native error and return an empty string; do not rely on a C# exception. Use HasAttribute or the safe getter for optional fields.

Parameters
Name	Type	Default
`name`	`string`	—

name

Exact case-sensitive attribute name. A namespace prefix remains part of the text name; do not automatically replace it.

Returns string

String from the current attribute list. Check presence and valid index/name separately.

GetNamedAttributeValueSafestring

# GetNamedAttributeValueSafe

C#
public string GetNamedAttributeValueSafe(string name);

Reads an attribute by exact name without missing-attribute diagnostics. Empty output means either absent or an existing empty value; distinguish with HasAttribute.

Parameters
Name	Type	Default
`name`	`string`	—

name

Exact case-sensitive attribute name. A namespace prefix remains part of the text name; do not automatically replace it.

Returns string

String from the current attribute list. Check presence and valid index/name separately.

GetNodeDatastring

# GetNodeData

C#
public string GetNodeData();

Reads current Text-token contents only, including supported character-reference decoding. Use GetNodeName for Comment/Cdata. An invalid token type causes a native error, not a guaranteed C# exception.

Returns string

Current Text-token contents. Other types can produce diagnostics and an empty string.

GetNodeNamestring

# GetNodeName

C#
public string GetNodeName();

Reads the tag name for Element/ElementEnd, or comment/CDATA contents for Comment/Cdata. Use GetNodeData for Text: GetNodeName on a text token is a native API error.

Returns string

Tag name or Comment/Cdata contents according to current type.

GetNodeOffsetulong

# GetNodeOffset

C#
public ulong GetNodeOffset();

Returns the byte offset at the start of the current parsing step in the original UTF-8 buffer. Not a C# string index or Unicode-character count. When short whitespace text is skipped, the step can start before <. A saved offset applies to the same unchanged input.

Returns ulong

Byte offset in original UTF-8 input. Not token length.

GetNodeTypeXmlParser.NodeType

# GetNodeType

C#
public XmlParser.NodeType GetNodeType();

Returns the stored current XML stream-token type. Check reading Error and the short-whitespace-tail Read limitation: the previous type can persist even after Ok. NodeType names describe XML, not the Entity gameplay hierarchy.

Returns XmlParser.NodeType

Current XmlParser.NodeType; check the reading Error first.

HasAttributebool

# HasAttribute

C#
public bool HasAttribute(string name);

Checks an exact, case-sensitive attribute name in the current list. Use on Element; absence and an existing empty-valued attribute are distinct.

Parameters
Name	Type	Default
`name`	`string`	—

name

Exact case-sensitive attribute name. A namespace prefix remains part of the text name; do not automatically replace it.

Returns bool

true for an exact existing name, including an empty-valued attribute.

IsEmptybool

# IsEmpty

C#
public bool IsEmpty();

For current Element, reports self-closing syntax such as <item/>. Not end-of-file or an empty-document indicator. Such an element has no separate ElementEnd token. Do not use this flag on other token types as structural validation.

Returns bool

true for a self-closing Element, not whole-document state.

OpenError

# Open

C#
public Error Open(string file);

Loads a file into an owned buffer for later Read. Successful opening neither parses the first token nor validates the whole XML document. Check Error before reading; the file is loaded into memory rather than streamed from disk on each Read.

Parameters
Name	Type	Default
`file`	`string`	—

file

FileAccess path: asset://, user:// or an accessible absolute path. Not XML text.

Returns Error

Error.Ok when input is prepared; otherwise a failure code. Success does not validate the entire XML document.

OpenBuffer2 overloads

# OpenBuffer · 1/2

C#
public Error OpenBuffer(byte[] buffer);

Copies input bytes into an owned buffer and moves the cursor to its start. Supply UTF-8 data; this does not automatically recognize every XML encoding. Read the first token separately. After reopening, do not use old current-token fields before successful Read.

Parameters
Name	Type	Default
`buffer`	`byte[]`	—

buffer

Nonempty UTF-8 bytes, such as Encoding.UTF8.GetBytes(text). Opening copies them; later source-array changes do not alter the reader input.

Returns Error

Error.Ok when input is prepared; otherwise a failure code. Success does not validate the entire XML document.

# OpenBuffer · 2/2

C#
public Error OpenBuffer(ReadOnlySpan<byte> buffer);

Parameters
Name	Type	Default
`buffer`	`ReadOnlySpan<byte>`	—

buffer

Nonempty UTF-8 bytes, such as Encoding.UTF8.GetBytes(text). Opening copies them; later source-array changes do not alter the reader input.

Returns Error

Error.Ok when input is prepared; otherwise a failure code. Success does not validate the entire XML document.

ReadError

# Read

C#
public Error Read();

Performs the next reading step. Check Error, but note the current limitation: a short whitespace-only tail can return Error.Ok with the previous type, name and attributes. The class example checks current-step bytes to avoid repeating an element. FileEof also leaves previous state intact. The reader does not validate complete XML correctness.

Returns Error

Error.Ok after a step or Error.FileEof at the end. Ok does not always mean a new token on a short whitespace-only tail; EOF does not establish structural XML validity.

SeekError

# Seek

C#
public Error Seek(ulong position);

Moves the cursor to a byte offset and immediately performs Read. After Error.Ok the current token is already read: another Read advances beyond it. Does not reconstruct the line counter. Prefer an offset previously obtained from the same buffer.

Parameters
Name	Type	Default
`position`	`ulong`	—

position

Byte offset from the current input start, not a UTF-16 index or line number. Must point inside the same buffer.

Returns Error

Read result at the new position; an unavailable/outside offset can produce FileEof with diagnostics.

SkipSectionvoid

# SkipSection

C#
public void SkipSection();

Call on an opening Element. Does not read anything for a self-closing element. Otherwise consumes nested tokens until the nesting counter reaches a closing element or EOF, leaving that closing token current. The next Read moves beyond the section. Does not validate tag names or a schema.

XmlParser.NodeType

Value	Description
`Cdata = 5`	A node type for CDATA (Character Data) sections, e.g. `<![CDATA[CDATA section]]>`.
`Comment = 4`	A comment node type, e.g. `<!--A comment-->`.
`Element = 1`	An element node type, also known as a tag, e.g. `<title>`.
`ElementEnd = 2`	An end of element node type, e.g. `</title>`.
`None = 0`	There's no node (no file or buffer opened).
`Text = 3`	A text node type, i.e. text that is not inside an element. This includes whitespace.
`Unknown = 6`	An unknown node type.