diff options
| -rw-r--r-- | README.md | 185 | ||||
| -rw-r--r-- | args.hxx | 36 | ||||
| -rw-r--r-- | test.cxx | 21 |
3 files changed, 232 insertions, 10 deletions
@@ -2,9 +2,11 @@ #### Note that this library is essentially in maintenance mode. I haven't had the time to work on it or give it the love that it deserves. I'm not adding new features, but I will fix bugs. I will also very gladly accept pull requests. -[](https://travis-ci.org/Taywee/args) -[](https://ci.appveyor.com/project/Taywee/args) +[](https://en.wikipedia.org/wiki/C%2B%2B11) +[](https://travis-ci.org/Taywee/args) +[](https://ci.appveyor.com/project/Taywee/args) [](https://coveralls.io/github/Taywee/args?branch=master) +[](https://taywee.github.io/args) A simple, small, flexible, single-header C++11 argument parsing library, in fewer than 2K lines of code. @@ -40,10 +42,10 @@ describe the usage, as it's built to push the boundaries. It: -* lets you handle flags, flag+value, and positional arguments simply and +* Lets you handle flags, flag+value, and positional arguments simply and elegently, with the full help of static typechecking. -* allows you to use your own types in a pretty simple way. -* lets you use count flags, and lists of all argument-accepting types. +* Allows you to use your own types in a pretty simple way. +* Lets you use count flags, and lists of all argument-accepting types. * Allows full validation of groups of required arguments, though output isn't pretty when something fails group validation. User validation functions are accepted. Groups are fully nestable. @@ -56,12 +58,11 @@ It: * Lets you decide not to allow separate-argument value flags or joined ones (like disallowing `--foo bar`, requiring `--foo=bar`, or the inverse, or the same for short options). -* Allows you to create subparsers somewhat like argparse, through the use of - kick-out arguments (check the gitlike.cxx example program for a simple sample - of this) -* Allow one value flag to take a specific number of values (like `--foo first +* Allows you to create subparsers, to reuse arguments for multiple commands and + to refactor your command's logic to a function or lambda +* Allows one value flag to take a specific number of values (like `--foo first second`, where --foo slurps both arguments). -* Allow you to have value flags only optionally accept values +* Allows you to have value flags only optionally accept values # What does it not do? @@ -377,6 +378,170 @@ Argument 'numbers' received invalid value type 'a' ... ``` +## Commands + +```cpp +#include <iostream> +#include <args.hxx> +int main(int argc, char **argv) +{ + args::ArgumentParser p("git-like parser"); + args::Group commands(p, "commands"); + args::Command add(commands, "add", "add file contents to the index"); + args::Command commit(commands, "commit", "record changes to the repository"); + args::Group arguments(p, "arguments", args::Group::Validators::DontCare, args::Options::Global); + args::ValueFlag<std::string> gitdir(arguments, "path", "", {"git-dir"}); + args::HelpFlag h(arguments, "help", "help", {'h', "help"}); + args::PositionalList<std::string> pathsList(arguments, "paths", "files to commit"); + + try + { + p.ParseCLI(argc, argv); + if (add) + { + std::cout << "Add"; + } + else + { + std::cout << "Commit"; + } + + for (auto &&path : pathsList) + { + std::cout << ' ' << path; + } + + std::cout << std::endl; + } + catch (args::Help) + { + std::cout << p; + } + catch (args::Error& e) + { + std::cerr << e.what() << std::endl << p; + return 1; + } + return 0; +} +``` + +```shell +% ./test -h + ./test COMMAND [paths...] {OPTIONS} + + git-like parser + + OPTIONS: + + commands + add add file contents to the index + commit record changes to the repository + arguments + --git-dir=[path] + -h, --help help + paths... files + "--" can be used to terminate flag options and force all following + arguments to be treated as positional options + +% ./test add 1 2 +Add 1 2 +``` + +## Refactoring commands + +```cpp +#include <iostream> +#include "args.hxx" + +args::Group arguments("arguments"); +args::ValueFlag<std::string> gitdir(arguments, "path", "", {"git-dir"}); +args::HelpFlag h(arguments, "help", "help", {'h', "help"}); +args::PositionalList<std::string> pathsList(arguments, "paths", "files to commit"); + +void CommitCommand(args::Subparser &parser) +{ + args::ValueFlag<std::string> message(parser, "MESSAGE", "commit message", {'m'}); + parser.Parse(); + + std::cout << "Commit"; + + for (auto &&path : pathsList) + { + std::cout << ' ' << path; + } + + std::cout << std::endl; + + if (message) + { + std::cout << "message: " << args::get(message) << std::endl; + } +} + +int main(int argc, const char **argv) +{ + args::ArgumentParser p("git-like parser"); + args::Group commands(p, "commands"); + args::Command add(commands, "add", "add file contents to the index", [&](args::Subparser &parser) + { + parser.Parse(); + std::cout << "Add"; + + for (auto &&path : pathsList) + { + std::cout << ' ' << path; + } + + std::cout << std::endl; + }); + + args::Command commit(commands, "commit", "record changes to the repository", &CommitCommand); + args::GlobalOptions globals(p, arguments); + + try + { + p.ParseCLI(argc, argv); + } + catch (args::Help) + { + std::cout << p; + } + catch (args::Error& e) + { + std::cerr << e.what() << std::endl << p; + return 1; + } + return 0; +} +``` + +```shell +% ./test -h + ./test COMMAND [paths...] {OPTIONS} + + git-like parser + + OPTIONS: + + commands + add add file contents to the index + commit record changes to the repository + arguments + --git-dir=[path] + -h, --help help + paths... files + "--" can be used to terminate flag options and force all following + arguments to be treated as positional options + +% ./test add 1 2 +Add 1 2 + +% ./test commit -m "my commit message" 1 2 +Commit 1 2 +message: my commit message +``` + # Custom type parsers (here we use std::tuple) ```cpp @@ -2577,6 +2577,42 @@ namespace args } }; + /** A flag class that calls a function when it's matched + */ + class ActionFlag : public FlagBase + { + private: + std::function<void(const std::vector<std::string> &)> action; + Nargs nargs; + + public: + ActionFlag(Group &group_, const std::string &name_, const std::string &help_, Matcher &&matcher_, Nargs nargs_, std::function<void(const std::vector<std::string> &)> action_, Options options_ = {}): + FlagBase(name_, help_, std::move(matcher_), options_), action(std::move(action_)), nargs(nargs_) + { + group_.Add(*this); + } + + ActionFlag(Group &group_, const std::string &name_, const std::string &help_, Matcher &&matcher_, std::function<void(const std::string &)> action_, Options options_ = {}): + FlagBase(name_, help_, std::move(matcher_), options_), nargs(1) + { + group_.Add(*this); + action = [action_](const std::vector<std::string> &a) { return action_(a.at(0)); }; + } + + ActionFlag(Group &group_, const std::string &name_, const std::string &help_, Matcher &&matcher_, std::function<void()> action_, Options options_ = {}): + FlagBase(name_, help_, std::move(matcher_), options_), nargs(0) + { + group_.Add(*this); + action = [action_](const std::vector<std::string> &) { return action_(); }; + } + + virtual Nargs NumberOfArguments() const noexcept override + { return nargs; } + + virtual void ParseValue(const std::vector<std::string> &value) override + { action(value); } + }; + /** A default Reader class for argument classes * * If destination type is assignable to std::string it uses an assignment to std::string. @@ -1097,6 +1097,27 @@ TEST_CASE("ValueParser works as expected", "[args]") REQUIRE_NOTHROW(p.ParseArgs(std::vector<std::string>{"-i", " 12"})); REQUIRE(args::get(i) == 12); + +TEST_CASE("ActionFlag works as expected", "[args]") +{ + args::ArgumentParser p("parser"); + std::string s; + + args::ActionFlag action0(p, "name", "description", {'x'}, [&]() { s = "flag"; }); + args::ActionFlag action1(p, "name", "description", {'y'}, [&](const std::string &arg) { s = arg; }); + args::ActionFlag actionN(p, "name", "description", {'z'}, 2, [&](const std::vector<std::string> &arg) { s = arg[0] + arg[1]; }); + args::ActionFlag actionThrow(p, "name", "description", {'v'}, [&]() { throw std::runtime_error(""); }); + + p.ParseArgs(std::vector<std::string>{"-x"}); + REQUIRE(s == "flag"); + + p.ParseArgs(std::vector<std::string>{"-y", "a"}); + REQUIRE(s == "a"); + + p.ParseArgs(std::vector<std::string>{"-z", "a", "b"}); + REQUIRE(s == "ab"); + + REQUIRE_THROWS_AS(p.ParseArgs(std::vector<std::string>{"-v"}), std::runtime_error); } #undef ARGS_HXX |