PathBuf Macro

A macro for ergonomic and safe construction of file and directory paths in Rust, with context-aware resolution.

• Supports both string literals and formatted paths with arguments.
• Automatically determines whether to allow a path relative to the current working directory, the executable directory, or the user data directory.

See more macros: docs, repository.

Path Patterns

The path! macro provides an intuitive template engine to resolve system-standard cross-platform directories at runtime without adding heavy external dependencies.

Application Name Resolution

When appending a trailing dollar sign ($) to a token (e.g., $config$), the macro isolates data within an application-specific subdirectory.

• It checks for an ambient APP_NAME constant in the calling context.
• If APP_NAME is not found, it seamlessly falls back to the CARGO_PKG_NAME defined at compile time.

1. Executable & Environment Layouts

Dynamic layouts tied directly to the location of the running binary.

2. System & Configuration Layouts (Isolated Contexts)

These targets are used for internal configuration, cache, and application runtimes. They utilize hidden folders on Unix systems or specific system locations on Windows.

3. User Directories (Open Contexts)

Standard destination folders accessible directly by the user. When application routing is applied ($token$), directories are intentionally kept unhidden (without a leading dot) across all platforms for visibility.

Examples

use macron_path::path;
use std::path::PathBuf;

// The application name is automatically integrated via your crate's APP_NAME constant
pub const APP_NAME: &str = "ovsy";

fn main() {
    // =========================================================================
    // 1. STATIC PATHS & TOKENS (Zero-Allocation for basic prefixes)
    // =========================================================================

    // Quick access to the current user's home directory
    let home_dir = path!("~");
    
    // Executable-relative path layout (ideal for self-contained deployments)
    let config_file = path!("$/config.toml");
    let asset_pack  = path!("$/assets/textures/skybox.png");


    // =========================================================================
    // 2. SYSTEM LAYOUTS & APPLICATION ISOLATION
    // =========================================================================
    // Prefix anchor ($) resolves to the global system directory.
    // Suffix anchor ($) isolates the path inside an app-specific subdirectory.

    // Global config directory:
    // Linux:   ~/.config/rules.ev
    // Windows: %APPDATA%\rules.ev
    let global_config = path!("$config/rules.ev");

    // Isolated app config directory (via trailing '$'):
    // Linux:   ~/.config/ovsy/rules.ev
    // Windows: %APPDATA%\ovsy\config\rules.ev
    let app_config = path!("$config$/rules.ev");
    
    // Isolated application cache
    // Linux:   ~/.cache/ovsy/storage.idx
    let cache_index = path!("$cache$/storage.idx");


    // =========================================================================
    // 3. USER-SPACE DIRECTORIES (Standard OS folders)
    // =========================================================================
    
    // User Documents directory with subfolders
    let export_dir = path!("$documents$/exports/report_2026.pdf");
    
    // Standard User Downloads folder
    let incoming   = path!("$downloads$/incoming/");


    // =========================================================================
    // 4. INLINED FORMATTING (Drop-in replacement for std::format!)
    // =========================================================================
    let log_file = "auth_service";
    let shard_id = 42;

    // Compiles using standard macro syntax, but returns a ready PathBuf
    let session_log = path!("$cache$/logs/{log_file}_shard_{shard_id}.log");
    let dynamic_img = path!("$pictures$/vacation/photo_{}.jpg", shard_id);


    // =========================================================================
    // 5. RUNTIME & DYNAMIC VARIABLES (String, &str, and PathBuf support)
    // =========================================================================
    
    // Passing a dynamic runtime String directly
    let runtime_string = String::from("$temp$/session.lock");
    let active_lock    = path!(runtime_string);

    // Safely forwarding an existing PathBuf containing internal tokens
    let raw_path    = PathBuf::from("$share$/production.db");
    let database_p  = path!(raw_path.to_string_lossy());
}

License & Feedback

This library is distributed under the MIT license.

You can contact me via GitHub or send a message to my E-Mail. This library is actively evolving, and your suggestions and feedback are always welcome!