{"id":19543305,"url":"https://github.com/uutils/uutils-args","last_synced_at":"2025-04-26T17:32:20.025Z","repository":{"id":65365861,"uuid":"571028346","full_name":"uutils/uutils-args","owner":"uutils","description":"An experimental derive-based argument parser specifically for uutils","archived":false,"fork":false,"pushed_at":"2025-04-12T12:20:48.000Z","size":401,"stargazers_count":7,"open_issues_count":14,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-12T13:36:15.446Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uutils.png","metadata":{"files":{"readme":"README.md","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}},"created_at":"2022-11-26T23:10:45.000Z","updated_at":"2025-04-12T12:20:52.000Z","dependencies_parsed_at":"2023-02-11T08:15:36.177Z","dependency_job_id":"0a8a69d5-1ff5-410d-84b2-7d563ff544e1","html_url":"https://github.com/uutils/uutils-args","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutils%2Fuutils-args","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutils%2Fuutils-args/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutils%2Fuutils-args/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uutils%2Fuutils-args/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uutils","download_url":"https://codeload.github.com/uutils/uutils-args/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251026202,"owners_count":21524935,"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","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":[],"created_at":"2024-11-11T03:18:17.209Z","updated_at":"2025-04-26T17:32:20.014Z","avatar_url":"https://github.com/uutils.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Discord](https://img.shields.io/badge/discord-join-7289DA.svg?logo=discord\u0026longCache=true\u0026style=flat)](https://discord.gg/wQVJbvJ)\n[![License](http://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/uutils/uutils-args/blob/main/LICENSE)\n[![dependency status](https://deps.rs/repo/github/uutils/uutils-args/status.svg)](https://deps.rs/repo/github/uutils/uutils-args)\n\n[![CodeCov](https://codecov.io/gh/uutils/uutils-args/branch/master/graph/badge.svg)](https://codecov.io/gh/uutils/uutils-args)\n![MSRV](https://img.shields.io/badge/MSRV-1.85.0-brightgreen)\n\n# uutils-args\n\nArgument parsing for the [uutils](https://www.github.com/uutils/) projects.\n\nIt is designed to be flexible, while providing default\nbehaviour that aligns with GNU coreutils and other tools.\n\n## Features\n\n- A derive macro for declarative argument definition.\n- Automatic help generation.\n- Positional and optional arguments.\n- Automatically parsing values into Rust types.\n- Define a custom exit code on errors.\n- Automatically accept unambiguous abbreviations of long options.\n- Handles invalid UTF-8 gracefully.\n\n## When you should not use this library\n\nThe goal of this library is to make it easy to build applications that\nmimic the behaviour of the GNU coreutils. There are other applications\nthat have similar behaviour, which are C application that use `getopt`\nand `getopt_long`. If you want to mimic that behaviour exactly, this\nis the library for you. If you want to write basically anything else,\nyou should probably pick another argument parser (for example: [clap](https://github.com/clap-rs/clap)).\n\n## Getting Started\n\nParsing with this library consists of two \"phases\". In the first\nphase, the arguments are mapped to an iterator of an `enum`\nimplementing [`Arguments`]. The second phase is mapping these\narguments onto a `struct` implementing [`Options`]. By defining\nyour arguments this way, there is a clear divide between the public\nAPI and the internal representation of the settings of your app.\n\nFor more information on these traits, see their respective documentation:\n\n- [`Arguments`]\n- [`Options`]\n\nBelow is a minimal example of a full CLI application using this library.\n\n```rust\nuse uutils_args::{Arguments, Options};\n\n#[derive(Arguments)]\nenum Arg {\n    // The doc strings below will be part of the `--help` text\n    // First we define a simple flag:\n    /// Transform input text to uppercase\n    #[arg(\"-c\", \"--caps\")]\n    Caps,\n\n    // This option takes a value:\n    /// Add exclamation marks to output\n    #[arg(\"-e N\", \"--exclaim=N\")]\n    ExclamationMarks(u8),\n}\n\n#[derive(Default)]\nstruct Settings {\n    caps: bool,\n    exclamation_marks: u8,\n    text: String,\n}\n\n// To implement `Options`, we only need to provide the `apply` method.\n// The `parse` method will be automatically generated.\nimpl Options\u003cArg\u003e for Settings {\n    fn apply(\u0026mut self, arg: Arg) -\u003e Result\u003c(), uutils_args::Error\u003e {\n        match arg {\n            Arg::Caps =\u003e self.caps = true,\n            Arg::ExclamationMarks(n) =\u003e self.exclamation_marks += n,\n        }\n        Ok(())\n    }\n}\n\nfn run(args: \u0026[\u0026str]) -\u003e String {\n    let (s, operands) = Settings::default().parse(args).unwrap();\n    let text = operands.iter().map(|s| s.to_string_lossy()).collect::\u003cVec\u003c_\u003e\u003e().join(\" \");\n    let mut output = if s.caps {\n        text.to_uppercase()\n    } else {\n        text\n    };\n    for i in 0..s.exclamation_marks {\n        output.push('!');\n    }\n    output\n}\n\n// The first argument is the binary name. In this example it's ignored.\nassert_eq!(run(\u0026[\"shout\", \"hello\"]), \"hello\");\nassert_eq!(run(\u0026[\"shout\", \"-e3\", \"hello\"]), \"hello!!!\");\nassert_eq!(run(\u0026[\"shout\", \"-e\", \"3\", \"hello\"]), \"hello!!!\");\nassert_eq!(run(\u0026[\"shout\", \"--caps\", \"hello\"]), \"HELLO\");\nassert_eq!(run(\u0026[\"shout\", \"-e3\", \"-c\", \"hello\"]), \"HELLO!!!\");\nassert_eq!(run(\u0026[\"shout\", \"-e3\", \"-c\", \"hello\", \"world\"]), \"HELLO WORLD!!!\");\n```\n\n## Value parsing\n\nTo make it easier to implement [`Arguments`] and [`Options`], there is the\n[`Value`] trait, which allows for easy parsing from `OsStr` to any type\nimplementing [`Value`]. This crate also provides a derive macro for\nthis trait.\n\n## Examples\n\nThe following files contain examples of commands defined with\n`uutils_args`:\n\n- [hello world](https://github.com/uutils/uutils-args/blob/main/examples/hello_world.rs)\n- [arch](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/arch.rs)\n- [b2sum](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/b2sum.rs)\n- [base32](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/base32.rs)\n- [basename](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/basename.rs)\n- [cat](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/cat.rs)\n- [echo](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/echo.rs)\n- [ls](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/ls.rs)\n- [mktemp](https://github.com/uutils/uutils-args/blob/main/tests/coreutils/mktemp.rs)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuutils%2Fuutils-args","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuutils%2Fuutils-args","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuutils%2Fuutils-args/lists"}