Lightweight XML Parser and Writer

Unit: MiniXML

Overview

MiniXML is a compact XML parser and writer designed for Turbo Pascal 7.0, providing DOM-style access to XML configuration files and data. It handles XML files up to ~64KB (Turbo Pascal real-mode heap block limit) and supports the core XML features needed for game configuration and data storage.

Features

64K file support: Handles XML files up to ~64KB
DOM-style tree structure: Navigate XML as parent/child/sibling nodes
Attribute support: Read element attributes, maximum 8, linear lookup
Text content: Handles both small (<255 bytes) and large text content
Comments and processing instructions: Skips XML comments and <?xml?> declarations
UTF-8 BOM detection: Automatically skips UTF-8 byte order mark
Memory efficient: Uses dynamic allocation for large text content
Helper utilities: Word array parser for numeric data

Dependencies

GENTYPES.PAS: Generic types

Type Definitions

const
  XML_MaxNameLength = 20;  { Maximum element/attribute name length }
  XML_MaxAttrsCount = 8;   { Maximum attributes per node }

type
  PAttrString = PChar;
  TPAttrStringArray = array[0..XML_MaxAttrsCount - 1] of PAttrString;

  PXMLNode = ^TXMLNode;
  TXMLNode = record
    Name    : string[XML_MaxNameLength];

    { Text content buffer (all text stored here) }
    TextBuf : Pointer;   { points to a byte buffer }
    TextLen : Word;      { number of bytes in TextBuf }
    TextCap : Word;      { allocated capacity in bytes }

    AttrKeys  : TPAttrStringArray;
    AttrValues: TPAttrStringArray;
    AttrCount : Integer;

    FirstChild : PXMLNode;
    NextSibling: PXMLNode;
    Parent     : PXMLNode;
  end;

Core API

Loading and Freeing

XMLLoadFile - Load XML from file

function XMLLoadFile(const FileName: string; var Root: PXMLNode): Boolean;

Parameters:

FileName: Path to XML file (DOS 8.3 format, max ~64KB)
Root: Returns pointer to root node on success

Returns: True if successful, False on error

Example:

var
  Root: PXMLNode;
begin
  if XMLLoadFile('CONFIG.XML', Root) then
  begin
    { Use the XML tree... }
    XMLFreeTree(Root);  { Always free when done! }
  end;
end;

XMLFreeTree - Free XML tree and all memory

procedure XMLFreeTree(Node: PXMLNode);

CRITICAL: Always call this to free the entire XML tree and prevent memory leaks.

Navigation

XMLFirstChild - Get first child element

function XMLFirstChild(const Node: PXMLNode; const Name: string): PXMLNode;

Parameters:

Node: Parent node
Name: Element name to find, or '' for any element

Returns: First matching child node, or nil if none

Example:

{ Find first <level> child }
Level := XMLFirstChild(Root, 'level');

{ Get first child of any type }
Child := XMLFirstChild(Node, '');

XMLNextSibling - Get next sibling element

function XMLNextSibling(const Node: PXMLNode; const Name: string): PXMLNode;

Parameters:

Node: Current node
Name: Element name to find, or '' for any element

Returns: Next matching sibling, or nil if none

Example:

{ Iterate through all <sprite> elements }
Sprite := XMLFirstChild(Root, 'sprite');
while Sprite <> nil do
begin
  { Process sprite... }
  Sprite := XMLNextSibling(Sprite, 'sprite');
end;

Attributes

XMLAttr - Get attribute value

function XMLAttr(const Node: PXMLNode; const Name: string): string;

Parameters:

Node: Element node
Name: Attribute name

Returns: Attribute value, or '' if not found

Example:

ID := XMLAttr(Node, 'id');
Width := XMLAttr(Sprite, 'width');

XMLHasAttr - Check if attribute exists

function XMLHasAttr(const Node: PXMLNode; const Name: string): Boolean;

Example:

if XMLHasAttr(Enemy, 'boss') then
  WriteLn('Boss enemy detected!');

XMLGetText - Get text content from node

function XMLGetText(const Node: PXMLNode): string;

Returns: Text content as string (clamped to 255 bytes if longer)

Example:

Description := XMLGetText(XMLFirstChild(Root, 'description'));
WriteLn('Description: ', Description);

Utility Functions

XMLReadWordArray - Parse numeric array from text content

function XMLReadWordArray(const Node: PXMLNode; var Arr: PWord;
                         var Count: Word): Boolean;

Parameters:

Node: Element containing numeric text (e.g., “10 20 30 40”)
Arr: Returns pointer to allocated Word array
Count: Returns number of values parsed

Returns: True if successful

IMPORTANT: Caller must free array with FreeMem(Arr, Count * SizeOf(Word))

Example:

var
  Values: PWord;
  Count: Word;
  i: Integer;
begin
  if XMLReadWordArray(DataNode, Values, Count) then
  begin
    for i := 0 to Count - 1 do
      WriteLn('Value[', i, '] = ', PWordArray(Values)^[i]);
    FreeMem(Values, Count * SizeOf(Word));
  end;
end;

Usage Examples

Iterating Through Lists

{ Load sprite definitions from XML }
var
  Root, Sprites, Sprite: PXMLNode;
  ID, FileName: string;

begin
  XMLLoadFile('SPRITES.XML', Root);

  Sprites := XMLFirstChild(Root, 'sprites');
  Sprite := XMLFirstChild(Sprites, 'sprite');

  while Sprite <> nil do
  begin
    ID := XMLAttr(Sprite, 'id');
    FileName := XMLAttr(Sprite, 'file');
    WriteLn('Sprite: ', ID, ' -> ', FileName);

    Sprite := XMLNextSibling(Sprite, 'sprite');
  end;

  XMLFreeTree(Root);
end;

Reading Text Content

var
  Node: PXMLNode;
begin
  Node := XMLFirstChild(Root, 'description');

  { Small text (<255 bytes) stored in Node^.Text }
  if Node^.Text <> '' then
    WriteLn('Description: ', Node^.Text);

  { Large text (>=255 bytes) stored in TextBuf }
  if Node^.TextBuf <> nil then
    WriteLn('Large text, ', Node^.TextLen, ' bytes');
end;

Checking Optional Attributes

var
  Level: PXMLNode;
  IsBoss: Boolean;
begin
  Level := XMLFirstChild(Root, 'level');

  { Check for optional 'boss' attribute }
  IsBoss := XMLHasAttr(Level, 'boss') and
            (XMLAttr(Level, 'boss') = 'true');

  if IsBoss then
    WriteLn('Boss level!')
  else
    WriteLn('Normal level');
end;

Sample XML File

<?xml version="1.0" encoding="US-ASCII"?>
<resources>
  <!-- Audio -->
  <music name="fantasy" path="FANTASY.HSC" />
  <sound name="explode" path="EXPLODE.VOC" />

  <!-- Images -->
  <image name="test" path="TEST.PCX" palette="test" />
  <image name="player" path="PLAYER.PCX" palette="player" />

  <!-- Fonts -->
  <font name="small" path="FONT-SM.XML" />
  <font name="large" path="FONT-LG.XML" />

  <!-- Animations -->
  <sprite name="player_idle" image="player" duration="0.8">
    <frame x="0" y="0" width="32" height="32" />
    <frame x="32" y="0" width="32" height="32" />
    <frame x="64" y="0" width="32" height="32" />
    <frame x="96" y="0" width="32" height="32" />
  </sprite>
  <sprite name="player_run" image="player" duration="0.5">
    <frame x="0" y="32" width="32" height="32" />
    <frame x="32" y="32" width="32" height="32" />
    <frame x="64" y="32" width="32" height="32" />
    <frame x="96" y="32" width="32" height="32" />
    <frame x="128" y="32" width="32" height="32" />
    <frame x="160" y="32" width="32" height="32" />
  </sprite>
</resources>

Limitations

File size: Maximum ~64KB (Turbo Pascal heap block limit in real-mode DOS)
Attributes per element: Maximum 8 attributes (can be increased via XML_MaxAttrsCount)
Attribute values: Maximum 255 bytes (Turbo Pascal string limit)
Element/Attribute names: Maximum 20 bytes (can be increased via XML_MaxNameLength)
No validation: Does not validate against DTD/XSD schemas
No entities: HTML entities (<, &, etc.) not decoded
No namespaces: XML namespaces not supported

Memory Management

Automatic allocation: Nodes and buffers allocated dynamically
Manual cleanup: Call XMLFreeTree(Root) to free entire tree
Memory leaks: Failing to call XMLFreeTree will leak memory
Nested elements: All children recursively freed by XMLFreeTree

Performance Characteristics

Attribute lookup: O(n) linear scan
Child iteration: O(n) linear scan
File loading: O(n) single-pass parse
Memory overhead: ~103 bytes per node (base) + text content + (actual attributes × ~20-50 bytes each)

📦 Memory Usage

This section describes the exact RAM footprint of the XML parser.

🧱 Base Memory per Node

A TXMLNode record contains:

Name:           21 bytes  (string[20])
TextBuf:         4 bytes  (pointer)
TextLen:         2 bytes  (Word)
TextCap:         2 bytes  (Word)

AttrKeys:       16 bytes  (8 × Pointer)
AttrValues:     16 bytes  (8 × Pointer)
AttrCount:       2 bytes  (Integer)

Tree pointers:  12 bytes  (FirstChild, NextSibling, Parent)
───────────────────────────────────────────────
Record total:   ~95–110 bytes per node

Attribute lookup is a simple and fast linear scan (max 8 attributes).

🏷️ Per Attribute Cost (Dynamic Allocation)

Each attribute uses variable-sized memory:

Key string:    Length(Key)   + 1 byte
Value string:  Length(Value) + 1 byte
───────────────────────────────────────────────
Total:         ~5–20 bytes typical
               (instead of the old 512 bytes)

Example:

code="65" → key 4 bytes + value 3 bytes = 8 bytes total
x="123" → ~7 bytes
name="monsterslayer" → ~16 bytes

📝 Text Content Memory

Text is stored in a dynamically growing buffer:

First allocation: 256 bytes
Grows by doubling, then +4096
Maximum size: ~64 KB

Memory used:

TextBuf capacity: 256–65520 bytes (depending on growth)
TextLen:          actual used bytes

Nodes without text do not allocate any text memory.

📉 Memory Usage Example (FONT-SM.XML)

For a ~5.5 KB XML containing:

92 nodes
367 attributes
No text content

Memory usage:

Node records:    ~9.8 KB
Attributes:      ~2.4 KB
Text buffers:    0 bytes
--------------------------------
Total:           ~12 KB

Common Patterns

Find specific element by attribute

function FindLevelByID(Root: PXMLNode; ID: string): PXMLNode;
var
  Levels, Level: PXMLNode;
begin
  FindLevelByID := nil;
  Levels := XMLFirstChild(Root, 'levels');
  if Levels = nil then Exit;

  Level := XMLFirstChild(Levels, 'level');
  while Level <> nil do
  begin
    if XMLAttr(Level, 'id') = ID then
    begin
      FindLevelByID := Level;
      Exit;
    end;
    Level := XMLNextSibling(Level, 'level');
  end;
end;

Count elements

function XMLCountChildren(const Node: PXMLNode; const Name: string): Integer;

Safe attribute parsing

procedure GetIntAttr(Node: PXMLNode; AttrName: string; var Value: Integer);
var
  S: string;
  Code: Integer;
begin
  if XMLHasAttr(Node, AttrName) then
  begin
    S := XMLAttr(Node, AttrName);
    Val(S, Value, Code);
    if Code <> 0 then
      WriteLn('Warning: Invalid integer in ', AttrName);
  end;
end;

XML Writing & Tree Modification

Saving XML Files

function XMLSaveFile(const FileName: string; Root: PXMLNode): Boolean;

Writes an XML file from a MiniXML tree.

Produces well-formed XML.
Correct indentation and nesting.
Self-closing empty tags.
Escapes all required characters (& < > " ').
Handles large text blocks (CSV, maps) without modification.
If the root node is #document, only its children are written.

Returns: True on success, False on error.

function GetSaveXMLError: string;

Returns last XML save error message.

Creating Child Nodes

function XMLAddChildElement(Parent: PXMLNode; const Name: string): PXMLNode;

Creates a new element and attaches it as the last child of Parent.

Example:

var N: PXMLNode;
N := XMLAddChildElement(Root, 'tileset');
XMLSetAttr(N, 'firstgid', '1');

Setting Element Text

procedure XMLSetText(Node: PXMLNode; const S: string);`

Replaces the entire text content of a node.

Useful for:

<data encoding="csv">
numeric lists
small strings

Example:

XMLSetText(DataNode, '1,2,3,4,5');

Appending Text to a Node

procedure XMLAppendText(Node: PXMLNode; const S: string);

Appends text to existing node text, expanding the internal buffer if needed.

Useful when writing large CSV maps:

XMLSetText(DataNode, '1,2,3');
XMLAppendText(DataNode, ',4,5,6');

Setting Attributes (Existing)

procedure XMLSetAttr(Node: PXMLNode; const Key, Value: string);

Creates or updates an attribute:

XMLSetAttr(Node, 'width', '320');
XMLSetAttr(Node, 'height', '200');

Building an XML File

Below is a simple example that demonstrates reading, modifying, and saving an XML file:

var
  Root, Node: PXMLNode;
begin
  if not XMLLoadFile('DATA\RES.XML', Root) then
    Halt;

  { Modify root attribute }
  XMLSetAttr(Root, 'version', '2.0');

  { Add a <resource> entry }
  Node := XMLAddChildElement(Root, 'resource');
  XMLSetAttr(Node, 'name', 'sprite');
  XMLSetAttr(Node, 'path', 'DATA\SPRITE.PCX');
  XMLSetText(Node, 'Auto-generated entry.');

  { Replace text of <testdata> }
  Node := XMLFirstChild(Root, 'testdata');
  if Node <> nil then
    XMLSetText(Node, '10,20,30,40,50');

  { Save the result }
  if not XMLSaveFile('DATA\RES-OUT.XML', Root) then
    WriteLn('Save error: ', GetSaveXMLError);

  XMLFreeTree(Root);
end.

Notes & Limitations

MiniXML does not preserve whitespace formatting of the input file.
The writer may reorder attributes (still valid XML).
Text nodes store bytes as-is; no UTF-8 conversion.
Large <data> blocks are handled efficiently using raw buffers.

Troubleshooting

Problem: XMLLoadFile returns False

Check file exists and path is correct (use DOS 8.3 format)
Ensure file is under ~64KB (65500 bytes)
Check file is valid XML (well-formed)

Problem: Attribute not found

Check attribute name spelling (case-sensitive)
Verify element actually has the attribute in XML file
Check if node pointer is nil

Problem: Memory leak / out of memory

Ensure XMLFreeTree is called for every loaded XML
Check for extremely large text content (>64KB per node)
Reduce number of nodes/attributes if memory constrained

Problem: Text content truncated at 255 bytes

This is expected for Node^.Text string
Large text automatically uses TextBuf instead
Check Node^.TextBuf <> nil and Node^.TextLen for large text

Testing

See TESTS\XMLTEST.PAS for a complete example program demonstrating all features.

Compile and run:

cd TESTS
CXMLTEST.BAT
XMLTEST.EXE

Design Goals

MiniXML was created in 2025 specifically for this DOS game engine with the following priorities:

Memory Efficiency:

Dynamic allocation for all variable-size data
Only allocate what’s actually needed (attributes, text)
Optimized for typical game config files (few attributes per node)
Result: ~103 bytes per empty node vs. 4680 bytes in naive design (98% reduction)

Real-Mode DOS Compatibility:

All allocations respect TP7 heap block limits (≤64KB per block)
Buffer growth capped at safe limits
Word-sized position/length fields for >32KB file support
Tested on DOSBox-X and real hardware

Simplicity:

Single-pass parser, no preprocessing
DOM-style tree for easy navigation

Lightweight XML Parser and Writer

Overview

Features

Dependencies

Type Definitions

Core API

Loading and Freeing

Navigation

Attributes

Utility Functions

Usage Examples

Iterating Through Lists

Reading Text Content

Checking Optional Attributes

Sample XML File

Limitations

Memory Management

Performance Characteristics

📦 Memory Usage

🧱 Base Memory per Node

🏷️ Per Attribute Cost (Dynamic Allocation)

📝 Text Content Memory

📉 Memory Usage Example (FONT-SM.XML)

Common Patterns

Find specific element by attribute

Count elements

Safe attribute parsing

XML Writing & Tree Modification

Saving XML Files

Creating Child Nodes

Example:

Setting Element Text

Example:

Appending Text to a Node

Setting Attributes (Existing)

Building an XML File

Notes & Limitations

Troubleshooting

Testing

Design Goals

See Also