app_path/app_path/
mod.rs

1//! AppPath implementation split into logical modules for better maintainability.
2
3use std::path::PathBuf;
4
5/// Creates paths relative to the executable location for portable applications.
6///
7/// **AppPath** enables building truly portable applications where configuration, data,
8/// and executable stay together as a deployable unit. Perfect for USB drives, network
9/// shares, or any directory without installation.
10///
11/// ## Key Features
12///
13/// - **Portable**: Relative paths resolve to executable directory
14/// - **System integration**: Absolute paths work as-is  
15/// - **Zero-cost**: Implements `Deref<Target=Path>` and all path traits
16/// - **Thread-safe**: Static caching with proper synchronization
17/// - **Memory efficient**: Only stores the final resolved path
18///
19/// ## API Overview
20///
21/// ### Constructors
22///
23/// - [`Self::new()`] - **Application base directory**: Returns the directory containing the executable
24/// - [`Self::with()`] - **Primary API**: Create paths relative to application base directory
25/// - [`Self::try_new()`] - **Libraries**: Fallible version for getting application base directory
26/// - [`Self::try_with()`] - **Libraries**: Fallible version for creating relative paths
27/// - [`Self::with_override()`] - **Deployment**: Environment-configurable paths
28/// - [`Self::try_with_override()`] - **Deployment (Fallible)**: Fallible environment-configurable paths
29/// - [`Self::with_override_fn()`] - **Advanced**: Function-based override logic
30/// - [`Self::try_with_override_fn()`] - **Advanced (Fallible)**: Fallible function-based override logic
31///
32/// ### Directory Creation
33///
34/// - [`Self::create_parents()`] - **Files**: Creates parent directories for files
35/// - [`Self::create_dir()`] - **Directories**: Creates directories (and parents)
36///
37/// ### Path Operations & Traits
38///
39/// - **All `Path` methods**: Available directly via `Deref<Target=Path>` (e.g., `exists()`, `is_file()`, `file_name()`, `extension()`)
40/// - [`Self::into_path_buf()`] - **Conversion**: Extract owned `PathBuf` from wrapper
41/// - [`Self::into_inner()`] - **Conversion**: Alias for `into_path_buf()` following Rust patterns
42/// - [`Self::to_bytes()`] - **Ecosystem**: Raw bytes for specialized libraries
43/// - [`Self::into_bytes()`] - **Ecosystem**: Owned bytes for specialized libraries
44///
45/// # Panics
46///
47/// Constructor methods panic if the executable location cannot be determined (an
48/// extremely rare condition). After the first successful call, these methods
49/// never panic because the result is cached.
50///
51/// # Examples
52///
53/// ```rust
54/// use app_path::AppPath;
55///
56/// // Get the executable directory itself
57/// let exe_dir = AppPath::new();
58/// let exe_dir = AppPath::default(); // Same thing
59///
60/// // Create paths relative to executable
61/// let config = AppPath::with("config.toml");
62/// let data = AppPath::with("data/users.db");
63///
64/// // Chainable with join (since AppPath implements all Path methods)
65/// let log_file = AppPath::new().join("logs").join("app.log");
66/// let nested = AppPath::with("data").join("cache").join("temp.txt");
67///
68/// // Works like standard paths - all Path methods available
69/// if config.exists() {
70///     let content = std::fs::read_to_string(&config); // &config works directly
71/// }
72/// data.create_parents(); // Creates data/ directory for the file
73///
74/// // Mixed portable and system paths
75/// let portable = AppPath::with("app.conf");           // → exe_dir/app.conf
76/// let system = AppPath::with("/var/log/app.log");     // → /var/log/app.log
77///
78/// // Override for deployment flexibility
79/// let config = AppPath::with_override(
80///     "config.toml",
81///     std::env::var("CONFIG_PATH").ok()
82/// );
83/// ```
84#[derive(Clone, Debug)]
85pub struct AppPath {
86    full_path: PathBuf,
87}
88
89mod constructors;
90mod directory;
91mod path_ops;
92mod traits;
app_path/app_path/mod.rs

app_path/app_path/
mod.rs
