#clap #stdin

bin+lib clap-stdin

Provides a type for easily accepting Clap arguments from stdin

4 releases

0.2.1 Jul 30, 2023
0.2.0 May 31, 2023
0.1.1 Apr 26, 2023
0.1.0 Apr 26, 2023

#239 in Command-line interface

Download history 214/week @ 2023-08-12 72/week @ 2023-08-19 147/week @ 2023-08-26 125/week @ 2023-09-02 181/week @ 2023-09-09 153/week @ 2023-09-16 51/week @ 2023-09-23 87/week @ 2023-09-30 125/week @ 2023-10-07 160/week @ 2023-10-14 173/week @ 2023-10-21 193/week @ 2023-10-28 213/week @ 2023-11-04 233/week @ 2023-11-11 137/week @ 2023-11-18 117/week @ 2023-11-25

729 downloads per month
Used in 4 crates

MIT/Apache

15KB
230 lines

clap-stdin Build

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

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 time 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 {
    contents: FileOrStdin,
}

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

Calling this CLI:

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

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

Compatible Types

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

use std::path::PathBuf;
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

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.

Dependencies

~0.4–1MB
~22K SLoC