OpenWalnut  1.4.0
WModuleMetaInformation.h
00001 //---------------------------------------------------------------------------
00002 //
00003 // Project: OpenWalnut ( http://www.openwalnut.org )
00004 //
00005 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
00006 // For more information see http://www.openwalnut.org/copying
00007 //
00008 // This file is part of OpenWalnut.
00009 //
00010 // OpenWalnut is free software: you can redistribute it and/or modify
00011 // it under the terms of the GNU Lesser General Public License as published by
00012 // the Free Software Foundation, either version 3 of the License, or
00013 // (at your option) any later version.
00014 //
00015 // OpenWalnut is distributed in the hope that it will be useful,
00016 // but WITHOUT ANY WARRANTY; without even the implied warranty of
00017 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00018 // GNU Lesser General Public License for more details.
00019 //
00020 // You should have received a copy of the GNU Lesser General Public License
00021 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
00022 //
00023 //---------------------------------------------------------------------------
00024 
00025 #ifndef WMODULEMETAINFORMATION_H
00026 #define WMODULEMETAINFORMATION_H
00027 
00028 #include <string>
00029 #include <vector>
00030 
00031 #include <boost/shared_ptr.hpp>
00032 #include <boost/filesystem/path.hpp>
00033 
00034 #include "../common/WStructuredTextParser.h"
00035 
00036 class WModule;
00037 
00038 /**
00039  * A class abstracting module meta information. It encapsulates module name, description, icon, author lists, help resources, online resources
00040  * and much more. It is guaranteed to, at least, provide a module name. Everything else is optional. It also encapsulates the
00041  * WStructuredTextParser class for loading the data.
00042  */
00043 class WModuleMetaInformation
00044 {
00045 public:
00046     /**
00047      * Convenience typedef for a boost::shared_ptr< WModuleMetaInformation >.
00048      */
00049     typedef boost::shared_ptr< WModuleMetaInformation > SPtr;
00050 
00051     /**
00052      * Convenience typedef for a boost::shared_ptr< const WModuleMetaInformation >.
00053      */
00054     typedef boost::shared_ptr< const WModuleMetaInformation > ConstSPtr;
00055 
00056     ///////////////////////////////////////////////////////////////////////////////////////////////
00057     // these are some structs to simply handling of the meta file structures
00058 
00059     /**
00060      * Structure to contain all supported author information
00061      */
00062     struct Author
00063     {
00064         /**
00065          * Author name. Will never be empty.
00066          */
00067         std::string m_name;
00068 
00069         /**
00070          * URL to a website of the author. Can be empty.
00071          */
00072         std::string m_url;
00073 
00074         /**
00075          * E-Mail contact to the author. Can be empty.
00076          */
00077         std::string m_email;
00078 
00079         /**
00080          * What has this author done on the module? Can be empty.
00081          */
00082         std::string m_what;
00083     };
00084 
00085     /**
00086      * Structure to encapsulate the META info online resources.
00087      */
00088     struct Online
00089     {
00090         /**
00091          * Online resource's name.
00092          */
00093         std::string m_name;
00094 
00095         /**
00096          * Online resource's description.
00097          */
00098         std::string m_description;
00099 
00100         /**
00101          * The url to the resource.
00102          */
00103         std::string m_url;
00104     };
00105 
00106     /**
00107      * Structure to encapsulate a screenshot info
00108      */
00109     struct Screenshot
00110     {
00111         /**
00112          * The screenshot filename
00113          */
00114         boost::filesystem::path m_filename;
00115 
00116         /**
00117          * The description text shown for the screenshot.
00118          */
00119         std::string m_description;
00120     };
00121 
00122     /**
00123      * Constructor. The help object will be empty, meaning there is no further meta info available. The name is the only required value. Of
00124      * course, this is of limited use in most cases.
00125      *
00126      * \param name the name of the module
00127      */
00128     explicit WModuleMetaInformation( std::string name );
00129 
00130     /**
00131      * Construct a meta info object that loads all information from the specified file. If the file exist and could not be parsed, only
00132      * an error log is printed. No exception is thrown.
00133      *
00134      * \param module The module to load the meta file for.
00135      */
00136     explicit WModuleMetaInformation( boost::shared_ptr< WModule > module );
00137 
00138     /**
00139      * Destructor. Cleans internal list.
00140      */
00141     virtual ~WModuleMetaInformation();
00142 
00143     /**
00144      * The name of the module. Will always return the name of the module given on construction.
00145      *
00146      * \return the name
00147      */
00148     std::string getName() const;
00149 
00150     /**
00151      * Get the icon path. Can be invalid. Check for existence before opening.
00152      *
00153      * \return the path to the icon file
00154      */
00155     boost::filesystem::path getIcon() const;
00156 
00157     /**
00158      * Check whether the meta info contained an icon.
00159      *
00160      * \return true if icon is available. Does not check existence or validity of image file.
00161      */
00162     bool isIconAvailable() const;
00163 
00164     /**
00165      * The URL to a module website. Can be empty.
00166      *
00167      * \return URL to website
00168      */
00169     std::string getWebsite() const;
00170 
00171     /**
00172      * A module description. Can be empty but is initialized with the description of the module given on construction.
00173      *
00174      * \return the description.
00175      */
00176     std::string getDescription() const;
00177 
00178     /**
00179      * Path to a text or HTML file containing some module help. Can be invalid. Check for existence before opening.
00180      *
00181      * \return the path to help
00182      */
00183     boost::filesystem::path getHelp() const;
00184 
00185     /**
00186      * A list of authors. If the META file did not contain any author information, this returns the OpenWalnut Team as author.
00187      *
00188      * \return Author list.
00189      */
00190     std::vector< Author > getAuthors() const;
00191 
00192     /**
00193      * A list of online resources. Can be empty.
00194      *
00195      * \return list of online material
00196      */
00197     std::vector< Online > getOnlineResources() const;
00198 
00199     /**
00200      * A list of tags provided for the module.
00201      *
00202      * \return the tag list.
00203      */
00204     std::vector< std::string > getTags() const;
00205 
00206     /**
00207      * Returns the list of screenshots.
00208      *
00209      * \return the screenshot list.
00210      */
00211     std::vector< Screenshot > getScreenshots() const;
00212 protected:
00213 private:
00214     /**
00215      * The name of the module providing this meta information.
00216      */
00217     std::string m_name;
00218 
00219     /**
00220      * The default description if none was specified in the META file. Initialized with the description of the module specified during
00221      * construction.
00222      */
00223     std::string m_description;
00224 
00225     /**
00226      * The tree representing the data
00227      */
00228     WStructuredTextParser::StructuredValueTree m_metaData;
00229 
00230     /**
00231      * If true, m_metaData should be queried in all getters. If false, you can query m_meta but it will only tell you that the desired value
00232      * could not be found.
00233      */
00234     bool m_loaded;
00235 
00236     /**
00237      * The module local path. Used for several meta infos returning a path.
00238      */
00239     boost::filesystem::path m_localPath;
00240 };
00241 
00242 #endif  // WMODULEMETAINFORMATION_H
00243