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 #include <boost/shared_ptr.hpp>
32 #include <boost/filesystem/path.hpp>
33 
34 #include "../common/WStructuredTextParser.h"
35 
36 class WModule;
37 
38 /**
39  * A class abstracting module meta information. It encapsulates module name, description, icon, author lists, help resources, online resources
40  * and much more. It is guaranteed to, at least, provide a module name. Everything else is optional. It also encapsulates the
41  * WStructuredTextParser class for loading the data.
42  */
44 {
45 public:
46  /**
47  * Convenience typedef for a boost::shared_ptr< WModuleMetaInformation >.
48  */
49  typedef boost::shared_ptr< WModuleMetaInformation > SPtr;
50 
51  /**
52  * Convenience typedef for a boost::shared_ptr< const WModuleMetaInformation >.
53  */
54  typedef boost::shared_ptr< const WModuleMetaInformation > ConstSPtr;
55 
56  ///////////////////////////////////////////////////////////////////////////////////////////////
57  // these are some structs to simply handling of the meta file structures
58 
59  /**
60  * Structure to contain all supported author information
61  */
62  struct Author
63  {
64  /**
65  * Author name. Will never be empty.
66  */
67  std::string m_name;
68 
69  /**
70  * URL to a website of the author. Can be empty.
71  */
72  std::string m_url;
73 
74  /**
75  * E-Mail contact to the author. Can be empty.
76  */
77  std::string m_email;
78 
79  /**
80  * What has this author done on the module? Can be empty.
81  */
82  std::string m_what;
83  };
84 
85  /**
86  * Structure to encapsulate the META info online resources.
87  */
88  struct Online
89  {
90  /**
91  * Online resource's name.
92  */
93  std::string m_name;
94 
95  /**
96  * Online resource's description.
97  */
98  std::string m_description;
99 
100  /**
101  * The url to the resource.
102  */
103  std::string m_url;
104  };
105 
106  /**
107  * Structure to encapsulate a screenshot info
108  */
109  struct Screenshot
110  {
111  /**
112  * The screenshot filename
113  */
114  boost::filesystem::path m_filename;
115 
116  /**
117  * The description text shown for the screenshot.
118  */
119  std::string m_description;
120  };
121 
122  /**
123  * Constructor. The help object will be empty, meaning there is no further meta info available. The name is the only required value. Of
124  * course, this is of limited use in most cases.
125  *
126  * \param name the name of the module
127  */
128  explicit WModuleMetaInformation( std::string name );
129 
130  /**
131  * Construct a meta info object that loads all information from the specified file. If the file exist and could not be parsed, only
132  * an error log is printed. No exception is thrown.
133  *
134  * \param module The module to load the meta file for.
135  */
136  explicit WModuleMetaInformation( boost::shared_ptr< WModule > module );
137 
138  /**
139  * Destructor. Cleans internal list.
140  */
141  virtual ~WModuleMetaInformation();
142 
143  /**
144  * The name of the module. Will always return the name of the module given on construction.
145  *
146  * \return the name
147  */
148  std::string getName() const;
149 
150  /**
151  * Get the icon path. Can be invalid. Check for existence before opening.
152  *
153  * \return the path to the icon file
154  */
155  boost::filesystem::path getIcon() const;
156 
157  /**
158  * Check whether the meta info contained an icon.
159  *
160  * \return true if icon is available. Does not check existence or validity of image file.
161  */
162  bool isIconAvailable() const;
163 
164  /**
165  * The URL to a module website. Can be empty.
166  *
167  * \return URL to website
168  */
169  std::string getWebsite() const;
170 
171  /**
172  * A module description. Can be empty but is initialized with the description of the module given on construction.
173  *
174  * \return the description.
175  */
176  std::string getDescription() const;
177 
178  /**
179  * Path to a text or HTML file containing some module help. Can be invalid. Check for existence before opening.
180  *
181  * \return the path to help
182  */
183  boost::filesystem::path getHelp() const;
184 
185  /**
186  * A list of authors. If the META file did not contain any author information, this returns the OpenWalnut Team as author.
187  *
188  * \return Author list.
189  */
190  std::vector< Author > getAuthors() const;
191 
192  /**
193  * A list of online resources. Can be empty.
194  *
195  * \return list of online material
196  */
197  std::vector< Online > getOnlineResources() const;
198 
199  /**
200  * A list of tags provided for the module.
201  *
202  * \return the tag list.
203  */
204  std::vector< std::string > getTags() const;
205 
206  /**
207  * Returns the list of screenshots.
208  *
209  * \return the screenshot list.
210  */
211  std::vector< Screenshot > getScreenshots() const;
212 protected:
213 private:
214  /**
215  * The name of the module providing this meta information.
216  */
217  std::string m_name;
218 
219  /**
220  * The default description if none was specified in the META file. Initialized with the description of the module specified during
221  * construction.
222  */
223  std::string m_description;
224 
225  /**
226  * The tree representing the data
227  */
229 
230  /**
231  * 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
232  * could not be found.
233  */
234  bool m_loaded;
235 
236  /**
237  * The module local path. Used for several meta infos returning a path.
238  */
239  boost::filesystem::path m_localPath;
240 };
241 
242 #endif // WMODULEMETAINFORMATION_H
243