fren-core

The core renaming engine behind the fren suite. This library provides a robust, safe, and powerful DSL for batch file renaming, suitable for use in CLI tools, GUI applications, or web backends.

📋 Changelog - See what's new in each version

Features

• Async-First Design: All operations are asynchronous and non-blocking, perfect for GUI applications and modern async Rust
• Recursive File Finding: Support for recursive directory searches with ** glob patterns, preserving full directory structure
• Sequential Pattern Parsing: Supports a wide range of tokens (%N, %E, %C, etc.) and modifiers (%L, %U, %R, %X)
• Order-Aware Processing: Modifiers apply to accumulated results, making patterns like %N%L.%E work correctly
• Path Preservation: When processing recursively found files, full paths are preserved - files stay in their original directories
• Safety First: Built-in detection for empty filenames, OS-aware validation, and permission checks
• Context Awareness: Access to file metadata (modification dates) and parent directory information
• Undo Facility: History tracking logic to safely reverse rename operations
• Comprehensive Validation: OS-specific filename validation, permission checks, and circular rename detection

Pattern Processing

Patterns are processed in two phases:

1. Placeholder Expansion: Tokens like %N, %E, %C are replaced with their values
2. Modifier Application: Modifiers like %L, %U, %R are applied left-to-right to the accumulated result

When a modifier is encountered, it operates on everything accumulated so far in the result string. This means:

• %L%N.%E and %N%L.%E both work (modifier before or after placeholder)
• Order matters: %U%N%L.%E will uppercase then lowercase the name
• See the main README.md for detailed examples

Installation

Add this to your Cargo.toml:

[dependencies]
fren-core = "0.2.1"
tokio = { version = "1", features = ["fs", "io-util", "macros", "rt-multi-thread"] }
futures = "0.3"

Note: fren-core requires a tokio runtime. Make sure your application uses #[tokio::main] or provides a tokio runtime.

Usage Example

use fren_core::RenamingEngine;
use fren_core::find_matching_files_recursive;
use std::path::PathBuf;

#[tokio::main]
async fn main() {
    let engine = RenamingEngine;
    
    // Find files recursively
    let files = find_matching_files_recursive("**/*.jpg", true)
        .await
        .unwrap();

    // Generate a preview plan (async)
    let preview = engine.generate_preview(&files, "%L%N_v2.%E")
        .await
        .unwrap();

    for rename in preview.renames {
        // old_path and new_path contain full paths, preserving directory structure
        println!("{} -> {}", rename.old_path.display(), rename.new_path.display());
        // new_name contains just the filename
        println!("  New filename: {}", rename.new_name);
    }
    
    // Validate renames (async)
    let validation = engine.validate(&preview.renames, false).await.unwrap();
    if !validation.issues.is_empty() {
        for issue in validation.issues {
            eprintln!("Validation issue: {:?}", issue);
        }
    }
}

Path Handling

When generate_preview processes files (including recursively found files), it preserves the full directory structure:

• old_path: Full original file path (e.g., /path/to/docs/document.pdf)
• new_path: Full new file path in the same directory (e.g., /path/to/docs/document_v2.pdf)
• new_name: Just the filename portion (e.g., document_v2.pdf)

Files found recursively maintain their directory structure - a file in subdir/nested/file.txt will be renamed to subdir/nested/<new_name>, not moved to the root directory.

Async API

All operations in fren-core are asynchronous. You'll need a Tokio runtime to use the library:

• Use #[tokio::main] for standalone applications
• Use tokio::spawn or tokio::task::spawn_blocking in existing async contexts
• All file system operations are non-blocking and suitable for GUI event loops

License

This project is licensed under the MIT License.