{"id":17059168,"url":"https://github.com/flit/options","last_synced_at":"2025-03-23T07:25:26.433Z","repository":{"id":150949760,"uuid":"41933736","full_name":"flit/options","owner":"flit","description":"C++ command line option library ","archived":false,"fork":false,"pushed_at":"2015-09-04T20:10:35.000Z","size":188,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-28T14:16:19.902Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","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/flit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-04T19:18:53.000Z","updated_at":"2015-09-04T19:59:07.000Z","dependencies_parsed_at":"2023-04-07T03:37:44.569Z","dependency_job_id":null,"html_url":"https://github.com/flit/options","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/flit%2Foptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flit%2Foptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flit%2Foptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flit%2Foptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flit","download_url":"https://codeload.github.com/flit/options/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245068720,"owners_count":20555811,"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-10-14T10:32:57.660Z","updated_at":"2025-03-23T07:25:26.402Z","avatar_url":"https://github.com/flit.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# options\n\nC++ command line option library.\n\nThe original options library was written by Brad Appleton back in the 90s. It was\nupdated to a more modern C++ style with STL and Doxygen comments by Chris Reed.\n\n## Synopsis\n\n```cpp\n#include \u003coptions.h\u003e\n\nchar cmdname[], *optv[];\nOptions opts(cmdname, optv);\n```\n\n## Description\n\nThe `Options` constructor expects a command-name (usually `argv[0]`) and\na pointer to an array of strings.  The last element in this array _must_\nbe `NULL`. Each non-`NULL` string in the array must have the following format:\n\n- The 1st character must be the option-name (`c` for a `-c` option).\n\n- The 2nd character must be one of `|`, `?`, `:`, `*`, or `+`.\n - `|` -- indicates that the option takes _no_ argument\n - `?` -- indicates that the option takes an _optional_ argument\n - `:` -- indicates that the option takes a _required_ argument\n - `*` -- indicates that the option takes 0 or more arguments\n - `+` -- indicates that the option takes 1 or more arguments\n\n- The remainder of the string must be the long-option name.\n\nIf desired, the long-option name may be followed by one or more\nspaces and then by the name of the option value. This name will\nbe used when printing usage messages. If the option-value-name\nis not given then the string `\u003cvalue\u003e` will be used in usage\nmessages.\n\nOne may use a space to indicate that a particular option does not\nhave a corresponding long-option.  For example, \"`c: `\" (or \"`c:`\")\nmeans the `-c` option takes a value and has _no_ corresponding long-option.\n\nTo specify a long-option that has no corresponding single-character\noption is a bit trickier: `Options::operator()` still needs an \"option-\ncharacter\" to return when that option is matched. One may use a whitespace\ncharacter or a non-printable character as the single-character option\nin such a case. (hence \"` |hello`\" would only match \"`--hello`\").\n\n### Exceptions to the above\n\nIf the 1st character of the string is `-`, then the rest of the\nstring must correspond to the above format, and the option is\nconsidered to be a hidden-option. This means it will be parsed\nwhen actually matching options from the command-line, but will\n_not_ show-up if a usage message is printed using the `usage()` member\nfunction. Such an example might be \"`-h|hidden`\". If you want to\nuse any \"dummy\" options (options that are not parsed, but that\nto show up in the usage message), you can specify them along with\nany positional parameters to the `usage()` member function.\n\nIf the 2nd character of the string is '`\\0`' then it is assumed\nthat there is no corresponding long-option and that the option\ntakes no argument (hence \"`f`\", and \"`f| `\" are equivalent).\n\n```cpp\nconst char * optv[] = {\n    \"c:count   \u003cnumber\u003e\",\n    \"s?str     \u003cstring\u003e\",\n    \"x\",\n    \" |hello\",\n    \"g+groups  \u003cnewsgroup\u003e\",\n    NULL\n} ;\n```\n\n`optv[]` now corresponds to the following:\n\n           usage: cmdname [-c|--count \u003cnumber\u003e] [-s|--str [\u003cstring\u003e]]\n                          [-x] [--hello] [-g|--groups \u003cnewsgroup\u003e ...]\n\nLong-option names are matched case-insensitive and only a unique prefix\nof the name needs to be specified.\n\nOption-name characters are case-sensitive!\n\n## Caveat\n\nBecause of the way in which multi-valued options and options with optional\nvalues are handled, it is _not_ possible to supply a value to an option in\na separate argument (different `argv[]` element) if the value is _optional_\nand begins with a `-`. What this means is that if an option `-s` takes an\noptional value value and you wish to supply a value of `-foo` then you must\nspecify this on the command-line as `-s-foo` instead of `-s -foo` because\n`-s -foo` will be considered to be two separate sets of options.\n\nA multi-valued option is terminated by another option or by the end-of\noptions. The following are all equivalent (if `-l` is a multi-valued\noption and `-x` is an option that takes no value):\n\n    cmdname -x -l item1 item2 item3 -- arg1 arg2 arg3\n    cmdname -x -litem1 -litem2 -litem3 -- arg1 arg2 arg3\n    cmdname -l item1 item2 item3 -x arg1 arg2 arg3\n\n\n## Full example\n\n```cpp\n#include \u003coptions.h\u003e\n\nstatic const char * optv[] = {\n  \"H|help\",\n  \"c:count   \u003cnumber\u003e\",\n  \"s?str     \u003cstring\u003e\",\n  \"x\",\n  \" |hello\",\n  \"g+groups  \u003cnewsgroup\u003e\",\n  NULL\n} ;\n\nmain(int argc, char * argv[]) {\n  int  optchar;\n  const char * optarg;\n  const char * str = \"default_string\";\n  int  count = 0, xflag = 0, hello = 0;\n  int  errors = 0, ngroups = 0;\n\n  Options  opts(*argv, optv);\n  OptArgvIter  iter(--argc, ++argv);\n\n  while( optchar = opts(iter, optarg) ) {\n     switch (optchar) {\n     case 'H' :\n        opts.usage(cout, \"files ...\");\n        exit(0);\n        break;\n     case 'g' :\n        ++ngroups; break;  //! the groupname is in \"optarg\"\n     case 's' :\n        str = optarg; break;\n     case 'x' :\n        ++xflag; break;\n     case ' ' :\n        ++hello; break;\n     case 'c' :\n        if (optarg == NULL)  ++errors;\n        else  count = (int) atol(optarg);\n        break;\n     default :  ++errors; break;\n     } //!switch\n  }\n\n  if (errors || (iter.index() == argc)) {\n     if (! errors) {\n        cerr \u003c\u003c opts.name() \u003c\u003c \": no filenames given.\" \u003c\u003c endl ;\n     }\n     opts.usage(cerr, \"files ...\");\n     exit(1);\n  }\n\n  cout \u003c\u003c \"xflag=\" \u003c\u003c ((xflag) ? \"ON\"  : \"OFF\") \u003c\u003c endl\n       \u003c\u003c \"hello=\" \u003c\u003c ((hello) ? \"YES\" : \"NO\") \u003c\u003c endl\n       \u003c\u003c \"count=\" \u003c\u003c count \u003c\u003c endl\n       \u003c\u003c \"str=\\\"\" \u003c\u003c ((str) ? str : \"No value given!\") \u003c\u003c \"\\\"\" \u003c\u003c endl\n       \u003c\u003c \"ngroups=\" \u003c\u003c ngroups \u003c\u003c endl ;\n\n  if (iter.index() \u003c argc) {\n     cout \u003c\u003c \"files=\" ;\n     for (int i = iter.index() ; i \u003c argc ; i++) {\n        cout \u003c\u003c \"\\\"\" \u003c\u003c argv[i] \u003c\u003c \"\\\" \" ;\n     }\n     cout \u003c\u003c endl ;\n  }\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflit%2Foptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflit%2Foptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflit%2Foptions/lists"}