3 releases (breaking)
0.3.0 | Apr 22, 2023 |
---|---|
0.2.0 | Apr 22, 2023 |
0.1.0 | Apr 19, 2023 |
#602 in Filesystem
390 downloads per month
Used in 3 crates
55KB
683 lines
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
andexamples/tokio-flipcase.rs
show how to use this crate withclap
.examples/revchars.rs
andexamples/tokio-revchars.rs
show how to use this crate withlexopt
.
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 withtokio
.clio
does not. -
patharg
has optional support forserde
.clio
does not.
Dependencies
~0–1.6MB
~29K SLoC