Expand description
Treat “-” (hyphen/dash) arguments as stdin/stdout
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
.
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.
Enums
- An input path that can refer to either standard input or a file system path
- An output path that can refer to either standard output or a file system path
Type Definitions
- AsyncInputArgReader
tokio
The type of the asynchronous readers returned byInputArg::async_open()
. - AsyncLines
tokio
The type of the streams returned byInputArg::async_lines()
. - AsyncOutputArgWriter
tokio
The type of the asynchronous writers returned byOutputArg::async_create()
. - The type of the readers returned by
InputArg::open()
. - The type of the iterators returned by
InputArg::lines()
. - The type of the writers returned by
OutputArg::create()
.