Invex.Rez.Configuration 1.1.0

Rez

Rez is a small .NET library for resolving terse, nestable template text such as {name} and {function(args)}. It is designed for application strings, configuration values, and other text where a full template engine would be unnecessary. Rez takes inspiration from Mustache, but uses curly-brace tokens that can be nested and resolved recursively.

var resolver = new Resolver();
resolver.AddSource(new ResolverSource(new Dictionary<string, string> { { "name", "World" } }));

var greeting = resolver.Resolve("Hello, {name}!");

// greeting: "Hello, World!"

Packages

Features

• Variables. {name} is replaced with its value.
• Functions. {repeat(abc,3)} invokes a function with the raw argument text.
• Nesting. {variable{number}} resolves inside-out, left-to-right.
• Recursion. Resolved values may themselves contain placeholders, with a nesting limit of 4096.
• Escaping. \{literal\} excludes braces from resolution (the backslashes are preserved in the output).
• Pluggable sources. Layer any number of variable and function sources; the first non-null result wins.
• Graceful fallback. Unresolvable placeholders are left in the output unchanged, and Resolve(null) returns null.
• High performance. Pooled buffers and span-based parsing minimize allocations.
• Configuration integration. Resolve templates inside Microsoft.Extensions.Configuration values.

Installation

Install the core package:

dotnet add package Invex.Rez

For Microsoft.Extensions.Configuration integration, install the additional package:

dotnet add package Invex.Rez.Configuration

Both packages target net10.0 and netstandard2.0. On netstandard2.0, Invex.Rez depends on System.Buffers and System.Memory. Invex.Rez.Configuration depends on Microsoft.Extensions.Configuration.Abstractions and Microsoft.Extensions.DependencyInjection.Abstractions.

Quick start

using Invex.Rez.Abstraction;
using Invex.Rez.Implementation;

var resolver = new Resolver()
    .AddSource(new ResolverSource(
        new Dictionary<string, string>
        {
            ["name"] = "World"
        },
        new Dictionary<string, Func<FunctionCall, string>>
        {
            ["shout"] = call => (call.Args ?? string.Empty).ToUpperInvariant() + "!"
        }));

var output = resolver.Resolve("{shout(hello)}, {name}! {unknown}");

// output: "HELLO!, World! {unknown}"

Usage

Variables and functions

Sources provide variables, functions, or both. Functions receive a FunctionCall whose Args property contains all text between the parentheses; Rez does not split or trim arguments, so parsing is owned by the function. Function delegates must return a non-null string; a source returns null only when it cannot resolve a name and wants the next source to be queried.

var resolver = new Resolver()
    .AddSource(new ResolverSource(new Dictionary<string, Func<FunctionCall, string>>
    {
        ["shout"] = call => (call.Args ?? string.Empty).ToUpperInvariant() + "!"
    }));

var output = resolver.Resolve("{shout(hello)}");

// output: "HELLO!"

See the Syntax Guide for the complete template language.

Source ordering and mutable values

ResolverSource is immutable and initialized with known values; ResolverStore is mutable and replaces an existing entry when the same name is added. Sources are queried in registration order for every placeholder and the first non-null result wins, so register overrides before defaults:

var overrides = new ResolverStore();
var defaults = new ResolverSource(new Dictionary<string, string> { ["env"] = "production" });

var resolver = new Resolver()
    .AddSource(overrides)
    .AddSource(defaults);

resolver.Resolve("{env}"); // "production"
overrides.AddVariable("env", "development");
resolver.Resolve("{env}"); // "development"

Use RemoveVariable and RemoveFunction to remove entries from a ResolverStore. Resolver and source types are not synchronized; configure them before concurrent use, or provide synchronization when mutating them. See Getting Started.

Configuration integration

Invex.Rez.Configuration provides two related features:

1. ConfigResolverSource exposes IConfigurationRoot values as Rez variables, including nested keys such as {Logging:Level}.
2. IResolvableConfig wraps configuration and resolves templates when values are read. The AddResolvableConfiguration() extension registers it in dependency injection. Values written through it are stored unmodified; resolution occurs on read.

var config = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

var resolver = new Resolver()
    .AddSource(new ConfigResolverSource(config));

var output = resolver.Resolve("The {ServiceName} service is ready.");

See Configuration Integration for dependency-injection setup.

Custom sources

Implement IResolverSource to pull values from anywhere: environment variables, a database, or computed values. Return null for names the source does not know so the next source is queried. See the Developer Guide.

Documentation

Full documentation: https://invex-games.github.io/rez/

Development

The repository requires the .NET 10 SDK selected by global.json:

dotnet build Invex.Rez.slnx
dotnet test Invex.Rez.slnx

Build and preview the documentation site with the Atom build:

atom BuildDocs
atom ServeDocs

See AGENTS.md for repository structure, code conventions, generated workflow rules, snapshot testing, and the complete contributor checklist.

Where did the name come from?

The name Rez is a play on the word "res" (short for "resolution"), which is the process of resolving a template. The name was chosen as it is short and memorable and is not too similar to other names in the .NET ecosystem.

License

Rez is licensed under the MIT License. See LICENSE.txt.