Crate patharg

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 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.

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.

Enums

• InputArg
  An input path that can refer to either standard input or a file system path
• OutputArg
  An output path that can refer to either standard output or a file system path

Type Definitions

• AsyncInputArgReadertokio
  The type of the asynchronous readers returned by InputArg::async_open().
• AsyncLinestokio
  The type of the streams returned by InputArg::async_lines().
• AsyncOutputArgWritertokio
  The type of the asynchronous writers returned by OutputArg::async_create().
• InputArgReader
  The type of the readers returned by InputArg::open().
• Lines
  The type of the iterators returned by InputArg::lines().
• OutputArgWriter
  The type of the writers returned by OutputArg::create().