OpenWalnut  1.4.0
WModuleMetaInformation.h
1 //---------------------------------------------------------------------------
2 //
3 // Project: OpenWalnut ( http://www.openwalnut.org )
4 //
5 // Copyright 2009 OpenWalnut Community, BSV@Uni-Leipzig and CNCF@MPI-CBS
6 // For more information see http://www.openwalnut.org/copying
7 //
8 // This file is part of OpenWalnut.
9 //
10 // OpenWalnut is free software: you can redistribute it and/or modify
11 // it under the terms of the GNU Lesser General Public License as published by
12 // the Free Software Foundation, either version 3 of the License, or
13 // (at your option) any later version.
14 //
15 // OpenWalnut is distributed in the hope that it will be useful,
16 // but WITHOUT ANY WARRANTY; without even the implied warranty of
17 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
18 // GNU Lesser General Public License for more details.
19 //
20 // You should have received a copy of the GNU Lesser General Public License
21 // along with OpenWalnut. If not, see <http://www.gnu.org/licenses/>.
22 //
23 //---------------------------------------------------------------------------
24 
25 #ifndef WMODULEMETAINFORMATION_H
26 #define WMODULEMETAINFORMATION_H
27 
28 #include <string>
29 #include <vector>
30 
31 #ifndef Q_MOC_RUN
32 #include <boost/shared_ptr.hpp>
33 #endif
34 #ifndef Q_MOC_RUN
35 #include <boost/filesystem/path.hpp>
36 #endif
37 
38 #include "../common/WStructuredTextParser.h"
39 
40 class WModule;
41 
42 /**
43  * A class abstracting module meta information. It encapsulates module name, description, icon, author lists, help resources, online resources
44  * and much more. It is guaranteed to, at least, provide a module name. Everything else is optional. It also encapsulates the
45  * WStructuredTextParser class for loading the data.
46  */
48 {
49 public:
50  /**
51  * Convenience typedef for a boost::shared_ptr< WModuleMetaInformation >.
52  */
53  typedef boost::shared_ptr< WModuleMetaInformation > SPtr;
54 
55  /**
56  * Convenience typedef for a boost::shared_ptr< const WModuleMetaInformation >.
57  */
58  typedef boost::shared_ptr< const WModuleMetaInformation > ConstSPtr;
59 
60  ///////////////////////////////////////////////////////////////////////////////////////////////
61  // these are some structs to simply handling of the meta file structures
62 
63  /**
64  * Structure to contain all supported author information
65  */
66  struct Author
67  {
68  /**
69  * Author name. Will never be empty.
70  */
71  std::string m_name;
72 
73  /**
74  * URL to a website of the author. Can be empty.
75  */
76  std::string m_url;
77 
78  /**
79  * E-Mail contact to the author. Can be empty.
80  */
81  std::string m_email;
82 
83  /**
84  * What has this author done on the module? Can be empty.
85  */
86  std::string m_what;
87  };
88 
89  /**
90  * Structure to encapsulate the META info online resources.
91  */
92  struct Online
93  {
94  /**
95  * Online resource's name.
96  */
97  std::string m_name;
98 
99  /**
100  * Online resource's description.
101  */
102  std::string m_description;
103 
104  /**
105  * The url to the resource.
106  */
107  std::string m_url;
108  };
109 
110  /**
111  * Structure to encapsulate a screenshot info
112  */
113  struct Screenshot
114  {
115  /**
116  * The screenshot filename
117  */
118  boost::filesystem::path m_filename;
119 
120  /**
121  * The description text shown for the screenshot.
122  */
123  std::string m_description;
124  };
125 
126  /**
127  * Constructor. The help object will be empty, meaning there is no further meta info available. The name is the only required value. Of
128  * course, this is of limited use in most cases.
129  *
130  * \param name the name of the module
131  */
132  explicit WModuleMetaInformation( std::string name );
133 
134  /**
135  * Construct a meta info object that loads all information from the specified file. If the file exist and could not be parsed, only
136  * an error log is printed. No exception is thrown.
137  *
138  * \param module The module to load the meta file for.
139  */
140  explicit WModuleMetaInformation( boost::shared_ptr< WModule > module );
141 
142  /**
143  * Destructor. Cleans internal list.
144  */
145  virtual ~WModuleMetaInformation();
146 
147  /**
148  * The name of the module. Will always return the name of the module given on construction.
149  *
150  * \return the name
151  */
152  std::string getName() const;
153 
154  /**
155  * Get the icon path. Can be invalid. Check for existence before opening.
156  *
157  * \return the path to the icon file
158  */
159  boost::filesystem::path getIcon() const;
160 
161  /**
162  * Check whether the meta info contained an icon.
163  *
164  * \return true if icon is available. Does not check existence or validity of image file.
165  */
166  bool isIconAvailable() const;
167 
168  /**
169  * The URL to a module website. Can be empty.
170  *
171  * \return URL to website
172  */
173  std::string getWebsite() const;
174 
175  /**
176  * A module description. Can be empty but is initialized with the description of the module given on construction.
177  *
178  * \return the description.
179  */
180  std::string getDescription() const;
181 
182  /**
183  * Path to a text or HTML file containing some module help. Can be invalid. Check for existence before opening.
184  *
185  * \return the path to help
186  */
187  boost::filesystem::path getHelp() const;
188 
189  /**
190  * A list of authors. If the META file did not contain any author information, this returns the OpenWalnut Team as author.
191  *
192  * \return Author list.
193  */
194  std::vector< Author > getAuthors() const;
195 
196  /**
197  * A list of online resources. Can be empty.
198  *
199  * \return list of online material
200  */
201  std::vector< Online > getOnlineResources() const;
202 
203  /**
204  * A list of tags provided for the module.
205  *
206  * \return the tag list.
207  */
208  std::vector< std::string > getTags() const;
209 
210  /**
211  * Returns the list of screenshots.
212  *
213  * \return the screenshot list.
214  */
215  std::vector< Screenshot > getScreenshots() const;
216 protected:
217 private:
218  /**
219  * The name of the module providing this meta information.
220  */
221  std::string m_name;
222 
223  /**
224  * The default description if none was specified in the META file. Initialized with the description of the module specified during
225  * construction.
226  */
227  std::string m_description;
228 
229  /**
230  * The tree representing the data
231  */
232  WStructuredTextParser::StructuredValueTree m_metaData;
233 
234  /**
235  * 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
236  * could not be found.
237  */
238  bool m_loaded;
239 
240  /**
241  * The module local path. Used for several meta infos returning a path.
242  */
243  boost::filesystem::path m_localPath;
244 };
245 
246 #endif // WMODULEMETAINFORMATION_H
247 
WModuleMetaInformation(std::string name)
Constructor.
std::vector< Screenshot > getScreenshots() const
Returns the list of screenshots.
boost::filesystem::path m_filename
The screenshot filename.
boost::filesystem::path m_localPath
The module local path.
std::string getName() const
The name of the module.
boost::shared_ptr< const WModuleMetaInformation > ConstSPtr
Convenience typedef for a boost::shared_ptr< const WModuleMetaInformation >.
std::vector< std::string > getTags() const
A list of tags provided for the module.
Class representing a single module of OpenWalnut.
Definition: WModule.h:83
std::vector< Online > getOnlineResources() const
A list of online resources.
WStructuredTextParser::StructuredValueTree m_metaData
The tree representing the data.
boost::shared_ptr< WModuleMetaInformation > SPtr
Convenience typedef for a boost::shared_ptr< WModuleMetaInformation >.
virtual ~WModuleMetaInformation()
Destructor.
std::string m_url
The url to the resource.
std::string m_description
The description text shown for the screenshot.
boost::filesystem::path getHelp() const
Path to a text or HTML file containing some module help.
std::string m_url
URL to a website of the author.
Structure to encapsulate the META info online resources.
bool isIconAvailable() const
Check whether the meta info contained an icon.
std::vector< Author > getAuthors() const
A list of authors.
std::string m_description
Online resource's description.
std::string m_what
What has this author done on the module? Can be empty.
Structure to encapsulate a screenshot info.
std::string m_description
The default description if none was specified in the META file.
Structure to contain all supported author information.
std::string getDescription() const
A module description.
std::string m_name
Online resource's name.
std::string m_email
E-Mail contact to the author.
boost::filesystem::path getIcon() const
Get the icon path.
A class abstracting module meta information.
bool m_loaded
If true, m_metaData should be queried in all getters.
std::string getWebsite() const
The URL to a module website.
std::string m_name
The name of the module providing this meta information.