[Mockpp-commits] mockpp/mockpp/docs/en dev_embedded.docbook,1.6,1.7

[Ewald A. <ewa...@us...>]

Update of /cvsroot/mockpp/mockpp/mockpp/docs/en
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19465/mockpp/docs/en

Modified Files:
	dev_embedded.docbook 
Log Message:
forward failures without execptions

Index: dev_embedded.docbook
===================================================================
RCS file: /cvsroot/mockpp/mockpp/mockpp/docs/en/dev_embedded.docbook,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -d -r1.6 -r1.7
--- dev_embedded.docbook	8 Dec 2005 18:16:19 -0000	1.6
+++ dev_embedded.docbook	23 Dec 2005 22:03:30 -0000	1.7
@@ -71,7 +71,7 @@
 </table>
 
 When changing the options for the test executables the size was reduced down to
-45%, but using the regular STL resulted only in 13% more code.</para>
+45%, but using the regular STL resulted only in 13% larger code.</para>
 
 </sect2>
 
@@ -80,7 +80,7 @@
 
 <para>Disabling RTTI in &mockpp; has little consequences. It is only used for a
 few diagnostic messages. In the worst case you might have to search for the
-problematic class.</para>
+problematic class because the name is not displayed.</para>
 
 <para>Disabling the regular STL is also no problem as far as &mockpp; is
 affected. If you use the minimalistic built-in STL for your own code you might
@@ -102,24 +102,89 @@
 the thread upon the first malfunction. Probably this significantly slows down
 the test execution. Another possibility is to split the tests into portable and
 platform specific sections. The portable sections can be run on the development
-machine with full speed very often wherereas the complete tests are run on the
-target device only if appropriate.
+machine with high speed very often wherereas the complete tests are run on the
+target device only if appropriate.</para>
 
+<para>Without exceptions you have to provide a way to forward the messages
+about the malfunction. &mockpp; uses some macros to run the built-in tests
+with or without exceptions using the same source files. When exceptions are
+enabled theses macros contain what you probably expect:
 
 <programlisting>
 
-void forwardMalfunctionData(const T &amp;e)
-
-#define MOCKPP_THROW(x) throw (x)
-#define MOCKPP_RETHROW  throw
-#define MOCKPP_TRY  try
-#define MOCKPP_CATCH(x) (x)
+#define MOCKPP_THROW(x)  throw (x)
+#define MOCKPP_RETHROW   throw
+#define MOCKPP_TRY       try
+#define MOCKPP_CATCH(x)  (x)
 #define MOCKPP_CATCH_ALL catch(...)
 
 </programlisting>
 
+</para>
+
+<para>One way to react upon bad test results without exceptions is to call a
+method which prints
+the results to the screen and exits with an according error level. Since the
+container with the resulting data can vary you might want to use a template
+with specialisations. The following example shows how this could look like.
+The macros should occur before the inclusion of
+<filename>mockpp.h</filename>. Otherwise they are defined with empty
+content.
+
+<caution>Please note that the macro is located in source (*.cpp) files as well as
+in header files. So changing the macro between different test files or projects
+might not work
+as expected. It is inteded as immutable glue between &mockpp; and your favourite
+unittest framework.</caution>
+
+To relax this constraint there is a mutable function pointer which can be changed
+at runtime to actually process the exception data. All internal assertions use
+this approch. The default is to throw an exception but by calling
+<function>setAssertionFailedForwarder</function> appropriately it is possible
+to print a message to the screen a exit the application.
+
+<programlisting>
+
+#define MOCKPP_THROW(x)  printMalfunctionData(x)
+#define MOCKPP_RETHROW   printMalfunctionData("unexpected rethrow")
+
+...
+
+template &lt;class T>
+inline
+void printMalfunctionData(const T &amp; /* dummy fallback */)
+{
+  std::cout &lt;&lt; "unknown exception occured" &lt;&lt; std::endl;
+  exit(1);
+}
+
+template &lt;>
+inline
+void printMalfunctionData(const mockpp::AssertionFailedError &amp;e)
+{
+  std::cout &lt;&lt; e.getMessage() &lt;&lt; std::endl;
+  exit(1);
+}
+
+template &lt;>
+inline
+void printMalfunctionData(const std::exception &amp;e)
+{
+  std::cout &lt;&lt; e.what() &lt;&lt; std::endl;
+  exit(1);
+}
+
+...
+
+  setAssertionFailedForwarder(printMalfunctionData&lt;mockpp::AssertionFailedError>);
+
+</programlisting>
 
 </para>
 
+<para>The test file <filename>tests/NoException_test.cpp</filename> shows a
+working solution.</para>
+
 </sect2>
+
 </sect1>