change precondition violation exceptions from opt-out to opt-in and make assertions the default

Author: Fytch

.travis.yml

@@ -205,12 +205,6 @@ script:
   - $CC --version
   - $CXX --version
 
-  - mkdir bin_noexcept
-  - cd bin_noexcept
-  - cmake .. $CMAKE_FLAGS -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_C_COMPILER=$CC -DCMAKE_CXX_COMPILER=$CXX -DPROGRAMOPTIONS_BUILD_TEST=OFF -DPROGRAMOPTIONS_NO_EXCEPTIONS=ON
-  - cmake --build .
-  - cd ..
-
   - mkdir bin
   - cd bin
   - cmake .. $CMAKE_FLAGS -DCMAKE_BUILD_TYPE=DEBUG -DCMAKE_C_COMPILER=$CC -DCMAKE_CXX_COMPILER=$CXX

CMakeLists.txt

@@ -13,7 +13,6 @@ add_library(ProgramOptionsHxx INTERFACE)
 target_include_directories(ProgramOptionsHxx INTERFACE "${CMAKE_CURRENT_LIST_DIR}/include")
 
 if(PROGRAMOPTIONS_NOT_SUBPROJECT)
-	option(PROGRAMOPTIONS_NO_EXCEPTIONS "disable exceptions" OFF)
 	option(PROGRAMOPTIONS_NO_COLORS "disable colored output" OFF)
 	option(PROGRAMOPTIONS_BUILD_TEST "build test" ON)
 	option(PROGRAMOPTIONS_BUILD_EXAMPLES "build examples" ON)
@@ -32,15 +31,6 @@ if(PROGRAMOPTIONS_NOT_SUBPROJECT)
 		set(CMAKE_CXX_FLAGS_RELEASE "${CMAKE_CXX_FLAGS_RELEASE} -O3 -march=native -DNDEBUG -s -flto")
 	endif()
 
-	if(PROGRAMOPTIONS_NO_EXCEPTIONS)
-		add_definitions(-DPROGRAMOPTIONS_NO_EXCEPTIONS)
-		if(PROGRAMOPTIONS_GNU_OPTIONS)
-			set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fno-exceptions")
-		elseif(PROGRAMOPTIONS_MS_OPTIONS)
-			set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} /EHsc")
-		endif()
-	endif()
-
 	if(PROGRAMOPTIONS_NO_COLORS)
 		add_definitions(-DPROGRAMOPTIONS_NO_COLORS)
 	endif()

README.md

@@ -28,13 +28,13 @@ It is highly recommended that you at least briefly skim through the chapters [**
 The quickest way to get started is to download *ProgramOptions.hxx* as well as one of the samples and go from there.
 
 ### `sample.cxx`
-The default choice. Using *ProgramOptions.hxx* incorrectly or failing to meet a function's preconditions will throw an exception which will, by default, terminate the program and display a useful message, explaining where exactly things went wrong.
+The default choice. Incorrect usage of *ProgramOptions.hxx*'s API will trigger an assertion which will crash the program in debug mode.
 
-### `sample_noexcept.cxx`
-Using this sample is only recommended if you are already somewhat familiar with *ProgramOptions.hxx*. Incorrect programs will crash without any messages unless your STL implementation does so when [`assert`ions](http://en.cppreference.com/w/cpp/error/assert) fail.
+### `sample_exceptions.cxx`
+In this sample, we [`#define PROGRAMOPTIONS_EXCEPTIONS`](#define-programoptions_exceptions). In consequence, incorrect usage of *ProgramOptions.hxx*'s API will throw an exception both in debug and release mode.
 
 ## Design goals
-- **Non-intrusive**. Unlike other program option libraries, such as [*Boost.Program_options*](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html), *ProgramOptions.hxx* requires neither additional library binaries nor integration into the build process. Just drop in the header, include it and you're all set. *ProgramOptions.hxx* doesn't force you to enable exceptions or RTTI and runs just fine with `-fno-rtti -fno-exceptions` (the latter requires you to [`#define PROGRAMOPTIONS_NO_EXCEPTIONS`](#define-programoptions_no_exceptions) prior to including the header, though).
+- **Non-intrusive**. Unlike other program option libraries, such as [*Boost.Program_options*](http://www.boost.org/doc/libs/1_63_0/doc/html/program_options.html), *ProgramOptions.hxx* requires neither additional library binaries nor integration into the build process. Just drop in the header, include it and you're all set. *ProgramOptions.hxx* doesn't force you to enable exceptions or RTTI and runs just fine with `-fno-rtti -fno-exceptions`.
 - **Intuitive**. *ProgramOptions.hxx* is designed to feel smooth and blend in well with other modern C++11 code.
 - **Correct**. Extensive unit tests and runtime checks contribute to more correct software, both on the side of the user and the developer of *ProgramOptions.hxx*.
 - **Permissive**. The [MIT License](https://tldrlegal.com/license/mit-license) under which *ProgramOptions.hxx* is published grants unrestricted freedom.
@@ -85,6 +85,11 @@ target_link_libraries(YourExecutable ProgramOptionsHxx)
 ```
 You must replace ```/third_party/ProgramOptions.hxx``` by the correct path and ```YourExecutable``` by the targets that use *ProgramOptions.hxx*.
 
+You can then include the header by writing:
+```cpp
+#include <ProgramOptions.hxx>
+```
+
 ## Usage
 Using *ProgramOptions.hxx* is straightforward; we'll explain it by means of practical examples. All examples shown here and more can be found in the [/examples](examples) directory, all of which are well-documented.
 
@@ -399,22 +404,22 @@ This small table helps clarifying the defaults for the different kinds of option
 |`.single` / `.multi` |`.single`            |`.single`            |`.multi`             |
 
 ## Flags
-All flags have to be `#define`d before including *ProgramOptions.hxx*. Different translation units may include *ProgramOptions.hxx* using different flags.
+All flags have to be `#define`d before including *ProgramOptions.hxx*.
 
-### `#define PROGRAMOPTIONS_NO_EXCEPTIONS`
-Disables all exceptions and thus allows compilation with `-fno-exceptions`. However, incorrect use of the library and unmet preconditions entail `abort()` via `assert(...)`. This flag is implied by `NDEBUG`.
+### `#define PROGRAMOPTIONS_EXCEPTIONS`
+When this flag is set, *ProgramOptions.hxx*'s functions' preconditions are validated with exceptions instead of assertions. If a precondition isn't met, an [```std::logic_error```](https://en.cppreference.com/w/cpp/error/logic_error) is thrown whose explanatory strings starts with "ProgramOptions.hxx:*N*:" where *N* is the respective line number.
 
-:exclamation: This flag must not vary across different translation units in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
+:exclamation: This flag must not vary across different translation units of a single program in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
 
 ### `#define NDEBUG`
-Disables all runtime checks and all exceptions. Incorrect use of the library and unmet preconditions will lead to undefined behaviour. Implies `#define PROGRAMOPTIONS_NO_EXCEPTIONS`.
+Setting this flag disables all assertions.
 
-:exclamation: This flag must not vary across different translation units in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
+:exclamation: This flag must not vary across different translation units of a single program in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
 
 ### `#define PROGRAMOPTIONS_NO_COLORS`
-Disables colored output. On Windows, *ProgramOptions.hxx* uses the WinAPI (i.e. [`SetConsoleTextAttribute`](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686047)) to achieve colored console output whereas it uses [ANSI escape codes](http://bluesock.org/~willg/dev/ansi.html) anywhere else.
+Setting this flag disables colored output. On Windows, *ProgramOptions.hxx* uses the WinAPI (i.e. [`SetConsoleTextAttribute`](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686047)) to achieve colored console output whereas it uses [ANSI escape codes](http://bluesock.org/~willg/dev/ansi.html) anywhere else.
 
-:exclamation: This flag must not vary across different translation units in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
+:exclamation: This flag must not vary across different translation units of a single program in order to not violate C++' [one definition rule (ODR)](http://en.cppreference.com/w/cpp/language/definition).
 
 ## Third-party libraries
 - [**Catch**](https://github.com/philsquared/Catch) for unit testing.

include/ProgramOptions.hxx

@@ -31,28 +31,25 @@
 #include <sstream>
 #include <iostream>
 
-#ifndef PROGRAMOPTIONS_NO_EXCEPTIONS
-	#include <stdexcept>
-#endif // !PROGRAMOPTIONS_NO_EXCEPTIONS
-
 #ifndef NDEBUG
 	#define PROGRAMOPTIONS_DEBUG
 #endif // !NDEBUG
 
 #undef PROGRAMOPTIONS_ASSERT
-#ifdef NDEBUG
-	#define PROGRAMOPTIONS_ASSERT(Expression, Message)
-#else // NDEBUG
-	#ifdef PROGRAMOPTIONS_NO_EXCEPTIONS
-		#define PROGRAMOPTIONS_ASSERT(Expression, Message) assert((Expression) && Message);
-	#else // PROGRAMOPTIONS_NO_EXCEPTIONS
-		#define PROGRAMOPTIONS_ASSERT(Expression, Message)\
-			do {\
-				if(!(Expression))\
-					throw std::logic_error{ ("ProgramOptions.hxx:" + std::to_string(__LINE__) + ": ") + (Message) };\
-			} while(0)
-	#endif // PROGRAMOPTIONS_NO_EXCEPTIONS
-#endif // NDEBUG
+#ifdef PROGRAMOPTIONS_EXCEPTIONS
+	#include <stdexcept>
+	#define PROGRAMOPTIONS_ASSERT(Expression, Message)\
+		do {\
+			if(!(Expression))\
+				throw std::logic_error{ ("ProgramOptions.hxx:" + std::to_string(__LINE__) + ": ") + (Message) };\
+		} while(0)
+#else // PROGRAMOPTIONS_EXCEPTIONS
+	#ifdef PROGRAMOPTIONS_DEBUG
+		#define PROGRAMOPTIONS_ASSERT(Expression, Message) assert(Message && (Expression));
+	#else // PROGRAMOPTIONS_DEBUG
+		#define PROGRAMOPTIONS_ASSERT(Expression, Message)
+	#endif // PROGRAMOPTIONS_DEBUG
+#endif // PROGRAMOPTIONS_EXCEPTIONS
 
 #if defined(PROGRAMOPTIONS_WINDOWS) && defined(PROGRAMOPTIONS_ANSI)
 	#error Please define either PROGRAMOPTIONS_WINDOWS or PROGRAMOPTIONS_ANSI

sample.cxx

@@ -1,33 +1,32 @@
 #include <ProgramOptions.hxx>
-#include <exception>
 #include <iostream>
 
-int main(int argc, char** argv)
-try {
+int main(int argc, char** argv) {
 	po::parser parser;
-	parser["help"]
-		.abbreviation('?')
-		.description("print this help screen")
-		.callback([&]{ std::cout << parser << '\n'; });
 
-	parser["PLACEHOLDER"]
+	auto& PLACEHOLDER = parser["PLACEHOLDER"]
 		.abbreviation('PLACEHOLDER')
 		.description("PLACEHOLDER")
 		.type(po::PLACEHOLDER)
 		.multi()
 		.fallback(PLACEHOLDER)
 		.callback([&]{ PLACEHOLDER; });
 
+	auto& help = parser["help"]
+		.abbreviation('?')
+		.description("print this help screen");
+
 	if(!parser(argc, argv)) {
 		// error
 		return 1;
 	}
 
-	if(parser["PLACEHOLDER"].available()) {
+	if(help.was_set()) {
+		std::cout << parser << '\n';
+		return 0;
+	}
+
+	if(PLACEHOLDER.available()) {
 		// do something
 	}
-} catch(std::exception const& e) {
-	std::cerr << "uncaught exception: " << e.what() << '\n';
-	std::cerr << "terminating application\n";
-	return -1;
 }

sample_exceptions.cxx

@@ -0,0 +1,39 @@
+#define PROGRAMOPTIONS_EXCEPTIONS
+#include <ProgramOptions.hxx>
+#include <exception>
+#include <iostream>
+
+int main(int argc, char** argv)
+try {
+	po::parser parser;
+
+	auto& PLACEHOLDER = parser["PLACEHOLDER"]
+		.abbreviation('PLACEHOLDER')
+		.description("PLACEHOLDER")
+		.type(po::PLACEHOLDER)
+		.multi()
+		.fallback(PLACEHOLDER)
+		.callback([&]{ PLACEHOLDER; });
+
+	auto& help = parser["help"]
+		.abbreviation('?')
+		.description("print this help screen");
+
+	if(!parser(argc, argv)) {
+		// error
+		return 1;
+	}
+
+	if(help.was_set()) {
+		std::cout << parser << '\n';
+		return 0;
+	}
+
+	if(PLACEHOLDER.available()) {
+		// do something
+	}
+} catch(std::exception const& e) {
+	std::cerr << "uncaught exception: " << e.what() << '\n';
+	std::cerr << "terminating application\n";
+	return -1;
+}

sample_noexcept.cxx

@@ -1,6 +1,7 @@
 #ifndef arg_provider_hxx_included
 #define arg_provider_hxx_included
 
+#define PROGRAMOPTIONS_EXCEPTIONS
 #include <ProgramOptions.hxx>
 #include <vector>
 #include <iterator>

test/arg_provider.hxx

@@ -1,4 +1,5 @@
 #include <catch2/catch.hpp>
+#define PROGRAMOPTIONS_EXCEPTIONS
 #include <ProgramOptions.hxx>
 #include "arg_provider.hxx"
 

test/bind.cxx

@@ -1,4 +1,5 @@
 #include <catch2/catch.hpp>
+#define PROGRAMOPTIONS_EXCEPTIONS
 #include <ProgramOptions.hxx>
 #include "arg_provider.hxx"