{"id":13424459,"url":"https://github.com/sailormoon/flags","last_synced_at":"2025-04-09T19:19:53.960Z","repository":{"id":13068546,"uuid":"73530193","full_name":"sailormoon/flags","owner":"sailormoon","description":"⛳ Simple, extensible, header-only C++17 argument parser released into the public domain.","archived":false,"fork":false,"pushed_at":"2023-09-10T21:13:39.000Z","size":40,"stargazers_count":228,"open_issues_count":2,"forks_count":15,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-04-09T19:19:49.831Z","etag":null,"topics":["argument-parser","c-plus-plus","c-plus-plus-17","free","free-software","header-only","parse","public-domain","publicdomain","simple"],"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/sailormoon.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}},"created_at":"2016-11-12T03:53:52.000Z","updated_at":"2024-12-18T03:17:56.000Z","dependencies_parsed_at":"2024-01-11T14:25:59.665Z","dependency_job_id":null,"html_url":"https://github.com/sailormoon/flags","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sailormoon%2Fflags","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sailormoon%2Fflags/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sailormoon%2Fflags/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sailormoon%2Fflags/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sailormoon","download_url":"https://codeload.github.com/sailormoon/flags/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248094991,"owners_count":21046770,"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":["argument-parser","c-plus-plus","c-plus-plus-17","free","free-software","header-only","parse","public-domain","publicdomain","simple"],"created_at":"2024-07-31T00:00:54.643Z","updated_at":"2025-04-09T19:19:53.928Z","avatar_url":"https://github.com/sailormoon.png","language":"C++","readme":"# ⛳ flags\n[![Build Status](https://travis-ci.org/sailormoon/flags.svg?branch=master)](https://travis-ci.org/sailormoon/flags)\n\nSimple, extensible, header-only C++17 argument parser released into the public domain.\n\n\n\u003c!-- vim-markdown-toc GFM --\u003e\n\n* [why](#why)\n* [requirements](#requirements)\n* [api](#api)\n  * [get](#get)\n  * [get (with default value)](#get-with-default-value)\n  * [positional](#positional)\n* [usage](#usage)\n  * [example](#example)\n  * [another example](#another-example)\n  * [extensions](#extensions)\n    * [example](#example-1)\n  * [command line details](#command-line-details)\n    * [key formatting](#key-formatting)\n    * [value assignment](#value-assignment)\n      * [bools](#bools)\n* [testing](#testing)\n* [contributing](#contributing)\n\n\u003c!-- vim-markdown-toc --\u003e\n\n# why\nOther argument parsers are:\n- bloated\n- non-extensible\n- not modern\n- complicated\n\n# requirements\nGCC 7.0 or Clang 4.0.0 at a minimum. This library makes extensive use of `optional`, `nullopt`, and `string_view`.\n\n# api\n`flags::args` exposes seven methods:\n\n## get\n`std::optional\u003cT\u003e get(const std::string_view\u0026 key) const`\n\nAttempts to parse the given key on the command-line. If the string is malformed or the argument was not passed, returns `nullopt`. Otherwise, returns the parsed type as an optional.\n\n## get (with default value)\n`T get(const std::string_view\u0026 key, T\u0026\u0026 default_value) const`\n\nFunctions the same as `get`, except if the value is malformed or the key was not provided, returns `default_value`. Otherwise, returns the parsed type.\n\n## get_multiple\n`std::vector\u003cstd::optional\u003cT\u003e\u003e get_multiple(const std::string_view\u0026 option) const`\n\nGet all values passed for an option. If no value is specified (`--foo --bar`) or the value is malformed, `nullopt` will be used. Values will be in the order they were passed.\n\n## get_multiple (with default value)\n`std::vector\u003cT\u003e get_multiple(const std::string_view\u0026 option, T\u0026\u0026 default_value) const`\n\nFunctions the same as `get_multiple`, except if the value is malformed or no value is provided, `default_value` will be used.\n\n## get (positional)\n`std::optional\u003cT\u003e get(size_t positional_index) const`\n\nGet an argument from the positional arguments at a specified index. If the value is malformed or the index is invalid, `nullopt` is returned.\n\n## get (positional with default value)\n`T get(size_t positional_index, T\u0026\u0026 default_value) const`\n\nFunctions the same as positional `get`, except if the value is malformed or the index is invalid, returns `default_value`. Otherwise, returns the parsed type.\n\n## positional\n`const std::vector\u003cstd::string_view\u003e\u0026 positional() const`\n\nReturns all of the positional arguments from argv in order.\n\n# usage\n### just the headers\nJust include `flags.h` from the `include` directory into your project.\n\n## Using CMake\n\n### CMake Installation\n\nFlags can be built and installed using [CMake], e.g.\n\n```sh\n$ mkdir build\n$ cd build\n$ cmake ..\n$ make\n$ make install\n```\n\nThe above will install Flags into the standard installation path on a UNIX\nsystem, e.g. `/usr/local/include/`. To change the installation path, use:\n\n```sh\n$ cmake .. -DCMAKE_INSTALL_PREFIX=../install\n```\n\nin the above.\n\n### `find_package`\n\nInstallation creates a `flags-config.cmake` which allows CMake\nprojects to find Flags using `find_package`:\n\n```cmake\nfind_package(flags)\n```\n\nThis exports the `flags` target which can be linked against any other\ntarget. Linking against `flags` automatically sets the include\ndirectories and required flags for C++17 or later. For example:\n\n```cmake\nadd_executable(myexe mysources...)\ntarget_link_libraries(myexe PRIVATE flags)\n```\n\n### `add_subdirectory`\n\nThe Flags can also be added as a dependency with `add_subdirectory`:\n\n```cmake\nadd_subdirectory(path/to/flags)\n```\n\nThis also exports the `flags` target which can be linked against any\nother target just as with the installation case.\n\n## example\n```c++\n#include \"flags.h\" // #include \u003cflags.h\u003e for cmake\n#include \u003ciostream\u003e\n\nint main(int argc, char** argv) {\n  const flags::args args(argc, argv);\n\n  const auto count = args.get\u003cint\u003e(\"count\");\n  if (!count) {\n    std::cerr \u003c\u003c \"No count supplied. :(\\n\";\n    return 1;\n  }\n  std::cout \u003c\u003c \"That's \" \u003c\u003c *count \u003c\u003c \" incredible, colossal credits!\\n\";\n\n  if (args.get\u003cbool\u003e(\"laugh\", false)) {\n    std::cout \u003c\u003c \"Ha ha ha ha!\\n\";\n  }\n  return 0;\n}\n```\n```bash\n$ ./program\n\u003e No count supplied. :(\n```\n```bash\n$ ./program --count=5 --laugh\n\u003e That's 5 incredible, colossal credits!\n\u003e Ha ha ha ha!\n```\n\n## another example\n```c++\n#include \"flags.h\" // #include \u003cflags.h\u003e for cmake\n#include \u003ciostream\u003e\n#include \u003cstring\u003e\n\nint main(int argc, char** argv) {\n  const flags::args args(argc, argv);\n  const auto\u0026 files = args.positional();\n  const auto verbose = args.get\u003cbool\u003e(\"verbose\", false);\n  if (verbose) {\n    std::cout \u003c\u003c \"I'm a verbose program! I'll be reading the following files:\\n\";\n    for (const auto\u0026 file : files) {\n      std::cout \u003c\u003c \"* \" \u003c\u003c file \u003c\u003c '\\n';\n    }\n  }\n  // read files(files);\n  return 0;\n}\n```\n```bash\n$ ./program /tmp/one /tmp/two /tmp/three --verbose\n\u003e I'm a verbose program! I'll be reading the following files:\n\u003e * /tmp/one\n\u003e * /tmp/two\n\u003e * /tmp/three\n```\n```bash\n$ ./program /tmp/one /tmp/two /tmp/three --noverbose\n\u003e%\n```\n\n## extensions\n`flags` simply uses the `istream` operator to parse values from `argv`. To extend the parser to support your own types, just supply an overloaded `\u003e\u003e`.\n\n### example\n```c++\nstruct Date {\n  int day;\n  int month;\n  int year;\n};\n\n// Custom parsing code.\nstd::istream\u0026 operator\u003e\u003e(std::istream\u0026 stream, Date\u0026 date) {\n  return stream \u003e\u003e date.day \u003e\u003e date.month \u003e\u003e date.year;\n}\n\nint main(int argc, char** argv) {\n  const flags::args args(argc, argv);\n  if (const auto date = args.get\u003cDate\u003e(\"date\")) {\n    // Output %Y/%m/%d if a date was provided.\n    std::cout \u003c\u003c date-\u003eyear \u003c\u003c \":\" \u003c\u003c date-\u003emonth \u003c\u003c \":\" \u003c\u003c date-\u003eday \u003c\u003c '\\n';\n    return 0;\n  }\n  // Sad face if no date was provided or if the input was malformed.\n  std::cerr \u003c\u003c \":(\\n\";\n  return 1;\n}\n```\n\n```bash\n$ ./program --date=\"10 11 2016\"\n\u003e 2016:11:10\n```\n\n```bash\n$ ./program\n\u003e :(\n```\n\n## command line details\n`flags`'s primary goal is to be simple to use for both the user and programmer.\n\n### key formatting\nA key can have any number of preceding `-`s, but must have more than 0.\nThe following are valid keys:\n- `-key`\n- `--key`\n- `-------------key`\n\n### value assignment\nA value can be assigned to a key in one of two ways:\n- `$ ./program --key=value`\n- `$ ./program --key value`\n\n#### bools\nbooleans are a special case. The following values make an argument considered `false`-y when parsed as a bool:\n- `f`\n- `false`\n- `n`\n- `no`\n- `0`\n\nIf none of these conditions are met, the bool is considered `true`.\n\n# testing\nflags uses both [bfg9000](https://github.com/jimporter/bfg9000) and [mettle](https://github.com/jimporter/mettle) for unit-testing. After installing both `bfg9000` and `mettle`, run the following commands to kick off the tests:\n\n1. `9k build/`\n2. `cd build`\n3. `ninja test`\n\n# contributing\nContributions of any variety are greatly appreciated. All code is passed through `clang-format` using the Google style.\n","funding_links":[],"categories":["Console","Argument Parsers"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsailormoon%2Fflags","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsailormoon%2Fflags","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsailormoon%2Fflags/lists"}