{"id":20888023,"url":"https://github.com/canop/clap-help","last_synced_at":"2025-05-12T20:30:47.331Z","repository":{"id":181389586,"uuid":"666704415","full_name":"Canop/clap-help","owner":"Canop","description":"A more compact help renderer for clap terminal applications","archived":false,"fork":false,"pushed_at":"2025-05-09T16:38:59.000Z","size":1628,"stargazers_count":72,"open_issues_count":1,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-05-09T16:50:39.561Z","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":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Canop.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"2023-07-15T09:49:46.000Z","updated_at":"2025-05-09T16:39:03.000Z","dependencies_parsed_at":"2024-01-18T02:37:02.041Z","dependency_job_id":"11ff1283-f742-40ed-b59f-76f38c1a6c63","html_url":"https://github.com/Canop/clap-help","commit_stats":null,"previous_names":["canop/clap-help"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Canop%2Fclap-help","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Canop%2Fclap-help/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Canop%2Fclap-help/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Canop%2Fclap-help/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Canop","download_url":"https://codeload.github.com/Canop/clap-help/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253816656,"owners_count":21968861,"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-18T08:23:50.211Z","updated_at":"2025-05-12T20:30:46.946Z","avatar_url":"https://github.com/Canop.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# clap-help\n\n[![MIT][s2]][l2] [![Latest Version][s1]][l1] [![docs][s3]][l3] [![Chat on Miaou][s4]][l4]\n\n[s1]: https://img.shields.io/crates/v/clap-help.svg\n[l1]: https://crates.io/crates/clap-help\n\n[s2]: https://img.shields.io/badge/license-MIT-blue.svg\n[l2]: LICENSE\n\n[s3]: https://docs.rs/clap-help/badge.svg\n[l3]: https://docs.rs/clap-help/\n\n[s4]: https://miaou.dystroy.org/static/shields/room.svg\n[l4]: https://miaou.dystroy.org/3768?rust\n\n## Purpose and Features\n\n**clap-help** prints the --help message of [clap](https://docs.rs/clap/) based terminal applications.\n\n### Differences with the vanilla help renderer of the clap crate:\n\n- more readable, thanks to a width aware layout\n- more compact: from 2 to 3 times less lines compared to vanilla\n- options rendered in a balanced table, optimized for the width of the terminal\n- introduction interpreted as Markdown, allowing lists, tables, code blocks, etc.\n- doc of options interpreted as Markdown\n- skin automatically selected for light or dark terminals\n- customizable [termimad](https://github.com/Canop/termimad/) skin\n- you can customize section templates, remove them, reorder them, add sections\n\nNote: there's no support for subcommands yet.\n\n## Example\n\nThe [bacon](https://dystroy.org/bacon) programs uses clap-help with an introduction text, a clearer options table, examples, and a skin consistent with the rest of the application:\n\n![bacon](doc/bacon.png)\n\nHow it's done: [https://github.com/Canop/bacon/blob/main/src/args.rs](https://github.com/Canop/bacon/blob/main/src/args.rs).\n\n## Usage\n\n### Basic usage\n\nYour program needs a clap `Command` defined.\n\nHere's for example with clap-derive:\n\n```rust\n#[derive(Parser, Debug)]\n#[command(name=\"area\", author, version, about, disable_help_flag = true)]\nstruct Args {\n\n    /// Print help\n    #[arg(long)]\n    help: bool,\n\n    /// Height, that is the distance between bottom and top\n    #[arg(short, long, default_value = \"9\")]\n    height: u16,\n\n    /// Width, from there, to there, eg `4` or `5`\n    #[arg(short, long, default_value = \"3\")]\n    width: u16,\n\n    /// Kill all birds to improve computation\n    #[arg(short, long)]\n    kill_birds: bool,\n\n    /// Computation strategy\n    #[arg(long, default_value = \"fast\")]\n    strategy: Strategy,\n\n    /// Bird separator\n    #[arg(short, long, value_name = \"SEP\")]\n    separator: Option\u003cString\u003e,\n\n    /// Root Directory\n    pub root: Option\u003cstd::path::PathBuf\u003e,\n}\n```\n\nNotice\n* the `disable_help_flag = true` disabling the standard behaviour of clap regarding help.\n* the explicit `help` argument. Here it's with only `#[arg(long)]` because `-h` is used for something more important but you would most often have `#[arg(short, long)]`.\n\nThe help introduction (the part before usage) is defined as a string which will be interpreted as Markdown. It can contain tables, lists, bold, italic, inline code, code blocks, etc.\n\n```rust\nstatic INTRO: \u0026str = \"\n\nCompute `height x width`\n*You can do it either precisely (enough) or fast (I mean not too slow)*.\n\";\n```\n\nOn program launch, you should check the value of the `help` flag and, if necessary, print the help:\n\n```rust\nlet args = Args::parse();\nif args.help {\n    Printer::new(Args::command())\n        .with(\"introduction\", INTRO)\n        .without(\"author\")\n        .print_help();\n    return;\n}\n```\n\nHelp rendered in a light terminal:\n\n![area light](doc/area-light.png)\n\nSame help in a dark terminal:\n\n![area dark](doc/area-dark.png)\n\nComplete example is in `/examples/area` and can be seen with `cargo run --example area -- --help`\n\n### Adding custom sections\n\nHelp is usually easier to grasp with a few examples.\nYou can write a few ones in your intro, or you can add them in a later section, after the options.\n\nIt's also possible to leverage the template system, which is what is done in the `with-examples` example, for this result:\n\n![with-examples](doc/with-examples.png)\n\nHere's how it's done:\n\n```rust\nstatic EXAMPLES_TEMPLATE: \u0026str = \"\n**Examples:**\n\n${examples\n**${example-number})** ${example-title}: `${example-cmd}`\n${example-comments}\n}\n\";\n```\n\n```rust\n\nlet mut printer = clap_help::Printer::new(Args::command())\n    .with(\"introduction\", INTRO_TEMPLATE)\n    .without(\"author\");\nprinter.template_keys_mut().push(\"examples\");\nprinter.set_template(\"examples\", EXAMPLES_TEMPLATE);\nfor (i, example) in EXAMPLES.iter().enumerate() {\n    printer\n        .expander_mut()\n        .sub(\"examples\")\n        .set(\"example-number\", i + 1)\n        .set(\"example-title\", example.title)\n        .set(\"example-cmd\", example.cmd)\n        .set_md(\"example-comments\", example.comments);\n}\nprinter.print_help();\n```\n\n[complete code of the example](examples/with-examples/main.rs)\n\n\n### Changing the skin\n\nIf your program has some kind of graphical identity, you may want to extend it to the help.\n\nYou may change colors, preferably with more compatible [ansi color codes](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit).\n\nSee example in `examples/custom` mainly features:\n\n![custom](doc/custom.png)\n\nThe strategy for those changes is\n\n* to redefine the `bold`, `italic`, and `inline_code` styles to change their foreground color, to remove the background of the code, and to remove the Italic attribute of `italic`\n* to use the `TEMPLATE_OPTIONS_MERGED_VALUE` template for options\n\nHere are the relevant parts of the code:\n\n\n```rust\nstatic INTRO: \u0026str = \"\n\nCompute `height x width`\nMore info at *https://dystroy.org*\n\";\n\nlet mut printer = Printer::new(Args::command())\n    .without(\"author\")\n    .with(\"introduction\", INTRO)\n    .with(\"options\", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);\nlet skin = printer.skin_mut();\nskin.headers[0].compound_style.set_fg(ansi(202));\nskin.bold.set_fg(ansi(202));\nskin.italic = termimad::CompoundStyle::with_fg(ansi(45));\nskin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));\nskin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;\nprinter.print_help();\n```\n\nComplete example is in `/examples/custom` and can be seen with `cargo run --example custom -- --help`\n\nPlease note that not every customization is possible or easy.\nAnd some may be easy but not obvious.\nCome to [the chat](https://miaou.dystroy.org/3768?rust) and ask if needed.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanop%2Fclap-help","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcanop%2Fclap-help","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcanop%2Fclap-help/lists"}