Add support for forward declarations

include/cppast/cpp_class.hpp

@@ -7,6 +7,7 @@
 
 #include <cppast/cpp_entity.hpp>
 #include <cppast/cpp_entity_container.hpp>
+#include <cppast/cpp_forward_declarable.hpp>
 #include <cppast/cpp_type.hpp>
 
 namespace cppast
@@ -112,7 +113,13 @@ namespace cppast
     };
 
     /// A [cppast::cpp_entity]() modelling a C++ class.
-    class cpp_class final : public cpp_entity, public cpp_entity_container<cpp_class, cpp_entity>
+    ///
+    /// This can either be a definition or just a forward declaration.
+    /// If it is just a forward declaration,
+    /// everything except the class type will not be available.
+    class cpp_class final : public cpp_entity,
+                            public cpp_entity_container<cpp_class, cpp_entity>,
+                            public cpp_forward_declarable
     {
     public:
         static cpp_entity_kind kind() noexcept;
@@ -164,6 +171,15 @@ namespace cppast
             std::unique_ptr<cpp_class> finish(const cpp_entity_index& idx,
                                               cpp_entity_id           id) noexcept;
 
+            /// \effects Marks the class as forward declaration.
+            /// \returns The finished class.
+            /// \notes It will not be registered, as it is not the main definition.
+            std::unique_ptr<cpp_class> finish_declaration(cpp_entity_id definition_id) noexcept
+            {
+                class_->set_definition(definition_id);
+                return std::move(class_);
+            }
+
         private:
             std::unique_ptr<cpp_class> class_;
         };

include/cppast/cpp_enum.hpp

@@ -13,6 +13,7 @@
 #include <cppast/cpp_entity_index.hpp>
 #include <cppast/cpp_entity.hpp>
 #include <cppast/cpp_expression.hpp>
+#include <cppast/cpp_forward_declarable.hpp>
 #include <cppast/cpp_type.hpp>
 
 namespace cppast
@@ -48,7 +49,12 @@ namespace cppast
     };
 
     /// A [cppast::cpp_entity]() modelling a C++ enumeration.
-    class cpp_enum final : public cpp_entity, public cpp_entity_container<cpp_enum, cpp_enum_value>
+    ///
+    /// This can either be a definition or just a forward declaration.
+    /// If it is just forward declared, it will not have any children.
+    class cpp_enum final : public cpp_entity,
+                           public cpp_entity_container<cpp_enum, cpp_enum_value>,
+                           public cpp_forward_declarable
     {
     public:
         static cpp_entity_kind kind() noexcept;
@@ -79,6 +85,15 @@ namespace cppast
                 return std::move(enum_);
             }
 
+            /// \effects Marks the enum as forward declaration.
+            /// \returns The finished enum.
+            /// \notes It will not be registered, as it is not the main definition.
+            std::unique_ptr<cpp_enum> finish_declaration(cpp_entity_id definition_id) noexcept
+            {
+                enum_->set_definition(definition_id);
+                return std::move(enum_);
+            }
+
         private:
             std::unique_ptr<cpp_enum> enum_;
         };

include/cppast/cpp_forward_declarable.hpp

@@ -0,0 +1,108 @@
+// Copyright (C) 2017 Jonathan Müller <jonathanmueller.dev@gmail.com>
+// This file is subject to the license terms in the LICENSE file
+// found in the top-level directory of this distribution.
+
+#ifndef CPPAST_CPP_FORWARD_DECLARABLE_HPP_INCLUDED
+#define CPPAST_CPP_FORWARD_DECLARABLE_HPP_INCLUDED
+
+#include <type_traits>
+
+#include <type_safe/optional.hpp>
+
+#include <cppast/cpp_entity.hpp>
+#include <cppast/cpp_entity_ref.hpp>
+
+namespace cppast
+{
+    /// Mixin base class for all entities that can have a forward declaration.
+    ///
+    /// Examples are [cppast::cpp_enum]() or [cppast::cpp_class](),
+    /// but also [cppast::cpp_function_base]().
+    /// Those entities can have multiple declarations and one definition.
+    class cpp_forward_declarable
+    {
+    public:
+        /// \returns Whether or not the entity is the definition.
+        bool is_definition() const noexcept
+        {
+            return !definition_.has_value();
+        }
+
+        /// \returns Whether or not the entity is "just" a declaration.
+        bool is_declaration() const noexcept
+        {
+            return definition_.has_value();
+        }
+
+        /// \returns The [cppast::cpp_entity_id]() of the definition,
+        /// if the current entity is not the definition.
+        const type_safe::optional<cpp_entity_id>& definition() const noexcept
+        {
+            return definition_;
+        }
+
+    protected:
+        /// \effects Marks the entity as definition.
+        /// \notes If it is not a definition,
+        /// [*set_definition]() must be called.
+        cpp_forward_declarable() noexcept = default;
+
+        ~cpp_forward_declarable() noexcept = default;
+
+        /// \effects Sets the definition of the entity,
+        /// marking it as a forward declaration.
+        void set_definition(cpp_entity_id def) noexcept
+        {
+            definition_ = std::move(def);
+        }
+
+    private:
+        type_safe::optional<cpp_entity_id> definition_;
+    };
+
+    /// \exclude
+    namespace detail
+    {
+        template <typename T>
+        auto get_definition_impl(const cpp_entity_index& idx, const T& entity) ->
+            typename std::enable_if<std::is_base_of<cpp_forward_declarable, T>::value,
+                                    type_safe::optional_ref<const T>>::type
+        {
+            if (!entity.definition())
+                return type_safe::opt_cref(&entity);
+            else
+                return idx
+                    .lookup(entity.definition().value())
+                    // downcast
+                    .map([](const cpp_entity& e) -> const T& {
+                        DEBUG_ASSERT(e.kind() == T::kind(), detail::assert_handler{});
+                        return static_cast<const T&>(e);
+                    });
+        }
+
+        template <typename T>
+        auto get_definition_impl(const cpp_entity_index&, const T& entity) ->
+            typename std::enable_if<!std::is_base_of<cpp_forward_declarable, T>::value,
+                                    type_safe::optional_ref<const T>>::type
+        {
+            return type_safe::opt_cref(&entity);
+        }
+    } // namespace detail
+
+    /// Gets the definition of an entity.
+    /// \returns A [ts::optional_ref]() to the entity that is the definition.
+    /// If the entity is a definition or not derived from [cppast::cpp_forward_declarable](),
+    /// returns a reference to the entity itself.
+    /// Otherwise lookups the definition id and returns it.
+    /// \requires `entity` must be derived from [cppast::cpp_entity]().
+    /// \param 1
+    /// \exclude
+    template <typename T,
+              typename = typename std::enable_if<std::is_base_of<cpp_entity, T>::value>::type>
+    type_safe::optional_ref<const T> get_definition(const cpp_entity_index& idx, const T& entity)
+    {
+        return detail::get_definition_impl(idx, entity);
+    }
+} // namespace cppast
+
+#endif // CPPAST_CPP_FORWARD_DECLARABLE_HPP_INCLUDED

include/cppast/cpp_function.hpp

@@ -7,6 +7,7 @@
 
 #include <cppast/cpp_entity.hpp>
 #include <cppast/cpp_entity_container.hpp>
+#include <cppast/cpp_forward_declarable.hpp>
 #include <cppast/cpp_storage_class_specifiers.hpp>
 #include <cppast/cpp_variable_base.hpp>
 
@@ -40,14 +41,30 @@ namespace cppast
         cpp_function_deleted,     //< Deleted definition.
     };
 
+    /// \returns Whether or not the function body is a declaration,
+    /// without a definition.
+    inline bool is_declaration(cpp_function_body_kind body) noexcept
+    {
+        return body == cpp_function_declaration;
+    }
+
+    /// \returns Whether or not the function body is a definition.
+    inline bool is_definition(cpp_function_body_kind body) noexcept
+    {
+        return !is_declaration(body);
+    }
+
     /// Base class for all entities that are functions.
     ///
     /// It contains arguments and common flags.
-    class cpp_function_base : public cpp_entity,
-                              public cpp_entity_container<cpp_function_base, cpp_function_parameter>
+    class cpp_function_base
+        : public cpp_entity,
+          public cpp_entity_container<cpp_function_base, cpp_function_parameter>,
+          public cpp_forward_declarable
     {
     public:
         /// \returns The [cppast::cpp_function_body_kind]().
+        /// \notes This matches the [cppast::cpp_forward_declarable]() queries.
         cpp_function_body_kind body_kind() const noexcept
         {
             return body_;
@@ -98,17 +115,16 @@ namespace cppast
                 static_cast<cpp_function_base&>(*function).noexcept_expr_ = std::move(cond);
             }
 
-            /// \effects Sets the [cppast::cpp_function_body_kind]().
-            void body_kind(cpp_function_body_kind kind)
-            {
-                static_cast<cpp_function_base&>(*function).body_ = kind;
-            }
-
-            /// \effects Registers the function.
+            /// \effects If the body is a definition, registers it.
+            /// Else marks it as a declaration.
             /// \returns The finished function.
-            std::unique_ptr<T> finish(const cpp_entity_index& idx, cpp_entity_id id)
+            std::unique_ptr<T> finish(const cpp_entity_index& idx, cpp_entity_id id,
+                                      cpp_function_body_kind body_kind)
             {
-                idx.register_entity(std::move(id), type_safe::cref(*function));
+                if (cppast::is_definition(body_kind))
+                    idx.register_entity(std::move(id), type_safe::cref(*function));
+                else
+                    function->set_definition(id);
                 return std::move(function);
             }
 

include/cppast/cpp_variable.hpp

@@ -6,6 +6,7 @@
 #define CPPAST_CPP_VARIABLE_HPP_INCLUDED
 
 #include <cppast/cpp_entity.hpp>
+#include <cppast/cpp_forward_declarable.hpp>
 #include <cppast/cpp_storage_class_specifiers.hpp>
 #include <cppast/cpp_variable_base.hpp>
 
@@ -15,7 +16,9 @@ namespace cppast
     /// \notes This is not a member variable,
     /// use [cppast::cpp_member_variable]() for that.
     /// But it can be `static` member variable.
-    class cpp_variable final : public cpp_entity, public cpp_variable_base
+    class cpp_variable final : public cpp_entity,
+                               public cpp_variable_base,
+                               public cpp_forward_declarable
     {
     public:
         static cpp_entity_kind kind() noexcept;
@@ -28,6 +31,14 @@ namespace cppast
                                                    cpp_storage_class_specifiers    spec,
                                                    bool                            is_constexpr);
 
+        /// \returns A newly created variable that is a declaration.
+        /// A declaration will not be registered and it does not have the default value.
+        static std::unique_ptr<cpp_variable> build_declaration(cpp_entity_id definition_id,
+                                                               std::string   name,
+                                                               std::unique_ptr<cpp_type>    type,
+                                                               cpp_storage_class_specifiers spec,
+                                                               bool is_constexpr);
+
         /// \returns The [cppast::cpp_storage_specifiers]() on that variable.
         cpp_storage_class_specifiers storage_class() const noexcept
         {