Document symbol bag class and methods

include/elna/boot/dependency.h

@@ -21,6 +21,7 @@ along with GCC; see the file COPYING3.  If not see
 #include <fstream>
 #include "elna/boot/result.h"
 #include "elna/boot/ast.h"
+#include "elna/boot/symbol.h"
 
 namespace elna::boot
 {

include/elna/boot/semantic.h

@@ -175,7 +175,7 @@ namespace elna::boot
     class declaration_visitor final : public empty_visitor, public error_container
     {
     public:
-        std::unordered_map<std::string, std::shared_ptr<alias_type>> unresolved;
+        forward_table unresolved;
 
         explicit declaration_visitor(const char *path);
 

include/elna/boot/symbol.h

@@ -231,6 +231,7 @@ namespace elna::boot
          * can not be found.
          *
          * \param name Symbol name.
+         *
          * \return Symbol from the table if found.
          */
         symbol_ptr lookup(const std::string& name)
@@ -250,6 +251,7 @@ namespace elna::boot
 
         /**
          * \param name Symbol name.
+         *
          * \return Whether the table contains a symbol with the given name.
          */
         bool contains(const std::string& name)
@@ -328,24 +330,101 @@ namespace elna::boot
 
     std::shared_ptr<symbol_table> builtin_symbol_table();
 
+    /**
+     * Symbol bag contains:
+     *
+     * - the symbol table of a module itself
+     * - symbol tables of imported modules
+     * - forward declarations
+     */
     class symbol_bag
     {
         std::shared_ptr<symbol_table> symbols;
         std::forward_list<std::shared_ptr<symbol_table>> imports;
-
-    public:
         forward_table unresolved;
 
-        symbol_bag();
-        symbol_bag(forward_table&& unresolved, std::shared_ptr<symbol_table> symbols);
+    public:
 
+        /**
+         * \param unresolved Forward declarations collected in the previous step.
+         * \param global_table Global symbols.
+         */
+        symbol_bag(forward_table&& unresolved, std::shared_ptr<symbol_table> global_table);
+
+        /**
+         * \return Iterator pointing to the first forward declaration.
+         */
+        forward_table::const_iterator begin();
+
+        /**
+         * \return Iterator pointing past the last forward declaration.
+         */
+        forward_table::const_iterator end();
+
+        /**
+         * Looks up a symbol in the current and imported modules.
+         *
+         * \param name Symbol name to look up.
+         *
+         * \return Symbol from one of the symbol tables if found.
+         */
         std::shared_ptr<info> lookup(const std::string& name);
-        bool enter(const std::string& name, std::shared_ptr<info> entry);
-        std::shared_ptr<symbol_table> enter();
-        void enter(std::shared_ptr<symbol_table> child);
-        void leave();
 
-        void add_import(std::shared_ptr<symbol_table> table);
+        /**
+         * Inserts a symbol into the current scope.
+         *
+         * \param name Symbol name.
+         * \param entry Symbol info.
+         *
+         * \return Whether the insertion took place.
+         */
+        bool enter(const std::string& name, std::shared_ptr<info> entry);
+
+        /**
+         * Enters a new scope.
+         *
+         * \return Reference to the allocated scope.
+         */
+        std::shared_ptr<symbol_table> enter();
+
+        /**
+         * Sets the current scope to \a child.
+         *
+         * \param child New scope.
+         */
+        void enter(std::shared_ptr<symbol_table> child);
+
+        /**
+         * Leave the current scope.
+         *
+         * \return Left scope.
+         */
+        std::shared_ptr<symbol_table> leave();
+
+        /**
+         * Checks whether there is a forward declaration \a symbol_name and
+         * returns it if so.
+         *
+         * \param symbol_name Type name to look up.
+         * \return Forward declaration or `nullptr` if the symbol is not declared.
+         */
+        std::shared_ptr<alias_type> declared(const std::string& symbol_name);
+
+        /**
+         * Completes the forward-declared type \a symbol_name and defines it to
+         * be \a resolution.
+         *
+         * \param symbol_name Type name.
+         * \param resolution Type definition.
+         * \return Alias to the defined type.
+         */
+        std::shared_ptr<alias_type> resolve(const std::string& symbol_name, type& resolution);
+
+        /**
+         * Add imported symbols to the scope.
+         *
+         * \param bag Symbol bag of another module.
+         */
         void add_import(const symbol_bag& bag);
     };
 }

include/elna/gcc/elna-builtins.h

@@ -36,4 +36,6 @@ namespace elna::gcc
     tree get_inner_alias(const boot::type& type, std::shared_ptr<symbol_table> symbols);
     void declare_procedure(const std::string& name, const boot::procedure_info& info,
             std::shared_ptr<symbol_table> symbols);
+    tree declare_variable(const std::string& name, const boot::variable_info& info,
+            std::shared_ptr<symbol_table> symbols);
 }