Refactor error class into API headers

CMakeLists.txt

@@ -217,7 +217,7 @@ set (LOOT_HEADERS "${CMAKE_SOURCE_DIR}/src/backend/app/loot_paths.h"
                 "${CMAKE_SOURCE_DIR}/src/backend/helpers/language.h"
                 "${CMAKE_SOURCE_DIR}/src/backend/helpers/version.h"
                 "${CMAKE_SOURCE_DIR}/src/backend/helpers/yaml_set_helpers.h"
-                "${CMAKE_SOURCE_DIR}/src/backend/error.h"
+                "${CMAKE_SOURCE_DIR}/include/loot/error.h"
                 "${CMAKE_SOURCE_DIR}/include/loot/game_type.h"
                 "${CMAKE_SOURCE_DIR}/include/loot/language_code.h"
                 "${CMAKE_SOURCE_DIR}/include/loot/loot_version.h"
@@ -242,6 +242,7 @@ set (LOOT_API_SRC "${CMAKE_BINARY_DIR}/generated/loot_version.cpp"
 
 set (LOOT_API_HEADERS "${CMAKE_SOURCE_DIR}/include/loot/api.h"
                       "${CMAKE_SOURCE_DIR}/include/loot/database_interface.h"
+                      "${CMAKE_SOURCE_DIR}/include/loot/error.h"
                       "${CMAKE_SOURCE_DIR}/include/loot/game_type.h"
                       "${CMAKE_SOURCE_DIR}/include/loot/language_code.h"
                       "${CMAKE_SOURCE_DIR}/include/loot/loot_version.h"

docs/api/reference.rst

@@ -43,5 +43,8 @@ Interfaces
 Classes
 =======
 
+.. doxygenclass:: loot::Error
+   :members:
+
 .. doxygenclass:: loot::LootVersion
    :members:

include/loot/api.h

@@ -33,6 +33,7 @@
 #include <memory>
 
 #include "loot/database_interface.h"
+#include "loot/error.h"
 #include "loot/game_type.h"
 #include "loot/loot_version.h"
 

include/loot/error.h

@@ -0,0 +1,154 @@
+/*  LOOT
+
+    A load order optimisation tool for Oblivion, Skyrim, Fallout 3 and
+    Fallout: New Vegas.
+
+    Copyright (C) 2012-2016    WrinklyNinja
+
+    This file is part of LOOT.
+
+    LOOT 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.
+
+    LOOT 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 LOOT.  If not, see
+    <https://www.gnu.org/licenses/>.
+    */
+
+#ifndef LOOT_ERROR
+#define LOOT_ERROR
+
+#include <exception>
+#include <string>
+
+/* set up dll import/export decorators
+when compiling the dll on windows, ensure LOOT_EXPORT is defined. clients
+that use this header do not need to define anything to import the symbols
+properly. */
+#if defined(_WIN32)
+#   ifdef LOOT_STATIC
+#       define LOOT_API
+#   elif defined LOOT_EXPORT
+#       define LOOT_API __declspec(dllexport)
+#   else
+#       define LOOT_API __declspec(dllimport)
+#   endif
+#else
+#   define LOOT_API
+#endif
+
+/**
+ * @file
+ * @brief Contains the Error class used for some exceptions thrown.
+ */
+
+namespace loot {
+/**
+ * @brief A class that defines the type of objects thrown as errors by the LOOT
+ *        API.
+ * @details Note that not all exceptions thrown from the LOOT API use this type,
+ *          so catch `std::exception` too.
+ */
+class Error : public std::exception {
+public:
+  /**
+   * @brief A code indicating the type of error that occurred.
+   */
+  enum struct Code : unsigned int {
+    /**
+     * No error occurred. This is used internally to indicate that an operation
+     * failed, but its failure was not fatal to the task being performed.
+     */
+    ok = 0,
+    /** An error was encountered when reading or writing the load order. */
+    liblo_error = 1,
+    /** An error was encountered when writing a file. */
+    path_write_fail = 2,
+    /** An error was encountered when reading a file. */
+    path_read_fail = 3,
+    /**
+     * An error was encountered when attempting to evaluate a metadata
+     * condition.
+     */
+    condition_eval_fail = 4,
+    /** An error was encountered when parsing a regular expression. */
+    regex_eval_fail = 5,
+    /** An error was encountered when trying to allocate memory. */
+    no_mem = 6,
+    /** An error was encountered due to invalid function arguments. */
+    invalid_args = 7,
+    /**
+     * @deprecated
+     * @brief An error was encountered when getting plugin tags as no tag map
+     * was built. **This code is obsolete and no longer used.**
+     */
+    no_tag_map = 8,
+    /** A path could not be found. */
+    path_not_found = 9,
+    /** None of LOOT's supported games could be detected. */
+    no_game_detected = 10,
+    /**
+     * @deprecated
+     * @brief An error was encountered while trying to run a Subversion command.
+     * **This code is obsolete and no longer used.**
+     */
+    subversion_error = 11,
+    /**
+     * An error was encountered while trying to create or interact with a Git
+     * repository.
+     */
+    git_error = 12,
+    /** A miscellaneous error occurred when using an operating system API. */
+    windows_error = 13,
+    /** An error occurred while trying to sort the load order. */
+    sorting_error = 14,
+  };
+
+  /**
+   * @brief Construct an error object giving a code and error message.
+   */
+  Error(const Code code_arg, const std::string& what_arg) : code_(code_arg), what_(what_arg) {}
+  ~Error() throw() {};
+
+  /**
+   * @brief Get the code describing the type of error that occurred.
+   * @return An error code.
+   */
+  Code code() const { return code_; }
+
+  /**
+   * @brief A utility function that casts the code to an unsigned int.
+   * @return An error code's unsigned integer value.
+   */
+  unsigned int codeAsUnsignedInt() const {
+    return asUnsignedInt(code_);
+  }
+
+  /**
+   * @brief Get the message that describes the error details.
+   * @return A string describing the error that occurred.
+   */
+  const char * what() const throw() { return what_.c_str(); }
+
+  /**
+   * A utility function that converts a given error code to an unsigned int.
+   * @param  code The code to convert.
+   * @return      The error code's unsigned integer value.
+   */
+  static unsigned int asUnsignedInt(Code code) {
+    return static_cast<unsigned int>(code);
+  }
+private:
+  Code code_;
+  std::string what_;
+};
+}
+
+#endif

src/api/api.cpp

@@ -28,7 +28,7 @@
 #include <boost/log/core.hpp>
 
 #include "api/api_database.h"
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/app/loot_paths.h"
 
 namespace loot {

src/api/api_database.cpp

@@ -27,7 +27,7 @@
 #include <vector>
 #include <unordered_map>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/game/game.h"
 #include "backend/plugin/plugin_sorter.h"
 

src/backend/app/loot_paths.cpp

@@ -28,7 +28,7 @@ Fallout: New Vegas.
 
 #include <boost/locale.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/helpers/helpers.h"
 
 #ifdef _WIN32

src/backend/app/loot_state.cpp

@@ -34,7 +34,7 @@
 #include <boost/log/utility/setup/common_attributes.hpp>
 #include <boost/log/utility/setup/file.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/app/loot_paths.h"
 #include "backend/helpers/helpers.h"
 #include "backend/helpers/language.h"

src/backend/error.h

@@ -1,73 +0,0 @@
-/*  LOOT
-
-    A load order optimisation tool for Oblivion, Skyrim, Fallout 3 and
-    Fallout: New Vegas.
-
-    Copyright (C) 2012-2016    WrinklyNinja
-
-    This file is part of LOOT.
-
-    LOOT 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.
-
-    LOOT 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 LOOT.  If not, see
-    <https://www.gnu.org/licenses/>.
-    */
-
-#ifndef LOOT_BACKEND_ERROR
-#define LOOT_BACKEND_ERROR
-
-#include <exception>
-#include <string>
-
-namespace loot {
-class Error : public std::exception {
-public:
-  enum struct Code : unsigned int {
-      // These must not be changed for API stability.
-    ok = 0,
-    liblo_error = 1,
-    path_write_fail = 2,
-    path_read_fail = 3,
-    condition_eval_fail = 4,
-    regex_eval_fail = 5,
-    no_mem = 6,
-    invalid_args = 7,
-    no_tag_map = 8,
-    path_not_found = 9,
-    no_game_detected = 10,
-    //11 was subversion_error, and was removed along with svn support.
-    git_error = 12,
-    windows_error = 13,
-    sorting_error = 14,
-  };
-
-  Error(const Code code_arg, const std::string& what_arg) : code_(code_arg), what_(what_arg) {}
-  ~Error() throw() {};
-
-  Code code() const { return code_; }
-
-  unsigned int codeAsUnsignedInt() const {
-    return asUnsignedInt(code_);
-  }
-
-  const char * what() const throw() { return what_.c_str(); }
-
-  static unsigned int asUnsignedInt(Code code) {
-    return static_cast<unsigned int>(code);
-  }
-private:
-  Code code_;
-  std::string what_;
-};
-}
-
-#endif

src/backend/game/game.cpp

@@ -32,7 +32,7 @@
 #include <boost/log/trivial.hpp>
 
 #include "backend/app/loot_paths.h"
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/helpers/helpers.h"
 
 using boost::locale::translate;

src/backend/game/game_cache.cpp

@@ -30,7 +30,7 @@
 #include <boost/locale.hpp>
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/helpers/helpers.h"
 
 using boost::locale::to_lower;

src/backend/game/game_settings.cpp

@@ -29,7 +29,7 @@
 #include <boost/log/trivial.hpp>
 
 #include "backend/app/loot_paths.h"
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/helpers/helpers.h"
 
 namespace fs = boost::filesystem;

src/backend/game/load_order_handler.cpp

@@ -28,7 +28,7 @@
 #include <boost/locale.hpp>
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 
 using boost::locale::translate;
 using std::string;

src/backend/helpers/git_helper.cpp

@@ -28,7 +28,7 @@
 #include <boost/locale.hpp>
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 
 using boost::locale::translate;
 using std::string;

src/backend/helpers/helpers.cpp

@@ -40,7 +40,7 @@
 #include <boost/log/trivial.hpp>
 #include <boost/spirit/include/karma.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 
 #ifdef _WIN32
 #   ifndef UNICODE

src/backend/masterlist.cpp

@@ -26,7 +26,7 @@
 
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/game/game.h"
 #include "backend/helpers/git_helper.h"
 

src/backend/metadata/condition_evaluator.cpp

@@ -26,7 +26,7 @@
 
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/helpers/helpers.h"
 
 namespace loot {

src/backend/metadata/condition_grammar.h

@@ -46,7 +46,7 @@
 #include <boost/spirit/include/phoenix_bind.hpp>
 #include <boost/spirit/include/qi.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/game/game.h"
 #include "backend/helpers/helpers.h"
 #include "backend/helpers/version.h"

src/backend/metadata/message.cpp

@@ -26,7 +26,7 @@
 
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/game/game.h"
 #include "backend/helpers/language.h"
 

src/backend/metadata/plugin_metadata.cpp

@@ -32,7 +32,7 @@
 #include <boost/locale.hpp>
 #include <boost/log/trivial.hpp>
 
-#include "backend/error.h"
+#include "loot/error.h"
 #include "backend/game/game.h"
 #include "backend/helpers/helpers.h"