bug fixes and updates

Author: stellar-aria

README.md

@@ -12,32 +12,38 @@ See [http://cppspec.readthedocs.org/](http://cppspec.readthedocs.org/) for full
 
 ## Requirements
 
-C++Spec requires a compiler and standard library with support for C++23: Currently tested and confirmed working are:
+C++Spec requires a compiler and standard library with C++23 support. Currently tested:
+
 - LLVM/Clang 18 (on Linux, macOS, and Windows)
 - GCC 14.2 (on Linux and macOS)
 - MSVC 19.43 (on Windows)
 - AppleClang 16 (on macOS)
 
-__Note:__ Only the tests require being compiled with C++23 support (`-std=c++23`). No other part of an existing project's build must be modified.
+__Note:__ Only spec files require C++23 (`-std=c++23`). No other part of an existing project's build needs modification.
 
 ## Usage
-The recommended usage is as a subproject integrated into your build system. For CMake this would look something like below:
+
+The recommended approach is to integrate C++Spec as a CMake subproject:
+
 ```cmake
 FetchContent_Declare(
-  c++spec
+  cppspec
   GIT_REPOSITORY https://github.com/toroidal-code/cppspec
   GIT_TAG        VERSION
 )
+FetchContent_MakeAvailable(cppspec)
 
 # Or using CPM
 CPMAddPackage("gh:toroidal-code/cppspec@VERSION")
 ```
 
-Specs can then be automatically added as targets with
+Spec files are picked up automatically with:
+
 ```cmake
 discover_specs(specs_folder)
 ```
-This will create a separate executable for every file ending in `_spec.cpp` in the given directory (recursive) and add them to CTest.
+
+This creates a separate CTest executable for every file ending in `_spec.cpp` in the given directory (recursive).
 
 ## Introduction
 
@@ -49,18 +55,18 @@ If you've ever used RSpec or Jasmine, chances are you'll be familiar with C++Spe
 
 describe order_spec("Order", $ {
   it("sums the prices of its line items", _ {
-    Order order();
+    Order order;
 
-	order.add_entry(LineItem().set_item(Item()
-	  .set_price(Money(1.11, Money::USD))
-	));
+    order.add_entry(LineItem().set_item(Item()
+      .set_price(Money(1.11, Money::USD))
+    ));
 
-	order.add_entry(LineItem().set_item(Item()
-	  .set_price(Money(1.11, Money::USD))
-	  .set_quantity(2)
-	));
+    order.add_entry(LineItem().set_item(Item()
+      .set_price(Money(1.11, Money::USD))
+      .set_quantity(2)
+    ));
 
-	expect(order.total()).to_equal(Money(5.55, Money::USD));
+    expect(order.total()).to_equal(Money(5.55, Money::USD));
   });
 });
 

docs/index.md

@@ -4,18 +4,51 @@ C++Spec is a behavior-driven development library with an RSpec-inspired DSL.
 
 -------------------------------------------------------------------------------
 
-## Overview ##
+## Overview
 
-C++Spec is a behavior-driven development library for C++ with an RSpec-inspired DSL. Designed with ease of use and rapid prototyping in mind, C++Spec offers an alternative to traditional testing libraries and frameworks.
+C++Spec is a behavior-driven development library for C++ with an RSpec-inspired DSL. Designed
+with ease of use and rapid prototyping in mind, C++Spec offers an alternative to traditional
+testing libraries and frameworks.
 
-Also see the [official GitHub pages site](http://toroidal-code.github.io/cppspec/) for more 
+Also see the [official GitHub pages site](http://toroidal-code.github.io/cppspec/) for more
 information.
 
-## Installing ##
+## Requirements
 
-Either run `git clone https://github.com/toroidal-code/cppspec.git` or download the collated header
-file (if it is available). You can also download a ZIP version of the repo.
+C++Spec requires a compiler and standard library with C++23 support. Currently tested:
 
-If you want to manually generate the collated `cppspec.hpp`, you can download the ccollate tool [here](https://raw.githubusercontent.com/toroidal-code/ccollate/master/ccollate.rb) and then run `./ccollate.rb include/cppspec.hpp > cppspec.hpp` in the 
-toplevel directory of the C++Spec repo. A `cppspec.hpp` file will then be 
-available in the root of the project for copying.
+- LLVM/Clang 18 (Linux, macOS, Windows)
+- GCC 14.2 (Linux, macOS)
+- MSVC 19.43 (Windows)
+- AppleClang 16 (macOS)
+
+## Installing
+
+The recommended approach is to integrate C++Spec as a CMake subproject:
+
+```cmake
+include(FetchContent)
+FetchContent_Declare(
+  cppspec
+  GIT_REPOSITORY https://github.com/toroidal-code/cppspec
+  GIT_TAG        VERSION
+)
+FetchContent_MakeAvailable(cppspec)
+```
+
+Spec files are picked up automatically with:
+
+```cmake
+discover_specs(specs_folder)
+```
+
+This creates a separate CTest executable for every file ending in `_spec.cpp` in the given
+directory (recursive).
+
+Alternatively, clone the repository and add the `include/` directory to your include path:
+
+```sh
+git clone https://github.com/toroidal-code/cppspec.git
+```
+
+Then `#include "cppspec.hpp"` in your spec files.

docs/syntax/before_after.md

@@ -0,0 +1,131 @@
+# before_each, after_each, before_all, after_all
+
+C++Spec provides four lifecycle hooks to manage setup and teardown around examples.
+
+## before_each
+
+Runs once **before every `it`** in the enclosing `describe` or `context`:
+
+```cpp
+namespace { int n = 0; }
+
+describe lifecycle_spec("lifecycle", $ {
+  before_each([] { n = 0; });
+
+  it("starts at zero", _ {
+    expect(n).to_equal(0);
+  });
+
+  it("can be set to 5", _ {
+    n = 5;
+    expect(n).to_equal(5);
+  });
+
+  it("is zero again (reset by before_each)", _ {
+    expect(n).to_equal(0);
+  });
+});
+```
+
+## after_each
+
+Runs once **after every `it`** in the enclosing block. Useful for releasing resources or
+asserting post-conditions:
+
+```cpp
+namespace { std::FILE* f = nullptr; }
+
+describe file_spec("File handle", $ {
+  before_each([] { f = std::tmpfile(); });
+  after_each([]  { if (f) { std::fclose(f); f = nullptr; } });
+
+  it("is open after setup", _ {
+    expect(f).not_().to_be_null();
+  });
+});
+```
+
+## before_all
+
+Runs **once** before the first `it` in the enclosing block. Unlike `before_each`, it does
+**not** re-run between examples — mutations made inside examples persist:
+
+```cpp
+namespace { int init_count = 0; }
+
+describe before_all_spec("Expensive setup", $ {
+  before_all([] { init_count = 42; });
+
+  it("sees the value set by before_all", _ {
+    expect(init_count).to_equal(42);
+  });
+
+  it("mutations persist (before_all does not re-run)", _ {
+    init_count = 99;
+    expect(init_count).to_equal(99);
+  });
+
+  it("sees the mutated value from the previous it", _ {
+    expect(init_count).to_equal(99);
+  });
+});
+```
+
+Use `before_all` only when setup is genuinely expensive and examples do not mutate shared
+state, or when mutation is intentional (as above).
+
+## after_all
+
+Runs **once** after the last `it` in the enclosing block:
+
+```cpp
+namespace { int x = 0; }
+
+describe after_all_spec("Timing", $ {
+  context("inner context", _ {
+    after_all([] { x = 777; });
+
+    it("x is still 0 while its run", _ { expect(x).to_equal(0); });
+    it("x is still 0 here too",      _ { expect(x).to_equal(0); });
+    // after_all fires here → x = 777
+  });
+
+  it("outer it sees x == 777 after inner context completed", _ {
+    expect(x).to_equal(777);
+  });
+});
+```
+
+## Hook inheritance in nested contexts
+
+Hooks defined in a parent `describe` or `context` run for all `it` blocks in child contexts
+as well. Additional hooks registered in a child context run **after** the parent's, stacking
+up:
+
+```cpp
+namespace { int total = 0; }
+
+describe stacked_spec("Stacked hooks", $ {
+  before_each([] { total = 0; total += 1; });  // runs first: total = 1
+
+  context("inner", _ {
+    before_each([] { total += 10; });           // runs second: total = 11
+
+    it("sees 11", _ {
+      expect(total).to_equal(11);
+    });
+  });
+
+  it("outer it sees only 1 (inner before_each does not apply)", _ {
+    expect(total).to_equal(1);
+  });
+});
+```
+
+Hook execution order for a nested `it`:
+
+1. Parent `before_each` hooks (outermost first)
+2. Child `before_each` hooks
+3. The `it` body runs
+4. Child `after_each` hooks
+5. Parent `after_each` hooks (outermost last)