{"id":31628042,"url":"https://github.com/jirutka/argp","last_synced_at":"2025-10-15T08:11:09.893Z","repository":{"id":65729361,"uuid":"594852287","full_name":"jirutka/argp","owner":"jirutka","description":"Rust derive-based argument parsing optimized for code size and flexibility","archived":false,"fork":false,"pushed_at":"2024-12-05T22:21:28.000Z","size":313,"stargazers_count":15,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-06T20:30:17.783Z","etag":null,"topics":["argh","argument-parser","arguments","command-line","derive","rust","rust-library"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jirutka.png","metadata":{"files":{"readme":"README.adoc","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-01-29T20:36:36.000Z","updated_at":"2025-09-28T07:03:01.000Z","dependencies_parsed_at":"2024-12-05T22:34:57.023Z","dependency_job_id":null,"html_url":"https://github.com/jirutka/argp","commit_stats":{"total_commits":202,"total_committers":29,"mean_commits":"6.9655172413793105","dds":0.4554455445544554,"last_synced_commit":"a1796fccf6699a0a78f7a5bbc247049077122d8e"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/jirutka/argp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Fargp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Fargp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Fargp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Fargp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jirutka","download_url":"https://codeload.github.com/jirutka/argp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jirutka%2Fargp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279060282,"owners_count":26095125,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-15T02:00:07.814Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["argh","argument-parser","arguments","command-line","derive","rust","rust-library"],"created_at":"2025-10-06T20:17:14.481Z","updated_at":"2025-10-15T08:11:09.847Z","avatar_url":"https://github.com/jirutka.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"= Argp\nJakub Jirutka \u003chttps://github.com/jirutka[@jirutka]\u003e\n:proj-name: argp\n:gh-name: jirutka/{proj-name}\n\nifdef::env-github[]\nimage:https://img.shields.io/crates/v/{proj-name}.svg[Version on crates.io, link=https://crates.io/crates/{proj-name}]\nimage:https://docs.rs/{proj-name}/badge.svg[docs.rs, link=https://docs.rs/crate/{proj-name}/]\nimage:https://github.com/{gh-name}/workflows/CI/badge.svg[CI Workflow, link=https://github.com/{gh-name}/actions?query=workflow%3A%22CI%22]\nendif::env-github[]\n\nArgp is a Derive-based argument parser optimized for code size and flexibility.\n\nThe public API of this library consists primarily of the `FromArgs` derive and the `parse_args_or_exit` function, which can be used to produce a top-level `FromArgs` type from the current program's command-line arguments.\n\n\n== Features\n\n* Zero runtime dependencies.\n* Small size overhead – ~40 kiB footnote:[Measured on a release build with `strip = true` and `panic = \"abort\"`. The exact size depends on several factors, including the number of options and subcommands.], that’s *10x less* than https://github.com/clap-rs/clap[clap] or https://github.com/clap-rs/clap/tree/master/clap_derive[clap_derive]! See https://github.com/jirutka/argparse-rosetta-rs[argparse-rosetta-rs] for more details.\n* Derive-based API – you define structs and enums for the parsed values, use attributes to specify how they should be parsed and a procedural derive macro will generate the parser at compile-time.\n* Context-sensitive parsing.\n* Support for subcommands.\n* Help message generator with Markdown support and dynamic wrapping based on terminal width.\n\n\n== Origins\n\nArgp originally started as a fork of https://github.com/google/argh/[argh] to make it less opinionated, more UNIXy and flexible.\n\nNotable changes from argh:\n\n* Support for global options (i.e. options defined at the top level can be used in subcommands).\n* Support for combined short options (e.g. `-ab` is parsed as `-a -b`, `-an 5` as `-a -n 5`).\n* Support for non-UTF8 arguments (OsStr).\n* The `from_str_fn` attribute can also contain a function path, not just a single identifier, and can return any `Err` type which implements `ToString`.\n* No pedantic requirement for descriptions to start with a lower-case letter.\n* Help message is dynamically wrapped based on terminal width (on unix systems).\n* The indentation of descriptions in the help message is dynamically calculated based on the widths of all elements.\n* The `arg_name` attribute can also be used even on positional arguments to customise how the argument is displayed in the help message.\n* Errors are represented using an enum instead of a String and the information used to generate a help message is stored in a partially structured form in a struct; this opens the door to customisation of messages.\n* Specialised `example`, `note`, and `error_code` attributes are replaced by a single `footer` attribute – you can use it for whatever you like.\n* Positional arguments in the Usage string are displayed _after_ options and switches and `\u003carg_name\u003e` is displayed in descriptions of options.\n* Trailing options are allowed after the `-h, --help` switch, but are not allowed after the `help` subcommand only.\n* The `from_env` function has been renamed to `parse_args_or_exit`, `cargo_from_env` to `cargo_parse_args_or_exit`.\n* `redact_arg_values` has been removed (if you happen to need it, let me know in Issues).\n\n\n== Basic Example\n\n[source, rust]\n----\nuse argp::FromArgs;\n\n/// Reach new heights.\n#[derive(FromArgs)]\nstruct GoUp {\n    /// Whether or not to jump.\n    #[argp(switch, short = 'j')]\n    jump: bool,\n\n    /// How high to go.\n    #[argp(option, arg_name = \"meters\")]\n    height: usize,\n\n    /// An optional nickname for the pilot.\n    #[argp(option, arg_name = \"name\")]\n    pilot_nickname: Option\u003cString\u003e,\n}\n\nfn main() {\n    let up: GoUp = argp::parse_args_or_exit(argp::DEFAULT);\n}\n----\n\n`./some_bin --help` will then output the following:\n\n....\nUsage: cmdname [-j] --height \u003cmeters\u003e [--pilot-nickname \u003cname\u003e]\n\nReach new heights.\n\nOptions:\n  -j, --jump                   Whether or not to jump.\n      --height \u003cmeters\u003e        How high to go.\n      --pilot-nickname \u003cname\u003e  An optional nickname for the pilot.\n  -h, --help                   Show this help message and exit.\n....\n\nThe resulting program can then be used in any of these ways:\n\n* `./some_bin --height 5`\n* `./some_bin -j --height 5`\n* `./some_bin --jump --height 5 --pilot-nickname Wes`\n\nSwitches, like `jump`, are optional and will be set to true if provided.\n\nOptions, like `height` and `pilot_nickname`, can be either required, optional, or repeating, depending on whether they are contained in an `Option` or a `Vec`.\nDefault values can be provided using the `#[argp(default = \"\u003cyour_code_here\u003e\")]` attribute, and in this case an option is treated as optional.\n\n[source, rust]\n----\nuse argp::FromArgs;\n\nfn default_height() -\u003e usize {\n    5\n}\n\n/// Reach new heights.\n#[derive(FromArgs)]\nstruct GoUp {\n    /// An optional nickname for the pilot.\n    #[argp(option)]\n    pilot_nickname: Option\u003cString\u003e,\n\n    /// An optional height.\n    #[argp(option, default = \"default_height()\")]\n    height: usize,\n\n    /// An optional direction which is \"up\" by default.\n    #[argp(option, default = \"String::from(\\\"only up\\\")\")]\n    direction: String,\n}\n\nfn main() {\n    let up: GoUp = argp::parse_args_or_exit(argp::DEFAULT);\n}\n----\n\nCustom option types can be deserialized so long as they implement the `FromArgValue` trait (already implemented for most types in std for which the `FromStr` trait is implemented).\nIf more customized parsing is required, you can supply a custom `fn(\u0026str) -\u003e Result\u003cT, E\u003e` using the `from_str_fn` attribute, or `fn(\u0026OsStr) -\u003e Result\u003cT, E\u003e` using the `from_os_str_fn` attribute, where `E` implements `ToString`:\n\n[source, rust]\n----\nuse argp::FromArgs;\nuse std::ffi::OsStr;\nuse std::path::PathBuf;\n\n/// Goofy thing.\n#[derive(FromArgs)]\nstruct FineStruct {\n    /// Always five.\n    #[argp(option, from_str_fn(always_five))]\n    five: usize,\n\n    /// File path.\n    #[argp(option, from_os_str_fn(convert_path))]\n    path: PathBuf,\n}\n\nfn always_five(_value: \u0026str) -\u003e Result\u003cusize, String\u003e {\n    Ok(5)\n}\n\nfn convert_path(value: \u0026OsStr) -\u003e Result\u003cPathBuf, String\u003e {\n    Ok(PathBuf::from(\"/tmp\").join(value))\n}\n----\n\nPositional arguments can be declared using `#[argp(positional)]`.\nThese arguments will be parsed in order of their declaration in the structure:\n\n[source, rust]\n----\nuse argp::FromArgs;\n\n/// A command with positional arguments.\n#[derive(FromArgs, PartialEq, Debug)]\nstruct WithPositional {\n    #[argp(positional)]\n    first: String,\n}\n----\n\nThe last positional argument may include a default, or be wrapped in `Option` or `Vec` to indicate an optional or repeating positional argument.\n\nSubcommands are also supported.\nTo use a subcommand, declare a separate `FromArgs` type for each subcommand as well as an enum that cases over each command:\n\n[source, rust]\n----\nuse argp::FromArgs;\n\n/// Top-level command.\n#[derive(FromArgs, PartialEq, Debug)]\nstruct TopLevel {\n    /// Be verbose.\n    #[argp(switch, short = 'v', global)]\n    verbose: bool,\n\n    #[argp(subcommand)]\n    nested: MySubCommandEnum,\n}\n\n#[derive(FromArgs, PartialEq, Debug)]\n#[argp(subcommand)]\nenum MySubCommandEnum {\n    One(SubCommandOne),\n    Two(SubCommandTwo),\n}\n\n/// First subcommand.\n#[derive(FromArgs, PartialEq, Debug)]\n#[argp(subcommand, name = \"one\")]\nstruct SubCommandOne {\n    /// How many x.\n    #[argp(option)]\n    x: usize,\n}\n\n/// Second subcommand.\n#[derive(FromArgs, PartialEq, Debug)]\n#[argp(subcommand, name = \"two\")]\nstruct SubCommandTwo {\n    /// Whether to fooey.\n    #[argp(switch)]\n    fooey: bool,\n}\n----\n\nFor more information, refer to the https://docs.rs/argp/latest/argp/[argp documentation].\n\n\n== How to debug the expanded derive macro for `argp`\n\nThe `argp::FromArgs` derive macro can be debugged with the https://crates.io/crates/cargo-expand[cargo-expand] crate.\n\n\n=== Expand the derive macro in `examples/simple_example.rs`\n\nSee link:argp/examples/simple_example.rs[] for the example struct we wish to expand.\n\nFirst, install `cargo-expand` by running `cargo install cargo-expand`.\nNote this requires the nightly build of Rust.\n\nOnce installed, run `cargo expand` with in the `argp` package and you can see the expanded code.\n\n\n== License\n\nThis project is licensed under http://opensource.org/licenses/BSD-3-Clause/[BSD-3-Clause license].\nFor the full text of the license, see the link:LICENSE[LICENSE] file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjirutka%2Fargp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjirutka%2Fargp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjirutka%2Fargp/lists"}