X-Git-Url: http://git.localhorst.tv/?a=blobdiff_plain;f=src%2Floader%2FInterpreter.h;h=1a73d2dce69c54591354a2ae09fdd9234d03df91;hb=ab063a95735fdb90e7c610015e9155283ba5eca6;hp=8c14d1e10435bd4615f4916c8b674fddb7803c72;hpb=0bbc2eda56eba3ea195c2043370ff4d3fd29ca79;p=l2e.git

diff --git a/src/loader/Interpreter.h b/src/loader/Interpreter.h
index 8c14d1e..1a73d2d 100644
--- a/src/loader/Interpreter.h
+++ b/src/loader/Interpreter.h
@@ -1,24 +1,9 @@
-/*
- * Interpreter.h
- *
- *  Created on: Aug 26, 2012
- *      Author: holy
- */
-
 #ifndef LOADER_INTERPRETER_H_
 #define LOADER_INTERPRETER_H_
 
-#include "fwd.h"
 #include "PagedAllocator.h"
 #include "ParsedSource.h"
-#include "TypeDescription.h"
-#include "../battle/fwd.h"
-#include "../common/fwd.h"
 #include "../common/Script.h"
-#include "../geometry/Vector.h"
-#include "../graphics/Color.h"
-#include "../graphics/ComplexAnimation.h"
-#include "../graphics/fwd.h"
 
 #include <map>
 #include <set>
@@ -41,23 +26,46 @@ public:
 	static const int STRING_ID = 7;
 	static const int VECTOR_ID = 8;
 
+	/// Instances of this class are thrown if an
+	/// interpretation error is encounteres such as a
+	/// reference to an undeclared or inlining of an undefined
+	/// object.
 	class Error: public std::runtime_error {
 	public:
-		Error(const std::string &msg) : std::runtime_error("interpreter error: " + msg) { }
+		Error(const std::string &msg)
+		: std::runtime_error("interpreter error: " + msg) { }
 	};
 
 public:
-	explicit Interpreter(const ParsedSource &source) : source(source), alloc(4096) { }
+	/// Create an interpreter that rads from given parsed
+	/// source.
+	/// After creation you should call ReadSource() before
+	/// querying e.g. with GetObject().
+	explicit Interpreter(const ParsedSource &source)
+	: source(source), alloc(4096) { }
 	~Interpreter();
 private:
 	Interpreter(const Interpreter &);
 	Interpreter &operator =(const Interpreter &);
 
 public:
+	/// Interpret all exported definitions of the underlying
+	/// source file.
 	void ReadSource();
+	/// Get an object of given type that is defined by given
+	/// name.
+	/// If the object identified by name is of another type,
+	/// a cast is performed for compatible types.
+	/// Error is thrown if the object is undefined or a cast
+	/// was unsuccessful.
 	void *GetObject(int typeId, const std::string &name);
 
+	/// Register the type descriptions of builtin types.
+	/// This should be called before any interpretation (like
+	/// calling ReadSource()) is performed.
 	static void CreateTypeDescriptions();
+	/// Represents a parsed definition with resulting type and
+	/// object IDs.
 	struct ParsedDefinition {
 		ParsedDefinition(const Definition *dfn, int type, int id)
 		: dfn(dfn), type(type), id(id) { }
@@ -65,42 +73,107 @@ public:
 		int type;
 		int id;
 	};
+	/// Represents a postponed object where the type and
+	/// target location are already known, but the definition
+	/// was not accessible at interpretation time.
+	/// It could become available later or be dynamically
+	/// linked by its identifier.
 	struct PostponedDefinition {
-		PostponedDefinition(int type, int id, std::ptrdiff_t offset, const char *identifier, int linkedType, bool inlined)
-		: type(type), id(id), offset(offset), identifier(identifier), linkedType(linkedType), inlined(inlined) { }
-		int type;
-		int id;
-		std::ptrdiff_t offset;
+		PostponedDefinition(
+				char *dest,
+				const char *identifier,
+				int type,
+				bool inlined,
+				bool aggregate)
+		: dest(dest)
+		, identifier(identifier)
+		, type(type)
+		, inlined(inlined)
+		, aggregate(aggregate) { }
+		char *dest;
 		const char *identifier;
-		int linkedType;
+		int type;
 		bool inlined;
+		bool aggregate;
 	};
 
-	const std::set<std::string> &ExportedIdentifiers() const { return source.Exports(); }
+	/// Get all the identifiers that are marked for export
+	/// by name in the source.
+	const std::set<std::string> &ExportedIdentifiers() const {
+		return source.Exports();
+	}
+	/// Get the object definition for given identifier.
 	const ParsedDefinition &GetDefinition(const std::string &identifier);
-	const std::map<std::string, SDL_Surface *> &Images() const { return imageCache; }
-	const std::vector<PostponedDefinition> &PostponedDefinitions() const { return postponedDefinitions; }
-	const std::map<int, std::vector<void *> > &Values() const { return values; }
+	/// Get all images reference by he source.
+	/// The returned map is indexed by filenames relative to
+	/// the source file and contains ready-to-blit surfaces.
+	const std::map<std::string, SDL_Surface *> &Images() const {
+		return imageCache;
+	}
+	/// Get all definitions that were postponed because they
+	/// were not in the parsed source.
+	const std::vector<PostponedDefinition> &PostponedDefinitions() const {
+		return postponedDefinitions;
+	}
+	/// A map of object id to object.
+	const std::map<int, std::vector<void *> > &Values() const {
+		return values;
+	}
 
 private:
+	/// Interpret given definition.
 	void ReadDefinition(const Definition &);
+	/// Interpret given definition as a literal.
 	void ReadLiteral(const Definition &);
+	/// Interpret given definition as a complex object.
 	void ReadObject(const Definition &);
 
+	/// Interpret given literal as an object of given type.
+	/// The resulting object shall be accessible by given ID
+	/// (whiich is already reserved) and be written to given
+	/// destination.
 	void ReadLiteral(int typeId, int id, char *dest, const Literal &);
+	/// Get an object of given type from given value.
+	/// The object will be registere as new and be given a
+	/// unique ID.
+	/// Any nested objects will be created likewise.
 	void *GetObject(int typeId, const Value &value);
+	/// Read an object of given type and properties into dest.
+	/// The object should alrady have an assigned identifier.
+	/// Pass -1 as ID if the object is anonymous.
+	/// Note that anonymous objects must not contain
+	/// references as they are excluded from linking.
 	void ReadObject(int typeId, int id, char *dest, const PropertyList &);
+	/// The function that does the actual compiling when you
+	/// call ReadScript(const vector<ScriptToken *> &).
 	void ReadScript(const std::vector<ScriptToken *> &, common::Script *);
+	/// Compile a tokenized script.
+	/// Storage for the script will be allocated as neccessary.
 	char *ReadScript(const std::vector<ScriptToken *> &);
+	/// Reinterpret dest as a script code and return a
+	/// reference to that.
 	common::Script::Code &CreateScriptCode(common::Script::Command c, char *dest);
+	/// Write address to dest.
 	void ReadScriptAddress(const ScriptToken &t, char *dest);
+	/// Write integer to est.
 	void ReadScriptInteger(const ScriptToken &t, char *dest);
+	/// Write vector to dest.
 	void ReadScriptVector(const ScriptToken &t, char *dest);
 
+	/// Get a surface from given image path.
+	/// Load it if neccessary.
 	SDL_Surface *GetImage(const std::string &);
 
+	/// Check if a value can be linked right now or if linkage
+	/// must be deferred (with Postpone()).
 	bool CanLink(const Value &) const;
-	void Postpone(int type, int id, std::ptrdiff_t offset, const std::string &identifier, int linkedType, bool inlined);
+	/// Defer linking of given object reference.
+	void Postpone(
+			char *dest,
+			const std::string &identifier,
+			int type,
+			bool inlined = true,
+			bool aggregate = false);
 
 private:
 	const ParsedSource &source;
@@ -116,4 +189,4 @@ private:
 
 }
 
-#endif /* LOADER_INTERPRETER_H_ */
+#endif