Add paced ASCII filename cleaner with drag-and-drop interface
Beffroi/beffroi-tools/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-11-11 16:15:05 +01:00
parent 7e470542ff
commit aceab5554b
11 changed files with 919 additions and 2 deletions

View File

@ -6,6 +6,11 @@ with quick-start examples and links to detailed documentation in `docs/`.
## Current tools
- `crates/ascii-names/` is the sequential ASCII filename cleaner: one Rust binary
with egui drag-and-drop and CLI modes. Keep renames paced and single-threaded,
preserve file contents, never overwrite collision targets, and skip symlinks.
The selected root stays unchanged; descendants are processed inside out.
- `crates/pptx-reporter/` is the Rust reporter: shared core, CLI and egui desktop interface.
PDF compilation and DejaVu fonts are embedded. Discover FFprobe beside the app,
under `bin/`, or on PATH. It is the sole PPTX video reporter; the Python

13
Cargo.lock generated
View File

@ -201,6 +201,19 @@ version = "1.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "175571dd1d178ced59193a6fc02dde1b972eb0bc56c892cde9beeceac5bf0f6b"
[[package]]
name = "ascii-names"
version = "0.3.0"
dependencies = [
"clap",
"eframe",
"rfd",
"rustix 1.1.5",
"tempfile",
"unicode-normalization",
"windows-sys 0.61.2",
]
[[package]]
name = "ash"
version = "0.38.0+1.3.281"

View File

@ -1,5 +1,5 @@
[workspace]
members = ["crates/pptx-reporter", "crates/rundown-converter"]
members = ["crates/pptx-reporter", "crates/rundown-converter", "crates/ascii-names"]
default-members = ["crates/pptx-reporter"]
resolver = "3"

View File

@ -5,7 +5,8 @@
![line coverage](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg)
Local document and media tools: a Rust PPTX video reporter with a drag-and-drop
app, a spreadsheet rundown converter for Ontime, and Python document exports.
app, a spreadsheet rundown converter for Ontime, an ASCII filename cleaner,
and Python document exports.
## Quick start
@ -24,6 +25,7 @@ cargo run --locked --bin pptx-reporter-gui
cargo run --locked --bin pptx-reporter -- presentation.pptx --report all
cargo run --locked --bin pptx-reporter -- ./show --timings-only --report ontime
cargo run --locked -p rundown-converter --bin rundown-converter-gui
cargo run --locked -p ascii-names
python3 tools/exporter.py presentation.pptx --output pdf,images
```
@ -42,6 +44,7 @@ opening reports, and reading video timings.
- [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt)
- [Report formats and timing semantics](docs/pptx-videos.md)
- [ASCII filename cleaner](docs/ascii-names.md)
- [Document exports](docs/exporter.md)
- [Rundown converter](docs/rundown-converter.md) · [Sample findings](docs/rundown-corpus.md)
- [Development](docs/development.md) · [CI and coverage](docs/ci.md)

View File

@ -0,0 +1,26 @@
[package]
name = "ascii-names"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
description = "Sequential ASCII filename cleanup for removable drives"
[features]
default = ["desktop"]
desktop = ["dep:eframe", "dep:rfd"]
[dependencies]
clap = { version = "4", features = ["derive"] }
unicode-normalization = "0.1"
eframe = { version = "0.31", optional = true, default-features = false, features = ["default_fonts", "glow", "x11", "wayland"] }
rfd = { version = "0.15", optional = true }
[target.'cfg(any(target_os = "linux", target_vendor = "apple"))'.dependencies]
rustix = { version = "1", features = ["fs"] }
[dev-dependencies]
tempfile = "3"
[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] }

View File

@ -0,0 +1,147 @@
//! Small drag-and-drop interface, with one background worker and bounded progress storage.
use crate::{Options, Summary, clean};
use eframe::egui;
use std::{
collections::VecDeque,
path::PathBuf,
sync::{
Arc, Mutex,
atomic::{AtomicBool, Ordering},
},
thread::{self, JoinHandle},
time::Duration,
};
#[derive(Default)]
struct Progress {
summary: Summary,
messages: VecDeque<String>,
}
impl Progress {
fn push(&mut self, message: String) {
if self.messages.len() == 200 {
self.messages.pop_front();
}
self.messages.push_back(message);
}
}
#[derive(Default)]
struct App {
folder: Option<PathBuf>,
progress: Arc<Mutex<Progress>>,
cancel: Arc<AtomicBool>,
worker: Option<JoinHandle<()>>,
}
impl App {
fn start(&mut self, dry_run: bool) {
let Some(folder) = self.folder.clone() else {
return;
};
self.cancel.store(false, Ordering::Relaxed);
*self.progress.lock().unwrap() = Progress::default();
let progress = self.progress.clone();
let cancel = self.cancel.clone();
self.worker = Some(thread::spawn(move || {
let result = clean(
&folder,
Options {
dry_run,
..Options::default()
},
&cancel,
|summary, message| {
let mut p = progress.lock().unwrap();
p.summary = summary.clone();
p.push(message);
},
);
let mut p = progress.lock().unwrap();
match result {
Ok(summary) => {
p.push(format!(
"{}: {summary}",
if dry_run {
"Preview complete"
} else {
"Cleanup complete"
}
));
p.summary = summary;
}
Err(error) => {
p.summary.errors += 1;
p.push(format!("Cannot clean {}: {error}", folder.display()));
}
}
}));
}
}
impl Drop for App {
fn drop(&mut self) {
self.cancel.store(true, Ordering::Relaxed);
}
}
impl eframe::App for App {
fn update(&mut self, ctx: &egui::Context, _: &mut eframe::Frame) {
if self.worker.as_ref().is_some_and(|w| w.is_finished())
&& self.worker.take().unwrap().join().is_err()
{
let mut p = self.progress.lock().unwrap();
p.summary.errors += 1;
p.push("Worker stopped unexpectedly; completed renames remain in place.".into());
}
let busy = self.worker.is_some();
if !busy {
let dropped = ctx.input(|i| i.raw.dropped_files.clone());
if let Some(file) = dropped.first() {
self.folder = file.path.clone();
}
}
egui::CentralPanel::default().show(ctx, |ui| {
ui.heading("ASCII names");
ui.label("Drop a folder here, then clean its file and subfolder names.");
ui.label("Accents become letters; unknown characters become underscores.");
ui.small("Contents stay intact. The selected folder keeps its name. Links are skipped.");
ui.small("Renaming can break playlists, shortcuts and project references. Keep the folder idle.");
ui.add_space(12.0);
ui.add_enabled_ui(!busy, |ui| {
if ui.button("Choose folder…").clicked()
&& let Some(folder) = rfd::FileDialog::new().pick_folder() { self.folder = Some(folder); }
ui.label(self.folder.as_ref().map_or_else(|| "No folder selected".into(), |p| p.display().to_string()));
ui.horizontal(|ui| {
ui.add_enabled_ui(self.folder.is_some(), |ui| {
if ui.button("Preview").clicked() { self.start(true); }
if ui.button("Clean names").clicked() { self.start(false); }
});
});
});
if busy {
ui.horizontal(|ui| {
ui.spinner(); ui.label("Working sequentially · 25 ms between renames");
if ui.button("Stop").clicked() { self.cancel.store(true, Ordering::Relaxed); }
});
ctx.request_repaint_after(Duration::from_millis(100));
}
ui.separator();
let p = self.progress.lock().unwrap();
ui.label(p.summary.to_string());
ui.small("Most recent 200 messages");
egui::ScrollArea::vertical().stick_to_bottom(true).show(ui, |ui| {
for message in &p.messages { ui.label(message); }
});
});
}
}
pub fn launch() -> eframe::Result {
eframe::run_native(
"ASCII names",
eframe::NativeOptions {
viewport: egui::ViewportBuilder::default()
.with_inner_size([760.0, 480.0])
.with_drag_and_drop(true),
..Default::default()
},
Box::new(|_| Ok(Box::<App>::default())),
)
}

View File

@ -0,0 +1,346 @@
//! Sequential, paced filename cleanup. File contents are never opened.
use std::{
collections::{HashMap, HashSet},
fs, io,
path::{Path, PathBuf},
sync::atomic::{AtomicBool, Ordering},
thread,
time::Duration,
};
use unicode_normalization::{UnicodeNormalization, char::is_combining_mark};
#[cfg(feature = "desktop")]
pub mod gui;
/// ASCII equivalents for accented Latin text and common punctuation; unknowns become `_`.
/// Also removes names that are unsafe on common removable-drive filesystems.
pub fn ascii_name(name: &str) -> String {
let mut result = String::new();
for c in name.nfkd().filter(|c| !is_combining_mark(*c)) {
let replacement = match c {
'ß' | 'ẞ' => "ss",
'æ' => "ae",
'Æ' => "AE",
'œ' => "oe",
'Œ' => "OE",
'ø' => "o",
'Ø' => "O",
'ł' => "l",
'Ł' => "L",
'đ' | 'ð' => "d",
'Đ' | 'Ð' => "D",
'þ' => "th",
'Þ' => "Th",
'‘' | '’' | '‚' | '‛' => "'",
'“' | '”' | '„' | '‟' => "'",
'–' | '—' | '−' => "-",
'…' => "...",
c if c.is_ascii() && !c.is_ascii_control() && !"<>:\"/\\|?*".contains(c) => {
result.push(c);
continue;
}
_ => "_",
};
result.push_str(replacement);
}
result = result.trim_end_matches([' ', '.']).to_owned();
if result.is_empty() {
result.push('_');
}
let base = result
.split('.')
.next()
.unwrap_or("")
.trim_end()
.to_ascii_uppercase();
if matches!(base.as_str(), "CON" | "PRN" | "AUX" | "NUL")
|| (base.len() == 4
&& (base.starts_with("COM") || base.starts_with("LPT"))
&& matches!(base.as_bytes()[3], b'1'..=b'9'))
{
result.insert(0, '_');
}
// Leave room for collision suffixes and stay below common 255-byte limits.
shorten(&result, 220)
}
fn shorten(name: &str, limit: usize) -> String {
if name.len() <= limit {
return name.to_owned();
}
if let Some((stem, ext)) = name.rsplit_once('.')
&& !stem.is_empty()
&& ext.len() < 32
{
return format!("{}.{}", &stem[..limit - ext.len() - 1], ext);
}
name[..limit].to_owned()
}
#[derive(Clone, Copy)]
pub struct Options {
pub dry_run: bool,
pub delay: Duration,
}
impl Default for Options {
fn default() -> Self {
Self {
dry_run: false,
delay: Duration::from_millis(25),
}
}
}
#[derive(Clone, Debug, Default)]
pub struct Summary {
pub visited: usize,
pub renamed: usize,
pub skipped: usize,
pub errors: usize,
pub cancelled: bool,
}
impl std::fmt::Display for Summary {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
write!(
f,
"{} visited; {} renames; {} skipped; {} errors{}",
self.visited,
self.renamed,
self.skipped,
self.errors,
if self.cancelled { "; stopped" } else { "" }
)
}
}
/// Clean the contents of a folder, keeping the selected root itself unchanged.
/// Symlinks and special files are skipped. No parallel I/O; stop between entries.
/// Keep the tree idle during cleanup (renaming can break links and application references).
pub fn clean(
root: &Path,
options: Options,
cancel: &AtomicBool,
mut report: impl FnMut(&Summary, String),
) -> io::Result<Summary> {
if !fs::symlink_metadata(root)?.file_type().is_dir() {
return Err(io::Error::new(
io::ErrorKind::InvalidInput,
"Drop a real folder, not a file or symlink",
));
}
let mut summary = Summary::default();
let mut targets = Targets::default();
// Explicit stack avoids call-stack overflow in deeply nested trees.
enum Work {
Visit(PathBuf),
Rename(PathBuf, bool),
}
let mut stack = vec![Work::Visit(root.to_owned())];
while let Some(work) = stack.pop() {
if cancel.load(Ordering::Relaxed) {
summary.cancelled = true;
break;
}
match work {
Work::Visit(dir) => {
let entries = match fs::read_dir(&dir)
.and_then(|entries| entries.collect::<io::Result<Vec<_>>>())
{
Ok(mut entries) => {
entries.sort_by_key(|e| e.file_name());
entries
}
Err(e) => {
summary.errors += 1;
report(&summary, format!("Cannot read {}: {e}", dir.display()));
continue;
}
};
for entry in entries.into_iter().rev() {
let path = entry.path();
match entry.file_type() {
Ok(kind) if kind.is_dir() => {
stack.push(Work::Rename(path.clone(), true));
stack.push(Work::Visit(path));
}
Ok(kind) if kind.is_file() => stack.push(Work::Rename(path, false)),
Ok(_) => {
summary.skipped += 1;
report(
&summary,
format!("Skipped link/special file: {}", path.display()),
);
}
Err(e) => {
summary.errors += 1;
report(&summary, format!("Cannot inspect {}: {e}", path.display()));
}
}
}
}
Work::Rename(path, is_dir) => {
summary.visited += 1;
if let Err(e) = rename_one(
&path,
is_dir,
options,
&mut targets,
&mut summary,
&mut report,
) {
summary.errors += 1;
report(&summary, format!("Cannot rename {}: {e}", path.display()));
}
}
}
}
Ok(summary)
}
#[derive(Default)]
struct Targets {
reserved: HashSet<PathBuf>,
next_suffix: HashMap<PathBuf, u64>,
}
fn rename_one(
path: &Path,
is_dir: bool,
options: Options,
targets: &mut Targets,
summary: &mut Summary,
report: &mut impl FnMut(&Summary, String),
) -> io::Result<()> {
let original = path.file_name().unwrap();
let name = ascii_name(&original.to_string_lossy());
if original == name.as_str() {
return Ok(());
}
let parent = path.parent().unwrap();
let base_key = parent.join(name.to_ascii_lowercase());
let mut number = targets.next_suffix.get(&base_key).copied().unwrap_or(0);
loop {
let candidate = if number == 0 {
name.clone()
} else {
let p = Path::new(&name);
match (p.file_stem(), p.extension()) {
(Some(stem), Some(ext)) if !is_dir => format!(
"{}_{number}.{}",
stem.to_string_lossy(),
ext.to_string_lossy()
),
_ => format!("{name}_{number}"),
}
};
let target = parent.join(candidate);
// Case-fold reservations also protect previews on case-insensitive media.
let key = parent.join(
target
.file_name()
.unwrap()
.to_string_lossy()
.to_ascii_lowercase(),
);
// Avoid repeated metadata probes when many names normalize to the same base.
if targets.reserved.contains(&key) {
number += 1;
continue;
}
let occupied = match fs::symlink_metadata(&target) {
Ok(_) => true,
Err(e) if e.kind() == io::ErrorKind::NotFound => false,
Err(e) => return Err(e),
};
if occupied {
number += 1;
continue;
}
if !options.dry_run {
// Pace attempts as well as successful renames.
thread::sleep(options.delay);
match rename_no_replace(path, &target) {
Ok(()) => (),
Err(e) if e.kind() == io::ErrorKind::AlreadyExists => {
number += 1;
continue;
}
Err(e) => return Err(e),
}
}
targets.reserved.insert(key);
targets.next_suffix.insert(base_key, number + 1);
summary.renamed += 1;
report(
summary,
format!(
"{}{} -> {}",
if options.dry_run { "Preview: " } else { "" },
path.display(),
target.display()
),
);
return Ok(());
}
}
fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> {
#[cfg(any(target_os = "linux", target_vendor = "apple"))]
{
rustix::fs::renameat_with(
rustix::fs::CWD,
from,
rustix::fs::CWD,
to,
rustix::fs::RenameFlags::NOREPLACE,
)
.map_err(Into::into)
}
#[cfg(target_os = "windows")]
{
use std::os::windows::ffi::OsStrExt;
let from: Vec<u16> = from.as_os_str().encode_wide().chain(Some(0)).collect();
let to: Vec<u16> = to.as_os_str().encode_wide().chain(Some(0)).collect();
// No MOVEFILE_REPLACE_EXISTING: an existing destination must survive.
let ok = unsafe {
windows_sys::Win32::Storage::FileSystem::MoveFileExW(from.as_ptr(), to.as_ptr(), 0)
};
if ok == 0 {
Err(io::Error::last_os_error())
} else {
Ok(())
}
}
#[cfg(not(any(target_os = "linux", target_vendor = "apple", target_os = "windows")))]
{
let _ = (from, to);
Err(io::Error::new(
io::ErrorKind::Unsupported,
"Safe no-overwrite rename is unavailable on this platform",
))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn atomic_rename_refuses_existing_files_and_directories() {
let tmp = tempfile::tempdir().unwrap();
let source = tmp.path().join("source");
let dest = tmp.path().join("dest");
fs::write(&source, "new").unwrap();
fs::write(&dest, "original").unwrap();
assert!(rename_no_replace(&source, &dest).is_err());
assert_eq!(fs::read_to_string(&dest).unwrap(), "original");
assert_eq!(fs::read_to_string(&source).unwrap(), "new");
fs::remove_file(&source).unwrap();
fs::remove_file(&dest).unwrap();
fs::create_dir(&source).unwrap();
fs::create_dir(&dest).unwrap();
assert!(rename_no_replace(&source, &dest).is_err());
assert!(source.is_dir());
assert!(dest.is_dir());
}
}

View File

@ -0,0 +1,52 @@
use clap::Parser;
use std::{path::PathBuf, sync::atomic::AtomicBool, time::Duration};
#[derive(Parser)]
#[command(
version,
about = "Clean filenames recursively for ASCII-only computers. Run without arguments for drag and drop."
)]
struct Args {
/// Folder whose contents will be renamed in place (root itself stays unchanged).
folder: Option<PathBuf>,
/// Show proposed renames without changing anything.
#[arg(long, requires = "folder")]
dry_run: bool,
/// Pause between renames, in milliseconds (one worker only).
#[arg(long, default_value_t = 25, requires = "folder", value_parser = clap::value_parser!(u64).range(0..=1000))]
delay_ms: u64,
}
fn main() {
let args = Args::parse();
if let Some(folder) = args.folder {
let options = ascii_names::Options {
dry_run: args.dry_run,
delay: Duration::from_millis(args.delay_ms),
};
match ascii_names::clean(&folder, options, &AtomicBool::new(false), |_, message| {
println!("{message}")
}) {
Ok(summary) => {
println!("{summary}");
if summary.errors > 0 {
std::process::exit(1);
}
}
Err(error) => {
eprintln!("{}: {error}", folder.display());
std::process::exit(1);
}
}
} else {
#[cfg(feature = "desktop")]
if let Err(error) = ascii_names::gui::launch() {
eprintln!("Cannot open window: {error}");
std::process::exit(1);
}
#[cfg(not(feature = "desktop"))]
{
eprintln!("Supply a folder, or build with the default desktop feature.");
std::process::exit(2);
}
}
}

View File

@ -0,0 +1,249 @@
use ascii_names::{Options, ascii_name, clean};
use std::{
fs,
sync::atomic::AtomicBool,
time::{Duration, Instant},
};
fn options() -> Options {
Options {
delay: Duration::ZERO,
dry_run: false,
}
}
#[test]
fn accents_punctuation_unknowns_and_portable_names() {
for (input, expected) in [
("Été à Noël.mov", "Ete a Noel.mov"),
("Cafe\u{301}.txt", "Cafe.txt"),
(
"œuf Straße Łódź Æsir Øresund",
"oeuf Strasse Lodz AEsir Oresund",
),
("‘Hello’—world…", "'Hello'-world"),
("日本🎬.txt", "___.txt"),
("a\nb:<>\"\\|?*c", "a_b________c"),
("\u{301}", "_"),
("..", "_"),
("foo. ", "foo"),
("CON.txt", "_CON.txt"),
("LPT9", "_LPT9"),
("COM0", "COM0"),
("ordinary file-01.txt", "ordinary file-01.txt"),
] {
assert_eq!(ascii_name(input), expected, "{input:?}");
}
let name = ascii_name(&format!("{}.txt", "ffi".repeat(100)));
assert_eq!(name.len(), 220);
assert!(name.ends_with(".txt"));
assert!(name.is_ascii());
}
#[test]
fn nested_cleanup_preserves_all_contents_and_is_idempotent() {
let tmp = tempfile::tempdir().unwrap();
let root = tmp.path().join("Sélection");
fs::create_dir_all(root.join("Étage/été")).unwrap();
fs::write(root.join("Étage/été/vidéo.mov"), b"video bytes").unwrap();
fs::write(root.join("resume.txt"), b"original").unwrap();
fs::write(root.join("résumé.txt"), b"accented").unwrap();
fs::write(root.join("résume.txt"), b"another").unwrap();
let cancel = AtomicBool::new(false);
let summary = clean(&root, options(), &cancel, |_, _| {}).unwrap();
assert_eq!(summary.errors, 0);
assert_eq!(summary.renamed, 5);
assert_eq!(
fs::read(root.join("Etage/ete/video.mov")).unwrap(),
b"video bytes"
);
assert_eq!(fs::read(root.join("resume.txt")).unwrap(), b"original");
let mut contents = [
fs::read(root.join("resume_1.txt")).unwrap(),
fs::read(root.join("resume_2.txt")).unwrap(),
];
contents.sort();
assert_eq!(contents, [b"accented".to_vec(), b"another".to_vec()]);
assert_eq!(
clean(&root, options(), &cancel, |_, _| {}).unwrap().renamed,
0
);
}
#[test]
fn preview_reserves_targets_and_changes_nothing() {
let tmp = tempfile::tempdir().unwrap();
fs::write(tmp.path().join("é.txt"), "a").unwrap();
fs::write(tmp.path().join("è.txt"), "b").unwrap();
let mut logs = vec![];
let summary = clean(
tmp.path(),
Options {
dry_run: true,
..options()
},
&AtomicBool::new(false),
|_, msg| logs.push(msg),
)
.unwrap();
assert_eq!(summary.renamed, 2);
assert!(logs[0].ends_with("e.txt"));
assert!(logs[1].ends_with("e_1.txt"));
assert!(tmp.path().join("é.txt").exists());
assert!(tmp.path().join("è.txt").exists());
assert!(!tmp.path().join("e.txt").exists());
}
#[test]
fn directory_and_file_collisions_never_merge() {
let tmp = tempfile::tempdir().unwrap();
fs::create_dir(tmp.path().join("Ete")).unwrap();
fs::create_dir(tmp.path().join("Été")).unwrap();
fs::write(tmp.path().join("Ete/original"), "keep").unwrap();
fs::write(tmp.path().join("Été/new"), "new").unwrap();
fs::write(tmp.path().join("été"), "file").unwrap();
let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
assert_eq!(result.errors, 0);
assert_eq!(
fs::read_to_string(tmp.path().join("Ete/original")).unwrap(),
"keep"
);
assert!(tmp.path().join("Ete_1/new").is_file());
}
#[test]
fn cancellation_stops_between_renames_and_delay_is_applied() {
let tmp = tempfile::tempdir().unwrap();
fs::write(tmp.path().join("é"), "a").unwrap();
fs::write(tmp.path().join("à"), "b").unwrap();
let cancel = AtomicBool::new(false);
let start = Instant::now();
let result = clean(
tmp.path(),
Options {
delay: Duration::from_millis(30),
dry_run: false,
},
&cancel,
|_, _| cancel.store(true, std::sync::atomic::Ordering::Relaxed),
)
.unwrap();
assert!(result.cancelled);
assert_eq!(result.renamed, 1);
assert!(start.elapsed() >= Duration::from_millis(30));
assert!(
clean(tmp.path(), options(), &cancel, |_, _| {})
.unwrap()
.cancelled
);
}
#[test]
fn missing_root_and_file_root_are_errors() {
let tmp = tempfile::tempdir().unwrap();
let file = tmp.path().join("file");
let cancel = AtomicBool::new(false);
assert!(clean(&file, options(), &cancel, |_, _| {}).is_err());
fs::write(&file, "x").unwrap();
assert!(clean(&file, options(), &cancel, |_, _| {}).is_err());
}
#[cfg(unix)]
#[test]
fn links_are_not_followed_and_invalid_utf8_is_cleaned() {
use std::{
ffi::OsString,
os::unix::{ffi::OsStringExt, fs::symlink},
};
let tmp = tempfile::tempdir().unwrap();
let outside = tempfile::tempdir().unwrap();
fs::write(outside.path().join("é.txt"), "outside").unwrap();
symlink(outside.path(), tmp.path().join("lïnk")).unwrap();
symlink("missing", tmp.path().join("e.txt")).unwrap();
fs::write(tmp.path().join("é.txt"), "inside").unwrap();
fs::write(
tmp.path().join(OsString::from_vec(b"bad\xff.txt".to_vec())),
"bytes",
)
.unwrap();
let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
assert_eq!(result.skipped, 2);
assert_eq!(result.errors, 0);
assert!(outside.path().join("é.txt").exists());
assert_eq!(
fs::read_to_string(tmp.path().join("bad_.txt")).unwrap(),
"bytes"
);
assert_eq!(
fs::read_to_string(tmp.path().join("e_1.txt")).unwrap(),
"inside"
);
assert!(
clean(
&tmp.path().join("lïnk"),
options(),
&AtomicBool::new(false),
|_, _| {}
)
.is_err()
);
}
#[test]
fn cli_preview_and_apply() {
let tmp = tempfile::tempdir().unwrap();
fs::write(tmp.path().join("été.txt"), "content").unwrap();
let bin = env!("CARGO_BIN_EXE_ascii-names");
let output = std::process::Command::new(bin)
.arg(tmp.path())
.arg("--dry-run")
.output()
.unwrap();
assert!(output.status.success());
assert!(tmp.path().join("été.txt").exists());
assert!(
std::process::Command::new(bin)
.arg(tmp.path())
.args(["--delay-ms", "0"])
.output()
.unwrap()
.status
.success()
);
assert_eq!(
fs::read_to_string(tmp.path().join("ete.txt")).unwrap(),
"content"
);
assert!(
!std::process::Command::new(bin)
.arg(tmp.path().join("missing"))
.output()
.unwrap()
.status
.success()
);
}
#[test]
fn many_names_with_same_fallback_keep_every_file() {
let tmp = tempfile::tempdir().unwrap();
for (index, character) in (0x4e00..0x4e80).filter_map(char::from_u32).enumerate() {
fs::write(
tmp.path().join(format!("{character}.txt")),
index.to_string(),
)
.unwrap();
}
let summary = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
assert_eq!(summary.renamed, 128);
assert_eq!(summary.errors, 0);
let values: std::collections::HashSet<_> = fs::read_dir(tmp.path())
.unwrap()
.map(|entry| {
let path = entry.unwrap().path();
assert!(path.file_name().unwrap().to_str().unwrap().is_ascii());
fs::read_to_string(path).unwrap()
})
.collect();
assert_eq!(values.len(), 128);
}

72
docs/ascii-names.md Normal file
View File

@ -0,0 +1,72 @@
# ASCII names
A small Rust application for cleaning filenames before using a folder on an
ASCII-only computer. Run it on your modern computer while the USB drive is plugged in.
It changes names in place; file contents are never opened or rewritten.
```sh
cargo run --locked -p ascii-names
```
Drop a folder into the window (or use **Choose folder**). **Preview** lists proposed
changes without writing anything. **Clean names** processes all files and subfolders.
**Stop** stops between entries; completed renames remain in place. The window keeps
the latest 200 messages. Drop one folder at a time.
The selected folder itself keeps its name, so selecting a drive's mount point is
safe. To clean a folder's own name too, select its parent. Symlinks and special
files are skipped, including links to other folders. Hidden files are included.
Nested mounted directories are treated as ordinary directories.
## Naming rules
- Accented Latin letters lose their accents, including decomposed macOS accents:
`Été.mov` → `Ete.mov`. Ligatures and common letters such as `œ`, `ß`, `ø`, `ł`
become `oe`, `ss`, `o`, `l`.
- Common Unicode quotes and dashes become ASCII punctuation. Other characters
without a supported equivalent become `_`. This is not transliteration of
every writing system: `日本.txt` becomes `__.txt`.
- ASCII control characters and `<>:"/\|?*` become `_` for filesystem compatibility.
Trailing dots/spaces are removed; empty names become `_`. Windows reserved
names such as `CON.txt` gain an underscore prefix.
- Names longer than 220 ASCII bytes are shortened, preserving short extensions.
- Existing destinations are never overwritten or merged. Collisions receive
`_1`, `_2`, etc., before a file's extension: `résumé.txt` becomes `resume_1.txt`
when `resume.txt` already exists. Directories get the suffix at the end.
Directories are handled inside out. Filesystem work runs on one worker, with
25 ms between rename attempts (at most about 40 renames per second). There are
no parallel scans, content copies, or per-file flushes. Eject the USB drive
normally afterward so the operating system finishes any buffered writes.
Keep the selected tree idle while running. Names referenced by playlists,
shortcuts, documents or projects are not updated inside those files. Preview
first when these references matter. There is no automatic undo. Read/rename
errors are reported and processing continues where possible; rerun after resolving
the reported cause. A failed directory rename can leave already-cleaned children.
## Command line
The same binary supports a folder argument, useful for terminal drag and drop:
```sh
cargo run --locked -p ascii-names -- /path/to/folder --dry-run
cargo run --locked -p ascii-names -- /path/to/folder
cargo run --locked -p ascii-names -- /path/to/folder --delay-ms 100
```
`--delay-ms` accepts 0–1000; the default is 25. Preview does not sleep.
The CLI prints every change and a summary, and exits nonzero on errors. Preview
paths show the traversal's intermediate paths before ancestor folders are renamed;
preview is not a saved plan, and cleanup scans again.
Build a standalone desktop binary with `cargo build --locked --release -p ascii-names`.
For a smaller CLI-only build, add `--no-default-features`. No FFprobe or other
external command is required. The desktop uses the same egui dependencies as the
other Rust tools. Linux/macOS use an atomic no-replace rename and Windows uses
MoveFileExW without replacement. Filesystems that do not support safe no-replace
renames produce an error; the tool never falls back to an overwriting rename.
The crate is included in workspace tests, Clippy, Rustdoc and coverage. Regression
tests cover collisions, nested directories, previews, cancellation, pacing,
symlinks, invalid UTF-8 filenames on Unix, and content preservation.

View File

@ -56,3 +56,7 @@ The converter can run without desktop dependencies using
Its tests generate synthetic XLSX inputs and never require private source files
or network downloads. The existing workspace test, lint, Rustdoc and coverage
commands include both tools; reporter release packaging remains separate.
The [ASCII filename cleaner](ascii-names.md) is a separate Rust workspace member.
Run `cargo run --locked -p ascii-names` for its drag-and-drop window, or pass a
folder for CLI cleanup. It uses the same workspace checks and coverage gates.