Changes between Initial Version and Version 1 of WritingNewClasses


Ignore:
Timestamp:
Jul 29, 2018 1:33:37 AM (11 months ago)
Author:
tirons
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WritingNewClasses

    v1 v1  
     1== Writing a new Lemma Class ==
     2This guideline provides a way to add a new class to Lemma. First you need to decide what Module you will be contributing to. For this example, we will be adding a new class RectilinearGridVTKImporter to !LemmaCore. We provide some vim tools to help with boilerplate which are located at `Lemma/vim`. Keep in mind the LemmaStyleGuide.
     3
     41. Create a new file with your class name. Note that Lemma uses mixed case filenames, and most POSIX systems are case sensitive. As such we create new files `RectilinearGridVTKImporter.h` and `RectilinearGridVTKImporter.cpp` which are located in the `Lemma/Modules/LemmaCore/include` and `Lemma/Modules/LemmaCore/src` directories of `Lemma`.
     52. Use standard include guards, in the case that your class has a intrinsic dependency on VTK you may also add such an include guard for that.
     6{{{
     7#!div style="font-size: 80%"
     8  {{{#!cpp
     9  #ifndef  RECTILINEARGRIDVTKIMPORTER_INC
     10  #define  RECTILINEARGRIDVTKIMPORTER_INC
     11
     12  #ifdef  LEMMAUSEVTK
     13
     14  #endif      // -----  LEMMAUSEVTK  -----
     15
     16  #endif   // ----- #ifndef RECTILINEARGRIDVTKIMPORTER_INC  -----
     17  }}}
     18}}}
     19
     203. Use the ''c-support'' vim extension to write your class definition, this is found under C/C++ --> C++ --> Lemma class. The extension will query you for the module, base class, and class name; in this case `LemmaCore`, `LemmaObject`, and `RectilinearGridVTKImporter` respectively. This will populate the class with most of the boilerplate and some basic Doxygen documentation.
     21
     22{{{
     23#!div style="font-size: 80%"
     24{{{#!cpp
     25#ifndef  RECTILINEARGRIDVTKIMPORTER_INC
     26#define  RECTILINEARGRIDVTKIMPORTER_INC
     27
     28#ifdef  LEMMAUSEVTK
     29
     30#pragma once
     31#include "LemmaObject.h"
     32
     33namespace Lemma {
     34
     35    /**
     36     * \ingroup LemmaCore
     37     * \brief
     38     * \details
     39     */
     40    class RectilinearGridVTKImporter : public LemmaObject {
     41
     42        friend std::ostream &operator<<(std::ostream &stream, const RectilinearGridVTKImporter &ob);
     43
     44        protected:
     45        /*
     46         *  This key is used to lock the constructor. It is protected so that inhereted
     47         *  classes also have the key to contruct their base class.
     48         */
     49        struct ctor_key {};
     50
     51        public:
     52
     53        // ====================  LIFECYCLE     =======================
     54
     55        /**
     56         * Default constructor.
     57         * @note This method is locked, and cannot be called directly.
     58         *       The reason that the method is public is to enable the use
     59         *       of make_shared whilst enforcing the use of shared_ptr,
     60         *       in c++-17, this curiosity may be resolved.
     61         * @see RectilinearGridVTKImporter::NewSP
     62         */
     63        explicit RectilinearGridVTKImporter ( const ctor_key& );
     64
     65        /**
     66         * DeSerializing constructor.
     67         * @note This method is locked, and cannot be called directly.
     68         *       The reason that the method is public is to enable the use
     69         *       of make_shared whilst enforcing the use of shared_ptr,
     70         *       in c++-17, this curiosity may be resolved.
     71         * @see RectilinearGridVTKImporter::DeSerialize
     72         */
     73        RectilinearGridVTKImporter ( const YAML::Node& node, const ctor_key& );
     74
     75        /**
     76         * Default destructor.
     77         * @note This method should never be called due to the mandated
     78         *       use of smart pointers. It is necessary to keep the method
     79         *       public in order to allow for the use of the more efficient
     80         *       make_shared constructor.
     81         */
     82        virtual ~RectilinearGridVTKImporter ();
     83
     84        /**
     85         *  Uses YAML to serialize this object.
     86         *  @return a YAML::Node
     87         *  @see RectilinearGridVTKImporter::DeSerialize
     88         */
     89        virtual YAML::Node Serialize() const;
     90
     91        /*
     92         *  Factory method for generating concrete class.
     93         *  @return a std::shared_ptr of type RectilinearGridVTKImporter
     94         */
     95        static std::shared_ptr< RectilinearGridVTKImporter > NewSP();
     96
     97        /**
     98         *   Constructs an RectilinearGridVTKImporter object from a YAML::Node.
     99         *   @see RectilinearGridVTKImporter::Serialize
     100         */
     101        static std::shared_ptr<RectilinearGridVTKImporter> DeSerialize(const YAML::Node& node);
     102
     103        // ====================  OPERATORS     =======================
     104
     105        // ====================  OPERATIONS    =======================
     106
     107        // ====================  ACCESS        =======================
     108
     109        // ====================  INQUIRY       =======================
     110        /**
     111         *  Returns the name of the underlying class, similiar to Python's type
     112         *  @return string of class name
     113         */
     114        virtual inline std::string GetName() const {
     115            return CName;
     116        }
     117
     118        protected:
     119
     120        // ====================  LIFECYCLE     =======================
     121
     122        /** Copy is disabled */
     123        RectilinearGridVTKImporter( const RectilinearGridVTKImporter& ) = delete;
     124
     125        // ====================  DATA MEMBERS  =========================
     126
     127        private:
     128
     129        /** ASCII string representation of the class name */
     130        static constexpr auto CName = "RectilinearGridVTKImporter";
     131
     132    }; // -----  end of class  RectilinearGridVTKImporter  -----
     133
     134}  // -----  end of namespace Lemma ----
     135
     136/* vim: set tabstop=4 expandtab: */
     137/* vim: set filetype=cpp: */
     138
     139#endif      // -----  LEMMAUSEVTK  -----
     140
     141#endif   // ----- #ifndef RECTILINEARGRIDVTKIMPORTER_INC  -----
     142}}}
     143}}}
     144
     1454. Unless your class is header only, open the implementation file `RectilinearGridVTKImporter.cpp`, and fill the class with boilerplate using ''C/C++'' -->  ''C++'' --> ''IMPLEMENTATION'' --> ''Lemma class''.
     146
     1475. Register your new class in CMakeLists.txt in the source directory.
     148
     1496. Test compile your code, if it compiles, start hacking.