{"id":21348773,"url":"https://github.com/cvelth/argument_parser","last_synced_at":"2025-10-24T10:31:45.691Z","repository":{"id":118654461,"uuid":"258178632","full_name":"Cvelth/argument_parser","owner":"Cvelth","description":"A small lightweight single header only library for command line options parsing. Written using modern C++, such as \u003ccharconv\u003e, \u003coptional\u003e and \u003cstring_view\u003e.","archived":false,"fork":false,"pushed_at":"2020-05-02T10:42:59.000Z","size":53,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-22T16:47:58.403Z","etag":null,"topics":["c-plus-plus","command-line","cpp","cpp17","cpp20","header-only","option-parser","options-parsing","positional-arguments","single-header-lib"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"unlicense","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Cvelth.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":"2020-04-23T11:14:54.000Z","updated_at":"2020-05-01T10:41:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"0d1543f3-83d3-40f9-a2df-1b147e576e98","html_url":"https://github.com/Cvelth/argument_parser","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":"Cvelth/cpp_starter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cvelth%2Fargument_parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cvelth%2Fargument_parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cvelth%2Fargument_parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Cvelth%2Fargument_parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Cvelth","download_url":"https://codeload.github.com/Cvelth/argument_parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243822993,"owners_count":20353583,"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":["c-plus-plus","command-line","cpp","cpp17","cpp20","header-only","option-parser","options-parsing","positional-arguments","single-header-lib"],"created_at":"2024-11-22T02:25:51.943Z","updated_at":"2025-10-24T10:31:40.653Z","avatar_url":"https://github.com/Cvelth.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Actions Status](https://github.com/Cvelth/argument_parser/workflows/MacOS/badge.svg)](https://github.com/Cvelth/argument_parser/actions)\n[![Actions Status](https://github.com/Cvelth/argument_parser/workflows/Windows/badge.svg)](https://github.com/Cvelth/argument_parser/actions)\n[![Actions Status](https://github.com/Cvelth/argument_parser/workflows/Ubuntu/badge.svg)](https://github.com/Cvelth/argument_parser/actions)\n[![Actions Status](https://github.com/Cvelth/argument_parser/workflows/Style/badge.svg)](https://github.com/Cvelth/argument_parser/actions)\n[![Actions Status](https://github.com/Cvelth/argument_parser/workflows/Install/badge.svg)](https://github.com/Cvelth/argument_parser/actions)\n[![codecov](https://codecov.io/gh/Cvelth/argument_parser/branch/master/graph/badge.svg)](https://codecov.io/gh/Cvelth/argument_parser)\n\n# Argument Parser\nA small single header only library for command line options parsing.\n\n## Usage\n\n### Defining Arguments\n\nInclude the header:\n\n```cpp\n#include \"argument_parser.hpp\"\n```\n\nCreate an `ap::arguments` object passing argument-objects to the constructor. For example:\n```cpp\nap::arguments args {\n    ap::flag(\"-help\", \"h\"),\n    ap::positional(\"value\")\n};\n```\n\nParsing is done with:\n```cpp\nint main(int argc, char **argv) {\n    ... \n    auto results = args.parse(argc, argv);\n    ...\n}\n```\n\nAdditional arguments can be added before the parsing:\n\n```cpp\nargs.add(\n    ap::value(\"-optional_path\", \"o\"),\n    ap::callable([](){/* do something */}, \"activate\")\n)\n```\n\nAttempt to add a new argument after parsing raises an error.\n\n### Accessing Results\n\nMethod function `parse` returns an `ap::parsing_results` object.\n\nThis object has overloaded `operator bool() const` allowing to:\n```cpp\nif (results) {\n    // on success\n} else {\n    // on error\n}\n```\nParsing errors can be accessed:\n```cpp\nstd::vector\u003cstd::string\u003e const \u0026errors() const noexcept; // vector of error strings\nstd::vector\u003cstd::string\u003e const \u0026warnings() const noexcept; // vector of warning strings\n\nstd::string error_string() const; // output of errors() concatenated into a single string\nstd::string warning_string() const; // output of warnings() concatenated into a single string\n\nstd::string what() const; // equivalent to error_string()\nstd::string verbose() const; // concatenation of both errors and warning strings\n```\n\nArgument values can be accessed using `get()` method or overloaded `operator[]()`.\n```cpp\nap::parsing_result::get(/*name*/) // returns std::optional\u003c\u003e of a result\nap::parsing_result::operator[](/*name*/) // return result, but throws an ap::access_error object on error.\n```\n\nAn object returned by these methods has three data access templates:\n```cpp\nstd::optional\u003cT\u003e get\u003cT\u003e() const; // std::nullopt, if unable to convert to T.\nT as\u003cT\u003e() const; // throws an ap::access_error object, if unable to convert to T.\nT value_or\u003cT\u003e(T) const; // returns passed value, if unable to convert to T. T can be deduced by the compiler\n```\n\nExample:\n```cpp\nargs[\"value\"].value_or(-1); // returns value passed to the \"value\" argument \n                            // (as int (type deduced from \"-1\")) if it was passed \n                            // and can be converted. \"-1\" otherwise.\n```\n\n### Example:\n```cpp\n#include \"argument_parser.hpp\" // header\n#include \u003ciostream\u003e // for std::cout and std::cerr\n\nint main(int argc, char **argv) {\n    ap::arguments args {\n        ap::flag(\"-help\", \"h\"), // help-flag\n        ap::positional(\"value\") // positional value\n    }; // define arguments\n    \n    auto results = args.parse(argc, argv); // parse\n    \n    if (results) { // if parsed successfully\n        if(results[\"-help\"]) // if \u003c--help\u003e was passed\n            std::cout \u003c\u003c \"Carefully designed help\\n\";\n        else \n            if(auto value = results[\"value\"].get\u003cstd::size_t\u003e(); \n                    value) // if value is passed and convertible to std::size_t\n                foo(*value); // do something with std::size_t value\n        else\n            std::cout \u003c\u003c \"The value is unsupported\";\n    } else\n        std::cerr \u003c\u003c results.what(); // print errors\n        \n    return 0;\n}\n```\n\n### Argument Types\n#### ap::flag\nThe simplest argument type: it's either provided or not. \nIf the name was mentioned at least once, the value is true, otherwise it's false.\nConversions to any type except for `bool` will fail.\n\n#### ap::value\nThis argument type is capable of storing single value, provided in either `-value_arg value` or `-value_arg=value` form.\nUsage in the form of `-value_arg -another_arg` will cause an error to be raised.\nConversions to string types (`std::string`, `std::string_view` and `const char *`) and types implicitly constructible or convertible from them are guaranteed.\nConversions to types satisfying `std::is_arithmetic` (except for `bool`) are provided using `std::from_chars` and return errors accordingly to the result of the conversion. Types implicitly convertible from these are also allowed.\n\n#### ap::positional\nThis argument is equivalent to `ap::value` except it's also triggered in the cases where value is met without an active value-argument.\nThe order in which these arguments were added (using constructor or `ap::arguments::add`) determines order of usage.\nFor example:\n\n```cpp\nap::arguments args {\n    ap::positional{\"-first\", \"f\"},\n    ap::positional{\"s\", \"-second\"}\n}\n```\n\nAfter running ```application_name value_1, value_2``` next is ensured:\n\n```cpp\nresults[\"f\"].as\u003cstd::string\u003e == \"value_1\"s \u0026\u0026 results[\"s\"].as\u003cstd::string\u003e == \"value_2\"s\n```\n\n#### ap::counter\nThis argument type is similar to `ap::flag` except it remembers how many times the argument's name(s) was mentioned.\nIt's convertible to bool (`true` if any of aliases was mentioned at least once) and to any type constructible from `std::size_t`.\n\n#### ap::callable\nThe most customizable argument type. Constructor accepts either `std::function\u003cvoid()\u003e` or `std::function\u003cvoid(std::string_view const\u0026)\u003e`, as well as both of them in addition to aliases.\nWhen a value is passed into this argument, value accepting overload is called (if it was defined, error otherwise). Where there's no value, second overload is called (if it wa defined, error otherwise).\nThis argument type is only convertible to `bool` similarly to flag. Any value-related functionality is up to the user. Functions are called from `ap::arguments::parse()` during its processing.\n\n## Build and run the library\n\nNo need to, it's header only. Just grab a copy of it and use in whatever projects you please.\n\n### Build and run tests\n\nUse the following commands from the project's root directory to run the test suite.\n\n```bash\ncmake -Htest -Bbuild/test\ncmake --build build/test\n./build/test/GreeterTests\n```\n\nTo collect code coverage information, run CMake with the `-DENABLE_TEST_COVERAGE=1` option.\n\n### Run clang-format\n\nUse the following commands from the project's root directory to run clang-format (must be installed on the host system).\n\n```bash\ncmake -Htest -Bbuild/test\n\n# view changes\ncmake --build build/test --target format\n\n# apply changes\ncmake --build build/test --target fix-format\n```\n\nSee [Format.cmake](https://github.com/TheLartians/Format.cmake) for more options.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvelth%2Fargument_parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcvelth%2Fargument_parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcvelth%2Fargument_parser/lists"}