From 0c82658184e90aecea1a5106352e8a4fc60532d9 Mon Sep 17 00:00:00 2001
From: philsquared <github@philnash.me>
Date: Wed, 28 Mar 2012 11:35:05 -0700
Subject: [PATCH] First draft

---
 Logging-Macros.md | 49 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 49 insertions(+)
 create mode 100644 Logging-Macros.md

diff --git a/Logging-Macros.md b/Logging-Macros.md
new file mode 100644
index 0000000..5c4c9ca
--- /dev/null
+++ b/Logging-Macros.md
@@ -0,0 +1,49 @@
+
+# Logging macros
+
+Messages can be logged during a test case.
+
+## Streaming macros
+
+All these macros allow heterogenous sequences of values to be streaming using the insertion operator (<<) in the same way that std::ostream, std::cout, etc support it.
+
+E.g.
+```c++
+INFO( "The number is " << i );
+```
+
+Note that the initial << is skipped - instead the insertion sequence is placed in parentheses.
+These macros come in three forms:
+
+**INFO(** _message expression_ **)**
+
+The message is logged to a buffer, but only reported if a subsequent failure occurs within the same test case. This allows you to log contextual information in case of failures which is not shown during a successful test run.
+
+**WARN(** _message expression_ **)**
+
+The message is always reported.
+
+**FAIL(** _message expression_ **)**
+
+The message is reported and the test case fails.
+
+**SCOPED_INFO(** _message expression_ **)**
+
+As INFO, but is only in effect during the current scope. If a failure occurs beyond the end of the scope the message is not logged.
+
+## Quickly capture a variable value
+
+**CAPTURE(** _expression_ **)**
+
+Sometimes you just want to log the name and value of a variable. While you can easily do this with the INFO macro, above, as a convenience the CAPTURE macro handles the stringising of the variable name for you (actually it works with any expression, not just variables).
+
+E.g.
+```c++
+CAPTURE( theAnswer );
+```
+
+This would log something like:
+
+<pre>
+info: "theAnswer := 42"
+</pre>