clio

clio is a Rust library for parsing command-line file name arguments. It implements the standard Unix convention where a file name of ”-” means read from stdin or write to stdout as appropriate, giving CLI tools stream-friendly file handling with almost no extra code. Input and Output types can be constructed directly from process arguments and error cleanly if a file cannot be opened.

With the optional clap-parse feature it integrates with clap 3.2+ as value parsers and adds validation filters (path exists, is or is not a directory, and more). It also offers deferred-open path types to avoid leaving empty output files on early errors, and optional HTTP input/output where a URL triggers a GET or PUT.

What You Get

• Input and Output types that treat ”-” as stdin/stdout automatically
• Deferred InputPath/OutputPath types that validate before opening
• Optional clap 3.2+ integration with value parsers and path filters
• Path validation filters such as exists, is_dir, and is not a directory
• Optional HTTP input/output where a URL triggers a GET or PUT

Common Use Cases

• Writing Unix-style CLI tools that accept files or piped stdin/stdout
• Validating file-path arguments in clap with clear error messages
• Deferring file opening to avoid leaving empty output files on early errors
• Reading from or writing to a URL directly from a command-line tool

Under The Hood

Architecture - clio is organized around Input and Output stream types (src/input.rs, src/output.rs) that abstract over files, stdin/stdout, and optional HTTP streams, a ClioPath and path types (src/path.rs) for deferred opening and validation, a clap integration layer (src/clapers.rs) implementing ValueParserFactory, an error module, and an http submodule for URL-backed sources. It handles subtleties like seekability detection and up-front size discovery. Tech Stack - Pure Rust with optional feature-gated dependencies: clap for the clap-parse feature and ureq or curl for the http-ureq/http-curl HTTP backends, keeping the default build dependency-light. Code Quality - The repo carries inline unit tests in lib.rs and the clap integration module, runnable examples (a cat replacement), helper shell scripts, and a documented, MSRV-aware design, with the README candidly discussing tradeoffs versus alternatives like patharg and nameless. API Design - The public API is ergonomic: construct Input::new/Output::new from an OsStr argument, or wire the types directly into a clap derive struct with value_parser filters, so adding stdin/stdout support to a tool is often a one-line change.