aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--README.md142
1 files changed, 116 insertions, 26 deletions
diff --git a/README.md b/README.md
index 7cfd07c..04dbb01 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,7 @@
# args
A simple, small, flexible, single-header C++11 argument parsing library, in
-about 1.2K lines of code.
+about 1.3K lines of code.
This is designed to somewhat replicate the behavior of Python's argparse, but
in C++, with static type checking, and hopefully a lot faster.
@@ -11,7 +11,9 @@ with its heavy use of inheritence), but it should be more flexible than most.
UTF-8 support is limited at best. No normalization is performed, so non-ascii
characters are very best kept out of flags, and combined glyphs are probably
-going to mess up help output if you use it.
+going to mess up help output if you use it. Most UTF-8 necessary for
+internationalization should work for most cases, though heavily combinatory UTF
+alphabets may wreak havoc.
This program is MIT-licensed, so you can use the header as-is with no
restrictions. I'd appreciate attribution in a README, Man page, or something if
@@ -42,8 +44,8 @@ It:
* Lets you customize all prefixes and most separators, allowing you to create
an infinite number of different argument syntaxes
* Lets you parse, by default, any type that has a stream extractor operator for
- it. If this doesn't work, you can supply a function and parse the string
- yourself if you like.
+ it. If this doesn't work for your uses, you can supply a function and parse
+ the string yourself if you like.
# What does it not do
@@ -57,7 +59,8 @@ There are tons of things this library does not do!
## It will not ever:
-* Allow you to create subparsers like argparse
+* Allow you to create subparsers like argparse in a master parser (you can do
+ this yourself with iterators and multiple parsers)
* Allow one argument flag to take a specific number of arguments
(like `--foo first second`). You can instead split that with a flag list
(`--foo first --foo second`) or a custom type extraction
@@ -76,7 +79,7 @@ There are tons of things this library does not do!
# How do I use it?
-Just copy and paste it into your source tree, or put it somewhere that your
+Just copy the header into your source tree, or put it somewhere that your
compiler can see. As long as you can `#include "args.hxx"` and use c++11, you
should be good to go.
@@ -99,13 +102,13 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
return 0;
@@ -135,7 +138,7 @@ int main(int argc, char **argv)
int main(int argc, char **argv)
{
args::ArgumentParser parser("This is a test program.", "This goes after the options.");
- args::Group group(parser, "This group is all exclusive", args::Group::Validators::Xor);
+ args::Group group(parser, "This group is all exclusive:", args::Group::Validators::Xor);
args::Flag foo(group, "foo", "The foo flag", args::Matcher({'f'}, {"foo"}));
args::Flag bar(group, "bar", "The bar flag", args::Matcher({'b'}));
args::Flag baz(group, "baz", "The baz flag", args::Matcher({"baz"}));
@@ -145,19 +148,19 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
catch (args::ValidationError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
if (foo) { std::cout << "foo" << std::endl; }
@@ -176,9 +179,10 @@ Group validation failed somewhere!
OPTIONS:
- -f, --foo The foo flag
- -b The bar flag
- --baz The baz flag
+ This group is all exclusive:
+ -f, --foo The foo flag
+ -b The bar flag
+ --baz The baz flag
This goes after the options.
% ./test -f
@@ -223,19 +227,19 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
catch (args::ValidationError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
if (integer) { std::cout << "i: " << integer.value << std::endl; }
@@ -323,13 +327,13 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
if (ints)
@@ -420,19 +424,19 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
catch (args::ValidationError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
return 0;
@@ -511,19 +515,19 @@ int main(int argc, char **argv)
}
catch (args::Help)
{
- std::cout << parser.Help();
+ std::cout << parser;
return 0;
}
catch (args::ParseError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
catch (args::ValidationError e)
{
std::cerr << e.what() << std::endl;
- std::cerr << parser.Help();
+ std::cerr << parser;
return 1;
}
std::cout << "bs = " << bs.value << std::endl;
@@ -583,3 +587,89 @@ skip = 87
if = /tmp/test.txt
%
```
+
+## Group nesting help menu text
+
+```cpp
+#include <iostream>
+#include <args.hxx>
+int main(int argc, char **argv)
+{
+ args::ArgumentParser parser("This is a test program.", "This goes after the options.");
+ args::Group xorgroup(parser, "this group provides xor validation:", args::Group::Validators::Xor);
+ args::Flag a(xorgroup, "a", "test flag", args::Matcher({'a'}));
+ args::Flag b(xorgroup, "b", "test flag", args::Matcher({'b'}));
+ args::Flag c(xorgroup, "c", "test flag", args::Matcher({'c'}));
+ args::Group nxor(xorgroup, "this group provides all-or-none (nxor) validation:", args::Group::Validators::AllOrNone);
+ args::Flag d(nxor, "d", "test flag", args::Matcher({'d'}));
+ args::Flag e(nxor, "e", "test flag", args::Matcher({'e'}));
+ args::Flag f(nxor, "f", "test flag", args::Matcher({'f'}));
+ args::Group nxor2(nxor, "this group provides all-or-none (nxor2) validation:", args::Group::Validators::AllOrNone);
+ args::Flag i(nxor2, "i", "test flag", args::Matcher({'i'}));
+ args::Flag j(nxor2, "j", "test flag", args::Matcher({'j'}));
+ args::Flag k(nxor2, "k", "test flag", args::Matcher({'k'}));
+ args::Group nxor3(nxor, "this group provides all-or-none (nxor3) validation:", args::Group::Validators::AllOrNone);
+ args::Flag l(nxor3, "l", "test flag", args::Matcher({'l'}));
+ args::Flag m(nxor3, "m", "test flag", args::Matcher({'m'}));
+ args::Flag n(nxor3, "n", "test flag", args::Matcher({'n'}));
+ args::Group atleastone(xorgroup, "this group provides at-least-one validation:", args::Group::Validators::AtLeastOne);
+ args::Flag g(atleastone, "g", "test flag", args::Matcher({'g'}));
+ args::Flag o(atleastone, "o", "test flag", args::Matcher({'o'}));
+ args::HelpFlag help(parser, "help", "Show this help menu", args::Matcher({'h'}, {"help"}));
+ try
+ {
+ parser.ParseCLI(argc, argv);
+ }
+ catch (args::Help)
+ {
+ std::cout << parser;
+ return 0;
+ }
+ catch (args::ParseError e)
+ {
+ std::cerr << e.what() << std::endl;
+ parser.Help(std::cerr);
+ return 1;
+ }
+ catch (args::ValidationError e)
+ {
+ std::cerr << e.what() << std::endl;
+ parser.Help(std::cerr);
+ return 1;
+ }
+ return 0;
+}
+```
+
+```shell
+ % /tmp/test -h
+ /tmp/test {OPTIONS}
+
+ This is a test program.
+
+ OPTIONS:
+
+ this group provides xor validation:
+ -a test flag
+ -b test flag
+ -c test flag
+ this group provides all-or-none (nxor) validation:
+ -d test flag
+ -e test flag
+ -f test flag
+ this group provides all-or-none (nxor2) validation:
+ -i test flag
+ -j test flag
+ -k test flag
+ this group provides all-or-none (nxor3) validation:
+ -l test flag
+ -m test flag
+ -n test flag
+ this group provides at-least-one validation:
+ -g test flag
+ -o test flag
+ -h, --help Show this help menu
+
+ This goes after the options.
+ %
+```