Files
Chronos/src/Chronos.Core/Naming/PathTemplate.cs
T
Alby96andClaude Opus 5.5 7e4a3b481d
CI / Build and test (push) Successful in 9m15s
CI / Windows tests and installer (push) Skipped
CI / YAML check (push) Successful in 6s
Release / Build, test and publish (push) Successful in 15m35s
CI / PostgreSQL 16 integration (push) Successful in 7m26s
CI / PostgreSQL 17 integration (push) Successful in 6m47s
CI / Docker image (push) Successful in 59s
Release / Server image (push) Successful in 1m24s
feat: owner review 2 phase 4a: Reorganize sequences after import (#12)
- Reorganize… on the web panel and the desktop: folder, file and title templates applied to existing sequences, with a dry run and an explicit Apply that runs as a job.
- One naming rule (FrameNaming) for import, upload and Reorganize.
- Crash-safe plan and file journals, held plans, stale-plan refusal; exports move with their folder.
- Writers refuse a folder another program moved or gave to another sequence.
- Server: POST /api/v1/archive/reorganize with a bounded plan cache; template rules.
- Phase 3 docs and translations merged; strings in all 38 languages.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Alberto Balbo <alberto.balbo.96@gmail.com>
2026-10-27 21:58:39 +01:00

279 lines
13 KiB
C#

using System.Globalization;
using System.Text;
using Chronos.Core.Archiving;
namespace Chronos.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",
];
/// <summary>The longest text <see cref="ExpandText"/> gives: the longest title a sequence takes.</summary>
public const int MaxTextLength = 200;
/// <summary>The longest folder level or file name a template gives (<see cref="SanitizeSegment"/>), before an appended extension.</summary>
public const int MaxSegmentLength = 200;
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>Whether the template holds <paramref name="token"/> (<c>title</c> for <c>{title}</c>), whatever its case or format.</summary>
public bool Uses(string token) => _parts.Any(p => p.IsToken && string.Equals(p.Text, token, StringComparison.OrdinalIgnoreCase));
/// <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). A level archive scans never enter
/// (<see cref="IsHiddenFolder"/>), which a token value such as a title can give, gets a leading <c>_</c>, so every
/// sequence filed or moved by a template stays where a scan finds it.
/// </summary>
public string ExpandFolder(NamingContext context) => string.Join('/', Levels(context).Select(s => IsHiddenFolder(s) ? "_" + s : s));
/// <summary>Whether a level of the folder this template gives for <paramref name="context"/> is one scans never enter, before it is escaped.</summary>
public bool WritesHiddenFolder(NamingContext context) => Levels(context).Any(IsHiddenFolder);
/// <summary>
/// A folder name archive scans never enter (<see cref="ArchiveScanner"/>): one that starts with a dot, or a folder
/// the layout keeps for itself (<c>.chronos</c>, <c>originals</c>, <c>proxies</c>, <c>exports</c>), whatever its case.
/// </summary>
public static bool IsHiddenFolder(string name)
{
ArgumentNullException.ThrowIfNull(name);
return name.StartsWith('.') || ArchiveLayout.IsReservedFolder(name);
}
private IEnumerable<string> Levels(NamingContext context) =>
Expand(context, allowSeparators: true).Split('/', StringSplitOptions.RemoveEmptyEntries).Select(SanitizeSegment).Where(s => s.Length > 0);
/// <summary>
/// Expands to a file name; the original extension is appended unless the template already ends with {ext}. A name
/// longer than <see cref="MaxSegmentLength"/> is shortened before the <c>.{ext}</c> the template ends with, never through it.
/// </summary>
public string ExpandFile(NamingContext context)
{
var hasExt = _parts.Count > 0 && _parts[^1] is { IsToken: true, Text: "ext" };
var name = Clean(Expand(context, allowSeparators: false));
var ext = hasExt && context.Extension.Length > 0 ? "." + context.Extension : string.Empty;
name = ext.Length > 0 && name.Length > MaxSegmentLength && name.EndsWith(ext, StringComparison.Ordinal)
? Shorten(name[..^ext.Length], MaxSegmentLength - ext.Length) + ext
: Shorten(name, MaxSegmentLength);
if (name.Length == 0) name = SanitizeSegment(context.OriginalName);
if (!hasExt && context.Extension.Length > 0) name += "." + context.Extension;
return name;
}
/// <summary>
/// Whether every file name the template gives ends with the photo's own extension: the template does not end with
/// <c>{ext}</c> (the extension is appended), or ends with <c>.{ext}</c>, which a long name keeps whole
/// (<see cref="ExpandFile"/>). <c>{n}{ext}</c> would drop the dot, and with it the extension every reader of the photo goes by.
/// </summary>
public bool KeepsExtension =>
_parts is not [.., { IsToken: true, Text: "ext" }] || _parts is [.., { IsToken: false, Text: var before }, { IsToken: true, Text: "ext" }] && before.EndsWith('.');
/// <summary>
/// Expands to plain text, such as a sequence title: the literals and the token values as they are, since a title may hold
/// characters a file name cannot (<c>Paris: night</c>), control characters as spaces, trimmed, no extension; at most
/// <see cref="MaxTextLength"/> characters.
/// </summary>
public string ExpandText(NamingContext context)
{
var text = new StringBuilder(Expand(context, allowSeparators: false, raw: true));
for (var i = 0; i < text.Length; i++)
{
if (char.IsControl(text[i])) text[i] = ' ';
}
return Shorten(text.ToString().Trim(), MaxTextLength);
}
/// <summary>At most <paramref name="max"/> characters of <paramref name="s"/>, a character outside the basic plane never cut in two, trailing spaces trimmed.</summary>
private static string Shorten(string s, int max)
{
if (s.Length <= max) return s;
var cut = char.IsHighSurrogate(s[max - 1]) ? max - 1 : max;
return s[..cut].TrimEnd();
}
/// <param name="raw">Token values as they are: text, not a path.</param>
private string Expand(NamingContext c, bool allowSeparators, bool raw = false)
{
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(raw ? value : 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; at most
/// <see cref="MaxSegmentLength"/> characters.
/// </summary>
public static string SanitizeSegment(string segment) => Shorten(Clean(segment), MaxSegmentLength);
/// <summary><see cref="SanitizeSegment"/> without its length limit.</summary>
private static string Clean(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;
}
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);
}
}