clap-stdin is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing `file_or_stdin_optional_arg` `file_or_stdin_positional_arg` `file_or_stdin_twice` `file_or_stdout_optional_arg` `file_or_stdout_positional_arg` `is_stdin` `maybe_stdin_optional_arg` `maybe_stdin_positional_arg` `maybe_stdin_twice` executables

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install clap-stdin

It will make file_or_stdin_optional_arg file_or_stdin_positional_arg file_or_stdin_twice file_or_stdout_optional_arg file_or_stdout_positional_arg is_stdin maybe_stdin_optional_arg maybe_stdin_positional_arg maybe_stdin_twice commands available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall clap-stdin uninstalls.

Adding `clap_stdin` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add clap-stdin

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

clap-stdin = "0.8.1"

The clap_stdin library will be automatically available globally. Read the clap_stdin library documentation.

Back to the crate overview.

Readme

clap-stdin

This library offers two wrapper types for clap Args that help for cases where values may be passed in via stdin. When an Arg value is to be read from stdin, the user will pass the commonly used stdin alias: -

MaybeStdin: Used when a value can be passed in via args OR stdin
FileOrStdin: Used when a value can be read in from a file OR stdin
FileOrStdout: Used to proxy as a writer for either a file OR stdout

`MaybeStdin`

Example usage with clap's derive feature for a positional argument:

use clap::Parser;

use clap_stdin::MaybeStdin;

#[derive(Debug, Parser)]
struct Args {
    value: MaybeStdin<String>,
}

let args = Args::parse();
println!("value={}", args.value);

Calling this CLI:

# using stdin for positional arg value
$ echo "testing" | cargo run -- -
value=testing

Compatible Types

MaybeStdin can wrap any type that matches the trait bounds for Arg: FromStr and Clone

use std::path::PathBuf;
use clap::Parser;
use clap_stdin::MaybeStdin;

#[derive(Debug, Parser)]
struct Args {
    path: MaybeStdin<PathBuf>,
}

$ pwd | ./example -

`FileOrStdin`

Example usage with clap's derive feature for a positional argument:

use clap::Parser;

use clap_stdin::FileOrStdin;

#[derive(Debug, Parser)]
struct Args {
    input: FileOrStdin,
}

# fn main() -> anyhow::Result<()> {
let args = Args::parse();
println!("input={}", args.input.contents()?);
# Ok(())
# }

Calling this CLI:

# using stdin for positional arg value
$ echo "testing" | cargo run -- -
input=testing

# using filename for positional arg value
$ echo "testing" > input.txt
$ cargo run -- input.txt
input=testing

Compatible Types

FileOrStdin can wrap any type that matches the trait bounds for Arg: FromStr and Clone

use clap::Parser;
use clap_stdin::FileOrStdin;

#[derive(Debug, Parser)]
struct Args {
    path: FileOrStdin<u32>,
}

# Value from stdin
$ wc ~/myfile.txt -l | ./example -

# Value from file
$ cat myfile.txt
42
$ .example myfile.txt

`FileOrStdout`

Example usage with clap's derive feature for a positional argument:

use std::io::Write;
use clap::Parser;
use clap_stdin::FileOrStdout;

#[derive(Debug, Parser)]
struct Args {
    output: FileOrStdout,
}

# fn main() -> anyhow::Result<()> {
let args = Args::parse();
let mut writer = args.output.into_writer()?;
writeln!(&mut writer, "testing");
# Ok(())
# }

Calling this CLI:

# using stdout for positional arg value
$ cargo run -- -
testing

# using filename for positional arg value
$ cargo run -- output.txt
$ cat output.txt
testing

Reading from Stdin without special characters

When using MaybeStdin or FileOrStdin, you can allow your users to omit the "-" character to read from stdin by providing a default_value to clap.

NOTE: This only works with positional args, since clap requires optional args (E.g. using #[arg(long, short)]) to have a value to parse.

use clap::Parser;

use clap_stdin::FileOrStdin;

#[derive(Debug, Parser)]
struct Args {
    #[arg(default_value = "-")]
    input: FileOrStdin,
}

# fn main() -> anyhow::Result<()> {
let args = Args::parse();
println!("input={}", args.input.contents()?);
# Ok(())
# }

Calling this CLI:

# using stdin for positional arg value
$ echo "testing" | cargo run
input=testing

# using filename for positional arg value
$ echo "testing" > input.txt
$ cargo run -- input.txt
input=testing

Async Support

FileOrStdin and FileOrStdout can also be used with tokio::io::AsyncRead and tokio::io::AsyncWrite respectively, using the tokio feature. See FileOrStdin::contents_async, FileOrStdin::into_async_reader, and FileOrStdout::into_async_writer for examples.

Using `MaybeStdin` or `FileOrStdin` multiple times

Both MaybeStdin and FileOrStdin will check at runtime if stdin is being read from multiple times. You can use this as a feature if you have mutually exclusive args that should both be able to read from stdin, but know that the user will receive an error if 2+ MaybeStdin args receive the "-" value.

For example, this compiles:

use clap_stdin::{FileOrStdin, MaybeStdin};

#[derive(Debug, clap::Parser)]
struct Args {
    first: FileOrStdin,
    second: MaybeStdin<u32>,
}

and it will work fine if the stdin alias - is only passed for one of the arguments:

$ echo "2" | ./example FIRST -

But if stdin is attempted to be used for both arguments, there will be no value for the second arg

$ echo "2" | ./example - -
error: invalid value '-' for '<SECOND>': stdin argument used more than once

License

clap-stdin is both MIT and Apache License, Version 2.0 licensed, as found in the LICENSE-MIT and LICENSE-APACHE files.

Installing file_or_stdin_optional_arg file_or_stdin_positional_arg file_or_stdin_twice file_or_stdout_optional_arg file_or_stdout_positional_arg is_stdin maybe_stdin_optional_arg maybe_stdin_positional_arg maybe_stdin_twice executables

Adding clap_stdin library as a dependency

Installing `file_or_stdin_optional_arg` `file_or_stdin_positional_arg` `file_or_stdin_twice` `file_or_stdout_optional_arg` `file_or_stdout_positional_arg` `is_stdin` `maybe_stdin_optional_arg` `maybe_stdin_positional_arg` `maybe_stdin_twice` executables

Adding `clap_stdin` library as a dependency