redsnow 0.3.1 → 0.3.2

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/contributing.md

@@ -0,0 +1,19 @@
+# Contributing to Catch
+
+So you want to contribute something to Catch? That's great! Whether it's a bug fix, a new feature, support for additional compilers - or just a fix to the documentation - all contributions are very welcome and very much appreciated. Of course so are bug reports and other comments and questions.
+
+If you are contributing to the code base there are a few simple guidelines to keep in mind. This also includes notes to help you find your way around. As this is liable to drift out of date please raise an issue or, better still, a pull request for this file, if you notice that.
+
+## Directory structure
+
+Users of Catch primarily use the single header version. Maintainers should work with the full source (which is still, primarily, in headers). This can be found in the ```include``` folder, but you may prefer to use one of the IDE project files (for MSVC or XCode). These can be found under ```projects/```*IDE Name*```/```*project name*. A number of contributors have proposed make files, and submitted their own versions. At some point these should be made available too.
+
+In addition to the include files and IDE projects there are a number of tests in cpp files. These can all be found in ```projects/SelfTest```. You'll also see a ```SurrogateCpps``` directory in there. This contains a set of cpp files that each ```#include``` a single header. While these files are not essential to compilation they help to keep the implementation headers self-contained. At time of writing this set is not complete but has reasonable coverage. If you add additional headers please try to remember to add a surrogate cpp for it.
+
+The other directories are ```scripts``` which contains a set of python scripts to help in testing Catch as well as generating the single include, and docs, which contains the documentation as a set of markdown files.
+
+ *this document is in-progress...*
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/logging.md

@@ -0,0 +1,52 @@
+# Logging macros
+
+Additional 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 there is no initial ```<<``` - 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 with the next assertion that is logged. This allows you to log contextual information in case of failures which is not shown during a successful test run (for the console reporter, without -s). Messages are removed from the buffer at the end of their scope, so may be used, for example, in loops.
+
+**WARN(** _message expression_ **)**
+
+The message is always reported but does not fail the test.
+
+**FAIL(** _message expression_ **)**
+
+The message is reported and the test case fails.
+
+## 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>"theAnswer := 42"</pre>
+
+## Deprecated macros
+
+**SCOPED_INFO and SCOPED_CAPTURE**
+
+These macros are now deprecated and are just aliases for INFO and CAPTURE (which were not previously scoped).
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/own-main.md

@@ -0,0 +1,68 @@
+# Supplying main() yourself
+
+The easiest way to use Catch is to let it supply ```main()``` for you and handle configuring itself from the command line.
+
+This is achieved by writing ```#define CATCH_CONFIG_MAIN``` before the ```#include "catch.hpp"``` in *exactly one* source file.
+
+Sometimes, though, you need to write your own version of main(). You can do this by writing ```#define CATCH_CONFIG_RUNNER``` instead. Now you are free to write ```main()``` as normal and call into Catch yourself manually.
+
+You now have a lot of flexibility - but here are three recipes to get your started:
+
+## Let Catch take full control of args and config
+
+If you just need to have code that executes before and/ or after Catch this is the simplest option.
+
+```c++
+#define CATCH_CONFIG_RUNNER
+#include "catch.hpp"
+
+int main( int argc, char* const argv[] )
+{
+  // global setup...
+
+  int result = Catch::Session().run( argc, argv );
+
+  // global clean-up...
+
+  return result;
+}
+```
+
+## Amending the config
+
+If you still want Catch to process the command line, but you want to programatically tweak the config, you can do so in one of two ways:
+
+```c++
+#define CATCH_CONFIG_RUNNER
+#include "catch.hpp"
+
+int main( int argc, char* const argv[] )
+{
+  Catch::Session session; // There must be exactly once instance
+
+  // writing to session.configData() here sets defaults
+  // this is the preferred way to set them
+
+  int returnCode = session.applyCommandLine( argc, argv );
+  if( returnCode != 0 ) // Indicates a command line error
+  	return returnCode;
+
+  // writing to session.configData() or session.Config() here 
+  // overrides command line args
+  // only do this if you know you need to
+
+  return session.run();
+}
+```
+
+Take a look at the definitions of Config and ConfigData to see what you can do with them.
+
+To take full control of the config simply omit the call to ```applyCommandLine()```.
+
+## Adding your own command line options
+
+Catch embeds a powerful command line parser which you can also use to parse your own options out. This capability is still in active development but will be documented here when it is ready.
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/reference-index.md

@@ -0,0 +1,14 @@
+These are the currently documented areas of the framework. There is more to come.
+
+Before looking at this material be sure to read the [tutorial](tutorial.md)
+
+* [Command Line](command-line.md)
+* [Assertion Macros](assertions.md)
+* [Test cases and sections](test-cases-and-sections.md)
+* [Logging Macros](logging.md)
+* [Supplying your own main()](own-main.md)
+* [Test fixtures](test-fixtures.md)
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/test-cases-and-sections.md

@@ -0,0 +1,60 @@
+# Test cases and sections
+
+While Catch fully supports the traditional, xUnit, style of class-based fixtures containing test case methods this is not the preferred style.
+
+Instead Catch provides a powerful mechanism for nesting test case sections within a test case. For a more detailed discussion see the [tutorial](tutorial.md#testCasesAndSections).
+
+Test cases and sections are very easy to use in practice:
+
+* **TEST_CASE(** _test name_ \[, _tags_ \] **)**
+* **SECTION(** _section name_ **)**
+
+_test name_ and _section name_ are free form, quoted, strings. The optional _tags_ argument is a quoted string containing one or more tags enclosed in square brackets. Tags are discussed below. Test names must be unique within the Catch executable.
+
+For examples see the [Tutorial](tutorial.md)
+
+## Tags
+
+Tags allow an arbitrary number of additional strings to be associated with a test case. Test cases can be selected (for running, or just for listing) by tag - or even by an expression that combines several tags. At their most basic level they provide a simple way to group several related tests together.
+
+As an example - given the following test cases:
+
+	TEST_CASE( "A", "[widget]" ) { /* ... */ }
+	TEST_CASE( "B", "[widget]" ) { /* ... */ }
+	TEST_CASE( "C", "[gadget]" ) { /* ... */ }
+	TEST_CASE( "D", "[widget][gadget]" ) { /* ... */ }
+
+The tag expression, ```"[widget]"``` selects A, B & D. ```"[gadget]"``` selects C & D. ```"[widget][gadget]"``` selects just D and ```"[widget],[gadget]"``` selects all four test cases.
+
+For more detail on command line selection see [the command line docs](command-line.md#specifying-which-tests-to-run)
+
+A special tag name, ```[hide]``` causes test cases to be skipped from the default list (ie when no test cases have been explicitly selected through tag expressions or name wildcards). ```[.]``` is an alias for ```[hide]```.
+
+Tag names are not case sensitive.
+
+## BDD-style test cases
+
+In addition to Catch's take on the classic style of test cases, Catch supports an alternative syntax that allow tests to be written as "executable specifications" (one of the early goals of [Behaviour Driven Development](http://dannorth.net/introducing-bdd/)). This set of macros map on to ```TEST_CASE```s and ```SECTION```s, with a little internal support to make them smoother to work with.
+
+* **SCENARIO(** _scenario name_ \[, _tags_ \] **)**
+
+This macro maps onto ```TEST_CASE``` and works in the same way, except that the test case name will be prefixed by "Scenario: "
+
+* **GIVEN(** _something_ **)**
+* **WHEN(** _something_ **)**
+* **THEN(** _something_ **)**
+
+These macros map onto ```SECTION```s except that the section names are the _something_s prefixed by "given: ", "when: " or "then: " respectively.
+
+* **AND_WHEN(** _something_ **)**
+* **AND_THEN(** _something_ **)**
+
+Similar to ```WHEN``` and ```THEN``` except that the prefixes start with "and ". These are used to chain ```WHEN```s and ```THEN```s together.
+
+When any of these macros are used the console reporter recognises them and formats the test case header such that the Givens, Whens and Thens are aligned to aid readability.
+
+Other than the additional prefixes and the formatting in the console reporter these macros behave exactly as ```TEST_CASE```s and ```SECTION```s. As such there is nothing enforcing the correct sequencing of these macros - that's up to the programmer!
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/test-fixtures.md

@@ -0,0 +1,32 @@
+Although Catch allows you to group tests together as sections within a test case, it can still convenient, sometimes, to group them using a more traditional test fixture. Catch fully supports this too. You define the test fixture as a simple structure:
+
+```c++
+class UniqueTestsFixture {
+  private:
+   static int uniqueID;
+  protected:
+   DBConnection conn;
+  public:
+   UniqueTestsFixture() : conn(DBConnection::createConnection("myDB")) {
+   }
+  protected:
+   int getID() {
+     return ++uniqueID;
+   }
+ };
+
+ int UniqueTestsFixture::uniqueID = 0;
+
+ TEST_CASE_METHOD(UniqueTestsFixture, "Create Employee/No Name", "[create]") {
+   REQUIRE_THROWS(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), ""));
+ }
+ TEST_CASE_METHOD(UniqueTestsFixture, "Create Employee/Normal", "[create]") {
+   REQUIRE(conn.executeSQL("INSERT INTO employee (id, name) VALUES (?, ?)", getID(), "Joe Bloggs"));
+ }
+```
+
+The two test cases here will create uniquely-named derived classes of UniqueTestsFixture and thus can access the `getID()` protected method and `conn` member variables. This ensures that both the test cases are able to create a DBConnection using the same method (DRY principle) and that any ID's created are unique such that the order that tests are executed does not matter.
+
+---
+
+[Home](../README.md)

data/ext/snowcrash/ext/markdown-parser/test/ext/Catch/docs/tutorial.md

@@ -0,0 +1,228 @@
+# Getting Catch
+
+The simplest way to get Catch is to download the single header version from [http://builds.catch-lib.net](http://builds.catch-lib.net). Don't be put off by the word "builds" there. The single header is generated by merging a set of individual headers but it is still just normal source code in a header file.
+
+The full source for Catch, including test projects, documentation, and other things, is hosted on GitHub. [http://catch-lib.net](http://catch-lib.net) will redirect you there.
+
+
+## Where to put it?
+
+Catch is header only. All you need to do is drop the file(s) somewhere reachable from your project - either in some central location you can set your header search path to find, or directly into your project tree itself! This is a particularly good option for other Open-Source projects that want to use Catch for their test suite. See [this blog entry for more on that](http://www.levelofindirection.com/journal/2011/5/27/unit-testing-in-c-and-objective-c-just-got-ridiculously-easi-1.html). 
+
+The rest of this tutorial will assume that the Catch single-include header (or the include folder) is available unqualified - but you may need to prefix it with a folder name if necessary.
+
+# Writing tests
+
+Let's start with a really simple example. Say you have written a function to calculate factorials and now you want to test it (let's leave aside TDD for now). 
+
+```c++
+unsigned int Factorial( unsigned int number ) {
+    return number <= 1 ? number : Factorial(number-1)*number;
+}
+```
+
+To keep things simple we'll put everything in a single file.
+
+```c++
+#define CATCH_CONFIG_MAIN  // This tells Catch to provide a main() - only do this in one cpp file
+#include "catch.hpp"
+
+unsigned int Factorial( unsigned int number ) {
+    return number <= 1 ? number : Factorial(number-1)*number;
+}
+
+TEST_CASE( "Factorials are computed", "[factorial]" ) {
+    REQUIRE( Factorial(1) == 1 );
+    REQUIRE( Factorial(2) == 2 );
+    REQUIRE( Factorial(3) == 6 );
+    REQUIRE( Factorial(10) == 3628800 );
+}
+```
+
+This will compile to a complete executable which responds to [command line arguments](command-line.md). If you just run it with no arguments it will execute all test cases (in this case there is just one), report any failures, report a summary of how many tests passed and failed and return the number of failed tests (useful for if you just want a yes/ no answer to: "did it work").
+
+If you run this as written it will pass. Everything is good. Right?
+Well, there is still a bug here. In fact the first version of this tutorial I posted here genuinely had the bug in! So it's not completely contrived (thanks to Daryle Walker (```@CTMacUser```) for pointing this out).
+
+What is the bug? Well what is the factorial of zero?
+[The factorial of zero is one](http://mathforum.org/library/drmath/view/57128.html) - which is just one of those things you have to know (and remember!).
+
+Let's add that to the test case:
+
+```c++
+TEST_CASE( "Factorials are computed", "[factorial]" ) {
+    REQUIRE( Factorial(0) == 1 );
+    REQUIRE( Factorial(1) == 1 );
+    REQUIRE( Factorial(2) == 2 );
+    REQUIRE( Factorial(3) == 6 );
+    REQUIRE( Factorial(10) == 3628800 );
+}
+```
+
+Now we get a failure - something like:
+
+```
+Example.cpp:9: FAILED:
+  REQUIRE( Factorial(0) == 1 )
+with expansion:
+  0 == 1
+```
+
+Note that we get the actual return value of Factorial(0) printed for us (0) - even though we used a natural expression with the == operator. That let's us immediately see what the problem is.
+
+Let's change the factorial function to:
+
+```c++
+unsigned int Factorial( unsigned int number ) {
+  return number > 1 ? Factorial(number-1)*number : 1;
+}
+```
+
+Now all the tests pass.
+
+Of course there are still more issues to do deal with. For example we'll hit problems when the return value starts to exceed the range of an unsigned int. With factorials that can happen quite quickly. You might want to add tests for such cases and decide how to handle them. We'll stop short of doing that here.
+
+## What did we do here?
+
+Although this was a simple test it's been enough to demonstrate a few things about how Catch is used. Let's take moment to consider those before we move on.
+
+1. All we did was ```#define``` one identifier and ```#include``` one header and we got everything - even an implementation of ```main()``` that will [respond to command line arguments](command-line.md). You can only use that ```#define``` in one implementation file, for (hopefully) obvious reasons. Once you have more than one file with unit tests in you'll just ```#include "catch.hpp"``` and go. Usually it's a good idea to have a dedicated implementation file that just has ```#define CATCH_CONFIG_MAIN``` and ```#include "catch.hpp"```. You can also provide your own implementation of main and drive Catch yourself (see [Supplying-your-own-main()](own-main.md).
+2. We introduce test cases with the TEST_CASE macro. This macro takes one or two arguments - a free form test name and, optionally, one or more tags (for more see <a href="#test-cases-and-sections">Test cases and Sections</a>, below. The test name must be unique. You can run sets of tests by specifying a wildcarded test name or a tag expression. See the [command line docs](command-line.md) for more information on running tests.
+3. The name and tags arguments are just strings. We haven't had to declare a function or method - or explicitly register the test case anywhere. Behind the scenes a function with a generated name is defined for you, and automatically registered using static registry classes. By abstracting the function name away we can name our tests without the constraints of identifier names.
+4. We write our individual test assertions using the REQUIRE macro. Rather than a separate macro for each type of condition we express the condition naturally using C/C++ syntax. Behind the scenes a simple set of expression templates captures the left-hand-side and right-hand-side of the expression so we can display the values in our test report. As we'll see later there _are_ other assertion macros - but because of this technique the number of them is drastically reduced.
+
+<a id="test-cases-and-sections"></a>
+## Test cases and sections
+
+Most test frameworks have a class-based fixture mechanism. That is, test cases map to methods on a class and common setup and teardown can be performed in ```setup()``` and ```teardown()``` methods (or constructor/ destructor in languages, like C++, that support deterministic destruction).
+
+While Catch fully supports this way of working there are a few problems with the approach. In particular the way your code must be split up, and the blunt granularity (you can only have one setup/ teardown pair across a set of methods - sometimes you want slightly different setup in each method - or you may want several levels of setup. We'll revisit that concept shortly and, hopefully, make it clearer). It was <a href="http://jamesnewkirk.typepad.com/posts/2007/09/why-you-should-.html">problems like these</a> that led James Newkirk, who led the team that built NUnit, to start again from scratch and <a href="http://jamesnewkirk.typepad.com/posts/2007/09/announcing-xuni.html">build xUnit</a>).
+
+Catch takes a different approach (to both NUnut and xUnit) that is a more natural fit for C++ and the C family of languages. This is best explaned through an example:
+
+```c++
+TEST_CASE( "vectors can be sized and resized", "[vector]" ) {
+
+    std::vector<int> v( 5 );
+    
+    REQUIRE( v.size() == 5 );
+    REQUIRE( v.capacity() >= 5 );
+    
+    SECTION( "resizing bigger changes size and capacity" ) {
+        v.resize( 10 );
+        
+        REQUIRE( v.size() == 10 );
+        REQUIRE( v.capacity() >= 10 );
+    }
+    SECTION( "resizing smaller changes size but not capacity" ) {
+        v.resize( 0 );
+        
+        REQUIRE( v.size() == 0 );
+        REQUIRE( v.capacity() >= 5 );
+    }
+    SECTION( "reserving bigger changes capacity but not size" ) {
+        v.reserve( 10 );
+        
+        REQUIRE( v.size() == 5 );
+        REQUIRE( v.capacity() >= 10 );
+    }
+    SECTION( "reserving smaller does not change size or capacity" ) {
+        v.reserve( 0 );
+        
+        REQUIRE( v.size() == 5 );
+        REQUIRE( v.capacity() >= 5 );
+    }
+}
+```
+
+For each ```SECTION``` the ```TEST_CASE``` is executed from the start - so as we enter each section we know that size is 5 and capacity is at least 5. We enforced those requirements with the ```REQUIRE```s at the top level so we can be confident in them.
+This works because the ```SECTION``` macro contains an if statement that calls back into Catch to see if the section should be executed. One leaf section is executed on each run through a ```TEST_CASE```. The other sections are skipped. Next time through the next section is executed, and so on until no new sections are encountered.
+
+So far so good - this is already an improvement on the setup/ teardown approach because now we see our setup code inline and we can use the stack.
+
+The power of sections really shows, however, when we need to execute a sequence of, checked, operations. Continuing the vector example we might want to verify that after reserving a larger capacity, if we reserve smaller capacity (but still larger than the current size) then the capacity is not, in fact, changed. We can do that, naturally, like so:
+
+```c++
+    SECTION( "reserving bigger changes capacity but not size" ) {
+        v.reserve( 10 );
+        
+        REQUIRE( v.size() == 5 );
+        REQUIRE( v.capacity() >= 10 );
+    
+        SECTION( "reserving smaller again does not change capacity" ) {
+            v.reserve( 7 );
+            
+            REQUIRE( v.capacity() >= 10 );
+        }
+    }
+```
+
+Sections can be nested to an arbitrary depth (limited only by your stack size). Each leaf section (i.e. a section that contains no nested sections) will be executed exactly once, on a separate path of execution from any other leaf section (so no leaf section can interfere with another). Obviously a failure in a parent section will prevent nested sections from running - but that's the idea.
+
+## BDD-Style
+
+If you name your test cases and sections appropriately you can achieve a BDD-style specification structure. This became such a useful way of working that first class support has been added to Catch. Scenarios can be specified using ```SCENARIO```, ```GIVEN```, ```WHEN``` and ```THEN``` macros, which map on to ```TEST_CASE```s and ```SECTION```s, respectively (for more details see [Test cases and sections](test-cases-and-sections.md)).
+
+The vector example can be adjusted to use these macros like so:
+
+```c++
+SCENARIO( "vectors can be sized and resized", "[vector]" ) {
+
+    GIVEN( "A vector with some items" ) {
+        std::vector<int> v( 5 );
+        
+        REQUIRE( v.size() == 5 );
+        REQUIRE( v.capacity() >= 5 );
+        
+        WHEN( "the size is increased" ) {
+            v.resize( 10 );
+            
+            THEN( "the size and capacity change" ) {
+                REQUIRE( v.size() == 10 );
+                REQUIRE( v.capacity() >= 10 );
+            }
+        }
+        WHEN( "the size is reduced" ) {
+            v.resize( 0 );
+            
+            THEN( "the size changes but not capacity" ) {
+                REQUIRE( v.size() == 0 );
+                REQUIRE( v.capacity() >= 5 );
+            }
+        }
+        WHEN( "more capacity is reserved" ) {
+            v.reserve( 10 );
+            
+            THEN( "the capacity changes but not the size" ) {
+                REQUIRE( v.size() == 5 );
+                REQUIRE( v.capacity() >= 10 );
+            }
+        }
+        WHEN( "less capacity is reserved" ) {
+            v.reserve( 0 );
+            
+            THEN( "neither size nor capacity are changed" ) {
+                REQUIRE( v.size() == 5 );
+                REQUIRE( v.capacity() >= 5 );
+            }
+        }
+    }
+}
+```
+
+A nice consequence of this is that when these tests are run the test names are reported like this:
+
+```
+Scenario: vectors can be sized and resized
+     Given: A vector with some items
+      When: more capacity is reserved
+      Then: the capacity changes but not the size
+```
+
+## Next steps
+For more specific information see the [Reference pages](reference-index.md)
+
+
+---
+
+[Home](../README.md)