Skip to content
oksydPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

osarg

osarg is a tiny, zero-dependency, borrow-first CLI parser for Rust binaries.

It is built for size-sensitive tools that want explicit control flow, OS-native argument handling, and enough ergonomics for real --help, --version, options, values, and positionals.

osarg is not a CLI framework. It does not use derive macros, schemas, or generated help text.

Supported Forms

  • -v
  • -abc
  • --verbose
  • --port=8080
  • --port 8080
  • -p 8080
  • -p8080
  • --
  • positional arguments
  • repeated options
  • passthrough via Parser::current_value_and_remaining() / into_remaining() / remaining_vec()

Parsing Rules

Call parser.check_flag()? before handling an option that takes no value. store_flag() performs this check automatically. An attached value such as --verbose=false or --help= is rejected with ErrorKind::UnexpectedValue. If an attached long value is left unread, next() reports it before advancing. For help/version output, classify the argument with standard::classify(), validate it with check_flag(), and then call Flag::write().

into_remaining() and remaining_vec() return Result; callers upgrading from the previous API must add ? or handle the error. A short tail beginning with - cannot be reconstructed without changing its meaning, so forwarding it returns ErrorKind::InvalidOptionName. Attached values such as -p-1 still work when consumed with value() or parse() before forwarding.

Example

use osarg::{Arg, Parser};
use std::path::PathBuf;

fn main() -> Result<(), osarg::Error> {
    let mut parser = Parser::from_args(["-p", "8080", "./data"]);

    let mut port = 8080;
    let mut path: Option<PathBuf> = None;

    while let Some(arg) = parser.next()? {
        match arg {
            Arg::Short('p') | Arg::Long("port") => {
                port = parser.parse::<u16>()?;
            }
            Arg::Value(value) => {
                value.store_path_buf(&mut path)?;
            }
            other => return Err(other.unexpected()),
        }
    }

    let path = osarg::required(path, "<PATH>")?;
    let _ = (port, path);
    Ok(())
}

Examples

See examples/ for:

  • basic single-command parsing
  • optional values
  • repeated options
  • passthrough wrappers

Benchmarks

Size benchmark:

bash ./scripts/size-bench.sh

The Clap comparison uses the checked-in manifest and lock file under scripts/size-bench/clap/. Dependency changes to that baseline must update those files explicitly. The script explicitly builds for CARGO_BUILD_TARGET when set, or the host target reported by rustc otherwise, and measures the binaries in that target's output directory.

Runtime benchmark:

cargo bench --bench parse -- --quick

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages