Lyo.Formatter 1.0.2

Lyo.Formatter

SmartFormat.NET-backed templating for user-defined strings: named placeholders, lists, pluralization, and culture-aware formatting. Designed for validation + formatting pipelines (for example IFormatterService with Lyo.Api computed fields and Lyo.Web.Automation step templates).

Examples

Register services

using Lyo.Formatter;
using Microsoft.Extensions.DependencyInjection;

services.AddFormatterService();
// Or: services.AddFormatterService(sp => /* custom SmartFormatter */);

ITemplate workflow

var t = formatter.CreateTemplate("{Title} — {Count}")
    .WithValue("Title", doc.Title)
    .WithValue("Count", doc.Count);

if (!t.TryValidate(out var err))
    throw new InvalidOperationException(err);

if (!t.TryValidateContext(out var ctxErr))
    throw new InvalidOperationException(ctxErr);

var text = t.Format();

When to use this package

• Turn stored templates ("{User.Name} — {Order.Total:C}") into final text with one or more context objects.
• Validate templates before persisting them (ValidateTemplate, TryValidateTemplate).
• Discover placeholders for dependency analysis (GetPlaceholders, GetUnresolvedPlaceholders, AllPlaceholdersResolved).
• Build context fluently with IContextBuilder (dates, conditional keys, custom formatters).

Registration

Register FormatterService as singleton and expose IFormatterService. Prefer the overload with a factory when you need extra SmartFormat extensions or custom * *SmartSettings**.

Core types

Formatting overloads

• Format(template, object? context) — single DTO, anonymous object, or any type SmartFormat can reflect over.
• Format(template, params object?[] contextItems) — multiple sources; later objects win on duplicate names.
• Format(template, IReadOnlyDictionary<string, object?>) — explicit name/value map.
• Format(template, Action<IContextBuilder>) — build the map with Add, AddIf, AddWhen, typed format strings, or custom Func<,> formatters.

Validation and placeholders

• ValidateTemplate / TryValidateTemplate — parser pass; catches syntax errors before you save a template.
• TryFormat — swallows exceptions from SmartFormat and returns false (use sparingly; prefer validation + known context).
• GetPlaceholders — lightweight regex-based names (first segment of each {...}); good for UI hints and entityTypes-style dependency lists.
• AllPlaceholdersResolved / GetUnresolvedPlaceholders — compare template to formatted output; relies on MaintainTokens so missing keys stay visible as {Name}.
• FormatSegments — walk the parsed template into ordered FormatterSegment spans (literal / placeholder / unresolved) so UIs can color-link {Name} to its replacement without a second parser.

ITemplate workflow

Use AddContext on the template to layer IContextBuilder steps without allocating a full dictionary at the call site. Format(additionalContext) merges a one-off context (dictionary or object) on top of the accumulated state for a single render.

ITemplate.TryValidateContext succeeds when the accumulated context keys cover every placeholder name (or supply a parent path like Order for {Order.Total}). Bare CLR objects passed via WithContext(object?) do not participate in this check (only the merged dictionary and dictionary-shaped extras do), so call WithValue/AddContext or supply a dictionary when you want the validator to confirm coverage.

SmartFormat behavior

This library does not fork SmartFormat; it configures a SmartFormatter instance. Refer to the SmartFormat documentation for list formatting, plural rules, and built-in extensions. Automation note: Lyo.Web.Automation documents that step templates use single-brace placeholders ({page.url}); legacy {{page.url}} is normalized there. This service accepts standard SmartFormat templates as-is.

Integration points

• Lyo.Api — optional IFormatterService for ComputedFields on projection/query responses (SmartFormat templates over projected rows).
• Lyo.Web.Automation — optional IFormatterService to validate automation plans before execution.
• Lyo.Formatter.Web.Components — WASM-safe live template editor + annotated preview (FormatSegments).

Thread safety

FormatterService is safe for concurrent reads if you do not mutate SmartFormatter or Culture from multiple threads without synchronization. Typical ASP.NET Core registration as a singleton treats Culture as ambient per request by setting it at the start of a request (or avoid mutating Culture on the shared instance and pass culture-aware data in context instead).

Dependencies

Generated from ProjectReference / PackageReference (same model as docs/Lyo.ProjectGraph.html).

• Lyo.Common — (direct, lyo)
• Lyo.Exceptions — (direct, lyo)
• Microsoft.Extensions.DependencyInjection.Abstractions 10.0.5 — (direct, microsoft)
• SmartFormat.NET 3.6.1 — (direct, third-party)
• Microsoft.Extensions.Logging.Abstractions 10.0.5 — (transitive, microsoft)
• System.Memory 4.6.3 — (transitive, microsoft, netstandard2.0)
• System.Text.Json 10.0.5 — (transitive, microsoft, netstandard2.0)