Merge pull request #45 from pavel-belikov/readme

Add examples for commands

1 files changed, 175 insertions, 10 deletions

diff --git a/README.md b/README.md
index c89804a..f3a35d8 100644
--- a/README.md
+++ b/README.md
@@ -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.
 
-[![build status](https://travis-ci.org/Taywee/args.svg?branch=master)](https://travis-ci.org/Taywee/args)
-[![Build status](https://ci.appveyor.com/api/projects/status/nlnlmpttdjlndyc2?svg=true)](https://ci.appveyor.com/project/Taywee/args)
+[![Cpp Standard](https://img.shields.io/badge/C%2B%2B-11-blue.svg)](https://en.wikipedia.org/wiki/C%2B%2B11)
+[![Travis status](https://travis-ci.org/Taywee/args.svg?branch=master)](https://travis-ci.org/Taywee/args)
+[![AppVeyor status](https://ci.appveyor.com/api/projects/status/nlnlmpttdjlndyc2?svg=true)](https://ci.appveyor.com/project/Taywee/args)
 [![Coverage Status](https://coveralls.io/repos/github/Taywee/args/badge.svg?branch=master)](https://coveralls.io/github/Taywee/args?branch=master)
+[![Read the Docs](https://img.shields.io/readthedocs/pip.svg)](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