[COMPOSITE]: Added ressources and sample code for Composite pattern.

Author: MericLuc

structural-patterns/composite/README.md

@@ -1,3 +1,57 @@
-# TODO
+# Intend
 
-Stay tuned, this section will be completed shortly !
+**Compose objects** into tree structures to represent part-whole hierarchies.
+
+It **lets clients treat individual objects and compositions uniformly**.
+
+You should use the _Composite_ pattern in the following cases :
+ - The core model of your app can be **represented as a tree**.
+ - You want (or you want the Client) to perform operations on composite objects as if they were standard objects - that is interacting with them using a **common interface**.
+
+# How it's done
+
+![UML](UML.jpg)
+
+**Participants**
+
+ - _Component_ : 
+   - Declares the **interface** for the objects in the composition.
+   - Implements the **default behaviour** for the **common interface** to all classes.
+   - Declares an **interface** for **managing childs components**.
+ - _Leaf_ : 
+   - An object of the composition that has no children.
+   - Defines the **default behaviour** of **primitive objects**.
+ - _Composite_ :
+   - Defines behaviour for components having children.
+   - **Stores** the child components.
+   - Implements the **child-related operations** in the _Component_ interface.
+ - _Client_ : Manipulates the objects in the composition through the _Component_ interface.
+
+**How to implement**
+
+ 1. **Make sure** the model of your app can be represented as a Tree.
+ 2. **Declare** the _Component_ interface with the methods that make sense for both _Leafs_ and _Composites_.
+ 3. **Create** _Leaf_ classes to represent simple elements that do not have children.
+ 4. **Create** _Composite_ classes with an underlying container for children, methods to add/remove children. 
+ 5. **Implement** the _Component_ methods in the _Composite_ delegating the hard work to children.
+
+Note : UML class diagram taken from [**here**](https://upload.wikimedia.org/wikipedia/commons/3/39/W3sDesign_Composite_Design_Pattern_Type_Safety_UML.jpg)
+
+# Pros & cons
+
+**Pros**
+
+ - You and your clients can work easily with complex structures.
+ - **Open/Closed principle**: It is easy to introduce new elements in the apps without breaking the existing code.
+ - Reduce code complexity by eliminating many loops over the homogeneous collection of objects.
+
+**Cons**
+
+ - It might be difficult to provide a common interface for classes whose functionality differs too much. In certain scenarios, you’d need to overgeneralize the component interface, making it harder to comprehend.
+
+# Notes
+
+Here are some _usefull ressources_ :
+ - A great article on [**Source making**](https://sourcemaking.com/design_patterns/composite)
+ - A [**blog article**](http://www.vishalchovatiya.com/composite-design-pattern-in-modern-cpp/) showing an example using [**CRTP**](https://en.wikipedia.org/wiki/Curiously_recurring_template_pattern)
+ - A [**Refactoring guru**](https://refactoring.guru/design-patterns/composite) article.

structural-patterns/composite/UML.jpg

@@ -0,0 +1,114 @@
+/*!
+ * @brief : This example was originally declared in "Desgin Patterns :
+ *          Elements of reusable Object-oriented software".
+ */
+
+#include <vector>
+#include <iostream> 
+#include <algorithm> 
+#include <functional> 
+ 
+// ------- COMPONENT ------- //
+/*!
+ * @brief Component - declares the common interface for every
+ *        objects (Leaf or Composite) of the composition.
+ */
+class Graphic {
+public:
+  virtual ~Graphic() = default;
+
+  virtual void draw       (void) const = 0; // An operation method
+  virtual bool isComposite(void) const { return false; }
+
+  virtual void     setParent(Graphic* p_parent) { m_parent = p_parent; }
+  virtual Graphic* getParent(void) const { return m_parent; }
+
+  /*! 
+   * Note : These are child-management operations.
+   * Defining them in the Component class ensure you that you
+   * will not need to expose any Leaf/Composite to the client code.
+   */
+  virtual void remove     (Graphic *g) { /* EMPTY */ }
+  virtual void add        (Graphic *g) { /* EMPTY */ }
+
+protected:
+  Graphic* m_parent;
+};
+
+// --------- LEAFS --------- //
+/*!
+ * @brief Leafs - Leaf objects of the composition.
+ *        - They have no children.
+ *        - They define the behaviour of the primitive objects.
+ */ 
+class Line : public Graphic {
+public:
+  void draw(void) const override { std::cout << "Line\n"; }
+};
+
+class Rectangle : public Graphic {
+public:
+  void draw(void) const override { std::cout << "Rectangle\n"; }
+};
+
+class Text : public Graphic {
+public:
+  void draw(void) const override { std::cout << "Text\n"; }
+};
+
+
+// --------- COMPOSITE --------- //
+/*!
+ * @brief Composite - Composite objects
+ *        - Stores children (Leaf or Composite)
+ *        - Implement the Component interface for
+ *          the child-related operations
+ */ 
+class Picture : public Graphic {
+public:
+  Picture(std::string&& p_name = ""): m_name(p_name) {}
+  virtual ~Picture() = default; 
+
+  virtual bool isComposite(void) const override { return true; }
+
+  void draw(void) const override {
+    std::for_each( std::begin(m_sons), 
+                   std::end  (m_sons), 
+                   [](Graphic* it){ it->draw(); } );
+  }
+ 
+  void add   (Graphic* p_elem) { m_sons.push_back(p_elem); }
+  void remove(Graphic* p_elem) { 
+    m_sons.erase(std::remove(std::begin(m_sons), 
+                             std::end  (m_sons), 
+                             p_elem), std::end  (m_sons));
+}
+
+private:
+  std::vector<Graphic*> m_sons;
+  std::string           m_name;
+
+};
+ 
+// --------- CLIENT CODE --------- //
+/*!
+ * @brief : Client Code 
+ * Can work with Picture just as if
+ * it was a Leaf.
+ */
+int main()
+{
+  Line      line; line.draw();
+  Rectangle rect; rect.draw();
+  Text      text; text.draw();
+
+  std::cout << std::endl;
+  
+  Picture pic;
+  pic.add(&line);
+  pic.add(&rect);
+  pic.add(&text);
+  pic.draw();
+
+  return 0;
+}