Function bpaf::positional_os

pub fn positional_os(metavar: &'static str) -> Positional<OsString>

Positional argument in OS specific encoding

For named flags and arguments ordering generally doesn’t matter: most programs would understand -O2 -v the same way as -v -O2, but for positional items order matters: in unix cat hello world and cat world hello would display contents of the same two files but in different order.

Important restriction

When parsing positional arguments from command lines you should have parsers for all your named values and command before parsers for positional items. In derive API fields parsed as positional should be at the end of your struct/enum. Same rule applies for positional fields nested inside other structures: such structures should go to the end as well. Failing to do can result in behavior confusing for the end user.

Combinatoric usage

fn input() -> impl Parser<std::ffi::OsString> {
    positional_os("INPUT")
}

Derive usage

bpaf_derive converts fields in tuple-like structures into positional items and automatically uses positional_os for OsString and PathBuf

#[derive(Debug, Clone, Bpaf)]
struct Options(std::ffi::OsString);

positional and positional_os annotations also accept an optional metavar name

#[derive(Debug, Clone, Bpaf)]
struct Options {
    #[bpaf(positional_os("INPUT"))]
    input: std::path::PathBuf,
}

See also positional_os - a simiar function

Examples found in repository

examples/positional.rs (line 18)

fn main() {
    let value = long("value")
        .help("Mysterious value")
        .argument("VAL")
        .from_str::<u32>()
        .fallback(42);
    let files = positional_os("FILE").map(PathBuf::from).many();
    let opts = construct!(Options { value, files }).to_options().run();

    println!("{:#?}", opts);
}