Crate patharg

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>, From<String>, and FromStr, 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:

• flipcase and tokio-flipcase show how to use this crate with clap.

• revchars and tokio-revchars show how to use this crate with lexopt.

Features

The patharg crate has the following optional features. None of them are enabled by default.

• serde — Enables serialization & deserialization of InputArg and OutputArg values with serde

• tokio — Enables using InputArg and OutputArg values for asynchronous I/O with tokio

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.

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 Aliases

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