API adjustments and documentation

Author: toroidal-code

include/child.hpp

@@ -58,15 +58,11 @@ class Child {
   Child &operator=(Child &&) = default;
 
   // Copy constructor/operator
+  Child(const Child &) = default;
   Child &operator=(const Child &) = default;
 
   // Custom constructors
-  explicit Child(Child &parent) noexcept : parent(&parent) {}
-  explicit Child(const Child &parent) noexcept
-      : parent(&const_cast<Child &>(parent)) {}
-  explicit Child(Child *parent) noexcept : parent(parent) {}
-  explicit Child(const Child *parent) noexcept
-      : parent(const_cast<Child *>(parent)) {}
+  static Child of(const Child& parent) noexcept { return Child().set_parent(&parent); }
 
   /*--------- Parent helper functions -------------*/
 
@@ -76,52 +72,42 @@ class Child {
 
   // TODO: Look in to making these references instead of pointer returns
   /** @brief Get the Child's parent. */
-  Child *get_parent() noexcept { return parent; }
-  const Child *get_parent() const noexcept {
-    return const_cast<Child *>(parent);
-  }
-
-  template <class C>
-  C get_parent_as() noexcept {
-    return static_cast<C>(get_parent());
-  }
+  Child *get_parent() const noexcept { return parent;  }
 
   template <class C>
   C get_parent_as() const noexcept {
     return static_cast<C>(get_parent());
   }
 
   /** @brief Set the Child's parent */
-  void set_parent(Child *parent) noexcept { this->parent = parent; }
-  void set_parent(const Child *parent) noexcept {
+  Child set_parent(Child *parent) noexcept { this->parent = parent; return *this; }
+  Child& set_parent(const Child *parent) noexcept {
     this->parent = const_cast<Child *>(parent);
+    return *this;
   }
 
   /*--------- Formatter helper functions -----------*/
   // Check to see if the tree has a printer
-  const bool has_formatter() noexcept;
+  const bool has_formatter() const noexcept;
 
   // Get the printer from the tree
-  Formatters::BaseFormatter &get_formatter() noexcept;
+  Formatters::BaseFormatter &get_formatter() const noexcept;
 
-  void set_printer(const Formatters::BaseFormatter &formatter) {
+  void set_formatter(const Formatters::BaseFormatter &formatter) {
     this->formatter = &const_cast<Formatters::BaseFormatter &>(formatter);
   }
 
   /*--------- Primary member functions -------------*/
 
   /** @brief Get the status of the object (success/failure) */
-  const bool get_status() noexcept { return this->status; }
   const bool get_status() const noexcept { return this->status; }
-
   void failed() noexcept;  // Report failure to the object.
 
   // Calculate the padding for printing this object
-  std::string padding() noexcept;
   std::string padding() const noexcept;
 };
 
-/*>>>>>>>>>>>>>>>>>>>> Child IMPLEMENTATION <<<<<<<<<<<<<<<<<<<<<<<<<*/
+/*>>>>>>>>>>>>>>>>>>>> Child <<<<<<<<<<<<<<<<<<<<<<<<<*/
 
 /**
  * @brief Report failure to the object.
@@ -139,21 +125,17 @@ inline void Child::failed() noexcept {
  * @brief Generate padding (indentation) fore the current object.
  * @return A string of spaces for use in pretty-printing.
  */
-inline std::string Child::padding() noexcept {
-  return this->has_parent() ? this->get_parent()->padding() + "  " : "";
-}
-
 inline std::string Child::padding() const noexcept {
   return this->has_parent() ? this->get_parent()->padding() + "  " : "";
 }
 
-inline const bool Child::has_formatter() noexcept {
+inline const bool Child::has_formatter() const noexcept {
   if (this->formatter != nullptr) return true;
   if (!this->has_parent()) return false;  // base case;
   return parent->has_formatter();
 }
 
-inline Formatters::BaseFormatter &Child::get_formatter() noexcept {
+inline Formatters::BaseFormatter &Child::get_formatter() const noexcept {
   if (this->formatter) return *formatter;
   if (!this->has_parent()) std::terminate();
   return parent->get_formatter();

include/class_description.hpp

@@ -25,6 +25,7 @@ class ClassDescription : public Description {
   std::string type = "";
 
  public:
+  const bool has_subject = true;
   T subject;  // subject field public for usage in `expect([self.]subject)`
 
   // Constructor
@@ -69,10 +70,6 @@ class ClassDescription : public Description {
                    Block block)
       : Description(description), block(block), subject(T(init_list)) {}
 
-  ClassDescription<T>(Description &d) : Description(d) {}
-
-  const bool has_subject = true;
-
   Result it(std::string description, std::function<void(ItCD<T> &)> block);
   Result it(std::function<void(ItCD<T> &)> block);
   /** @brief an alias for it */
@@ -99,11 +96,7 @@ class ClassDescription : public Description {
 
   Result run(Formatters::BaseFormatter &printer) override;
 
-  //  std::string get_descr() noexcept override { return description; }
-  //  const std::string get_descr() const noexcept override { return
-  //  description; }
-  std::string get_subject_type() noexcept override { return type; }
-  const std::string get_subject_type() const noexcept override { return type; }
+  std::string get_subject_type() const noexcept override { return type; }
 };
 
 template <class T>
@@ -246,7 +239,7 @@ Result ClassDescription<T>::it(std::function<void(ItCD<T> &)> block) {
 
 template <class T>
 Result ClassDescription<T>::run(Formatters::BaseFormatter &printer) {
-  if (not this->has_formatter()) this->set_printer(printer);
+  if (not this->has_formatter()) this->set_formatter(printer);
   printer.format(*this);
   this->block(*this);
   for (const auto &a : after_alls) a();

include/description.hpp

@@ -9,6 +9,7 @@
 #include <string>
 #include <deque>
 #include <queue>
+#include <forward_list>
 #include "it.hpp"
 #include "class_description.hpp"
 
@@ -18,18 +19,28 @@ template <typename T>
 class ClassDescription;  // forward-declaration for ClassDescription
 
 class Description : public Runnable {
+  using VoidBlock = std::function<void()>;
+
  public:
   using Block = std::function<void(Description &)>;
-  using VoidBlock = std::function<void()>;
+
+  const bool has_subject = false;
+  std::forward_list<LetBase *> lets;
+  std::deque<VoidBlock> after_alls;
+  std::deque<VoidBlock> before_eaches;
+  std::deque<VoidBlock> after_eaches;
 
  private:
   Block block;
 
  protected:
   std::string description = "";
 
-  Description() {}
-
+  // These two constructors are the most basic ones,
+  // used to create Descriptions with only their description
+  // field initialized. They should only be used by subclasses
+  // of Description.
+  Description() = default;
   explicit Description(std::string description) noexcept
       : description(description) {}
 
@@ -42,22 +53,21 @@ class Description : public Runnable {
   void exec_after_eaches();
 
  public:
-  // Constructor
+  // Copy constructor
+  Description(const Description &copy) = default;
+
+  // Primary constructor. Entry of all specs.
   Description(std::string description, Block block) noexcept
       : block(block),
         description(description) {}
 
-  const bool has_subject = false;
-  std::unordered_set<LetBase *> lets;
-  std::deque<VoidBlock> after_alls;
-  std::deque<VoidBlock> before_eaches;
-  std::deque<VoidBlock> after_eaches;
+  /********* Specify/It *********/
 
-  // Specify/It functions
   Result it(std::string description, ItD::Block body);
   Result it(ItD::Block body);
 
-  // Context functions
+  /********* Context ***********/
+
   Result context(std::string name, Block body);
 
   template <class T>
@@ -71,34 +81,34 @@ class Description : public Runnable {
   Result context(std::initializer_list<U> init_list,
                  std::function<void(ClassDescription<T> &)> block);
 
+  /********* Each/All *********/
+
   void before_each(VoidBlock block);
   void before_all(VoidBlock block);
   void after_each(VoidBlock block);
   void after_all(VoidBlock block);
 
+  /********* Let *********/
+
   template <typename T>
   auto let(T body) -> Let<decltype(body())>;
   void reset_lets() noexcept;
 
-  Result run(Formatters::BaseFormatter &printer) override;
+  /********* Standard getters *********/
 
-  virtual std::string get_description() noexcept { return description; }
-  virtual const std::string get_description() const noexcept {
-    return description;
-  }
+  virtual std::string get_description() const noexcept { return description; }
+  virtual std::string get_subject_type() const noexcept { return ""; }
+
+  /********* Run *********/
 
-  virtual std::string get_subject_type() noexcept { return ""; }
-  virtual const std::string get_subject_type() const noexcept { return ""; }
+  Result run(Formatters::BaseFormatter &printer) override;
 };
 
 using Context = Description;
 
-inline Result Description::context(std::string description, Block body) {
-  Context context(*this, description, body);
-  context.before_eaches = this->before_eaches;
-  context.after_eaches = this->after_eaches;
-  return context.run(this->get_formatter());
-}
+/*>>>>>>>>>>>>>>>>>>>> Description <<<<<<<<<<<<<<<<<<<<<<<<<*/
+
+/*========= Description::it =========*/
 
 inline Result Description::it(std::string description, ItD::Block block) {
   ItD it(*this, description, block);
@@ -116,6 +126,17 @@ inline Result Description::it(ItD::Block block) {
   return result;
 }
 
+/*========= Description::context =========*/
+
+inline Result Description::context(std::string description, Block body) {
+  Context context(*this, description, body);
+  context.before_eaches = this->before_eaches;
+  context.after_eaches = this->after_eaches;
+  return context.run(this->get_formatter());
+}
+
+/*========= Description:: each/alls =========*/
+
 inline void Description::before_each(VoidBlock b) {
   before_eaches.push_back(b);
 
@@ -134,14 +155,18 @@ inline void Description::after_each(VoidBlock b) { after_eaches.push_back(b); }
 
 inline void Description::after_all(VoidBlock b) { after_alls.push_back(b); }
 
+/*----------- private -------------*/
+
 inline void Description::exec_before_eaches() {
-  for (VoidBlock b : before_eaches) b();
+  for (VoidBlock &b : before_eaches) b();
 }
 
 inline void Description::exec_after_eaches() {
-  for (VoidBlock b : after_eaches) b();
+  for (VoidBlock &b : after_eaches) b();
 }
 
+/*========= Description::let =========*/
+
 /**
  * @brief Object generator for Let.
  *
@@ -150,26 +175,48 @@ inline void Description::exec_after_eaches() {
  * @return a new Let object
  */
 template <typename T>
-inline auto Description::let(T block) -> Let<decltype(block())> {
-  Let<decltype(block())> let(block);
-  lets.insert(&let);
-  return let;
-}
-
-inline Result Description::run(Formatters::BaseFormatter &printer) {
-  if (not this->has_formatter()) this->set_printer(printer);
-  printer.format(*this);
-  block(*this);
-  for (auto a : after_alls) a();
-  if (this->get_parent() == nullptr) printer.flush();
-  return this->get_status() ? Result::success() : Result::failure();
+auto Description::let(T block) -> Let<decltype(block())> {
+  // In reality, this gets inlined due to the fact that it's
+  // a templated function. Otherwise we wouldn't be able to
+  // add the address of the Let, return the Let by value,
+  // and still be able to do a valid deference of the Let
+  // pointer later on when we needed to reset the Let.
+
+  Let<decltype(block())> let(block);  // Create a Let
+  lets.push_front(&let);              // Add it to our list
+  return let;                         // Hand it object off
 }
 
+// TODO: Should this be protected?
 inline void Description::reset_lets() noexcept {
+  // For every let in our list, reset it.
   for (auto &let : lets) let->reset();
-  if (this->has_parent()) this->get_parent_as<Description *>()->reset_lets();
+
+  // Recursively reset all the lets in the family tree
+  if (this->has_parent()) {
+    this->get_parent_as<Description *>()->reset_lets();
+  }
 }
 
+/*========= Description::run =========*/
+
+inline Result Description::run(Formatters::BaseFormatter &formatter) {
+  // If there isn't already a formatter in the family tree, set ours.
+  if (!this->has_formatter()) this->set_formatter(formatter);
+
+  formatter.format(*this);              // Format our description in some way
+  block(*this);                         // Run the block
+  for (VoidBlock &a : after_alls) a();  // Run all our after_alls
+  if (!this->has_parent()) formatter.flush();  // Inform the printer we're done
+
+  // Return success or failure
+  return this->get_status() ? Result::success() : Result::failure();
+}
+
+/*>>>>>>>>>>>>>>>>>>>> ItD <<<<<<<<<<<<<<<<<<<<<<<<<*/
+
+/*========= ItD::run =========*/
+
 inline Result ItD::run(Formatters::BaseFormatter &printer) {
   block(*this);
   printer.format(*this);

include/expectations/expectation.hpp

@@ -51,12 +51,7 @@ class Expectation : public Child {
   bool ignore_failure = false;
 
  public:
-  Expectation(Expectation const &copy)
-      : Child(copy.get_parent()),
-        // block(copy.block),
-        // has_block(copy.has_block),
-        is_positive(copy.is_positive),
-        ignore_failure(copy.ignore_failure) {}
+  Expectation(const Expectation &) = default;
 
   /**
    * @brief Create an Expectation using a value.
@@ -65,7 +60,7 @@ class Expectation : public Child {
    *
    * @return The constructed Expectation.
    */
-  Expectation(ItBase &it) : Child(it) {}
+  explicit Expectation(ItBase &it) : Child(Child::of(it)) {}
 
   /** @brief Get the target of the expectation. */
   // virtual const A &get_target() const & { return target; }
@@ -520,7 +515,7 @@ class ExpectationFunc : public Expectation<decltype(std::declval<F>()())> {
   // Expectation<A>::get_target()(); }
 
   ExpectationFunc &not_() override {
-    this->is_positive = not this->is_positive;
+    this->is_positive = !this->is_positive;
     return *this;
   }