[DECORATOR]: Added ressources and example code for Decorator pattern.

Author: MericLuc

structural-patterns/decorator/README.md

@@ -1,3 +1,58 @@
-# TODO
+Also known as **Wrapper**.
 
-Stay tuned, this section will be completed shortly !
+# Intend
+
+**Dynamically attach responsabilities to an object**.
+
+It provides a flexible alternative to subclassing for extending functionality.
+
+You should use the _Decorator_ pattern in the following cases :
+ - You want to **provide individual objects** (not an entire class) **with a new behaviour**.
+ - You want to **add responsabilities _dynamically_ and _transparently_**.
+ - When the alternative (_extension by subclassing_) is impractical :
+   - When it would produce an explosion of subclasses to support every combination.
+   - The class definition is hidden or unavailable for subclassing.
+
+# How it's done
+
+![UML](UML.jpg)
+
+**Participants**
+
+ - _Component_ : The interface for objects that can have responsabilities dynamically added.
+ - _ConcreteComponent_ : The objects to which responsabilities can be added.
+ - _Decorator_ : Defines an interface that conforms to _Component_'s interface.
+ Maintain a reference to a _Component_ object (_wrappee_).
+ - _ConcreteDecorator_ : The object that adds responsabilities to _ConcreteComponent_.
+
+**How to implement**
+
+ 1. **Create an interface** and declare the methods common to both the primary _Component_ and the optional layers.
+ 2. **Create your _ConcreteComponent_** class with its base behaviour.
+ 3. **Create your _Decorator_** class with a field storing a reference to the wrapped object (Your _Component_). The _Decorator_ will delegate all the work (i.e. except for the additional responsabilities) to the wrapped object.
+ 4. **Create your _ConcreteDecorator_** and implement the additional responsabilities before or after the call to the _wrappee_ behaviour.
+
+Note : The _Client_ can then **create and compose _ConcreteDecorators_** in the way he needs.
+
+Note : UML class diagram taken from [**here**](https://upload.wikimedia.org/wikipedia/commons/8/83/W3sDesign_Decorator_Design_Pattern_UML.jpg)
+
+# Pros & cons
+
+**Pros**
+
+ - **Extend** an object's behaviour without subclassing.
+ - **Add responsabilities at runtime**.
+ - **Combine behaviours** (decorators composition) to suit your needs.
+ - **Single responsability principle** : Divide monolithic classes into many classes with unique responsabilities.
+
+
+**Cons**
+
+ - It is hard to **remove a decorator** once it has been added.
+ - **Order** : It might be difficult to implement decorators in a way they are order-independant.
+
+# Notes
+
+Here are some _usefull ressources_ :
+ - A [Refactoring guru](https://refactoring.guru/design-patterns/decorator) article.
+ - A complete example [here](https://www.bogotobogo.com/DesignPatterns/decorator.php)

structural-patterns/decorator/UML.jpg

@@ -0,0 +1,120 @@
+// Rewritten example - Original here
+// https://en.wikipedia.org/wiki/Decorator_pattern#UML_class_and_sequence_diagram
+
+#include <memory>
+#include <iostream>
+#include <string>
+
+/*!
+ * @brief : Component - defines the interface of the
+ *          objects you want to provide additional layers
+ *          of behaviours to.
+ */
+class WebPage
+{
+public:
+    virtual void display(void) const = 0;
+    virtual ~WebPage() = default;
+};
+
+/*!
+ * @brief : ConcreteComponent - The objects you want to
+ *          be able to add responsabilities to.
+ */
+class BasicWebPage : public WebPage
+{
+public:
+    void display(void) const override { std::cout << "Basic WEB page" << std::endl; }
+
+     BasicWebPage(std::string&& p_html = "") : m_html(p_html) {}
+    ~BasicWebPage()=default;
+
+private:
+    std::string m_html;
+};
+
+/*!
+ * @brief : Decorator - Interface that conforms to WebPage interface
+ *          Keep a reference (in that case a std::unique_ptr) on the
+ *          WebPage object.
+ */
+class WebPageDecorator : public WebPage
+{
+public:
+    WebPageDecorator(std::unique_ptr<WebPage> webPage): _webPage(std::move(webPage)) {}
+    ~WebPageDecorator()=default;
+
+    /*!
+     * @brief : Note that the "basic behaviour" is still realized by the wrappee.
+     */
+    void display(void) const override { _webPage->display(); }
+
+private:
+    std::unique_ptr<WebPage> _webPage;
+};
+
+/*!
+ * @brief : ConcreteDecorator1 - Implements the new behaviour
+ *          added to the wrappee.
+ */
+class AuthenticatedWebPage : public WebPageDecorator
+{
+public:
+    AuthenticatedWebPage(std::unique_ptr<WebPage> webPage):
+    WebPageDecorator(std::move(webPage)) {}
+    ~AuthenticatedWebPage()=default;
+
+    /*!
+     * @brief : New behaviour enhanced by the ConcreteDecorator
+     */
+    void display(void) const override
+    {
+        // Could be in any order
+        authenticateUser();
+        WebPageDecorator::display();
+    }
+
+private:
+    void authenticateUser(void) const { std::cout << "authentification done" << std::endl; }
+};
+
+/*!
+ * @brief : ConcreteDecorator2 - Implements the new behaviour
+ *          added to the wrappee.
+ */
+class AuthorizedWebPage : public WebPageDecorator
+{
+public:
+    AuthorizedWebPage(std::unique_ptr<WebPage> webPage):
+    WebPageDecorator(std::move(webPage)) {}
+    ~AuthorizedWebPage()=default;
+
+    void display(void) const override
+    {
+        // Once again, could be in any order
+        WebPageDecorator::display();
+        authorizedUser();
+    }
+
+private:
+    void authorizedUser(void) const { std::cout << "authorized done" << std::endl; }
+};
+
+int main()
+{
+    std::unique_ptr<WebPage> myPage = std::make_unique<BasicWebPage>();
+    std::cout << "     ---    ConcreteComponent     --- " << std::endl;
+    myPage->display();
+
+    myPage = std::make_unique<AuthorizedWebPage   >(std::move(myPage));
+    std::cout << "     --- Added ConcreteDecorator1 --- " << std::endl;
+    myPage->display();
+
+    myPage = std::make_unique<AuthenticatedWebPage>(std::move(myPage));
+    std::cout << "     --- Added ConcreteDecorator2 --- " << std::endl;
+    myPage->display();
+
+    std::cout << std::endl;
+
+    return 0;
+}