/
package.h
188 lines (154 loc) · 5.39 KB
/
package.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
/** @file package.h Package containing metadata, data, and/or files.
*
* @authors Copyright (c) 2014 Jaakko Keränen <jaakko.keranen@iki.fi>
*
* @par License
* LGPL: http://www.gnu.org/licenses/lgpl.html
*
* <small>This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU Lesser General Public License as published by
* the Free Software Foundation; either version 3 of the License, or (at your
* option) any later version. This program is distributed in the hope that it
* will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
* of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser
* General Public License for more details. You should have received a copy of
* the GNU Lesser General Public License along with this program; if not, see:
* http://www.gnu.org/licenses</small>
*/
#ifndef LIBDENG2_PACKAGE_H
#define LIBDENG2_PACKAGE_H
#include "../String"
#include "../File"
#include <QSet>
namespace de {
class Package;
/**
* Container package with metadata, data, and/or files.
* @ingroup fs
*
* A @em package is a collection of files packaged into a single unit (possibly using an
* Archive). Examples of packages are add-on packages (in various formats, e.g., PK3/ZIP
* archive or the Snowberry add-on bundle), savegames, custom maps, and demos.
*
* An instance of Package represents a package that is currently loaded. Note that
* the package's metadata namespace is owned by the file that contains the package;
* Package only consists of state that is relevant while the package is loaded (i.e.,
* in active use).
*/
class DENG2_PUBLIC Package
{
public:
/// Package's source is missing or inaccessible. @ingroup errors
DENG2_ERROR(SourceError);
/// Package fails validation. @ingroup errors
DENG2_ERROR(ValidationError);
/// Package is missing some required metadata. @ingroup errors
DENG2_SUB_ERROR(ValidationError, IncompleteMetadataError);
typedef QSet<String> Assets;
/**
* Utility for accessing asset metadata. @ingroup fs
*/
class DENG2_PUBLIC Asset : public RecordAccessor
{
public:
Asset(Record const &rec);
Asset(Record const *rec);
/**
* Retrieves the value of a variable and resolves it to an absolute path in
* relation to the asset.
*
* @param varName Variable name in the package asset metadata.
*
* @return Absolute path.
*
* @see ScriptedInfo::absolutePathInContext()
*/
String absolutePath(String const &varName) const;
};
public:
/**
* Creates a package whose data comes from a file. The file's metadata is used
* as the package's metadata namespace.
*
* @param file File or folder containing the package's contents.
*/
Package(File const &file);
virtual ~Package();
File const &file() const;
/**
* Returns the package's root folder, if it has one. Returns @c NULL if the package
* is "flat" and comes with no folder structure.
*/
Folder const &root() const;
Record &info();
Record const &info() const;
/**
* Returns the unique package identifier. This is the file name of the package
* without any file extension.
*/
String identifier() const;
/**
* Composes a list of assets contained in the package.
*
* @return Assets declared in the package metadata.
*/
Assets assets() const;
/**
* Executes a script function in the metadata of the package.
*
* @param name Name of the function to call.
*
* @return @c true, if the function exists and was called. @c false, if the
* function was not found.
*/
bool executeFunction(String const &name);
void setOrder(int ordinal);
int order() const;
/**
* Called by PackageLoader after the package has been marked as loaded.
*/
virtual void didLoad();
/**
* Called by PackageLoader immediately before the package is marked as unloaded.
*/
virtual void aboutToUnload();
public:
/**
* Parse the embedded metadata found in a package file.
*
* @param packageFile File containing a package.
*/
static void parseMetadata(File &packageFile);
/**
* Checks that all the metadata seems legit. An IncompleteMetadataError or
* another exception is thrown if the package is not deemed valid.
*
* @param packageInfo Metadata to validate.
*/
static void validateMetadata(Record const &packageInfo);
static QStringList tags(File const &packageFile);
static String identifierForFile(File const &file);
/**
* Locates the file that represents the package where @a file is in.
*
* @param file File.
*
* @return Containing package, or nullptr if the file is not inside a package.
*/
static File const *containerOfFile(File const &file);
static String identifierForContainerOfFile(File const &file);
/**
* Finds the package that contains @a file and returns its modification time.
* If the file doesn't appear to be inside a package, returns the file's
* modification time.
*
* @param file File.
*
* @return Modification time of file or package.
*/
static Time containerOfFileModifiedAt(File const &file);
private:
DENG2_PRIVATE(d)
};
} // namespace de
#endif // LIBDENG2_PACKAGE_H