Crate fren_date 

fren - file renamer that understands dates.

Library crate. The CLI binary lives in fren-cli and is a thin consumer of this library.

Quick example

use fren_date::{slugify_camel_iso_with_year, SlugOpts};
use slug_preserve::CaseMode;

let legacy_python = SlugOpts {
    separator: '_',
    case: CaseMode::Capitalize,
    split_camel: true,
};
let out = slugify_camel_iso_with_year("Hello World 2024-01-15.txt", &legacy_python, 2024);
assert!(out.starts_with("Hello"));

Library discipline

This crate must obey:

• No panic! on user input - return Err(FrenError::*)
• No println!/eprintln! - output flows through trait objects
• No global state - all configuration via opts structs

Structs

DetectedDate

A date span detected inside a filename. byte_span is recorded so a future caller can locate the date and move it within the name.

ExecutionReport

Summary of an executed batch.

JsonlLogSink

JSONL log sink that appends to a file in ${XDG_STATE_HOME:-~/.local/state}/fren/log/.

MergeMove

Outcome of a single file move during a merge.

MergeReport

Report from merge_directories.

NullLogSink

No-op sink for tests / --no-log.

NullProgressSink

No-op ProgressSink. Used by execute and execute_with_log.

PlanOpts

Options for planning a rename batch.

RenameOpts

Top-level options for fren::rename (the high-level convenience entry).

RenamePlan

A single planned rename operation. Produced by the planner; consumed by the executor in bottom-up order.

SlugOpts

Options controlling how a string is slugified.

Enums

CaseMode

How to handle character case in the slugified output.

ConflictPolicy

Conflict resolution policy when a rename target already exists or two plans target the same path.

DateKind

What kind of date was detected inside a filename.

FrenError

Top-level error for the fren library.

ItemKind

What kind of filesystem item a plan refers to.

LogRecord

One record in the JSONL stream.

Traits

LogSink

Trait for sinks that record rename events. The default implementation is JsonlLogSink; tests can use NullLogSink.

ProgressSink

Callback invoked after each successful rename during execution.

Functions

execute

Apply a sorted plan vector with no transaction logging.

execute_with_log

Apply a sorted plan vector, recording every rename to log_sink.

execute_with_progress

Apply a sorted plan vector, recording to log_sink and calling progress after each successful rename.

merge_directories

Merge sources into target. Files already in target get a _Copy{N} suffix appended to their stem. Directories are created as needed. .DS_Store and similar metadata files are skipped.

plan

Build a RenamePlan vector for the given roots.

plan_with_year

Variant exposing the “current year” for deterministic testing.

rename

High-level entry point: plan + (optionally) execute a rename batch.

slugify_camel_iso

Slugify a string with CamelCase splitting, ISO date detection, and the user’s chosen output separator/case.

slugify_camel_iso_with_year

Variant exposing the “current year” so tests can pin time.

slugify_str

Slugify a single string with the given options.

sort_bottom_up

Sort a plan vector in-place: deepest first; at equal depth, files before directories.

unique_file_name

Find a unique file name by appending _Copy, _Copy1, _Copy2, … to the stem until the path no longer exists.