Lyo.Formatter 1.0.13

Lyo.Formatter

SmartFormat.NET templating for user-defined strings: named placeholders, lists, pluralization, and culture-aware formatting, plus a C# subset for DateTime math, ternary, and in-memory LINQ. Built for validate-then-format pipelines. IFormatterService is what Lyo.Api computed fields, Lyo.Job.Worker string parameters, and Lyo.Web.Automation step templates call.

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).
• List placeholders for dependency analysis (GetPlaceholders, GetUnresolvedPlaceholders, AllPlaceholdersResolved).
• Build context with IContextBuilder (dates, conditional keys, custom formatters).

Registration

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

Core types

Formatting overloads

• Format(template, object? context). One 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. Unknown context identifiers are not syntax errors.
• TryFormat. Swallows exceptions from SmartFormat and returns false. Prefer validation plus known context.
• GetPlaceholders. Selector paths and expression member paths the host must supply (amount, lastSuccessJobRun.Timestamp). Drops type names (DateTime) and lambda parameters.
• AllPlaceholdersResolved / GetUnresolvedPlaceholders. Compare template to formatted output. Relies on MaintainTokens so missing keys stay visible as {Name}.
• FormatSegments. Walks 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. Simple selectors ({Name}, {Count:N0}, {Items:list:{}|, }) still go through a configured SmartFormatter. See the SmartFormat documentation for list formatting, plural rules, and built-in extensions. {{ / }} emit a literal { / } — they are not a second placeholder form. Write {Name}, not {{Name}}. Lyo.Web.Automation step templates use single-brace placeholders ({page.url}). Legacy {{page.url}} is normalized there.

Expressions

Tokens that are not a plain SmartFormat selector (ternary ? :, =>, comparisons, arithmetic, this., DateTime / TimeSpan / Math / Convert / LINQ) are evaluated with DynamicExpresso against the same context bag. Missing data and unknown methods leave the raw {...} (MaintainTokens). TryValidateTemplate returns syntax errors for the editor; unknown context names (Order in {Order.Total > 6}) are not syntax errors.

Clock (injectable Func<DateTimeOffset> on FormatterService, default real time): {DateTime.Now}, {DateTime.UtcNow}, {DateTime.Today}, {DateTimeOffset.Now} / UtcNow. Offset: {DateTime.Now.AddDays(-1)}, {DateTime.UtcNow - TimeSpan.FromHours(24)}. Format the result with a SmartFormat spec: {DateTime.Now.AddDays(-1):yyyy-MM-dd}.

Context: {amount}, {this.amount}, {client.contact.emailAddress}. Nested {DateTime.UtcNow - {lastSuccessJobRun.Timestamp}} is rewritten innermost-first to keep DateTime types.

Logic / strings: {this.amount > 2 ? "true" : "false"}, {this.nickname ?? this.name}, {string.IsNullOrWhiteSpace(this.nickname) ? this.name : this.nickname}, {string.Join(", ", this.items.Select(x => x.Name))}, {this.items[0].Name}, {Convert.ToInt32(this.qty)}.

LINQ (in-memory Enumerable only): Where / Select / Count / Any / Sum / First / OrderBy / Take / ToList, and the rest of the usual in-memory operators. Not IQueryable, not SQL.

Not in this pass: assignment, new of arbitrary types, extra assemblies, {client.Delete()}, currentTimestamp / 24hrs aliases (use DateTime.* / TimeSpan.*).

WASM

Default Blazor WASM (IL interpreted, no AOT) can run expressions: DynamicExpresso interprets expression trees and does not emit an assembly. Live preview in Lyo.Formatter.Web.Components stays in-process. WASM AOT and Native AOT cannot run the expression engine (no AOT support in DynamicExpresso). SmartFormat-only placeholders still work there; failed expression eval leaves the {token}.

Integration points

• Lyo.Api. Optional IFormatterService for ComputedFields on projection/query responses (SmartFormat and expressions over projected rows).
• Lyo.Job.Worker. Optional IFormatterService for in-memory string parameter placeholders ({jobrun.parameters.startdate}, {client.contact.emailAddress}, {DateTime.UtcNow.AddDays(-1):yyyy-MM-dd}).
• Lyo.Web.Automation. Optional IFormatterService to validate automation plans before execution.
• Lyo.Formatter.Web.Components. Live template editor and annotated preview (FormatSegments). Works on WASM.

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 leave Culture alone 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)
• DynamicExpresso.Core 2.19.3 (direct, third-party)
• 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)