feat(core): naming templates with tokens, formats and sanitizing

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012iLMBNwBE2GnphAsu4cjaC
This commit is contained in:
Claude committed 2026-10-02 09:37:52 +00:00
1 parent c40b6a7cd3
commit a76695f2e9
4 files changed
+346

No files matched your search

+36
View File
@@ -0,0 +1,36 @@
namespace Titano.Core.Naming;
/// <summary>Values available to folder/file templates for one frame (BRIEF §7.1).</summary>
public sealed record NamingContext
{
/// <summary>Camera wall-clock capture time.</summary>
public DateTime CapturedAt { get; init; }
/// <summary>Start of the session the frame belongs to.</summary>
public DateTime SessionStart { get; init; }
/// <summary>1-based session number within the import.</summary>
public int Session { get; init; } = 1;
/// <summary>1-based frame number across the import (or sequence).</summary>
public int Number { get; init; } = 1;
/// <summary>1-based frame number within the session.</summary>
public int NumberInSession { get; init; } = 1;
public string? CameraMake { get; init; }
public string? CameraModel { get; init; }
public string? Lens { get; init; }
public int? Iso { get; init; }
public double? ExposureTime { get; init; }
public double? FNumber { get; init; }
/// <summary>Original file name without extension.</summary>
public string OriginalName { get; init; } = string.Empty;
/// <summary>Original extension without the dot, as found on the card.</summary>
public string Extension { get; init; } = string.Empty;
/// <summary>Sequence title, when the user gave one.</summary>
public string? Title { get; init; }
}
+210
View File
@@ -0,0 +1,210 @@
using System.Globalization;
using System.Text;
namespace Titano.Core.Naming;
/// <summary>A parse problem in a template, with the character position for live validation in the UI.</summary>
public sealed record TemplateError(int Position, string Code, string? Token);
/// <summary>
/// Folder/file naming templates (BRIEF §7.1). Tokens are written as <c>{name}</c> or <c>{name:format}</c>, where the
/// format is passed to the .NET formatter (e.g. <c>{n:0000}</c>, <c>{date:yyyyMMdd}</c>). <c>{{</c> and <c>}}</c> are literal
/// braces. Characters that are illegal in Windows/Linux file names are replaced, never passed through.
/// </summary>
public sealed class PathTemplate
{
/// <summary>Every token the templates understand. Descriptions are localized resources <c>Import.Token.&lt;name&gt;</c>.</summary>
public static readonly IReadOnlyList<string> Tokens =
[
"year", "month", "day", "date", "time", "hm", "session", "sessionstart", "camera", "lens",
"iso", "shutter", "aperture", "n", "nsession", "name", "ext", "title",
];
private static readonly HashSet<string> TokenSet = new(Tokens, StringComparer.OrdinalIgnoreCase);
private static readonly char[] Illegal = ['<', '>', ':', '"', '|', '?', '*', '\\', '/', '\0'];
private static readonly HashSet<string> ReservedNames = new(StringComparer.OrdinalIgnoreCase)
{
"CON", "PRN", "AUX", "NUL", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9",
"LPT1", "LPT2", "LPT3", "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9",
};
private readonly List<Part> _parts;
private PathTemplate(string source, List<Part> parts, IReadOnlyList<TemplateError> errors)
{
Source = source;
_parts = parts;
Errors = errors;
}
public string Source { get; }
/// <summary>Problems found while parsing; a template with errors still expands best-effort.</summary>
public IReadOnlyList<TemplateError> Errors { get; }
public bool IsValid => Errors.Count == 0;
/// <summary>Parses a template; '/' separates folder levels (only meaningful for folder templates).</summary>
public static PathTemplate Parse(string template)
{
ArgumentNullException.ThrowIfNull(template);
var parts = new List<Part>();
var errors = new List<TemplateError>();
var literal = new StringBuilder();
for (var i = 0; i < template.Length; i++)
{
var c = template[i];
if (c == '{')
{
if (i + 1 < template.Length && template[i + 1] == '{')
{
literal.Append('{');
i++;
continue;
}
var close = template.IndexOf('}', i + 1);
if (close < 0)
{
errors.Add(new TemplateError(i, "UnclosedBrace", null));
literal.Append(template, i, template.Length - i);
break;
}
if (literal.Length > 0)
{
parts.Add(Part.Literal(literal.ToString()));
literal.Clear();
}
var body = template[(i + 1)..close];
var colon = body.IndexOf(':', StringComparison.Ordinal);
var name = (colon < 0 ? body : body[..colon]).Trim();
var format = colon < 0 ? null : body[(colon + 1)..];
if (name.Length == 0) errors.Add(new TemplateError(i, "EmptyToken", null));
else if (!TokenSet.Contains(name)) errors.Add(new TemplateError(i, "UnknownToken", name));
parts.Add(Part.Token(name.ToLowerInvariant(), format));
i = close;
}
else if (c == '}')
{
if (i + 1 < template.Length && template[i + 1] == '}')
{
literal.Append('}');
i++;
continue;
}
errors.Add(new TemplateError(i, "UnopenedBrace", null));
}
else
{
literal.Append(c);
}
}
if (literal.Length > 0) parts.Add(Part.Literal(literal.ToString()));
if (template.Trim().Length == 0) errors.Add(new TemplateError(0, "Empty", null));
return new PathTemplate(template, parts, errors);
}
/// <summary>Expands to a relative folder path (forward slashes; each segment sanitized).</summary>
public string ExpandFolder(NamingContext context)
{
var raw = Expand(context, allowSeparators: true);
var segments = raw.Split('/', StringSplitOptions.RemoveEmptyEntries)
.Select(SanitizeSegment)
.Where(s => s.Length > 0);
return string.Join('/', segments);
}
/// <summary>Expands to a file name; the original extension is appended unless the template already ends with {ext}.</summary>
public string ExpandFile(NamingContext context)
{
var hasExt = _parts.Count > 0 && _parts[^1] is { IsToken: true, Text: "ext" };
var name = SanitizeSegment(Expand(context, allowSeparators: false));
if (name.Length == 0) name = SanitizeSegment(context.OriginalName);
if (!hasExt && context.Extension.Length > 0) name += "." + context.Extension;
return name;
}
private string Expand(NamingContext c, bool allowSeparators)
{
var inv = CultureInfo.InvariantCulture;
var sb = new StringBuilder();
foreach (var part in _parts)
{
if (!part.IsToken)
{
sb.Append(allowSeparators ? part.Text.Replace('\\', '/') : part.Text);
continue;
}
var f = part.Format;
var value = part.Text switch
{
"year" => c.CapturedAt.ToString(f ?? "yyyy", inv),
"month" => c.CapturedAt.ToString(f ?? "MM", inv),
"day" => c.CapturedAt.ToString(f ?? "dd", inv),
"date" => c.CapturedAt.ToString(f ?? "yyyy-MM-dd", inv),
"time" => c.CapturedAt.ToString(f ?? "HH-mm-ss", inv),
"hm" => c.CapturedAt.ToString(f ?? "HH-mm", inv),
"sessionstart" => c.SessionStart.ToString(f ?? "yyyy-MM-dd HH-mm", inv),
"session" => c.Session.ToString(f ?? "0", inv),
"n" => c.Number.ToString(f ?? "0000", inv),
"nsession" => c.NumberInSession.ToString(f ?? "0000", inv),
"camera" => CameraName(c.CameraMake, c.CameraModel),
"lens" => c.Lens ?? string.Empty,
"iso" => c.Iso?.ToString(f ?? "0", inv) ?? string.Empty,
"shutter" => Shutter(c.ExposureTime),
"aperture" => c.FNumber is { } fn ? "f" + fn.ToString(f ?? "0.#", inv) : string.Empty,
"name" => c.OriginalName,
"ext" => c.Extension,
"title" => c.Title ?? string.Empty,
_ => string.Empty,
};
// Token values never introduce folder levels.
sb.Append(value.Replace('/', '-').Replace('\\', '-'));
}
return sb.ToString();
}
/// <summary>"Canon EOS R5" from make "Canon" + model "Canon EOS R5"; avoids the duplicated brand most cameras report.</summary>
public static string CameraName(string? make, string? model)
{
make = make?.Trim();
model = model?.Trim();
if (string.IsNullOrEmpty(model)) return make ?? string.Empty;
if (string.IsNullOrEmpty(make)) return model;
var brand = make.Split(' ', StringSplitOptions.RemoveEmptyEntries)[0];
if (brand.Equals("NIKON", StringComparison.OrdinalIgnoreCase)) brand = "Nikon";
if (model.StartsWith(brand, StringComparison.OrdinalIgnoreCase)) return brand + model[brand.Length..];
return brand + " " + model;
}
/// <summary>1/250 s → "1-250", 2 s → "2s" (file-name safe).</summary>
public static string Shutter(double? seconds)
{
if (seconds is not > 0) return string.Empty;
var t = seconds.Value;
if (t >= 0.3) return t.ToString("0.#", CultureInfo.InvariantCulture) + "s";
return "1-" + Math.Round(1 / t).ToString(CultureInfo.InvariantCulture);
}
/// <summary>Replaces characters that are illegal on Windows or Linux and fixes reserved names and trailing dots/spaces.</summary>
public static string SanitizeSegment(string segment)
{
var sb = new StringBuilder(segment.Length);
foreach (var ch in segment)
{
if (ch < 32 || Array.IndexOf(Illegal, ch) >= 0) sb.Append('_');
else sb.Append(ch);
}
var s = sb.ToString().Trim().TrimEnd('.');
while (s.Contains(" ", StringComparison.Ordinal)) s = s.Replace(" ", " ", StringComparison.Ordinal);
var stem = s.Split('.')[0];
if (ReservedNames.Contains(stem)) s = "_" + s;
if (s is "." or "..") s = "_";
return s.Length > 200 ? s[..200].TrimEnd() : s;
}
private readonly record struct Part(bool IsToken, string Text, string? Format)
{
public static Part Literal(string text) => new(false, text, null);
public static Part Token(string name, string? format) => new(true, name, format);
}
}
@@ -0,0 +1,89 @@
using Titano.Core.Naming;
using Titano.Testing;
namespace Titano.Core.Tests.Naming;
public sealed class PathTemplateTests
{
private static readonly NamingContext Frame = new()
{
CapturedAt = new DateTime(2026, 9, 28, 18, 2, 11, 250),
SessionStart = new DateTime(2026, 9, 28, 18, 2, 11),
Session = 2,
Number = 1,
NumberInSession = 1,
CameraMake = "Canon",
CameraModel = "Canon EOS R5",
Lens = "RF24-70mm F2.8 L IS USM",
Iso = 400,
ExposureTime = 1.0 / 8,
FNumber = 8,
OriginalName = "IMG_0001",
Extension = "CR2",
Title = "Harbour sunset",
};
[Test]
public void DefaultTemplatesMatchTheBriefExample()
{
Assert.Equal("2026/2026-09-28 Canon EOS R5", PathTemplate.Parse(TemplateDefaults.Folder).ExpandFolder(Frame));
Assert.Equal("2026-09-28_18-02-11_0001.CR2", PathTemplate.Parse(TemplateDefaults.File).ExpandFile(Frame));
}
[Theory]
[Case("{n:000000}", "000001.CR2")]
[Case("{date:yyyyMMdd}_{name}", "20260928_IMG_0001.CR2")]
[Case("{iso}_{shutter}_{aperture}", "400_1-8_f8.CR2")]
[Case("{name}.{ext}", "IMG_0001.CR2")]
[Case("{{literal}}_{n}", "{literal}_0001.CR2")]
[Case("{session}-{nsession:00}", "2-01.CR2")]
public void FileTokens(string template, string expected) =>
Assert.Equal(expected, PathTemplate.Parse(template).ExpandFile(Frame));
[Test]
public void IllegalCharactersAreReplaced()
{
var context = Frame with { Title = "a:b*c?<d>|e\"f" };
Assert.Equal("a_b_c__d__e_f.CR2", PathTemplate.Parse("{title}").ExpandFile(context));
}
[Test]
public void TokenValuesNeverCreateFolders()
{
var context = Frame with { Lens = "18/55 mm" };
Assert.Equal("2026/18-55 mm", PathTemplate.Parse("{year}/{lens}").ExpandFolder(context));
}
[Test]
public void ReservedWindowsNamesAreEscaped() =>
Assert.Equal("_CON.CR2", PathTemplate.Parse("{title}").ExpandFile(Frame with { Title = "CON" }));
[Test]
public void ErrorsCarryPositionAndToken()
{
var t = PathTemplate.Parse("{date}_{bogus}_{n");
Assert.False(t.IsValid);
Assert.Contains(new TemplateError(7, "UnknownToken", "bogus"), t.Errors);
Assert.Contains(t.Errors, e => e.Code == "UnclosedBrace");
}
[Test]
public void EmptyExpansionFallsBackToOriginalName() =>
Assert.Equal("IMG_0001.CR2", PathTemplate.Parse("{title}").ExpandFile(Frame with { Title = null }));
[Theory]
[Case("NIKON CORPORATION", "NIKON Z 8", "Nikon Z 8")]
[Case("SONY", "ILCE-7M4", "SONY ILCE-7M4")]
[Case("Canon", "Canon EOS R5", "Canon EOS R5")]
[Case(null, "HERO12 Black", "HERO12 Black")]
public void CameraNameAvoidsDuplicatedBrand(string? make, string model, string expected) =>
Assert.Equal(expected, PathTemplate.CameraName(make, model));
[Test]
public void ShutterFormatting()
{
Assert.Equal("1-250", PathTemplate.Shutter(0.004));
Assert.Equal("2s", PathTemplate.Shutter(2));
Assert.Equal(string.Empty, PathTemplate.Shutter(null));
}
}
+11
View File
@@ -142,6 +142,17 @@ public static class Assert
if (!collection.Contains(expected)) Fail($"{expression}: does not contain {Format(expected)}");
}
/// <summary>At least one element satisfies <paramref name="predicate"/>.</summary>
public static T Contains<T>(IEnumerable<T> collection, Func<T, bool> predicate, [CallerArgumentExpression(nameof(predicate))] string? expression = null)
{
foreach (var item in collection)
{
if (predicate(item)) return item;
}
Fail($"No element matches {expression}");
return default!;
}
public static void DoesNotContain<T>(T unexpected, IEnumerable<T> collection, [CallerArgumentExpression(nameof(collection))] string? expression = null)
{
if (collection.Contains(unexpected)) Fail($"{expression}: unexpectedly contains {Format(unexpected)}");