Initial commit

engines/ags/shared/util/error.h

@@ -0,0 +1,170 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU 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 General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ *
+ */
+
+//=============================================================================
+//
+// Universal error class, that may be used both as a return value or
+// thrown as an exception.
+//
+//=============================================================================
+
+#ifndef AGS_SHARED_UTIL_ERROR_H
+#define AGS_SHARED_UTIL_ERROR_H
+
+#include "common/std/memory.h"
+#include "ags/shared/util/string.h"
+
+namespace AGS3 {
+namespace AGS {
+namespace Shared {
+
+class Error;
+typedef std::shared_ptr<Error> PError;
+
+//
+// A simple struct, that provides several fields to describe an error in the program.
+// If wanted, may be reworked into subclass of std::exception.
+//
+class Error {
+public:
+	Error(int code, String general, PError inner_error = PError()) : _code(code), _general(general), _innerError(inner_error) {
+	}
+	Error(int code, String general, String comment, PError inner_error = PError()) : _code(code), _general(general), _comment(comment), _innerError(inner_error) {
+	}
+	Error(String general, PError inner_error = PError()) : _code(0), _general(general), _innerError(inner_error) {
+	}
+	Error(String general, String comment, PError inner_error = PError()) : _code(0), _general(general), _comment(comment), _innerError(inner_error) {
+	}
+
+
+	// Error code is a number, defining error subtype. It is not much use to the end-user,
+	// but may be checked in the program to know more precise cause of the error.
+	int    Code() const {
+		return _code;
+	}
+	// General description of this error type and subtype.
+	String General() const {
+		return _general;
+	}
+	// Any complementary information.
+	String Comment() const {
+		return _comment;
+	}
+	PError InnerError() const {
+		return _innerError;
+	}
+	// Full error message combines general description and comment.
+	// NOTE: if made a child of std::exception, FullMessage may be substituted
+	// or complemented with virtual const char* what().
+	String FullMessage() const {
+		String msg;
+		const Error *err = this;
+		do {
+			msg.Append(err->General());
+			if (!err->Comment().IsEmpty()) {
+				msg.AppendChar('\n');
+				msg.Append(err->Comment());
+			}
+			err = err->InnerError().get();
+			if (err)
+				msg.AppendChar('\n');
+		} while (err);
+		return msg;
+	}
+
+private:
+	int    _code; // numeric code, for specific uses
+	String _general; // general description of this error class
+	String _comment; // additional information about particular case
+	PError _innerError; // previous error that caused this one
+};
+
+
+// ErrorHandle is a helper class that lets you have an Error object
+// wrapped in a smart pointer. ErrorHandle's only data member is a
+// shared_ptr, which means that it does not cause too much data copying
+// when used as a function's return value.
+// Note, that the reason to have distinct class instead of a shared_ptr's
+// typedef is an inverted boolean comparison:
+// shared_ptr converts to 'true' when it contains an object, but ErrorHandle
+// returns 'true' when it *does NOT* contain an object, meaning there
+// is no error.
+template <class T> class ErrorHandle {
+public:
+	static ErrorHandle<T> None() {
+		return ErrorHandle();
+	}
+
+	ErrorHandle() {}
+	ErrorHandle(T *err) : _error(err) {
+	}
+	ErrorHandle(std::shared_ptr<T> err) : _error(err) {
+	}
+
+	bool HasError() const {
+		return _error.get() != NULL;
+	}
+	explicit operator bool() const {
+		return _error.get() == nullptr;
+	}
+	operator PError() const {
+		return _error;
+	}
+	T *operator ->() const {
+		return _error.operator->();
+	}
+	T &operator *() const {
+		return _error.operator * ();
+	}
+
+private:
+	std::shared_ptr<T> _error;
+};
+
+
+// Basic error handle, containing Error object
+typedef ErrorHandle<Error> HError;
+
+
+// TypedCodeError is the Error's subclass, which only purpose is to override
+// error code type in constructor and Code() getter, that may be useful if
+// you'd like to restrict code values to particular enumerator.
+// TODO: a type identifier as a part of template (string, or perhaps a int16
+// to be placed at high-bytes in Code) to be able to distinguish error group.
+template <typename CodeType, String(*GetErrorText)(CodeType)>
+class TypedCodeError : public Error {
+public:
+	TypedCodeError(CodeType code, PError inner_error = PError()) : Error(code, GetErrorText(code), inner_error) {
+	}
+	TypedCodeError(CodeType code, String comment, PError inner_error = PError()) :
+		Error(code, GetErrorText(code), comment, inner_error) {
+	}
+
+	CodeType Code() const {
+		return (CodeType)Error::Code();
+	}
+};
+
+} // namespace Shared
+} // namespace AGS
+} // namespace AGS3
+
+#endif