Crate nanoargs 

nanoargs

A minimal, zero-dependency argument parser for Rust CLI applications. Part of the nano crate family.

nanoargs gives you flags, options, positional arguments, subcommands, environment variable fallbacks, typed parsing, auto-generated help text, version handling, and optional colored help — all without pulling in a single transitive dependency.

Quick Start

use nanoargs::{ArgBuilder, Flag, Opt, Pos};

let parser = ArgBuilder::new()
    .name("myapp")
    .description("A sample CLI tool")
    .flag(Flag::new("verbose").desc("Enable verbose output").short('v'))
    .option(Opt::new("output").placeholder("FILE").desc("Output file path").short('o'))
    .positional(Pos::new("input").desc("Input file").required())
    .build()
    .unwrap();

// Parse from a Vec<String>:
// let result = parser.parse(args)?;

// Or parse from std::env::args():
// let result = parser.parse_env()?;

Features

Feature	Description
Flags	Boolean switches like --verbose / -v
Options	Key-value pairs like --output file.txt or -o=file.txt
Positionals	Ordered arguments like <input> (required) or [extra] (optional)
Subcommands	Nested command trees with independent argument sets
Short flag clusters	Combined flags like -abc and -aboval
Typed parsing	get_option_or_default::<T>(), get_option_required::<T>(), and more
Env var fallback	.env("MY_VAR") on options, with CLI > env > default precedence
Multi-value options	.multi() to collect repeated --tag a --tag b into a Vec
Hidden arguments	.hidden() to keep flags/options out of help text
Default values	.default("value") for optional options
Required arguments	.required() on options and positionals
Auto help	Built-in -h / --help with column-aligned output
Version flag	.version("1.0.0") enables --version / -V
Colored output	Opt-in color feature for ANSI-styled help and errors via nanocolor
Shell completions	Generate completion scripts for Bash, Zsh, Fish, and PowerShell via ArgParser::generate_completions

Builder API

All argument definitions flow through ArgBuilder using a chainable builder pattern:

let parser = ArgBuilder::new()
    .name("greet")
    .version("1.0.0")
    .flag(Flag::new("loud").desc("Shout the greeting").short('l'))
    .option(Opt::new("name").placeholder("NAME").desc("Who to greet").short('n').required())
    .option(Opt::new("times").placeholder("N").desc("Repeat count").default("1"))
    .positional(Pos::new("extra").desc("Extra words"))
    .build()
    .unwrap();

Construct argument definitions using Flag, Opt, and Pos, chain modifiers like .required(), .default(), .env(), .multi(), .hidden(), then pass them directly to the builder methods.

Parsing and Results

let result = parser.parse_env().unwrap();

// Flags return bool
let verbose = result.get_flag("verbose");

// Options return Option<&str>
let output = result.get_option("output");

// Typed parsing with default (returns Result — Err on bad parse)
let count: u32 = result.get_option_or_default("times", 1).unwrap();

// Or require it (returns Result for ? operator)
// let count: u32 = result.get_option_required("times")?;

// Lazy default via closure
// let count: u32 = result.get_option_or("times", || expensive_default())?;

// Low-level typed parse: Option<Result<T, Err>>
let parsed: Option<Result<u32, _>> = result.get_option_parsed("times");

// Multi-value options return &[String]
let tags = result.get_option_values("tags");

// Typed multi-values with fallback
// let tags: Vec<String> = result.get_option_values_or_default("tags", vec![])?;

// Positionals in order
let positionals = result.get_positionals();

// Subcommand access
if let Some(name) = result.subcommand() {
    let sub = result.subcommand_result().unwrap();
}

Subcommands

let sub = ArgBuilder::new()
    .positional(Pos::new("file").desc("File to add").required())
    .build().unwrap();

let parser = ArgBuilder::new()
    .name("git-lite")
    .flag(Flag::new("verbose").desc("Verbose output").short('v'))
    .subcommand("add", "Stage files", sub)
    .build().unwrap();

Global flags are parsed before the subcommand name. Everything after the subcommand name is delegated to the subcommand’s parser.

Error Handling

Parsing returns Result<ParseResult, ParseError>. The ParseError variants cover missing required arguments, missing option values, unknown arguments, invalid formats, unknown subcommands, and the special HelpRequested / VersionRequested cases (which carry the formatted text).

Colored Output

Enable the color Cargo feature for ANSI-styled help text and error messages:

[dependencies]
nanoargs = { version = "0.1", features = ["color"] }

Colors are applied automatically and suppressed when NO_COLOR is set or stdout is not a TTY (handled by nanocolor).

Schema-Free Parsing (Escape Hatch)

parse_loose is a convenience escape hatch for throwaway scripts where defining a full schema is overkill. It is not the recommended way to parse arguments — prefer ArgBuilder for anything user-facing.

let result = nanoargs::parse_loose().unwrap();
let verbose = result.get_flag("verbose");
let output = result.get_option("output");
let positionals = result.get_positionals();

parse_loose uses a heuristic (if the next token doesn’t start with -, it’s consumed as a value), which means --output -v silently treats --output as a flag. It also provides no help text, no required-argument validation, and no typed parsing. For anything beyond a quick script, use ArgBuilder.

Re-exports

pub use validators::max_length;

pub use validators::min_length;

pub use validators::non_empty;

pub use validators::one_of;

pub use validators::path_exists;

pub use validators::range;

pub use validators::Validator;

Modules

validators

Macros

extract

Declarative macro for one-step typed extraction from ParseResult.

Structs

ArgBuilder

Fluent builder for constructing an ArgParser.

ArgParser

The argument parser. Holds the schema (flags, options, positionals, subcommands) and provides methods to parse arguments, generate help text, and serialize/deserialize the schema.

ConflictDef

Definition of a conflict set: at most one member may be provided.

Flag

Standalone builder for defining a boolean flag argument.

FlagDef

Definition of a boolean flag (e.g. --verbose / -v).

GroupDef

Definition of an argument group: at least one member must be provided.

Opt

Standalone builder for defining a key-value option argument.

OptionDef

Definition of a key-value option (e.g. --output FILE / -o FILE).

ParseResult

The result of parsing a set of arguments.

ParseResultBuilder

Builder for constructing a ParseResult manually.

Pos

Standalone builder for defining a positional argument.

PositionalDef

Definition of a positional argument (e.g. <input> or [extra]).

SubcommandDef

Definition of a subcommand: a name, description, and its own ArgParser.

Enums

OptionError

Error returned by typed accessor methods (get_option_required, get_option_or_default, get_option_or, get_option_values_or_default, and extract!) when an option is missing or its value cannot be parsed.

ParseError

Errors produced during argument parsing.

Shell

Supported shell targets for completion script generation.

Functions

parse_loose

Schema-free parse of std::env::args() for quick-and-dirty scripts.