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.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:
toml
[dependencies]
patharg = "0.2.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:
toml
[dependencies]
patharg = { version = "0.2.0", features = ["tokio"] }
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.