More documentation

Author: toroidal-code

include/expectations/expectation.hpp

@@ -4,10 +4,11 @@
 #include <vector>
 #include "runnable.hpp"
 #include "matchers/basematcher.hpp"
+#include "matchers/be.hpp"
 #include "matchers/be_between.hpp"
+#include "matchers/be_within.hpp"
 #include "matchers/include.hpp"
 #include "matchers/equal.hpp"
-#include "matchers/be_within.hpp"
 
 namespace Expectations {
 
@@ -17,10 +18,10 @@ namespace Expectations {
  *   expect(something)
  *   expect([] -> auto { return something })
  *
- *   // used with `to` matchers
+ *   // used with a matcher
  *   expect(actual).to_equal(target)
  *
- *   // used with `not` and matchers
+ *   // used with `not` and a matcher
  *   expect(actual).not_().to_equal(target)
  * @endcode
  *
@@ -31,32 +32,64 @@ template <class A>
 class Expectation : public Child {
   A target;
   std::function<A(void)> block;
-  bool has_block = false;
-  bool is_positive = true;
+  bool has_block = false;   // Is the target a lambda?
+  bool is_positive = true;  // Have we been negated?
 
   template <typename E>
   bool setup_and_run(Matchers::BaseMatcher<A, E> &matcher, std::string msg);
 
  public:
+  /**
+   * @brief Create an Expectation using a value.
+   *
+   * @param value The target to test, an explicit value.
+   *
+   * @return The constructed Expectation.
+   */
   Expectation(A &value) : target(value) {}
 
+  /**
+   * @brief Create an Expectation using a function.
+   *
+   * This does not simply contain the return value of the given
+   * lambda, but instead wraps the thunk, delaying execution until it is time
+   * to perform the match.
+   *
+   * @param block A function that returns some value to test against.
+   *
+   * @return The constructed Expectation.
+   */
   Expectation(std::function<A(void)> block) : block(block), has_block(true) {}
 
+  /**
+   * @brief Create an Expectation using an initializer list.
+   *
+   * @param init_list The initializer list to match against.
+   *
+   * @return The constructed Expectation.
+   */
   template <typename U>
   Expectation(std::initializer_list<U> init_list)
       : target(std::vector<U>(init_list)) {}
 
-  A &get_target();
-  bool get_sign();
+  /** @brief Get the target of the expectation. */
+  A &get_target() { return target; }
+
+  /** @brief Get whether the expectation is normal or negated. */
+  bool get_sign() { return is_positive; }
 
   Expectation &not_();
-  Expectation &to();
+
+  bool to_be(std::function<bool(A)>, std::string msg = "");
+  bool to_be_null(std::string msg = "");
+  bool to_be_true(std::string msg = "");
+  bool to_be_false(std::string msg = "");
 
   template <typename U>
   bool to_include(std::initializer_list<U> expected, std::string msg = "");
 
-  template <typename U>
-  bool to_include(U expected, std::string msg = "");
+  template <typename E>
+  bool to_include(E expected, std::string msg = "");
 
   template <typename E>
   bool to_be_between(E min, E max, Matchers::RangeMode mode,
@@ -72,18 +105,8 @@ class Expectation : public Child {
   bool to_be_within(E expected, std::string msg = "");
 };
 
-template <typename A>
-A &Expectation<A>::get_target() {
-  return target;
-}
-
-template <typename A>
-bool Expectation<A>::get_sign() {
-  return is_positive;
-}
-
 /**
- * @brief Inverts the current matcher
+ * @brief Invert the current matcher.
  */
 template <typename A>
 Expectation<A> &Expectation<A>::not_() {
@@ -106,6 +129,69 @@ bool Expectation<A>::setup_and_run(Matchers::BaseMatcher<A, E> &matcher,
   return matcher(msg);
 }
 
+/** 
+ * @brief Match using the Matchers::Be matcher.
+ *
+ * @param test The function to use to test the output of the
+ *             expectation expression.
+ * @param msg Optional message to give on failure.
+ *
+ * @return Whether the expectation succeeds or fails.
+ */ template <typename A>
+bool Expectation<A>::to_be(std::function<bool(A)> test, std::string msg) {
+  Matchers::Be<A> matcher(*this, test);
+  return setup_and_run(matcher, msg);
+}
+
+/**
+ * @brief Match using the Matchers::BeNullptr matcher.
+ *
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
+template <typename A>
+bool Expectation<A>::to_be_null(std::string msg) {
+  Matchers::BeNullptr<A> matcher(*this);
+  return setup_and_run(matcher, msg);
+}
+
+/**
+ * @brief Match using the Matchers::Be matcher, testing for truthy-ness.
+ *
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
+template <typename A>
+bool Expectation<A>::to_be_true(std::string msg) {
+  Matchers::Be<A> matcher(*this, [](A t) { return static_cast<bool>(t); });
+  return setup_and_run(matcher, msg);
+}
+
+/**
+ * @brief Match using the Matchers::Be matcher, testing for falsy-ness.
+ *
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
+template <typename A>
+bool Expectation<A>::to_be_false(std::string msg) {
+  Matchers::Be<A> matcher(*this, [](A t) { return not static_cast<bool>(t); });
+  return setup_and_run(matcher, msg);
+}
+
+/**
+ * @brief Match using the Matchers::BeBetween matcher.
+ *
+ * @param min
+ * @param max
+ * @param mode
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
 template <typename E>
 bool Expectation<A>::to_be_between(E min, E max, Matchers::RangeMode mode,
@@ -114,12 +200,30 @@ bool Expectation<A>::to_be_between(E min, E max, Matchers::RangeMode mode,
   return setup_and_run(matcher, msg);
 }
 
+/**
+ * @brief Match using the Matchers::BeBetween matcher, with an explicit
+ *        range mode.
+ *
+ * @param min
+ * @param max
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
 template <typename E>
 bool Expectation<A>::to_be_between(E min, E max, std::string msg) {
   return this->to_be_between(min, max, Matchers::RangeMode::inclusive, msg);
 }
 
+/**
+ * @brief Match using the Matchers::Include matcher, given an initializer list.
+ *
+ * @param expected
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
 template <typename U>
 bool Expectation<A>::to_include(std::initializer_list<U> expected,
@@ -128,20 +232,44 @@ bool Expectation<A>::to_include(std::initializer_list<U> expected,
   return setup_and_run(matcher, msg);
 }
 
+/**
+ * @brief Match using the Matchers::Include matcher.
+ *
+ * @param expected
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
-template <typename U>
-bool Expectation<A>::to_include(U expected, std::string msg) {
-  Matchers::Include<A, U, U> matcher(*this, expected);
+template <typename E>
+bool Expectation<A>::to_include(E expected, std::string msg) {
+  Matchers::Include<A, E, E> matcher(*this, expected);
   return setup_and_run(matcher, msg);
 }
 
+/**
+ * @brief Match using the Matchers::Equal matcher.
+ *
+ * @param expected
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
 template <typename E>
 bool Expectation<A>::to_equal(E expected, std::string msg) {
   Matchers::Equal<A, E> matcher(*this, expected);
   return setup_and_run(matcher, msg);
 }
 
+/**
+ * @brief Match using the Matchers::BeWithin matcher.
+ *
+ * @param expected
+ * @param msg Optional message to give on failure.
+ *
+ * @return
+ */
 template <typename A>
 template <typename E>
 bool Expectation<A>::to_be_within(E expected, std::string msg) {

include/it.hpp

@@ -28,9 +28,7 @@ class ItD : public ItExpBase {
   ItD(std::string descr, std::function<void(ItD &)> body)
       : ItExpBase(descr), body(body) {}
 
-  ItD(std::function<void(ItD &)> body) : body(body) {
-    this->set_needs_descr(true);
-  }
+  ItD(std::function<void(ItD &)> body) : body(body) {}
 
   bool run();
 };
@@ -45,9 +43,7 @@ class ItCd : public ItExpBase {
   ItCd(std::string descr, std::function<void(ItCd<T> &)> body)
       : ItExpBase(descr), body(body) {}
 
-  ItCd(std::function<void(ItCd<T> &)> body) : body(body) {
-    this->set_needs_descr(true);
-  }
+  ItCd(std::function<void(ItCd<T> &)> body) : body(body) {}
 
   Expectations::Expectation<T> is_expected();
   bool run();
@@ -86,16 +82,15 @@ Expectations::Expectation<std::vector<T>> ItExpBase::expect(
 
 template <class T>
 Expectations::Expectation<T> ItCd<T>::is_expected() {
-  ClassDescription<T> *cd =
-      static_cast<ClassDescription<T> *>(this->get_parent());
+  auto cd = static_cast<ClassDescription<T> *>(this->get_parent());
   Expectations::Expectation<T> expectation(cd->get_subject());
   expectation.set_parent(this);
   return expectation;
 }
 
 bool ItD::run() {
   if (!this->needs_descr()) {
-    std::cout << padding() << descr << std::endl;
+    std::cout << padding() << get_descr() << std::endl;
   }
   body(*this);
   return this->get_status();
@@ -104,7 +99,7 @@ bool ItD::run() {
 template <class T>
 bool ItCd<T>::run() {
   if (!this->needs_descr()) {
-    std::cout << padding() << descr << std::endl;
+    std::cout << padding() << get_descr() << std::endl;
   }
   body(*this);
   return this->get_status();

include/it_base.hpp

@@ -4,19 +4,46 @@
 #include <string>
 #include "runnable.hpp"
 
+/**
+ * @brief Most base class for `it` expressions.
+ *
+ * This class is needed to prevent a circular dependency between it.hpp and
+ * basematcher.hpp. Matchers need to know whether or not an `it` has an explicit
+ * description string or whether the description should be generated. `it`s need
+ * to be able to refer to Expectations, and Expectations need to know about
+ * Matchers and execute them. This class is the least common denominator of the
+ * `it` classes, and thus is used to resolve the dependency cycle.
+ */
 class ItBase : public Runnable {
- protected:
   std::string descr = "";
-  bool does_need_descr = false;
 
  public:
+  /**
+   * @brief Create an ItBase without an explicit description
+   * @return the constructed ItBase
+   */
   ItBase(){};
-  ItBase(std::string descr) : descr(descr){};
+
+  /**
+   * @brief Create an ItBase with an explicit description.
+   * @param descr the description of the `it` statement
+   * @return the constructed ItBase
+   */
+  explicit ItBase(std::string descr) : descr(descr){};
 
   bool run() { return false; };
 
-  void set_needs_descr(bool nd) { does_need_descr = nd; }
-  bool needs_descr() { return does_need_descr; }
+  /**
+   * @brief Get whether the object needs a description string
+   * @return whether this object needs a description to be generated or not
+   */
+  bool needs_descr() { return descr.empty(); }
+
+  /**
+   * @brief Get the description string for the `it` statement
+   * @return the description string
+   */
+  std::string get_descr() { return descr; }
 };
 
 #endif /* IT_BASE_H */

include/matchers/basematcher.hpp

@@ -38,8 +38,6 @@ class BaseMatcher : public Child, public Pretty {
     //               different");
   }
 
-  virtual ~BaseMatcher(){};
-
   virtual bool matches(Actual actual);
   virtual std::string failure_message();
   virtual std::string failure_message_when_negated();
@@ -80,7 +78,7 @@ std::string BaseMatcher<A, E>::description() {
 template <typename A, typename E>
 bool BaseMatcher<A, E>::operator()(std::string message) {
   bool matched;
-  ItBase *par = static_cast<ItBase *>(this->get_parent());
+  auto par = static_cast<ItBase *>(this->get_parent());
 
   if (par->needs_descr()) {
     std::cout << par->padding() << "should "