feat(tdl): Add helper classes for parser error handling.

src/spider/.clang-format

@@ -7,7 +7,7 @@ IncludeCategories:
   - Regex: "^<spider"
     Priority: 4
   # External library headers. Update when adding new libraries.
-  - Regex: "^<(absl|boost|catch2|fmt|mariadb|msgpack|spdlog|ystdlib)"
+  - Regex: "^<(antlr4|absl|boost|catch2|fmt|mariadb|msgpack|spdlog|ystdlib)"
     Priority: 3
   # C system headers
   - Regex: "^<.+\\.h>"

src/spider/CMakeLists.txt

@@ -230,6 +230,7 @@ set(SPIDER_TDL_SHARED_SOURCES
 )
 
 set(SPIDER_TDL_SHARED_HEADERS
+    tdl/Error.hpp
     tdl/parser/ast/Node.hpp
     tdl/parser/ast/FloatSpec.hpp
     tdl/parser/ast/IntSpec.hpp
@@ -249,8 +250,9 @@ set(SPIDER_TDL_SHARED_HEADERS
     tdl/parser/ast/node_impl/type_impl/primitive_impl/Int.hpp
     tdl/parser/ast/node_impl/type_impl/Struct.hpp
     tdl/parser/ast/nodes.hpp
-    tdl/parser/ast/SourceLocation.hpp
     tdl/parser/ast/utils.hpp
+    tdl/parser/ErrorListener.hpp
+    tdl/parser/SourceLocation.hpp
     CACHE INTERNAL
     "spider task definition language shared header files"
 )

src/spider/tdl/Error.hpp

@@ -0,0 +1,45 @@
+#ifndef SPIDER_TDL_ERROR_HPP
+#define SPIDER_TDL_ERROR_HPP
+
+#include <optional>
+#include <string>
+#include <string_view>
+#include <system_error>
+#include <utility>
+
+#include <spider/tdl/parser/SourceLocation.hpp>
+
+namespace spider::tdl {
+/**
+ * Represents a generic error in the TDL compiler.
+ */
+class Error {
+public:
+    // Constructor
+    Error(std::string message,
+          parser::SourceLocation source_location,
+          std::optional<std::error_code> error_code = std::nullopt)
+            : m_message{std::move(message)},
+              m_source_location{source_location},
+              m_error_code{error_code} {}
+
+    // Methods
+    [[nodiscard]] auto get_message() const noexcept -> std::string_view { return m_message; }
+
+    [[nodiscard]] auto get_source_location() const noexcept -> parser::SourceLocation {
+        return m_source_location;
+    }
+
+    [[nodiscard]] auto get_error_code() const noexcept -> std::optional<std::error_code> {
+        return m_error_code;
+    }
+
+private:
+    // Variables
+    std::string m_message;
+    parser::SourceLocation m_source_location;
+    std::optional<std::error_code> m_error_code;
+};
+}  // namespace spider::tdl
+
+#endif  // SPIDER_TDL_ERROR_HPP

src/spider/tdl/parser/ErrorListener.hpp

@@ -0,0 +1,58 @@
+#ifndef SPIDER_TDL_PARSER_ERRORLISTENER_HPP
+#define SPIDER_TDL_PARSER_ERRORLISTENER_HPP
+
+#include <cstddef>
+#include <exception>
+#include <optional>
+#include <string>
+#include <utility>
+
+#include <antlr4-runtime.h>
+#include <fmt/format.h>
+
+#include <spider/tdl/Error.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
+
+namespace spider::tdl::parser {
+class ErrorListener : public antlr4::BaseErrorListener {
+public:
+    // Constructor
+    explicit ErrorListener(std::string tag) : m_tag{std::move(tag)} {}
+
+    // Methods implementing `antlr4::BaseErrorListener`
+    auto syntaxError(
+            [[maybe_unused]] antlr4::Recognizer* recognizer,
+            [[maybe_unused]] antlr4::Token* offending_symbol,
+            size_t line,
+            size_t char_position_in_line,
+            std::string const& msg,
+            [[maybe_unused]] std::exception_ptr e
+    ) -> void override {
+        m_error.emplace(
+                fmt::format("{}: {}", m_tag, msg),
+                SourceLocation{line, char_position_in_line},
+                std::nullopt
+        );
+    }
+
+    // Methods
+    [[nodiscard]] auto has_error() const -> bool { return m_error.has_value(); }
+
+    /**
+     * @return A reference to the error. The caller must ensure that `has_error()` is true before
+     * calling this method.
+     */
+    [[nodiscard]] auto error() const -> Error const& {
+        // We require the caller to check `has_error()` before calling this method, which ensures
+        // the optional var has a value.
+        // NOLINTNEXTLINE(bugprone-unchecked-optional-access)
+        return m_error.value();
+    }
+
+private:
+    std::string m_tag;
+    std::optional<Error> m_error;
+};
+}  // namespace spider::tdl::parser
+
+#endif  // SPIDER_TDL_PARSER_ERRORLISTENER_HPP

src/spider/tdl/parser/ast/SourceLocation.hpp → src/spider/tdl/parser/SourceLocation.hpp

@@ -1,9 +1,9 @@
-#ifndef SPIDER_TDL_AST_SOURCELOCATION_HPP
-#define SPIDER_TDL_AST_SOURCELOCATION_HPP
+#ifndef SPIDER_TDL_PARSER_SOURCELOCATION_HPP
+#define SPIDER_TDL_PARSER_SOURCELOCATION_HPP
 
 #include <cstddef>
 
-namespace spider::tdl::parser::ast {
+namespace spider::tdl::parser {
 class SourceLocation {
 public:
     // Constructor
@@ -19,6 +19,6 @@ class SourceLocation {
     size_t m_line;
     size_t m_column;
 };
-}  // namespace spider::tdl::parser::ast
+}  // namespace spider::tdl::parser
 
-#endif  // SPIDER_TDL_AST_SOURCELOCATION_HPP
+#endif  // SPIDER_TDL_PARSER_SOURCELOCATION_HPP

src/spider/tdl/parser/ast/Node.hpp

@@ -11,7 +11,7 @@
 #include <ystdlib/error_handling/ErrorCode.hpp>
 #include <ystdlib/error_handling/Result.hpp>
 
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast {
 /**

src/spider/tdl/parser/ast/node_impl/Function.cpp

@@ -17,8 +17,8 @@
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/NamedVar.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 using spider::tdl::parser::ast::node_impl::Function;
 using FunctionErrorCodeCategory = ystdlib::error_handling::ErrorCategory<Function::ErrorCodeEnum>;

src/spider/tdl/parser/ast/node_impl/Function.hpp

@@ -16,7 +16,7 @@
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/NamedVar.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 class Function : public Node {

src/spider/tdl/parser/ast/node_impl/Identifier.hpp

@@ -10,7 +10,7 @@
 #include <ystdlib/error_handling/Result.hpp>
 
 #include <spider/tdl/parser/ast/Node.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 class Identifier : public Node {

src/spider/tdl/parser/ast/node_impl/NamedVar.cpp

@@ -11,8 +11,8 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 auto NamedVar::create(

src/spider/tdl/parser/ast/node_impl/NamedVar.hpp

@@ -10,7 +10,7 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 /**

src/spider/tdl/parser/ast/node_impl/Namespace.cpp

@@ -17,8 +17,8 @@
 #include <spider/tdl/parser/ast/node_impl/Function.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/Namespace.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 using spider::tdl::parser::ast::node_impl::Namespace;
 using NamespaceErrorCodeCategory = ystdlib::error_handling::ErrorCategory<Namespace::ErrorCodeEnum>;

src/spider/tdl/parser/ast/node_impl/Namespace.hpp

@@ -15,7 +15,7 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Function.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 /**

src/spider/tdl/parser/ast/node_impl/StructSpec.cpp

@@ -16,8 +16,8 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/NamedVar.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 using spider::tdl::parser::ast::node_impl::StructSpec;
 using StructSpecErrorCodeCategory

src/spider/tdl/parser/ast/node_impl/StructSpec.hpp

@@ -15,7 +15,7 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/NamedVar.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 /**

src/spider/tdl/parser/ast/node_impl/Type.hpp

@@ -2,7 +2,7 @@
 #define SPIDER_TDL_PARSER_AST_NODE_IMPL_TYPE_HPP
 
 #include <spider/tdl/parser/ast/Node.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl {
 // Abstract base class for all type nodes in the AST.

src/spider/tdl/parser/ast/node_impl/type_impl/Container.hpp

@@ -2,7 +2,7 @@
 #define SPIDER_TDL_PARSER_AST_NODE_IMPL_TYPE_IMPL_CONTAINER_HPP
 
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl {
 // Abstract base class for all container type nodes in the AST.

src/spider/tdl/parser/ast/node_impl/type_impl/Primitive.hpp

@@ -2,7 +2,7 @@
 #define SPIDER_TDL_PARSER_AST_NODE_IMPL_TYPE_IMPL_PRIMITIVE_HPP
 
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl {
 // Abstract base class for all primitive type nodes in the AST.

src/spider/tdl/parser/ast/node_impl/type_impl/Struct.cpp

@@ -12,8 +12,8 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/StructSpec.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 using spider::tdl::parser::ast::node_impl::type_impl::Struct;
 using StructErrorCodeCategory = ystdlib::error_handling::ErrorCategory<Struct::ErrorCodeEnum>;

src/spider/tdl/parser/ast/node_impl/type_impl/Struct.hpp

@@ -14,7 +14,7 @@
 #include <spider/tdl/parser/ast/node_impl/Identifier.hpp>
 #include <spider/tdl/parser/ast/node_impl/StructSpec.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl {
 class Struct : public Type {

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/List.cpp

@@ -10,8 +10,8 @@
 
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::container_impl {
 auto List::create(std::unique_ptr<Node> element_type, SourceLocation source_location)

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/List.hpp

@@ -10,7 +10,7 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Container.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::container_impl {
 class List : public Container {

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/Map.cpp

@@ -14,8 +14,8 @@
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/container_impl/List.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/primitive_impl/Int.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 using spider::tdl::parser::ast::node_impl::type_impl::container_impl::Map;
 using MapErrorCodeCategory = ystdlib::error_handling::ErrorCategory<Map::ErrorCodeEnum>;

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/Map.hpp

@@ -12,7 +12,7 @@
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Container.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::container_impl {
 class Map : public Container {

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/Tuple.cpp

@@ -13,8 +13,8 @@
 
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/Type.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
 #include <spider/tdl/parser/ast/utils.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::container_impl {
 auto Tuple::create(std::vector<std::unique_ptr<Node>> elements, SourceLocation source_location)

src/spider/tdl/parser/ast/node_impl/type_impl/container_impl/Tuple.hpp

@@ -10,7 +10,7 @@
 
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Container.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::container_impl {
 class Tuple : public Container {

src/spider/tdl/parser/ast/node_impl/type_impl/primitive_impl/Bool.hpp

@@ -9,7 +9,7 @@
 
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Primitive.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::primitive_impl {
 class Bool : public Primitive {

src/spider/tdl/parser/ast/node_impl/type_impl/primitive_impl/Float.hpp

@@ -10,7 +10,7 @@
 #include <spider/tdl/parser/ast/FloatSpec.hpp>
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Primitive.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::primitive_impl {
 class Float : public Primitive {

src/spider/tdl/parser/ast/node_impl/type_impl/primitive_impl/Int.hpp

@@ -10,7 +10,7 @@
 #include <spider/tdl/parser/ast/IntSpec.hpp>
 #include <spider/tdl/parser/ast/Node.hpp>
 #include <spider/tdl/parser/ast/node_impl/type_impl/Primitive.hpp>
-#include <spider/tdl/parser/ast/SourceLocation.hpp>
+#include <spider/tdl/parser/SourceLocation.hpp>
 
 namespace spider::tdl::parser::ast::node_impl::type_impl::primitive_impl {
 class Int : public Primitive {