Struct InputPathHandler 

pub struct InputPathHandler {
    pub paths: Vec<PathBuf>,
    pub recursive: bool,
    pub file_extensions: Vec<String>,
    pub no_extract: bool,
}

Universal input path processing structure for CLI commands.

InputPathHandler provides a unified interface for processing file and directory inputs across different SubX CLI commands. It supports multiple input sources, recursive directory scanning, and file extension filtering.

This handler is used by commands like match, convert, sync, and detect-encoding to provide consistent -i parameter functionality and directory processing behavior.

Features

• Multiple Input Sources: Supports multiple files and directories via -i parameter
• Recursive Processing: Optional recursive directory scanning with --recursive flag
• File Filtering: Filter files by extension for command-specific processing
• Path Validation: Validates all input paths exist before processing
• Cross-Platform: Handles both absolute and relative paths correctly
• Archive Extraction: Transparently extracts .zip (and .rar when built with the archive-rar feature) archives passed directly as inputs into a temporary directory and processes the extracted files as if they had been supplied directly. Archives discovered during recursive directory traversal are NOT extracted. The behaviour can be disabled per command via --no-extract (see with_no_extract), in which case archive files are treated as regular files and filtered by the command’s extension list.

Return Value

collect_files returns a CollectedFiles handle that dereferences to &[PathBuf]. When archive extraction is performed, CollectedFiles owns the underlying tempfile::TempDir handles; the extracted directories are removed automatically (RAII) when the CollectedFiles value is dropped. Callers must therefore keep the CollectedFiles value alive for as long as the extracted file paths are in use. CollectedFiles also exposes archive_origin so callers can map an extracted file back to the original archive that produced it.

Examples

Basic Usage

use subx_cli::cli::InputPathHandler;
use std::path::PathBuf;


// Create handler from multiple paths
let paths = vec![file1, file2];
let handler = InputPathHandler::from_args(&paths, false)?
    .with_extensions(&["srt", "ass"]);

// Collect all matching files
let files = handler.collect_files()?;
assert_eq!(files.len(), 2);

Directory Processing

use subx_cli::cli::InputPathHandler;
use std::path::PathBuf;


// Flat directory scanning (non-recursive)
let handler_flat = InputPathHandler::from_args(&[test_dir.to_path_buf()], false)?
    .with_extensions(&["srt"]);
let files_flat = handler_flat.collect_files()?;
assert_eq!(files_flat.len(), 1); // Only finds file1

// Recursive directory scanning
let handler_recursive = InputPathHandler::from_args(&[test_dir.to_path_buf()], true)?
    .with_extensions(&["srt"]);
let files_recursive = handler_recursive.collect_files()?;
assert_eq!(files_recursive.len(), 2); // Finds both file1 and file2

Command Integration

use subx_cli::cli::{InputPathHandler, MatchArgs};

// Example of how commands use InputPathHandler
let handler = args.get_input_handler()?;
let files = handler.collect_files()?;
// Process files...

Fields

paths: Vec<PathBuf>

List of input paths (files and directories) to process

recursive: bool

Whether to recursively scan subdirectories

file_extensions: Vec<String>

File extension filters (lowercase, without dot)

no_extract: bool

Whether to skip archive extraction for archive file inputs

Implementations

impl InputPathHandler

pub fn merge_paths_from_multiple_sources( optional_paths: &[Option<PathBuf>], multiple_paths: &[PathBuf], string_paths: &[String], ) -> Result<Vec<PathBuf>, SubXError>

Merge paths from multiple sources to create a unified path list

This method provides a unified interface for CLI commands to merge different types of path parameters into a single PathBuf vector.

Arguments

• optional_paths - Optional path list (e.g., path, input, video, subtitle, etc.)
• multiple_paths - Multiple path list (e.g., input_paths)
• string_paths - String format path list (e.g., file_paths)

Returns

Returns the merged PathBuf vector, or an error if all inputs are empty

Examples

use subx_cli::cli::InputPathHandler;
use std::path::PathBuf;

// Merge paths from different sources
let optional = vec![Some(PathBuf::from("single.srt"))];
let multiple = vec![PathBuf::from("dir1"), PathBuf::from("dir2")];
let strings = vec!["file1.srt".to_string(), "file2.ass".to_string()];

let merged = InputPathHandler::merge_paths_from_multiple_sources(
    &optional,
    &multiple,
    &strings
)?;

// merged now contains all paths
assert_eq!(merged.len(), 5);

pub fn from_args( input_args: &[PathBuf], recursive: bool, ) -> Result<Self, SubXError>

Create InputPathHandler from command line arguments

pub fn with_extensions(self, extensions: &[&str]) -> Self

Set supported file extensions (without dot)

pub fn with_no_extract(self, no_extract: bool) -> Self

Set whether to skip archive extraction.

When true, archive files (.zip, .rar) are treated as regular files and subject to the normal extension filter instead of being extracted.

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

Validate that all paths exist

pub fn get_directories(&self) -> Vec<PathBuf>

Get all specified directory paths

This method returns all specified directory paths for commands that need to process directories one by one. If the specified path contains files, it will return the directory containing that file.

Returns

Deduplicated list of directory paths

Examples

use subx_cli::cli::InputPathHandler;
use std::path::PathBuf;


let paths = vec![file1.clone(), test_dir.to_path_buf()];
let handler = InputPathHandler::from_args(&paths, false)?;
let directories = handler.get_directories();

// Should contain test_dir (after deduplication)
assert_eq!(directories.len(), 1);
assert_eq!(directories[0], test_dir);

pub fn collect_files(&self) -> Result<CollectedFiles, SubXError>

Expand files and directories, collecting all files that match the filter conditions.

When archive extraction is enabled (the default), directly-specified archive files (.zip, .rar) are transparently extracted to temporary directories and their contents are included in the result instead of the archive path itself. Archives found during directory traversal are not extracted.

Trait Implementations

impl Clone for InputPathHandler

fn clone(&self) -> InputPathHandler

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for InputPathHandler

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

Formats the value using the given formatter.