updates README, adds new expression tree drawio diagram, expands unit tests

attwoodn · attwoodn · commit 752a4b09eb4f · 2023-05-10T15:45:27.000-03:00
diff --git a/README.md b/README.md
@@ -24,20 +24,67 @@ This project is under development and is subject to change. Project contribution
 ## A Quick Example
 
 ```cpp
-// some code here
-// imagine we have some class struct whatever ...
-// we can create an expression_tree for evaluating the contents of instances of this struct class whatever
+#include <attwoodn/expression_tree.hpp>
+
+using namespace attwoodn::expression_tree;
+
+// imagine there is some user-defined type, like so
+struct my_type {
+    int my_int;
+    bool my_bool;
+
+    int get_my_int() const {
+        return my_int;      
+    }
+};
+
+...
+
+// the Cpp Expression Tree library can be used to create an expression tree to evaluate instances of my_type
+
+// create an expression tree: my_bool == true OR (get_my_int() > 0 AND my_int < 10)
+expression_tree<my_type> expr {
+    make_expr(&my_type::my_bool, op::equals, true)
+    ->OR((make_expr(&my_type::get_my_int, op::greater_than, 0)
+        ->AND(make_expr(&my_type::my_int, op::less_than, 10))
+        )
+    )
+};
+
+// create an instance of my_type that satisfies the above expression
+my_type obj;
+obj.my_bool = true;
+obj.my_int = 4;
+
+// evaluating obj against the expression_tree above returns true
+assert(expr.evaluate(obj));
+
+// update obj so that my_int is outside the range 1..9
+obj.my_bool = true;
+obj.my_int = 12;
+
+// evaluating obj against the expression_tree above returns true
+assert(expr.evaluate(obj));
+
+// update obj so that my_bool is false and my_int is outside the range 1..9
+obj.my_bool = false;
+obj.my_int = 0;
+
+// evaluating obj against the expression_tree above returns false
+assert(!expr.evaluate(obj));
 ```
 
-Below is a tree diagram showing the content of the expression_tree that was created in the example code above:
+Below is a diagram showing the content of the `expression_tree<my_type>` that was created in the example code above:
 
 <p align="center">
-    <img src="docs/expression-tree.png"/>
+    <img src="docs/a_quick_example_expression_tree.png"/>
 </p>
 
+As you can imagine, this example code can be expanded to fit a variety of use cases and struct/class type structures. More complex code examples are provided in the documentation below. Further, there are a number of unit tests located in the `tests` directory, which may be helpful for getting familiar with the library.
+
 ## Creating Expression Trees
 
-The `expression_tree` class is a templated, RAII container class that takes ownership of user-defined expressions. The template parameter of `expression_tree` is the type of object that the `expression_tree` can evaluate. Assuming there is a user-defined class named `my_type`, the templated `expression_tree` type would look like this: `expression_tree<my_type>`. The template argument of `expression_tree` cannot be a primitive type, like `int`, `char`, or `double`.
+The `expression_tree` class is a templated, RAII container class that takes ownership of user-defined expressions. The `expression_tree` class can be moved and/or copied to different contexts while maintaining consistency and safety. The template parameter of `expression_tree` is the type of object that the `expression_tree` can evaluate. Assuming there is a user-defined class named `my_type`, the templated `expression_tree` type would look like this: `expression_tree<my_type>`. The template argument of `expression_tree` cannot be a primitive type, like `int`, `char`, or `double`.
 
 An `expression_tree` cannot be default constructed - it must be initialized with an expression. Users can easily and intuitively define expressions using one of the `make_expr` helper functions found in the namespace `attwoodn::expression_tree`. `make_expr` generates heap-allocated pointers to expression tree nodes and returns them. As such, the returned expression tree node pointers should be managed carefully. If the returned pointers are not wrapped in an `expression_tree` or a smart pointer, they will need to be explicitly `delete`d by the calling code. 
 
@@ -49,20 +96,29 @@ Here are some examples of how you might handle the return value from one of the
 
 using namespace attwoodn::expression_tree;
 
+// let's bring back the same implementation of my_type as shown above
 struct my_type {
-   int my_int = 5;
-   bool my_bool = true;
+    int my_int;
+    bool my_bool;
+
+    int get_my_int() const {
+        return my_int;      
+    }
 };
 
+
 ...
 
+
 // The heap-allocated expression node pointer returned by make_expr becomes owned by the expression_tree
 expression_tree<my_type> expr_tree_raw {
     make_expr(&my_type::my_bool, op::equals, true)
 };
  
+
 ...
 
+
 // The heap-allocated expression node pointer returned by make_expr becomes owned by the unique_ptr
 std::unique_ptr<node::expression_tree_node<my_type>> smart_expr {
     make_expr(&my_type::my_bool, op::equals, true)
@@ -71,8 +127,10 @@ std::unique_ptr<node::expression_tree_node<my_type>> smart_expr {
 // the expression_tree takes ownership of the unique_ptr
 expression_tree<my_type> expr_tree_smart(std::move(smart_expr));
 
+
 ...
 
+
 // The heap-allocated expression node pointer returned by make_expr must be explicitly deleted
 auto* expr_raw = make_expr(&my_type::my_bool, op::equals, true);
 delete expr_raw;
@@ -205,4 +263,6 @@ After cloning and compiling the project, navigate to the build directory that wa
 ctest .
 ```
 
-CTest will execute the unit tests and provide a pass/fail indication for each one.
+CTest will execute the unit tests and provide a pass/fail indication for each one. 
+
+The address sanitizer is enabled on every unit test executable. A test will fail should memory leak during test execution.
diff --git a/docs/a_quick_example_expression_tree.drawio b/docs/a_quick_example_expression_tree.drawio
@@ -0,0 +1,44 @@
+<mxfile host="Electron" modified="2023-05-10T18:19:44.134Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/21.2.8 Chrome/112.0.5615.165 Electron/24.2.0 Safari/537.36" etag="A1TK9bRuSOZq5wIYVlKq" version="21.2.8" type="device">
+  <diagram name="Page-1" id="MzqSHk1QGt0DU5yl56VU">
+    <mxGraphModel dx="1360" dy="738" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="4_OO1GRJjltScIyBnV0f-2" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;expression_tree&amp;lt;my_type&amp;gt;&lt;/font&gt;" style="swimlane;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;shadow=1;" vertex="1" parent="1">
+          <mxGeometry x="80" y="95" width="550" height="435" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-4" value="&lt;font size=&quot;1&quot; style=&quot;&quot;&gt;&lt;b style=&quot;font-size: 15px;&quot;&gt;OR&lt;/b&gt;&lt;/font&gt;" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#dae8fc;strokeColor=#6c8ebf;shadow=1;" vertex="1" parent="4_OO1GRJjltScIyBnV0f-2">
+          <mxGeometry x="174" y="50" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-6" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;endArrow=none;endFill=0;edgeStyle=orthogonalEdgeStyle;curved=1;shadow=1;" edge="1" parent="4_OO1GRJjltScIyBnV0f-2" source="4_OO1GRJjltScIyBnV0f-5" target="4_OO1GRJjltScIyBnV0f-4">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-5" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;my_bool == true&lt;/font&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;shadow=1;" vertex="1" parent="4_OO1GRJjltScIyBnV0f-2">
+          <mxGeometry x="40" y="200" width="134" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-8" style="edgeStyle=orthogonalEdgeStyle;rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;curved=1;startArrow=classic;startFill=1;endArrow=none;endFill=0;shadow=1;" edge="1" parent="4_OO1GRJjltScIyBnV0f-2" source="4_OO1GRJjltScIyBnV0f-7" target="4_OO1GRJjltScIyBnV0f-4">
+          <mxGeometry relative="1" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-7" value="&lt;font style=&quot;font-size: 15px;&quot;&gt;&lt;b&gt;AND&lt;/b&gt;&lt;/font&gt;" style="ellipse;whiteSpace=wrap;html=1;aspect=fixed;fillColor=#dae8fc;strokeColor=#6c8ebf;shadow=1;" vertex="1" parent="4_OO1GRJjltScIyBnV0f-2">
+          <mxGeometry x="290" y="200" width="80" height="80" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-10" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;endArrow=none;endFill=0;edgeStyle=orthogonalEdgeStyle;curved=1;shadow=1;" edge="1" parent="4_OO1GRJjltScIyBnV0f-2" source="4_OO1GRJjltScIyBnV0f-11" target="4_OO1GRJjltScIyBnV0f-7">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="328" y="280" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-11" value="&lt;span style=&quot;font-size: 15px;&quot;&gt;get_my_int() &amp;gt; 0&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;shadow=1;" vertex="1" parent="4_OO1GRJjltScIyBnV0f-2">
+          <mxGeometry x="150" y="350" width="140" height="60" as="geometry" />
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-12" style="rounded=0;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=0;exitDx=0;exitDy=0;entryX=0.5;entryY=1;entryDx=0;entryDy=0;startArrow=classic;startFill=1;endArrow=none;endFill=0;edgeStyle=orthogonalEdgeStyle;curved=1;shadow=1;" edge="1" parent="4_OO1GRJjltScIyBnV0f-2" source="4_OO1GRJjltScIyBnV0f-13" target="4_OO1GRJjltScIyBnV0f-7">
+          <mxGeometry relative="1" as="geometry">
+            <mxPoint x="580" y="280" as="targetPoint" />
+          </mxGeometry>
+        </mxCell>
+        <mxCell id="4_OO1GRJjltScIyBnV0f-13" value="&lt;span style=&quot;font-size: 15px;&quot;&gt;my_int &amp;lt; 10&lt;/span&gt;" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;shadow=1;" vertex="1" parent="4_OO1GRJjltScIyBnV0f-2">
+          <mxGeometry x="370" y="350" width="140" height="60" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/a_quick_example_expression_tree.png b/docs/a_quick_example_expression_tree.png
diff --git a/tests/expression_tree.cpp b/tests/expression_tree.cpp
@@ -6,6 +6,7 @@
 using namespace attwoodn::expression_tree;
 
 void test_expression_tree_std_string_template();
+void test_quick_example_expression_tree();
 void test_simple_expression_tree();
 void test_complex_expression_tree();
 void test_moved_expression_tree();
@@ -14,6 +15,7 @@ void test_user_defined_operator();
 
 int main(int argc, char** argv) {
     test_expression_tree_std_string_template();
+    test_quick_example_expression_tree();
     test_simple_expression_tree();
     test_complex_expression_tree();
     test_moved_expression_tree();
@@ -23,6 +25,30 @@ int main(int argc, char** argv) {
     return EXIT_SUCCESS;
 }
 
+void test_quick_example_expression_tree() {
+    expression_tree<my_type> expr {
+        make_expr(&my_type::my_bool, op::equals, true)
+        ->OR((make_expr(&my_type::get_my_int, op::greater_than, 0)
+            ->AND(make_expr(&my_type::my_int, op::less_than, 10))
+            )
+        )
+    };
+    
+    my_type obj;
+    
+    obj.my_bool = true;
+    obj.my_int = 4;
+    assert(expr.evaluate(obj));
+
+    obj.my_bool = true;
+    obj.my_int = 12;
+    assert(expr.evaluate(obj));
+
+    obj.my_bool = false;
+    obj.my_int = 0;
+    assert(!expr.evaluate(obj));
+}
+
 void test_expression_tree_std_string_template() {
     expression_tree<std::string> expr {
         make_expr(&std::string::empty, op::equals, true)
diff --git a/tests/make_expr_safety.cpp b/tests/make_expr_safety.cpp
@@ -1,15 +1,11 @@
 #include <attwoodn/expression_tree.hpp>
+#include "test_utils.hpp"
 #include <cassert>
 
 using namespace attwoodn::expression_tree;
 
 void make_expr_memory_safety_test();
 
-struct my_type {
-   int my_int = 5;
-   bool my_bool = true;
-};
-
 int main(int argc, char** argv) {
     make_expr_memory_safety_test();
 
diff --git a/tests/test_utils.hpp b/tests/test_utils.hpp
@@ -31,4 +31,13 @@ class data_packet {
     public:
         std::string sender_name;
         packet_payload payload;
+};
+
+struct my_type {
+    int my_int;
+    bool my_bool;
+
+    int get_my_int() const {
+        return my_int;      
+    }
 };
