make examples easier to understand

Author: Fytch

README.md

@@ -96,13 +96,12 @@ The following snippet is the complete source code of a simple program expecting
 
 int main(int argc, char** argv) {
     po::parser parser;
-    parser["optimization"]    // corresponds to --optimization
-        .abbreviation('O')    // corresponds to -O
-        .type(po::u32);       // expects an unsigned 32-bit integer
+    auto& O = parser["optimization"]  // corresponds to --optimization
+        .abbreviation('O')            // corresponds to -O
+        .type(po::u32);               // expects an unsigned 32-bit integer
 
-    parser(argc, argv);       // parses the command line arguments
+    parser(argc, argv);               // parses the command line arguments
 
-    auto&& O = parser["optimization"];
     if(!O.available())
         std::cout << "no optimization level set!\n";
     else
@@ -134,26 +133,25 @@ By calling the method `.multi()` we're telling the library to store *all* values
 
 int main(int argc, char** argv) {
     po::parser parser;
-    parser["optimization"]
-        .abbreviation('O')
-        .type(po::u32)
-        .fallback(0);         // if --optimization is not explicitly specified, assume 0
+    auto& O = parser["optimization"]  // corresponds to --optimization
+        .abbreviation('O')            // corresponds to -O
+        .type(po::u32)                // expects an unsigned 32-bit integer
+        .fallback(0);                 // if --optimization is not explicitly specified, assume 0
 
-    parser["include-path"]    // corresponds to --include-path
-        .abbreviation('I')    // corresponds to -I
-        .type(po::string)     // expects a string
-        .multi();             // allows multiple arguments for the same option
+    auto& I = parser["include-path"]  // corresponds to --include-path
+        .abbreviation('I')            // corresponds to -I
+        .type(po::string)             // expects a string
+        .multi();                     // allows multiple arguments for the same option
 
-    parser(argc, argv);
+    parser(argc, argv);               // parses the command line arguments
 
-    auto&& O = parser["optimization"];
     // .was_set() reports whether the option was specified by the user or relied on the predefined fallback value.
     std::cout << "optimization level (" << (O.was_set() ? "manual" : "auto") << ") = " << O.get().u32 << '\n';
 
-    auto&& I = parser["include-path"];
-    // .size() and .count() return the number of arguments given. Without .multi(), their return value would always be <= 1.
+    // .size() and .count() return the number of given arguments. Without .multi(), their return value is always <= 1.
     std::cout << "include paths (" << I.size() << "):\n";
-    // Here, the non-template .begin() / .end() methods are being used. Their value type is po::value,
+
+    // Here, the non-template .begin() / .end() methods were used. Their value type is po::value,
     // which is not a value in itself but contains the desired values as members, i.e. i.string.
     for(auto&& i : I)
         std::cout << '\t' << i.string << '\n';
@@ -182,25 +180,27 @@ Note that, in order to pass arguments starting with a hyphen to the unnamed para
 
 int main(int argc, char** argv) {
     po::parser parser;
-    parser["optimization"]
+    auto& O = parser["optimization"]
         .abbreviation('O')
         .description("set the optimization level (default: -O0)")
         .type(po::u32)
         .fallback(0);
 
-    parser["include-path"]
+    auto& I = parser["include-path"]
         .abbreviation('I')
         .description("add an include path")
         .type(po::string)
         .multi();
 
-    parser["help"]            // corresponds to --help
-        .abbreviation('?')    // corresponds to -?
+    auto& help = parser["help"]
+        .abbreviation('?')
         .description("print this help screen")
+        // .type(po::void_)   // redundant; default for named parameters
+        // .single()          // redundant; default for named parameters
         .callback([&]{ std::cout << parser << '\n'; });
                               // callbacks get invoked when the option occurs
 
-    parser[""]                // the unnamed parameter is used for non-option arguments, i.e. gcc a.c b.c
+    auto& files = parser[""]  // the unnamed parameter is used for non-option arguments as in: gcc a.c b.c
         // .type(po::string)  // redundant; default for the unnamed parameter
         // .multi()           // redundant; default for the unnamed parameter
         .callback([&](std::string const& x){ std::cout << "processed \'" << x << "\' successfully!\n"; });
@@ -212,29 +212,33 @@ int main(int argc, char** argv) {
         return -1;
     }
     // we don't want to print anything else if the help screen has been displayed
-    if(parser["help"].size())
+    if(help.was_set())
         return 0;
 
-    std::cout << "processed files: " << parser[""].size() << '\n';
+    std::cout << "processed files: " << files.size() << '\n';
 
-    auto&& O = parser["optimization"];
+    // .was_set() reports whether the option was specified by the user or relied on the predefined fallback value.
     std::cout << "optimization level (" << (O.was_set() ? "manual" : "auto") << ") = " << O.get().u32 << '\n';
 
-    auto&& I = parser["include-path"];
+    // .size() and .count() return the number of given arguments. Without .multi(), their return value is always <= 1.
     std::cout << "include paths (" << I.size() << "):\n";
+
+    // Here, the non-template .begin() / .end() methods were used. Their value type is
+    // po::value, which is not a value in itself but contains the desired values as members, i.e. i.string.
     for(auto&& i : I)
         std::cout << '\t' << i.string << '\n';
 }
+
 ```
 How the help screen appears:
 ```
 $ ./files --help
 Usage:
   files.exe [arguments...] [options]
 Available options:
+  -O, --optimization  set the optimization level (default: -O0)
   -I, --include-path  add an include path
   -?, --help          print this help screen
-  -O, --optimization  set the optimization level (default: -O0)
 ```
 In action:
 ```
@@ -281,10 +285,10 @@ In this example, we will employ already known mechanics but lay the focus on the
 int main(int argc, char** argv) {
     po::parser parser;
 
-    auto&& x = parser[""]
-        .type(po::f64)            // expects 64-bit floating point numbers
-        .multi()                  // allows multiple arguments
-        .fallback(-8, "+.5e2")    // if no arguments were provided, assume these as default
+    auto& x = parser[""]        // the unnamed parameter
+        .type(po::f64)          // expects 64-bit floating point numbers
+        .multi()                // allows multiple arguments
+        .fallback(-8, "+.5e2")  // if no arguments were provided, assume these as default
         .callback([&]{ std::cout << "successfully parsed "; })
         .callback([&](std::string const& x){ std::cout << x; })
         .callback([&]{ std::cout << " which equals "; })
@@ -351,7 +355,7 @@ int main(int argc, char** argv) {
         .description("add an include path")
         .bind(include_paths);       // append paths to the vector 'include_paths'
 
-    parser["help"]
+    auto& help = parser["help"]
         .abbreviation('?')
         .description("print this help screen");
 
@@ -363,7 +367,7 @@ int main(int argc, char** argv) {
         return -1;
 
     // we don't want to print anything else if the help screen has been displayed
-    if(parser["help"].was_set()) {
+    if(help.was_set()) {
         std::cout << parser << '\n';
         return 0;
     }

examples/1 optimization.cxx

@@ -3,13 +3,12 @@
 
 int main(int argc, char** argv) {
 	po::parser parser;
-	parser["optimization"]	// corresponds to --optimization
-		.abbreviation('O')	// corresponds to -O
-		.type(po::u32);		// expects an unsigned 32-bit integer
+	auto& O = parser["optimization"]	// corresponds to --optimization
+		.abbreviation('O')				// corresponds to -O
+		.type(po::u32);					// expects an unsigned 32-bit integer
 
-	parser(argc, argv);		// parses the command line arguments
+	parser(argc, argv);					// parses the command line arguments
 
-	auto&& O = parser["optimization"];
 	if(!O.available())
 		std::cout << "no optimization level set!\n";
 	else

examples/2 include.cxx

@@ -3,25 +3,24 @@
 
 int main(int argc, char** argv) {
 	po::parser parser;
-	parser["optimization"]	// corresponds to --optimization
-		.abbreviation('O')	// corresponds to -O
-		.type(po::u32)		// expects an unsigned 32-bit integer
-		.fallback(0);		// if --optimization is not explicitly specified, assume 0
+	auto& O = parser["optimization"]	// corresponds to --optimization
+		.abbreviation('O')				// corresponds to -O
+		.type(po::u32)					// expects an unsigned 32-bit integer
+		.fallback(0);					// if --optimization is not explicitly specified, assume 0
 
-	parser["include-path"]	// corresponds to --include-path
-		.abbreviation('I')	// corresponds to -I
-		.type(po::string)	// expects a string
-		.multi();			// allows multiple arguments for the same option
+	auto& I = parser["include-path"]	// corresponds to --include-path
+		.abbreviation('I')				// corresponds to -I
+		.type(po::string)				// expects a string
+		.multi();						// allows multiple arguments for the same option
 
-	parser(argc, argv);		// parses the command line arguments
+	parser(argc, argv);					// parses the command line arguments
 
-	auto&& O = parser["optimization"];
 	// .was_set() reports whether the option was specified by the user or relied on the predefined fallback value.
 	std::cout << "optimization level (" << (O.was_set() ? "manual" : "auto") << ") = " << O.get().u32 << '\n';
 
-	auto&& I = parser["include-path"];
 	// .size() and .count() return the number of given arguments. Without .multi(), their return value is always <= 1.
 	std::cout << "include paths (" << I.size() << "):\n";
+
 	// Here, the non-template .begin() / .end() methods were used. Their value type is po::value,
 	// which is not a value in itself but contains the desired values as members, i.e. i.string.
 	for(auto&& i : I)

examples/3 files.cxx

@@ -3,51 +3,52 @@
 
 int main(int argc, char** argv) {
 	po::parser parser;
-	parser["optimization"]		// corresponds to --optimization
-		.abbreviation('O')		// corresponds to -O
+	auto& O = parser["optimization"]	// corresponds to --optimization
+		.abbreviation('O')				// corresponds to -O
 		.description("set the optimization level (default: -O0)")
-								// the description to be shown when printing the parser
-		.type(po::u32)			// expects an unsigned 32-bit integer
-		.fallback(0);			// if --optimization is not explicitly specified, assume 0
+										// the description to be shown when printing the parser
+		.type(po::u32)					// expects an unsigned 32-bit integer
+		.fallback(0);					// if --optimization is not explicitly specified, assume 0
 
-	parser["include-path"]		// corresponds to --include-path
-		.abbreviation('I')		// corresponds to -I
+	auto& I = parser["include-path"]	// corresponds to --include-path
+		.abbreviation('I')				// corresponds to -I
 		.description("add an include path")
-		.type(po::string)		// expects a string
-		.multi();				// allows multiple arguments for the same option
+										// the description to be shown when printing the parser
+		.type(po::string)				// expects a string
+		.multi();						// allows multiple arguments for the same option
 
-	parser["help"]				// corresponds to --help
-		.abbreviation('?')		// corresponds to -?
+	auto& help = parser["help"]			// corresponds to --help
+		.abbreviation('?')				// corresponds to -?
 		.description("print this help screen")
-		// .type(po::void_)		// redundant; default for named parameters
-		// .single()			// redundant; default for named parameters
+										// the description to be shown when printing the parser
+		// .type(po::void_)				// redundant; default for named parameters
+		// .single()					// redundant; default for named parameters
 		.callback([&]{ std::cout << parser << '\n'; });
-								// callbacks get invoked when the option occurs
+										// callbacks get invoked when the option occurs
 
-	parser[""]					// the unnamed parameter is used for non-option arguments, i.e. gcc a.c b.c
-		// .type(po::string)	// redundant; default for the unnamed parameter
-		// .multi()				// redundant; default for the unnamed parameter
+	auto& files = parser[""]			// the unnamed parameter is used for non-option arguments as in: gcc a.c b.c
+		// .type(po::string)			// redundant; default for the unnamed parameter
+		// .multi()						// redundant; default for the unnamed parameter
 		.callback([&](std::string const& x){ std::cout << "processed \'" << x << "\' successfully!\n"; });
-								// as .get_type() == po::string, the callback may take an std::string
+										// as .get_type() == po::string, the callback may take an std::string
 
 	// parsing returns false if at least one error has occurred
 	if(!parser(argc, argv)) {
 		std::cerr << "errors occurred; aborting\n";
 		return -1;
 	}
 	// we don't want to print anything else if the help screen has been displayed
-	if(parser["help"].size())
+	if(help.was_set())
 		return 0;
 
-	std::cout << "processed files: " << parser[""].size() << '\n';
+	std::cout << "processed files: " << files.size() << '\n';
 
-	auto&& O = parser["optimization"];
 	// .was_set() reports whether the option was specified by the user or relied on the predefined fallback value.
 	std::cout << "optimization level (" << (O.was_set() ? "manual" : "auto") << ") = " << O.get().u32 << '\n';
 
-	auto&& I = parser["include-path"];
 	// .size() and .count() return the number of given arguments. Without .multi(), their return value is always <= 1.
 	std::cout << "include paths (" << I.size() << "):\n";
+
 	// Here, the non-template .begin() / .end() methods were used. Their value type is
 	// po::value, which is not a value in itself but contains the desired values as members, i.e. i.string.
 	for(auto&& i : I)

examples/4 sum.cxx

@@ -5,7 +5,7 @@
 int main(int argc, char** argv) {
 	po::parser parser;
 
-	auto&& x = parser[""]		// the unnamed parameter
+	auto& x = parser[""]		// the unnamed parameter
 		.type(po::f64)			// expects 64-bit floating point numbers
 		.multi()				// allows multiple arguments
 		.fallback(-8, "+.5e2")	// if no arguments were provided, assume these as default

examples/5 bind.cxx

@@ -21,7 +21,7 @@ int main(int argc, char** argv) {
 		.description("add an include path")
 		.bind(include_paths);		// append paths to the vector 'include_paths'
 
-	parser["help"]					// corresponds to --help
+	auto& help = parser["help"]		// corresponds to --help
 		.abbreviation('?')			// corresponds to -?
 		.description("print this help screen");
 
@@ -34,7 +34,7 @@ int main(int argc, char** argv) {
 		return -1;
 
 	// we don't want to print anything else if the help screen has been displayed
-	if(parser["help"].was_set()) {
+	if(help.was_set()) {
 		std::cout << parser << '\n';
 		return 0;
 	}

examples/detect_type.cxx

@@ -3,7 +3,7 @@
 
 int main(int argc, char** argv) {
 	po::parser parser;
-	auto&& o = parser[""];
+	auto& o = parser[""];
 	parser(argc, argv);
 
 	po::value_type testing_order[] = { po::void_, po::u32, po::u64, po::i32, po::i64, po::f32, po::f64, po::string };

examples/flag.cxx

@@ -3,7 +3,7 @@
 
 int main(int argc, char** argv) {
 	po::parser parser;
-	auto&& x = parser["x"];	// creates an option with name 'x'
+	auto& x = parser["x"];	// creates an option with name 'x'
 
 	parser(argc, argv);		// parses the command line arguments
 

examples/getopt.cxx

@@ -7,12 +7,12 @@
 int main(int argc, char** argv) {
 	po::parser parser;
 
-	auto&& a = parser["a"];
-	auto&& b = parser["b"];
-	auto&& c = parser["c"]
+	auto& a = parser["a"];
+	auto& b = parser["b"];
+	auto& c = parser["c"]
 		.type(po::string)
 		.fallback("(null)");
-	auto&& unnamed = parser[""]
+	auto& unnamed = parser[""]
 		.type(po::string)
 		.multi();