GitHub | crates.io | Documentation | Issues | Changelog

Most CLI commands that take file paths as arguments follow the convention of treating a path of - (a single hyphen/dash) as referring to either standard input or standard output (depending on whether the path is read from or written to). The patharg crate lets your programs follow this convention too: it provides InputArg and OutputArg types that wrap command-line arguments, with methods for reading from/writing to either the given path or — if the argument is just a hyphen — the appropriate standard stream.

InputArg and OutputArg implement From<OsString>, From<String>, and FromStr, so you can use them seamlessly with your favorite Rust source of command-line arguments, be it clap, lexopt, plain old std::env::args/std::env::args_os, or whatever else is out there. The source repository contains examples of two of these:

• examples/flipcase.rs and examples/tokio-flipcase.rs show how to use this crate with clap.
• examples/revchars.rs and examples/tokio-revchars.rs show how to use this crate with lexopt.

Comparison with clio

The only other library I am aware of that provides similar functionality to patharg is clio. Compared to clio, patharg aims to be a much simpler, smaller library that doesn't try to be too clever. Major differences between the libraries include:

• When a clio path instance is created, clio will either (depending on the type used) open the path immediately — which can lead to empty files being needlessly left behind if an output file is constructed during argument processing but an error occurs before the file is actually used — or else check that the path can be opened — which is vulnerable to TOCTTOU bugs. patharg does no such thing.

• clio supports reading from & writing to HTTP(S) URLs and has special treatment for FIFOs. patharg sees no need for such excesses.

• patharg has a feature for allowing async I/O with tokio. clio does not.

• patharg has optional support for serde. clio does not.