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> and From<String>, 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.

Installation

patharg requires version 1.65 of Rust or higher. To use the patharg library in your Cargo project, add the following to your Cargo.toml:

[dependencies]
patharg = "0.3.0"

patharg has an optional tokio feature for enabling async I/O support with tokio. To use this in your project, add the following instead:

[dependencies]
patharg = { version = "0.3.0", features = ["tokio"] }

patharg also has an optional serde feature for enabling serializing & deserializing InputArg & OutputArg values with serde. To use this in your project, add the following instead:

[dependencies]
patharg = { version = "0.3.0", features = ["serde"] }

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.