{"id":26753725,"url":"https://github.com/jibsen/cpparg","last_synced_at":"2025-03-28T13:34:33.398Z","repository":{"id":284321877,"uuid":"954551206","full_name":"jibsen/cpparg","owner":"jibsen","description":"C++ parser for argv","archived":false,"fork":false,"pushed_at":"2025-03-25T09:09:10.000Z","size":134,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-25T10:23:41.785Z","etag":null,"topics":["cpp","getopt"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit-0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jibsen.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":"2025-03-25T08:58:31.000Z","updated_at":"2025-03-25T09:09:13.000Z","dependencies_parsed_at":"2025-03-25T10:23:44.771Z","dependency_job_id":"aaee5ae7-7fbf-47ea-b846-945191ff2fdb","html_url":"https://github.com/jibsen/cpparg","commit_stats":null,"previous_names":["jibsen/cpparg"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jibsen%2Fcpparg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jibsen%2Fcpparg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jibsen%2Fcpparg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jibsen%2Fcpparg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jibsen","download_url":"https://codeload.github.com/jibsen/cpparg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246037439,"owners_count":20713418,"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":["cpp","getopt"],"created_at":"2025-03-28T13:32:07.485Z","updated_at":"2025-03-28T13:34:33.390Z","avatar_url":"https://github.com/jibsen.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `cpparg` - C++ parser for `argv`\n\n## About\n\n`cpparg` is a parser for command-line options. It is a header-only library,\nwritten in C++23.\n\nIt is made available under the [MIT No Attribution License](LICENSE) (MIT-0).\n\n## Usage\n\nParsing command-line options is handled by `cpparg::OptionParser`.\n\n### Declaring Options\n\nYou use the `add_option()` function to add options, it takes four strings\nas arguments:\n\n  - short flag as a string containing one character, for instance `\"s\"`\n  - long flag, for instance `\"size\"`\n  - display name of the argument to the option (if any), for instance\n    `\"SIZE\"`, or `\"[SIZE]\"` if the argument is optional\n  - description of the option\n\nThe long flag is used to identify the option. So for instance\n\n```cpp\n    cpparg::OptionParser parser;\n\n    parser.add_option(\"h\", \"help\",     \"\",      \"print this help and exit\")\n          .add_option(\"r\", \"required\", \"ARG\",   \"option with required argument\")\n          .add_option(\"o\", \"optional\", \"[ARG]\", \"option with optional argument\");\n```\n\nwill create an `OptionParser` that handles 3 options named `help`,\n`required`, and `optional`. The `help` option takes no arguments, the\n`required` option requires an argument, and the `optional` option may\ntake an argument if present.\n\nThe short flag may be empty, in which case the option only supports the\nlong flag.\n\nLikewise, the long flag may be empty, which results in a long flag with\nthe name of the short flag being created (because it is used to identify\nthe option), but not shown in the help.\n\n### Printing Help\n\n`OptionParser` has a function `get_option_help()` that returns a string\nwith formatted help for the options it supports. For instance our example\nabove would return a string containing\n\n```\n  -h, --help            print this help and exit\n  -r, --required ARG    option with required argument\n  -o, --optional[=ARG]  option with optional argument\n```\n\nIf you prefer required arguments be printed as part of the option, you can\nadd a `=` to the string, as in `\"=ARG\"`.\n\nYou can group options in the help output by inserting a newline at the end\nof the preceeding option description.\n\n`get_option_help()` takes the desired line width as an optional parameter.\nIf you supply a line width, it will attempt to break the option description\nat spaces.\n\n`cpparg` only handles this part of the help because there are choices for\nhow to display usage that are difficult to combine. Instead you can print\nyour own usage instructions and include this option help string.\n\n### Parsing `argv`\n\nParsing is done with the `parse_argv()` function, which returns a\n`std::expected` containing either a `cpparg::ParseResult` or a\n`cpparg::ParseError`.\n\n`ParseError` is a struct containing two members, `originating_arg` which is\nthe index of the element of `argv` that contained the error, and `what`,\nwhich is a string describing the error.\n\n```cpp\n    auto result = parser.parse_argv(argc, argv);\n\n    if (!result) {\n        std::println(std::cerr, \"cpparg: {}\", result.error().what);\n\n        return EXIT_FAILURE;\n    }\n```\n\n### Using `ParseResult`\n\n`cpparg::ParseResult` has a number of functions:\n\n  - `count(\"name\")` returns the number of times option `name` occured\n  - `get_last_argument_for_option(\"name\")` returns an optional containing\n    the last option argument given for option `name`, if any\n  - `get_arguments_for_option(\"name\")` returns a reference to a vector\n    containing all the arguments that were provided for the `name` option\n  - `get_parsed_options()` returns a reference to a vector of\n    `cpparg::ParsedOption`\n  - `get_positional_arguments()` returns a reference to a vector containing\n    all the positional arguments\n\nA `cpparg::ParsedOption` is a struct containing three members, `name` which\nis the name of the option, `count` which is how many times it occured, and\n`arguments`, which is a vector of arguments supplied to the option.\n\nOption arguments are provided as `std::string`.\n\n```cpp\n    // If the `help` option appeared, show help\n    if (result-\u003ecount(\"help\")) {\n        std::println(\n            \"usage: cpparg_example [options] POSITIONAL_ARG...\\n\"\n            \"\\n\"\n            \"Example program for cpparg.\\n\"\n            \"\\n\"\n            \"{}\",\n            parser.get_option_help()\n        );\n\n        return EXIT_SUCCESS;\n    }\n\n    // Check that at least one positional argument was supplied\n    if (result-\u003eget_positional_arguments().size() \u003c 1) {\n        std::println(std::cerr, \"usage: cpparg_example [options] POSITIONAL_ARG...\\n\");\n\n        return EXIT_FAILURE\n    }\n\n    // Iterate over options\n    for (const auto \u0026option : result-\u003eget_parsed_options()) {\n        std::print(\"option '{}' appeared {} time(s)\", option.name, option.count);\n\n        if (!option.arguments.empty()) {\n            std::print(\" with argument(s):\");\n\n            for (const auto \u0026argument : option.arguments) {\n                std::print(\" '{}'\", argument);\n            }\n        }\n\n        std::print(\"\\n\");\n    }\n\n    // Iterate over positional arguments\n    for (const auto \u0026argument : result-\u003eget_positional_arguments()) {\n        std::println(\"positional argument '{}'\", argument);\n    }\n```\n\n## Known Limitations\n\n`cpparg` parses all options at once, you cannot know the ordering between\noptions and positional arguments.\n\nOnly exact matches for long options are supported. You cannot use an\nunambiguous prefix of a long option like with `getopt_long` or `parg`.\n\n`cpparg` provides option arguments as `std::string`, you have to do your\nown conversion if needed.\n\n## Alternatives\n\nPlease see the README file for [`parg`][parg] for a list of alternatives.\n\n[parg]: https://github.com/jibsen/parg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjibsen%2Fcpparg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjibsen%2Fcpparg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjibsen%2Fcpparg/lists"}