PathArbiter 0.1.2

🌳 PathArbiter

PathArbiter is a lightweight, static .NET utility class for managing hierarchical JSON settings. It is designed to be simple, fast, and easy to integrate, providing a robust solution for loading default settings and merging them with user-provided overrides.

🦀 Core Concept

The core idea behind PathArbiter is to simplify configuration by providing a "set it and forget it" settings layer.

1. Default Settings: You embed a default configuration file (PathArbiter.json) into your application as an Embedded Resource. PathArbiter loads these first.
2. User Settings: You then tell PathArbiter to load a user's file (i.e. settings.json) from disk.
3. Automatic Merging: PathArbiter automatically merges the user's settings on top of the default settings.

This gives you a powerful, layered configuration system with zero boilerplate. Your application can always safely request a setting, knowing it will get the user's custom value if it exists, or fall back to the sensible default.

✨ Key Features

• Static API: No instantiation needed. Just call Arbiter.GetValue(...).
• Layered JSON Configuration: Automatically merges user settings over default embedded settings.
• Simple Dot-Notation: Access all settings with a simple, human-readable path (e.g., "network.server.timeout").
• Type-Safe Generics: Get any value deserialized to your desired type with GetValue<T>().
• Dynamic Path Creation: SetValue<T>() automatically creates the necessary JSON objects if they don't exist.
• Rich Exception Handling: Provides specific exceptions for common issues (PathNotFoundException, SettingsParseException, etc.).

🚀 Quick Start

1. Installation

Install the package from NuGet.

dotnet add package PathArbiter

2. Basic Usage

Here is a common use-case for loading, reading, and writing settings.

Loading User Settings

PathArbiter automatically loads default settings from an embedded resource (you must provide one). You can then load user settings from a file or stream to merge them.

// Load a user's settings file. This will be merged on top of the defaults.
try
{
    Arbiter.LoadUserData("user-settings.json"); 
}
catch (Exception ex)
{
    Console.WriteLine($"Error loading user settings: {ex}");
    throw;
}

Getting Values

Use GetValue<T>() with a dot-notation path to retrieve any setting.

try
{
    // Get a top-level value
    string appName = Arbiter.GetValue<string>("application.name");
    
    // Get a nested value
    int timeout = Arbiter.GetValue<int>("network.timeout");

    Console.WriteLine($"Starting {appName} with a {timeout}ms timeout.");
}
catch (PathNotFoundException ex)
{
    Console.WriteLine($"Error: A required setting was not found: {ex.Path}");
}

Setting Values

Use SetValue<T>() to modify a setting in memory. The path will be created if it doesn't exist.

// Set a simple value
Arbiter.SetValue("application.name", "MyApp");

// Set a nested value. 
// If "network" doesn't exist, it will be created automatically.
Arbiter.SetValue("network.timeout", 5000);

Saving Values

You can save the current in-memory settings (including all merged values) to any writable stream.

// Save settings to a file with pretty printing (default)
try
{
    using (var fileStream = File.Create("user-settings.json"))
    {
        Arbiter.SaveUserData(fileStream);
    }
}
catch (Exception ex)
{
    Console.WriteLine($"Could not save settings: {ex.Message}");
}

// Save settings to a memory stream without pretty printing
using (var memoryStream = new MemoryStream())
{
    Arbiter.SaveUserData(memoryStream, prettyPrint: false);
    // ...
}

Checking for Errors

If any errors occur during the initial static load (e.g., your default embedded settings file is corrupt), you can check them.

IList<Exception> exceptions = Arbiter.GetInitializationExceptions();
if (exceptions.Any())
{
    Console.WriteLine("Error(s) during default settings initialization:");
    foreach(Exception ex in exceptions)
    {
        Console.WriteLine(ex);
    }
}

📓 API Overview

The Arbiter class is static. All methods are called directly.

🚫 Exception Handling

PathArbiter provides specific exceptions to make error handling clean.

• SettingsParseException: Thrown if the JSON data in a file or stream is invalid and cannot be parsed.
• PathNotFoundException: Thrown by GetValue<T> if the specified path does not exist in the merged settings.
• InvalidPathException: Thrown by SetValue<T> if a path conflicts with an existing value (e.g., trying to set "a.b" when "a" is already a string, not an object).
• FileNotFoundException: Thrown by LoadUserData(string path) if the file does not exist.
• FileUnopenableException: Thrown by LoadUserData(string path) if the file exists but cannot be opened for reading (e.g., permissions issue).
• StreamUnwritableException: Thrown by SaveUserData when the provided stream is not writable.
• NoSettingsLoadedException: Thrown by SaveUserData when no settings are available to save (e.g., initialization failed).

🤝 Contributing

Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

📜 License

PathArbiter is provided free of charge for both personal and commercial use.

This software is proprietary and is not open source. You may not modify, decompile, or redistribute the source code without express written permission. For the full terms and conditions of use, please refer to the LICENSE file included in the NuGet package.