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:
4 files changed
+346
No files matched your search
@@ -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; }
|
||||
}
|
||||
@@ -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.<name></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));
|
||||
}
|
||||
}
|
||||
@@ -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)}");
|
||||
|
||||
Reference in new issue
Block a user