Module file_path 

File Path Value Object

This module provides a generic, type-safe file path value object for the adaptive pipeline system. It uses phantom types to enforce compile-time path category safety while providing shared validation and utility methods.

Overview

The file path value object provides:

• Type Safety: Compile-time enforcement of path categories
• Path Validation: Comprehensive validation of file paths
• Cross-Platform: Platform-independent path handling
• Zero-Cost Abstractions: Phantom types with no runtime overhead
• Extensibility: Easy addition of new path categories

Architecture

The file path follows Domain-Driven Design principles:

• Value Object: Immutable value object with equality semantics
• Type Safety: Phantom types prevent category mixing at compile time
• Rich Domain Model: Encapsulates path-related business logic
• Validation: Comprehensive validation of path formats and constraints

Key Features

Type-Safe Path Categories

• Input Paths: Paths for input files and directories
• Output Paths: Paths for output files and directories
• Temporary Paths: Paths for temporary files and directories
• Configuration Paths: Paths for configuration files
• Log Paths: Paths for log files and directories

Path Validation

• Format Validation: Validate path format and structure
• Security Validation: Prevent path traversal attacks
• Platform Validation: Ensure paths are valid on target platform
• Permission Validation: Check path permissions and accessibility

Cross-Platform Support

• Path Normalization: Normalize paths for different platforms
• Separator Handling: Handle different path separators
• Case Sensitivity: Handle case sensitivity differences
• Unicode Support: Full Unicode path support

Usage Examples

Basic Path Creation

Path Validation and Properties

Path Manipulation

Type Safety Demonstration

Path Conversion and Interoperability

Custom Path Categories

Path Categories

Built-in Categories

• InputPath: For input files and directories

  • Validation: Must be readable
  • Use case: Source files for processing

• OutputPath: For output files and directories

  • Validation: Parent directory must be writable
  • Use case: Destination files for processing results

• TempPath: For temporary files and directories

  • Validation: Must be in temporary directory
  • Use case: Intermediate processing files

• LogPath: For log files and directories

  • Validation: Must be writable, appropriate for logging
  • Use case: Application and processing logs

Custom Categories

Create custom path categories by implementing the PathCategory trait:

• Category Name: Unique identifier for the category
• Validation Logic: Custom validation rules
• Usage Constraints: Specific usage patterns and constraints

Validation Rules

General Validation

• Non-empty: Path cannot be empty
• Valid Characters: Must contain only valid path characters
• Length Limits: Must be within platform-specific length limits
• Format: Must follow platform-specific path format

Security Validation

• Path Traversal: Prevent “../” path traversal attacks
• Null Bytes: Prevent null byte injection
• Reserved Names: Avoid platform-specific reserved names
• Permissions: Validate appropriate permissions

Platform-Specific Validation

• Windows: Validate Windows path constraints
• Unix: Validate Unix/Linux path constraints
• macOS: Validate macOS-specific constraints
• Case Sensitivity: Handle case sensitivity differences

Error Handling

Path Errors

• Invalid Format: Path format is invalid
• Invalid Characters: Path contains invalid characters
• Too Long: Path exceeds maximum length
• Security Violation: Path violates security constraints

File System Errors

• Not Found: Path does not exist
• Permission Denied: Insufficient permissions
• IO Error: File system I/O error
• Invalid Path: Path is not valid on current platform

Performance Considerations

Memory Usage

• Efficient Storage: Compact path storage
• String Interning: Intern common path components
• Zero-Cost Abstractions: Phantom types have no runtime cost

Validation Performance

• Lazy Validation: Validate only when necessary
• Caching: Cache validation results
• Efficient Algorithms: Use efficient validation algorithms

Cross-Platform Compatibility

Path Separators

• Normalization: Normalize path separators
• Conversion: Convert between different separator styles
• Platform Detection: Detect current platform conventions

Character Encoding

• Unicode Support: Full Unicode path support
• Encoding Conversion: Handle different character encodings
• Normalization: Normalize Unicode characters

Integration

The file path value object integrates with:

• File System: Direct integration with file system operations
• Processing Pipeline: Type-safe path handling in pipeline stages
• Configuration: Path configuration and validation
• Logging: Path information in logs and error messages

Thread Safety

The file path value object is thread-safe:

• Immutable: Paths are immutable after creation
• Safe Sharing: Safe to share between threads
• Concurrent Access: Safe concurrent access to path data

Future Enhancements

Planned enhancements include:

• Path Templates: Template-based path generation
• Path Watching: File system watching integration
• Path Compression: Compressed path storage
• Advanced Validation: More sophisticated validation rules

Structs

AutoCleanupTempPath

RAII wrapper for temporary paths that auto-cleanup on drop

ConfigMarker

Marker type for configuration file paths

FilePath

Generic file path value object with type-safe path categories

InputMarker

Marker type for input file paths

LogMarker

Marker type for log file paths

OutputMarker

Marker type for output file paths

TempMarker

Marker type for temporary file paths

Traits

PathCategory

Path category trait for type-specific behavior

Type Aliases

ConfigPath

InputPath

Type aliases for common path types

LogPath

OutputPath

TempPath