Struct FilePath 

pub struct FilePath<T> { /* private fields */ }

Generic file path value object with type-safe path categories

Purpose

Type-safe file path that provides:

• Compile-time path category enforcement (Input vs Output vs Temp)
• Shared validation and utility methods
• Zero-cost abstractions with phantom types
• Extensible design for new path categories

Generic Benefits

• Type Safety: Cannot mix input and output paths at compile time
• Code Reuse: Shared implementation for all path types
• Extensibility: Easy to add new path categories
• Zero Cost: Phantom types have no runtime overhead

Use Cases

• Pipeline input/output path specification
• Temporary file management
• Configuration file paths
• Log file paths

Cross-Language Mapping

• Rust: FilePath<T> with marker types

Examples

• Go: Separate types with shared interface
• JSON: String representation with type hints
• SQLite: TEXT column with category metadata

Implementations

impl<T: PathCategory> FilePath<T>

pub fn new<P: AsRef<Path>>(path: P) -> Result<Self, PipelineError>

Creates a new file path with category-specific validation

Purpose

Creates a type-safe file path with compile-time category enforcement. Uses phantom types to prevent mixing different path categories at compile time. # Why Type-safe paths provide:

• Compile-time prevention of input/output path mixing
• Category-specific validation rules
• Zero-cost abstractions with phantom types
• Clear API contracts for path requirements

Arguments

• path - Path to validate (can be &str, String, Path, PathBuf)

Returns

• Ok(FilePath<T>) - Validated path with category type
• Err(PipelineError::InvalidConfiguration) - Validation failed

Errors

Returns PipelineError::InvalidConfiguration when:

• Path is empty
• Path contains null bytes
• Path exceeds 4096 characters
• Category-specific validation fails

Examples

pub fn parse(path: &str) -> Result<Self, PipelineError>

Creates a file path from a string

pub fn as_path(&self) -> &Path

Gets the underlying path

pub fn to_path_buf(&self) -> PathBuf

Gets the path as a PathBuf

pub fn to_string_lossy(&self) -> String

Gets the path as a string

pub fn file_name(&self) -> Option<&str>

Gets the file name component

pub fn file_stem(&self) -> Option<&str>

Gets the file stem (name without extension)

pub fn extension(&self) -> Option<&str>

Gets the file extension

pub fn parent(&self) -> Option<FilePath<T>>

Gets the parent directory

pub fn exists(&self) -> bool

Checks if the path exists

pub fn is_file(&self) -> bool

Checks if the path is a file

pub fn is_dir(&self) -> bool

Checks if the path is a directory

pub fn category(&self) -> &'static str

Gets the path category name

pub fn into_category<U: PathCategory>( self, ) -> Result<FilePath<U>, PipelineError>

Converts to a different path category (type conversion)

Purpose

Safely converts a path from one category to another with validation. Useful when a path needs to be used in a different context.

Why

Category conversion enables:

• Reusing paths across different contexts
• Type-safe path transformations
• Validation of new category requirements
• Flexible path handling

Type Parameters

• U - Target path category (must implement PathCategory)

Returns

• Ok(FilePath<U>) - Converted path with new category
• Err(PipelineError) - Target category validation failed

Errors

Returns PipelineError if the path doesn’t meet the target category’s validation requirements.

Examples

pub fn with_extension(&self, extension: &str) -> FilePath<T>

Creates a path with a different extension

pub fn join<P: AsRef<Path>>(&self, path: P) -> FilePath<T>

Joins with another path component

pub fn validate(&self) -> Result<(), PipelineError>

Validates the file path with category-specific rules

impl FilePath<InputMarker>

Specialized constructors for different path types

pub fn existing<P: AsRef<Path>>(path: P) -> Result<Self, PipelineError>

Creates an input path that must exist

pub fn with_required_extension<P: AsRef<Path>>( path: P, ext: &str, ) -> Result<Self, PipelineError>

Creates an input path with required extension

impl FilePath<OutputMarker>

pub fn with_parent_creation<P: AsRef<Path>>( path: P, ) -> Result<Self, PipelineError>

Creates an output path, ensuring parent directory exists

pub fn create_backup(&self) -> Result<OutputPath, PipelineError>

Creates a backup of an existing output path

impl FilePath<TempMarker>

pub fn unique(prefix: &str, extension: &str) -> Result<Self, PipelineError>

Creates a temporary path with unique name

pub fn auto_cleanup( prefix: &str, extension: &str, ) -> Result<AutoCleanupTempPath, PipelineError>

Creates a temporary path that will be automatically cleaned up

Trait Implementations

impl<T> AsRef<Path> for FilePath<T>

fn as_ref(&self) -> &Path

Converts this type into a shared reference of the (usually inferred) input type.

impl<T: Clone> Clone for FilePath<T>

fn clone(&self) -> FilePath<T>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T: Debug> Debug for FilePath<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de, T> Deserialize<'de> for FilePath<T>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<T> Display for FilePath<T>

where T: PathCategory,

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T> From<FilePath<T>> for PathBuf

fn from(file_path: FilePath<T>) -> Self

Converts to this type from the input type.

impl<T: Hash> Hash for FilePath<T>

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<T: PartialEq> PartialEq for FilePath<T>

fn eq(&self, other: &FilePath<T>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<T> Serialize for FilePath<T>

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<T: Eq> Eq for FilePath<T>

impl<T> StructuralPartialEq for FilePath<T>