2bc41aeb8602
naming.rs
//! File-name templates for batch exports (`document.exportForScreens {name}`): the same pattern
//! gives every exported file a consistent name, such as `COMPANY-Logo-<filename>-####-YYYYMMDD`.
//!
//! Tokens:
//! - `<filename>` (or `<document>`): the document's name without its extension;
//! - `<name>` (or `<artboard>`, `<item>`): the artboard's, asset's, layer's or selection's name;
//! - `<index>`: the item's place in the export, from 1;
//! - a run of `#`: the counter, zero-padded to the run's length (`####` → `0001`);
//! - `<format>` (or `<ext>`): the file's extension; `<scale>`: the row's size (`2x`, `100w`);
//! `<suffix>`: the row's suffix (otherwise added at the end);
//! - the date and time: `YYYYMMDD`, `YYYY-MM-DD` and `YYYY` as written, and `<date>`
//! (YYYYMMDD), `<time>` (hhmmss), `<YYYY>`, `<MM>`, `<DD>`, `<hh>`, `<mm>`, `<ss>`.
//!
//! A trailing `.ext` (or `.<ext>`, `.<format>`) is dropped: the extension comes from the format.
//! The characters Windows does not allow in a file name (`/`, `\`, `:`, `<`, `>`, `"`, `|`, `?`,
//! `*` and control characters) become `-`, in the template's text and in what the tokens put in.
use super::screens::file_part;
/// What a template's tokens stand for, for one file.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct NameParts<'a> {
pub filename: &'a str,
pub name: &'a str,
pub index: usize,
pub counter: u64,
pub format: &'a str,
pub scale: &'a str,
pub suffix: &'a str,
/// `[year, month, day, hour, minute, second]`.
pub when: [i64; 6],
}
/// The bracketed tokens and what each stands for.
fn token(name: &str, p: &NameParts<'_>) -> Option<String> {
let [y, mo, d, h, mi, s] = p.when;
Some(match name {
"filename" | "document" => p.filename.to_string(),
"name" | "artboard" | "item" => p.name.to_string(),
"index" => p.index.to_string(),
"format" | "ext" => p.format.to_string(),
"scale" => p.scale.to_string(),
"suffix" => p.suffix.to_string(),
"date" => format!("{y:04}{mo:02}{d:02}"),
"time" => format!("{h:02}{mi:02}{s:02}"),
"YYYY" => format!("{y:04}"),
"MM" => format!("{mo:02}"),
"DD" => format!("{d:02}"),
"hh" => format!("{h:02}"),
"mm" => format!("{mi:02}"),
"ss" => format!("{s:02}"),
_ => return None,
})
}
/// Does `template` place the row's suffix itself (so it isn't added at the end)?
pub fn has_suffix_token(template: &str) -> bool {
template.contains("<suffix>")
}
/// The file name (without extension) `template` gives for `p`.
pub fn render(template: &str, p: &NameParts<'_>) -> String {
let mut t = template.trim();
for ext in [".ext", ".<ext>", ".<format>"] {
if let Some(stripped) = t.strip_suffix(ext) {
t = stripped;
}
}
let [y, mo, d, ..] = p.when;
let mut out = String::with_capacity(t.len() + 16);
let mut rest = t;
while let Some(c) = rest.chars().next() {
// Bracketed tokens; an unknown one stays as written, with `-` for its brackets. A token's
// name has no `<`, so the search for its `>` stops at the next `<`: each part of the
// pattern is searched once, not once for every `<` before it.
if c == '<'
&& let Some(end) = rest.get(1..).and_then(|r| r.find(['<', '>'])).map(|i| i + 1).filter(|&i| rest.as_bytes().get(i) == Some(&b'>'))
&& let Some(value) = rest.get(1..end).and_then(|name| token(name, p))
{
out.push_str(&value);
rest = rest.get(end + 1..).unwrap_or("");
continue;
}
if c == '#' {
let run = rest.chars().take_while(|c| *c == '#').count();
out.push_str(&format!("{:0run$}", p.counter));
rest = rest.get(run..).unwrap_or("");
continue;
}
// The date spelled out, longest first.
let date = [("YYYYMMDD", format!("{y:04}{mo:02}{d:02}")), ("YYYY-MM-DD", format!("{y:04}-{mo:02}-{d:02}")), ("YYYY", format!("{y:04}"))];
if let Some((pat, value)) = date.iter().find(|(pat, _)| rest.starts_with(pat)) {
out.push_str(value);
rest = rest.get(pat.len()..).unwrap_or("");
continue;
}
out.push(c);
rest = rest.get(c.len_utf8()..).unwrap_or("");
}
file_part(out.trim())
}
/// `YYYY-MM-DD` (or `YYYYMMDD`) as `[year, month, day, 0, 0, 0]`; `None` when it isn't a date.
pub fn parse_date(s: &str) -> Option<[i64; 6]> {
let s = s.trim();
let digits: String = match s.len() {
8 => s.to_string(),
10 if s.as_bytes()[4] == b'-' && s.as_bytes()[7] == b'-' => s.chars().filter(|c| *c != '-').collect(),
_ => return None,
};
if digits.len() != 8 || !digits.bytes().all(|b| b.is_ascii_digit()) {
return None;
}
let num = |a: usize, b: usize| digits.get(a..b).and_then(|t| t.parse::<i64>().ok());
let (y, m, d) = (num(0, 4)?, num(4, 6)?, num(6, 8)?);
chrono::NaiveDate::from_ymd_opt(i32::try_from(y).ok()?, u32::try_from(m).ok()?, u32::try_from(d).ok()?)?;
Some([y, m, d, 0, 0, 0])
}
#[cfg(test)]
mod tests {
use super::*;
fn parts() -> NameParts<'static> {
NameParts { filename: "Brand", name: "Dark", index: 3, counter: 7, format: "png", scale: "2x", suffix: "@2x", when: [2026, 10, 16, 9, 5, 0] }
}
#[test]
fn the_example_from_the_request() {
assert_eq!(render("COMPANY-Logo-<filename>-####-YYYYMMDD.ext", &parts()), "COMPANY-Logo-Brand-0007-20261016");
}
#[test]
fn every_token() {
let p = parts();
assert_eq!(render("<document>_<name>_<artboard>_<item>", &p), "Brand_Dark_Dark_Dark");
assert_eq!(render("<index>-#-##-<format>-<ext>-<scale><suffix>", &p), "3-7-07-png-png-2x@2x");
assert_eq!(render("<date>T<time> <YYYY>/<MM>/<DD> <hh>:<mm>:<ss>", &p), "20261016T090500 2026-10-16 09-05-00");
assert_eq!(render("YYYY-MM-DD YYYY", &p), "2026-10-16 2026");
// Words are left alone: only the date patterns and bracketed tokens are replaced.
assert_eq!(render("SUMMER-DD-MM", &p), "SUMMER-DD-MM");
assert_eq!(render("<unknown>-x", &p), "-unknown--x");
assert_eq!(render("logo.<format>", &p), "logo", "the extension comes from the format");
assert!(has_suffix_token("a<suffix>") && !has_suffix_token("a"));
}
#[test]
fn no_name_climbs_out_of_its_folder() {
let p = NameParts { name: "../../etc", ..parts() };
let n = render("a/b\\c:<name>", &p);
assert!(!n.contains('/') && !n.contains('\\') && !n.contains(':'), "{n}");
// Nor any other character Windows does not allow in a file name, typed or put in.
let p = NameParts { name: "<a>\"b|c?d*\u{0}\u{1f}", ..parts() };
assert_eq!(render("<name>|?*\u{1}", &p), "-a--b-c-d-------");
// A long counter is padded, a short run is not cut.
assert_eq!(render("########", &NameParts { counter: 123, ..parts() }), "00000123");
assert_eq!(render("#", &NameParts { counter: 12345, ..parts() }), "12345");
}
/// Many `<` without a `>`, or before one far away, are each looked at once.
#[test]
fn unmatched_brackets_are_read_in_one_pass() {
let p = parts();
let n = 200_000;
assert_eq!(render(&"<".repeat(n), &p), "-".repeat(n));
assert_eq!(render(&format!("{}<name>", "<".repeat(n)), &p), format!("{}Dark", "-".repeat(n)));
assert_eq!(render("<a<name>>", &p), "-aDark-");
}
#[test]
fn dates_are_strict_about_hyphens_and_days() {
for bad in ["2026-1-011", "2-0-2-6-1-0-1-6", "2026--10--16", "2026-02-31", "2026-10-16-", "202610-16"] {
assert_eq!(parse_date(bad), None, "{bad}");
}
assert_eq!(parse_date("2024-02-29"), Some([2024, 2, 29, 0, 0, 0]));
}
#[test]
fn dates_parse() {
assert_eq!(parse_date("2026-10-16"), Some([2026, 10, 16, 0, 0, 0]));
assert_eq!(parse_date("20261016"), Some([2026, 10, 16, 0, 0, 0]));
for bad in ["", "2026-13-01", "2026-1-1", "today", "2026-10-1x"] {
assert_eq!(parse_date(bad), None, "{bad}");
}
}
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.