#argv #args #stdin #stdout


Treat "-" (hyphen/dash) arguments as stdin/stdout

3 releases (breaking)

0.3.0 Apr 22, 2023
0.2.0 Apr 22, 2023
0.1.0 Apr 19, 2023

#602 in Filesystem

Download history 70/week @ 2023-08-06 74/week @ 2023-08-13 74/week @ 2023-08-20 74/week @ 2023-08-27 37/week @ 2023-09-03 70/week @ 2023-09-10 39/week @ 2023-09-17 25/week @ 2023-09-24 64/week @ 2023-10-01 31/week @ 2023-10-08 78/week @ 2023-10-15 90/week @ 2023-10-22 63/week @ 2023-10-29 96/week @ 2023-11-05 114/week @ 2023-11-12 113/week @ 2023-11-19

390 downloads per month
Used in 3 crates

MIT license

683 lines

Project Status: Active – The project has reached a stable, usable state and is being actively developed. CI Status codecov.io MIT License

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:


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:

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:

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:

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.


~29K SLoC