TwoDimensionalArray.ParserLib 1.0.0

TwoDimensionalArray.ParserLib

A lightweight .NET library for parsing 2DA (Two-Dimensional Array) files. Written in C#, but fully compatible with all .NET languages including VB.NET, F#, and C++.

Special thanks to the creators of the 2DA file format and the game development/modding community for sharing documentation.

Features

• Parses 2DA files (Two-Dimensional Array format used in various games)
• Handles empty cells correctly (returns empty strings)
• Supports comments (lines starting with //)
• Provides a clean, immutable data structure for parsed data
• Supports parsing from both file paths and string content
• Includes an extension method for easy value retrieval
• Compatible with all .NET languages (C#, VB.NET, F#, C++/CLI)

Installation

NuGet Package

Install via NuGet:

Install-Package TwoDimensionalArray.ParserLib -Version 1.0.0

Or via .NET CLI:

dotnet add package TwoDimensionalArray.ParserLib --version 1.0.0

Usage

Parsing from File

C# Example:

using TwoDimensionalArray.ParserLib;

// Parse a 2DA file
var data = Parser2DA.ParseFile("path/to/your/file.2da");

// Access version info
Console.WriteLine($"Version: {data.Version}");

// Access column names
foreach (string col in data.Columns)
{
    Console.WriteLine(col);
}

// Access rows
foreach (var row in data.Rows)
{
    foreach (var (columnName, value) in row)
    {
        Console.WriteLine($"{columnName}: {value}");
    }
}

VB.NET Example:

Imports TwoDimensionalArray.ParserLib

' Parse a 2DA file
Dim data As Data2DA = Parser2DA.ParseFile("path/to/your/file.2da")

' Access version info
Console.WriteLine($"Version: {data.Version}")

' Access column names
For Each col In data.Columns
    Console.WriteLine(col)
Next col

' Access rows
For Each row In data.Rows
    For Each entry In row
        Console.WriteLine($"{entry.Key}: {entry.Value}")
    Next entry
Next row

F# Example:

open TwoDimensionalArray.ParserLib

// Parse a 2DA file
let data = Parser2DA.ParseFile("path/to/your/file.2da")

// Access version info
printfn "Version: %s" data.Version

// Access column names
data.Columns |> Seq.iter (printfn "%s")

// Access rows
data.Rows |> Seq.iter (fun row -> 
    row |> Seq.iter (fun (KeyValue(k, v)) -> printfn "%s: %s" k v)
)

Parsing from String Content

C# Example:

using TwoDimensionalArray.ParserLib;

// Define the multi-line string content
string content = @"2DA V2.0
ID  Name    Level
0   Warrior 5
1   Mage    4";

// Parse from string content
var data = Parser2DA.ParseContent(content);
// Access data
string name = data.GetValue(0, "Name"); // "Warrior"

VB.NET Example:

Imports TwoDimensionalArray.ParserLib

' Define the multi-line string content
Dim content As String = @"2DA V2.0
ID  Name    Level
0   Warrior 5
1   Mage    4"

' Parse from string content and access data
Dim data As Data2DA = Parser2DA.ParseContent(content)
Dim name As String = data.GetValue(0, "Name")  ' "Warrior"

Get Value by Row and Column

C# Example:

using TwoDimensionalArray.ParserLib;

var data = Parser2DA.ParseFile("characters.2da");

// Get value using extension method
string name = data.GetValue(0, "Name");
int level = int.Parse(data.GetValue(0, "Level"));

VB.NET Example:

Imports TwoDimensionalArray.ParserLib

Dim data As Data2DA = Parser2DA.ParseFile("characters.2da")

' Get value using extension method
Dim name As String = data.GetValue(0, "Name")
Dim level As Integer = Integer.Parse(data.GetValue(0, "Level"))

2DA File Format

The 2DA format is a simple tabular data format used by games:

2DA V2.0
// This is a comment
ID  Name    Level  HP
0   Warrior 5      120
1   Mage    4      60
2   Rogue   6      85
3   Cleric  3      90

Format Rules

1. First line must start with 2DA (version identifier)
2. Second line contains column names separated by whitespace
3. Subsequent lines contain data rows
4. Empty cells are preserved as empty strings
5. Comments start with // and are ignored

API Reference

Data2DA Record

public record Data2DA(
    string Version,
    IReadOnlyList<string> Columns,
    IReadOnlyList<IReadOnlyDictionary<string, string>> Rows
);

Properties:

• Version - The version string from the 2DA file header (e.g., "2DA V2.0")
• Columns - Read-only list of column names
• Rows - Read-only collection of data rows, each represented as a dictionary

Note for VB.NET users: C# records are treated as classes with read-only properties in VB.NET. You can access properties directly using standard VB.NET syntax.

Parser2DA Class

ParseFile(string filePath)

Parses a 2DA file from the specified path.

Parameters:

• filePath - Path to the 2DA file

Returns:

• Data2DA - Parsed data object

Exceptions:

• InvalidDataException - If file is empty, contains only comments, or has invalid header
• FileNotFoundException - If file does not exist

ParseContent(string content)

Parses 2DA data from a string.

Parameters:

• content - String containing the 2DA data

Returns:

• Data2DA - Parsed data object

Exceptions:

• InvalidDataException - If content is empty, contains only comments, or has invalid header

GetValue(this Data2DA data, int rowIndex, string columnName)

Extension method to retrieve a value from the parsed data.

Parameters:

• data - The parsed Data2DA object
• rowIndex - Zero-based row index
• columnName - Name of the column

Returns:

• string - The value at the specified position, or empty string if cell is empty

Exceptions:

• IndexOutOfRangeException - If row index is out of range
• KeyNotFoundException - If column name is not found

.NET Language Support

This library is designed to work seamlessly with all .NET languages:

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the BSD 3-Clause License. See the LICENSE file for details.