{"id":17912739,"url":"https://github.com/stypox/arg-parser","last_synced_at":"2025-10-18T20:31:35.562Z","repository":{"id":48349537,"uuid":"168401595","full_name":"Stypox/arg-parser","owner":"Stypox","description":"Argument parser for modern C++: no runtime overhead; auto-generated help screen.","archived":false,"fork":false,"pushed_at":"2021-08-26T16:30:41.000Z","size":108,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-19T00:07:20.466Z","etag":null,"topics":["argparse","argparser","argument-parser","argument-parsing","arguments","command-line","commandline","compile-time","compiler-optimization","cpp-library","cpp17","cpp20","local","localstorage","overhead","reference-data"],"latest_commit_sha":null,"homepage":"","language":"C++","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/Stypox.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}},"created_at":"2019-01-30T19:27:08.000Z","updated_at":"2025-02-21T15:51:05.000Z","dependencies_parsed_at":"2022-08-29T17:11:51.532Z","dependency_job_id":null,"html_url":"https://github.com/Stypox/arg-parser","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/Stypox%2Farg-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Farg-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Farg-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Stypox%2Farg-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Stypox","download_url":"https://codeload.github.com/Stypox/arg-parser/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245180384,"owners_count":20573663,"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":["argparse","argparser","argument-parser","argument-parsing","arguments","command-line","commandline","compile-time","compiler-optimization","cpp-library","cpp17","cpp20","local","localstorage","overhead","reference-data"],"created_at":"2024-10-28T19:46:46.663Z","updated_at":"2025-10-18T20:31:35.511Z","avatar_url":"https://github.com/Stypox.png","language":"C++","readme":"# Argument parser\n\nA **C++** library that **parses command line arguments** and automatically generates a **help screen**. The initialization of the parser should not impose **any run-time overhead**.\n\n# Features\n\n## **Options** \nThere are three different options that can be used:\n - **Switch option**: they are not followed by any value (e.g. `--help`). When used they set the underlying reference to a provided value. \n - **Option**: they except an integer, a decimal number or some text (e.g. `--size=50 --gravity=9.8 --say=Hello!`).\n   - The type `T` of the underlying reference must meet one of these requirements:\n     - `std::is_integer\u003cT\u003e`: excepts an integer that does not overflow/underflow `T` limits.\n\t  Represented by `I` in the help screen.\n     - `std::is_floating_point\u003cT\u003e`: excepts a decimal number that does not overflow/underflow `T` limits.\n\t  Represented by `D` in the help screen.\n     - `std::is_convertible\u003cstd::string_view, T\u003e`: excepts some text.\n\t  Represented by `T` in the help screen.\n\t- excepts a valid value, checked using a **user-defined validation function** (if present).\n - **Manual option**: they except an arbitrary string which is manipulated in a non-standard way. (e.g. `--html=\u003cp\u003eHello!\u003c/p\u003e`)\n\t- Requires a **user-defined function** to convert the string to the type of the underlying reference.\n\t- Represented by `S` in the help screen.\n   \n\nEvery option has these attributes:\n - ***name***: used for error reporting;\n - ***reference*** to a variable: the output in which to save the inserted value;\n - one or more ***arguments***: what the user has to pass in the console to set the value of the option;\n - ***description***: used in the help screen;\n - whether it is ***required*** or not; represented by `*` in the help screen when set to `true`;\n\n## **Error checking and reporting**\nDuring the parsing process every argument has to meet these requirements:\n - every argument must have a **corresponding option** (this does not apply if positional arguments are valid);\n - that option should **not have already been encountered**;\n - if the option excepts a **value**, the argument must contain one (but empty texts/strings are ok);\n - the value has to be **convertible** to the underlying variable type (either normally or via the user-defined function);\n - for *normal options*, the value must **not overflow** (this only applies to integers and decimal numbers)\n\nDuring the validation process every computed option has to meet these requirements:\n - if the option is required, it must **have been encountered**;\n - for *normal options*, the value must **pass the validity check**, represented by the user-defined function (that passes by default);\n\nThe parsing process and the validation process are **separate**, so that even if an option is invalid no error is generated until the validation starts. This is useful, for example, to display the help screen when `--help` is provided, even if other options are invalid. Every error contains an **thorough description** about what caused it.\n\n## **Help screen**\nSee [below](#output) for an example help screen.\n - Titles and lines of description can be added to the help screen by providing **help sections**.\n - The **indentation** of the description of sections can be changed. When the indentation is not enough a newline is added between the arguments and the description\n - The first argument is considered, by default, the **executable path**, but this can be manually changed. The executable path is used for the help screen.\n\n# Installation\nJust **download** the header file `argparser.hpp` and **`#include`** it into your project! If you want to `#include` it as `\u003cstypox/argparser.hpp\u003e` you need to add `-IPATH/TO/arg-parser/include` to your compiler options.  \nNote: it requires C++17, so add to your compiler options `-std=c++17`. C++20 is also supported, along with `requires` clauses.\n\n# Documentation\nAll types are defined in `namespace stypox`. To simplify reading, `std::` is omitted before `tuple`, `string`, `string_view`, `vector` and `array`; also `const Type\u0026` is written just `Type`. Read the code for more precise details.\n## **ArgParser**\n`ArgParser` is the class that does the job of parsing arguments.\n\n### ArgParser::ArgParser()\n`(tuple\u003cOptions...\u003e options, string_view programName, size_t descriptionIndentation = 25)`  \nConstructs the ArgParser object. `Options...` must be made only of `SwitchOption`, `Option`, `ManualOption` or `HelpSection`. The `tuple` can be instantiated using `std::make_tuple(Options...)`.\n\n### ArgParser::parse()\n(1) `void (Iter first, Iter last, bool firstArgumentIsExecutablePath)`  \n(2) `void (int argc, char const* argv[], bool firstArgumentIsExecutablePath = true)`  \nParses all the arguments in range [first, last) (1) / [argv, argv+argc) (2), reports parsing errors (by throwing `std::runtime_error`) as described [above](#options), saves the new values for options. Throws `std::out_of_range` if `firstArgumentIsExecutablePath` is set to `true` but the list of arguments is empty.\n\n### ArgParser::parsePositional()\n(1) `vector\u003cstring\u003e (Iter first, Iter last, bool firstArgumentIsExecutablePath)`  \n(2) `vector\u003cstring\u003e (int argc, char const* argv[], bool firstArgumentIsExecutablePath = true)`  \nParses all the arguments in range [first, last) (1) / [argv, argv+argc) (2), reports parsing errors (by throwing `std::runtime_error`) as described [above](#options), saves the new values for options. Returns the arguments that didn't match any option. Throws `std::out_of_range` if `firstArgumentIsExecutablePath` is set to `true` but the list of arguments is empty.\n\n### ArgParser::validate()\n`void ()`  \nReports logical errors (by throwing `std::runtime_error`) as described [above](#error-checking-and-reporting).\n\n### ArgParser::reset()\n`void ()`  \nEvery argument is set as if it had never been encountered.\n\n### ArgParser::usage()\n`string ()`  \nReturns the usage screen. See the [output of the code below](#output) for an example.\n\n### ArgParser::help()\n`string ()`  \nReturns the help screen. The indentation of the description of options can be set in the constructor. See the [output of the code below](#output) for an example.\n\n## SwitchOption, Option, ManualOption, HelpSection\n`HelpSection`\n`SwitchOption`, `Option` and `ManualOption` are the classes that keep information about every option. The difference between them is explained [above](#options). The array of possible arguments (of size `N`) can be initialized using `stypox::args()`.  \n`HelpSection` is a class that holds a string of text to be printed in the help screen.\n\n### args()\n`array\u003cstring_view, sizeof...(Args)\u003e args(Args... list)`  \nBuilds an array of possible arguments using the provided `list` (needed for the constructors of options).\n\n### SwitchOption::SwitchOption()\n(when T is bool) `(string_view name, T\u0026 output, array\u003cstring_view, N\u003e arguments, string_view help, T valueWhenSet = true, required = false)`  \n(when T is not bool) `(string_view name, T\u0026 output, array\u003cstring_view, N\u003e arguments, string_view help, T valueWhenSet, required = false)`  \n`SwitchOption`'s constructor. When parsing, the value will be saved in `output`.\n\n### Option::Option()\n`(string_view name, T\u0026 output, array\u003cstring_view, N\u003e arguments, string_view help, required = false, F validityChecker = [](){ return true; })`  \n`Option`'s constructor. When parsing, the value will be saved in `output`. When validating `validityChecker` is called with `(output)` (it must return `bool`). See [above](#options) to read about the valid types `T`.\n\n### ManualOption::ManualOption()\n`(string_view name, T\u0026 output, array\u003cstring_view, N\u003e arguments, string_view help, F assignerFunctor, required = false)`  \n`ManualOption`'s constructor. When parsing, the value, converted to `T` by calling `assignerFunctor(string_view)`, will be saved in `output`.\n\n### HelpSection::HelpSection()\n`(string_view title)`  \n`HelpSection`'s constructor. When generating the help screen `title` is appended to it followed by `\\n`.\n\n\n# Example\n```cpp\n#include \u003ciostream\u003e\n#include \"arg-parser/include/stypox/argparser.hpp\"\n\nint main(int argc, char const* argv[]) {\n\t// initialize variables with the default values\n\tbool help = false;\n\tbool usage = false;\n\tint exitCode = 0;\n\tfloat cake = 0.5f;\n\n\t// a default value would be useless, since the corresponding option is required\n\tstd::pair\u003cstd::string, int\u003e person;\n\n\tstypox::ArgParser p{\n\t\tstd::make_tuple(\n\t\t\tstypox::HelpSection{\"\\nHelp options:\"},\n\t\t\tstypox::SwitchOption{\"help\", help, stypox::args(\"-?\", \"-h\", \"--help\"), \"show help screen\"},\n\t\t\tstypox::SwitchOption{\"usage\", usage, stypox::args(\"-u\", \"--usage\"), \"show usage screen\"},\n\n\t\t\tstypox::HelpSection{\"\\nOther important options:\"},\n\t\t\tstypox::SwitchOption{\"exitWithError\", exitCode, stypox::args(\"--exit-with-error\"), \"set exit code to 1\",\n\t\t\t\t1 /* value to set to variable @exitCode when the option is used*/},\n\t\t\tstypox::Option{\"cake\", cake, stypox::args(\"-c=\", \"--cake=\"), \"how much cake will you take? (0-1; default=0.5)\",\n\t\t\t\tfalse, // option not required\n\t\t\t\t[](float value){ // validation function\n\t\t\t\t\treturn value \u003e= 0.0f \u0026\u0026 value \u003c= 1.0f;\n\t\t\t\t}},\n\t\t\tstypox::ManualOption{\"person\", person, stypox::args(\"-p=\", \"--person=\"), \"a person (format: `name;age`)\",\n\t\t\t\t[](const std::string_view\u0026 str) { // conversion function\n\t\t\t\t\ttry {\n\t\t\t\t\t\tsize_t semicolonIndex = str.find_first_of(\";\");\n\t\t\t\t\t\tif (semicolonIndex == std::string::npos)\n\t\t\t\t\t\t\tthrow std::runtime_error{\"\"};\n\n\t\t\t\t\t\tstd::string name{str.substr(0, semicolonIndex)},\n\t\t\t\t\t\t\tage{str.substr(semicolonIndex + 1, str.size() - semicolonIndex - 1)};\n\t\t\t\t\t\t// the type of the returned value matches the type of variable @person\n\t\t\t\t\t\treturn std::pair\u003cstd::string, float\u003e{name, std::stoi(age)};\n\t\t\t\t\t} catch (...) {\n\t\t\t\t\t\tthrow std::runtime_error{\"Invalid person \" + std::string{str}};\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\ttrue /* option required */}\n\t\t),\n\t\t\"Example program by Stypox\"\n\t};\n\n\tp.parse(argc, argv);\n\t// check for help before validating\n\tif (help) {\n\t\tstd::cout \u003c\u003c p.help();\n\t\treturn 0;\n\t}\n\tif (usage) {\n\t\tstd::cout \u003c\u003c p.usage();\n\t\treturn 0;\n\t}\n\n\tp.validate();\n\tstd::cout \u003c\u003c \"Here is a piece of cake of size \" \u003c\u003c cake \u003c\u003c \"!\\n\"\n\t\t\u003c\u003c person.first \u003c\u003c \" is now my best friend: he is \" \u003c\u003c person.second \u003c\u003c \" years old :-D\\n\";\n\n\treturn exitCode;\n}\n```\n### Output\nOutput for different commands (`; echo 'Exit code: '$?;` is only there to print the exit code):\n```sh\n$ ./executable; echo 'Exit code: '$?;\nterminate called after throwing an instance of 'std::runtime_error'\n  what():  Option person is required\nAborted\nExit code: 134\n\n\n$ ./executable --help; echo 'Exit code: '$?;\nExample program by Stypox\nLegend: I=integer; D=decimal; T=text; S=custom string; *=required;\nUsage: ./executable [-?] [-u] [--exit-with-error] [-c=D] -p=S\n\nHelp options:\n  -? -h --help           show help screen\n  -u --usage             show usage screen\n\nOther important options:\n  --exit-with-error      set exit code to 1\n  -c=D --cake=D          how much cake will you take? (0-1; default=0.5)\n  -p=S --person=S        *a person (format: `name;age`)\n\nExit code: 0\n\n\n$./executable --usage; echo 'Exit code: '$?;\nExample program by Stypox\nLegend: I=integer; D=decimal; T=text; S=custom string; *=required;\nUsage: ./executable [-?] [-u] [--exit-with-error] [-c=D] -p=S\nExit code: 0\n\n\n$./executable --cake=0.7245 --person=\"John Smith;17\" --exit-with-error; echo 'Exit code: '$?;\nHere is a piece of cake of size 0.7245!\nJohn Smith is now my best friend: he is 17 years old :-D\nExit code: 1\n\n\n$ ./executable --cak; echo 'Exit code: '$?;\nterminate called after throwing an instance of 'std::runtime_error'\n  what():  Unknown argument: --cak\nAborted\nExit code: 134\n\n\n$ ./executable --cake=1.2; echo 'Exit code: '$?;\nterminate called after throwing an instance of 'std::runtime_error'\n  what():  Option cake: value 1.200000 is not allowed\nAborted\nExit code: 134\n\n\n$ ./executable --cake=1.2e10000; echo 'Exit code: '$?;\nterminate called after throwing an instance of 'std::runtime_error'\n  what():  Option cake: out of range decimal \"1.2e10000\" (must be between 0.000000 and 340282346638528859811704183484516925440.000000): --cake=1.2e10000\nAborted\nExit code: 134\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstypox%2Farg-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstypox%2Farg-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstypox%2Farg-parser/lists"}