feat(debugger): create a minimalistic shell for the debugger

SuperFola · SuperFola · commit 31f78d00a946 · 2026-01-18T17:11:33.000+01:00
diff --git a/include/Ark/Utils/Utils.hpp b/include/Ark/Utils/Utils.hpp
@@ -99,6 +99,21 @@ namespace Ark::Utils
      * @return std::size_t
      */
     ARK_API std::size_t levenshteinDistance(const std::string& str1, const std::string& str2);
+
+    /**
+     * @brief Count the open enclosure and its counterpart: (), {}, []
+     * @param line data to operate on
+     * @param open the open char: (, { or [
+     * @param close the closing char: ), } or ]
+     * @return positive if there are more open enclosures than closed. 0 when both are equal, negative otherwise
+     */
+    ARK_API long countOpenEnclosures(const std::string& line, char open, char close);
+
+    /**
+     * @brief Remove whitespaces at the start and end of a string
+     * @param line string modified in place
+     */
+    ARK_API void trimWhitespace(std::string& line);
 }
 
 #endif
diff --git a/include/Ark/VM/Debugger.hpp b/include/Ark/VM/Debugger.hpp
@@ -72,19 +72,28 @@ namespace Ark::internal
          */
         void run(VM& vm, ExecutionContext& context);
 
-        inline bool isRunning() const noexcept
+        [[nodiscard]] inline bool isRunning() const noexcept
         {
             return m_running;
         }
 
+        [[nodiscard]] inline bool shouldQuitVM() const noexcept
+        {
+            return m_quit_vm;
+        }
+
     private:
         std::vector<std::unique_ptr<SavedState>> m_states;
         std::vector<std::filesystem::path> m_libenv;
         std::vector<std::string> m_symbols;
         std::vector<Value> m_constants;
         bool m_running;
+        bool m_quit_vm;
 
         std::string m_code;  ///< Code added while inside the debugger
+        std::size_t m_line_count = 0;
+
+        std::optional<std::string> prompt();
 
         /**
          * @brief Take care of compiling new code using the existing data tables
diff --git a/include/CLI/REPL/Utils.hpp b/include/CLI/REPL/Utils.hpp
@@ -18,21 +18,6 @@
 
 namespace Ark::internal
 {
-    /**
-     * @brief Count the open enclosure and its counterpart: (), {}, []
-     * @param line data to operate on
-     * @param open the open char: (, { or [
-     * @param close the closing char: ), } or ]
-     * @return positive if there are more open enclosures than closed. 0 when both are equal, negative otherwise
-     */
-    long countOpenEnclosures(const std::string& line, char open, char close);
-
-    /**
-     * @brief Remove whitespaces at the start and end of a string
-     * @param line string modified in place
-     */
-    void trimWhitespace(std::string& line);
-
     /**
      * @brief Compute a list of all the language keywords and builtins
      *
diff --git a/src/arkreactor/Utils/Utils.cpp b/src/arkreactor/Utils/Utils.cpp
@@ -1,5 +1,7 @@
 #include <Ark/Utils/Utils.hpp>
 
+#include <ranges>
+
 namespace Ark::Utils
 {
     std::size_t levenshteinDistance(const std::string& str1, const std::string& str2)
@@ -29,4 +31,19 @@ namespace Ark::Utils
 
         return edit_distances[str1_len][str2_len];
     }
+
+    long countOpenEnclosures(const std::string& line, const char open, const char close)
+    {
+        return std::ranges::count(line, open) - std::ranges::count(line, close);
+    }
+
+    void trimWhitespace(std::string& line)
+    {
+        const std::size_t string_begin = line.find_first_not_of(" \t");
+        if (std::string::npos != string_begin)
+        {
+            const std::size_t string_end = line.find_last_not_of(" \t");
+            line = line.substr(string_begin, string_end - string_begin + 1);
+        }
+    }
 }
diff --git a/src/arkreactor/VM/Debugger.cpp b/src/arkreactor/VM/Debugger.cpp
@@ -5,13 +5,15 @@
 
 #include <Ark/State.hpp>
 #include <Ark/VM/VM.hpp>
+#include <Ark/Utils/Files.hpp>
 #include <Ark/Compiler/Welder.hpp>
 #include <Ark/Compiler/BytecodeReader.hpp>
+#include <Ark/Error/Diagnostics.hpp>
 
 namespace Ark::internal
 {
     Debugger::Debugger(const ExecutionContext& context, const std::vector<std::filesystem::path>& libenv, const std::vector<std::string>& symbols, const std::vector<Value>& constants) :
-        m_libenv(libenv), m_symbols(symbols), m_constants(constants), m_running(false)
+        m_libenv(libenv), m_symbols(symbols), m_constants(constants), m_running(false), m_quit_vm(false)
     {
         saveState(context);
     }
@@ -46,31 +48,59 @@ namespace Ark::internal
         m_running = true;
         const bool is_vm_running = vm.m_running;
 
-        // TODO: create a shell
-        fmt::print("> ");
-        std::string line;
-        std::getline(std::cin, line);
-
-        if (const auto pages = compile(m_code + line, vm.m_state.m_pages.size()); pages.has_value())
+        // show the line where the breakpoint hit
+        const auto maybe_source_loc = vm.findSourceLocation(context.ip, context.pp);
+        if (maybe_source_loc)
         {
-            context.ip = 0;
-            context.pp = vm.m_state.m_pages.size();
-            // create dedicated scope, so that we won't be overwriting existing variables
-            context.locals.emplace_back(context.scopes_storage.data(), context.locals.back().storageEnd());
+            const auto filename = vm.m_state.m_filenames[maybe_source_loc->filename_id];
+
+            if (Utils::fileExists(filename))
+            {
+                fmt::println("");
+                Diagnostics::makeContext(
+                    Diagnostics::ErrorLocation {
+                        .filename = filename,
+                        .start = FilePos { .line = maybe_source_loc->line, .column = 0 },
+                        .end = std::nullopt },
+                    std::cout,
+                    /* maybe_context= */ std::nullopt,
+                    /* colorize= */ true);
+                fmt::println("");
+            }
+        }
 
-            vm.m_state.extendBytecode(pages.value(), m_symbols, m_constants);
+        while (true)
+        {
+            std::optional<std::string> maybe_input = prompt();
 
-            if (vm.safeRun(context) == 0)
+            if (maybe_input)
             {
-                // executing code worked
-                m_code += line;
+                const std::string& line = maybe_input.value();
 
-                const Value* maybe_value = vm.peekAndResolveAsPtr(context);
-                if (maybe_value != nullptr && maybe_value->valueType() != ValueType::Undefined && maybe_value->valueType() != ValueType::InstPtr)
-                    fmt::println("{}", fmt::styled(maybe_value->toString(vm), fmt::fg(fmt::color::chocolate)));
-            }
+                if (const auto pages = compile(m_code + line, vm.m_state.m_pages.size()); pages.has_value())
+                {
+                    context.ip = 0;
+                    context.pp = vm.m_state.m_pages.size();
+                    // create dedicated scope, so that we won't be overwriting existing variables
+                    context.locals.emplace_back(context.scopes_storage.data(), context.locals.back().storageEnd());
+
+                    vm.m_state.extendBytecode(pages.value(), m_symbols, m_constants);
 
-            context.locals.pop_back();
+                    if (vm.safeRun(context) == 0)
+                    {
+                        // executing code worked
+                        m_code += line;
+
+                        const Value* maybe_value = vm.peekAndResolveAsPtr(context);
+                        if (maybe_value != nullptr && maybe_value->valueType() != ValueType::Undefined && maybe_value->valueType() != ValueType::InstPtr)
+                            fmt::println("{}", fmt::styled(maybe_value->toString(vm), fmt::fg(fmt::color::chocolate)));
+                    }
+
+                    context.locals.pop_back();
+                }
+            }
+            else
+                break;
         }
 
         m_running = false;
@@ -80,6 +110,55 @@ namespace Ark::internal
         vm.m_running = is_vm_running;
     }
 
+    std::optional<std::string> Debugger::prompt()
+    {
+        std::string code;
+        long open_parens = 0;
+        long open_braces = 0;
+
+        while (true)
+        {
+            const bool unfinished_block = open_parens != 0 || open_braces != 0;
+            fmt::print("dbg:{:0>3}{} ", m_line_count, unfinished_block ? ":" : ">");
+            std::string line;
+            std::getline(std::cin, line);
+
+            Utils::trimWhitespace(line);
+
+            if (line == "c" || line == "continue" || line.empty())
+            {
+                fmt::println("dbg: continue");
+                return std::nullopt;
+            }
+            else if (line == "q" || line == "quit")
+            {
+                fmt::println("dbg: stop");
+                m_quit_vm = true;
+                return std::nullopt;
+            }
+            else if (line == "help")
+            {
+                fmt::println("Available commands:");
+                fmt::println("  help -- display this message");
+                fmt::println("  c, continue -- resume execution");
+                fmt::println("  q, quit -- quit the debugger, stopping the script execution");
+            }
+            else
+            {
+                code += line;
+
+                open_parens += Utils::countOpenEnclosures(line, '(', ')');
+                open_braces += Utils::countOpenEnclosures(line, '{', '}');
+
+                ++m_line_count;
+                if (open_braces == 0 && open_parens == 0)
+                    break;
+            }
+        }
+
+        return code;
+    }
+
     std::optional<std::vector<bytecode_t>> Debugger::compile(const std::string& code, const std::size_t start_page_at_offset)
     {
         Welder welder(0, m_libenv, DefaultFeatures);
diff --git a/src/arkreactor/VM/VM.cpp b/src/arkreactor/VM/VM.cpp
@@ -1197,6 +1197,9 @@ namespace Ark
                                 initDebugger(context);
                                 m_debugger->run(*this, context);
                                 m_debugger->resetContextToSavedState(context);
+
+                                if (m_debugger->shouldQuitVM())
+                                    GOTO_HALT();
                             }
                         }
                         DISPATCH();
diff --git a/src/arkscript/REPL/Repl.cpp b/src/arkscript/REPL/Repl.cpp
@@ -8,6 +8,7 @@
 #include <Ark/VM/DefaultValues.hpp>
 #include <Ark/TypeChecker.hpp>
 #include <Ark/Utils/Files.hpp>
+#include <Ark/Utils/Utils.hpp>
 
 #include <CLI/REPL/Repl.hpp>
 #include <CLI/REPL/Utils.hpp>
@@ -166,7 +167,7 @@ namespace Ark
 
         // line history
         m_repl.history_add(line);
-        trimWhitespace(line);
+        Utils::trimWhitespace(line);
 
         // specific commands handling
         if (line == "quit" || buf == nullptr)
@@ -233,8 +234,8 @@ namespace Ark
             if (maybe_line.has_value() && !maybe_line.value().empty())
             {
                 code_block += maybe_line.value() + "\n";
-                open_parentheses += countOpenEnclosures(maybe_line.value(), '(', ')');
-                open_braces += countOpenEnclosures(maybe_line.value(), '{', '}');
+                open_parentheses += Utils::countOpenEnclosures(maybe_line.value(), '(', ')');
+                open_braces += Utils::countOpenEnclosures(maybe_line.value(), '{', '}');
 
                 // lines number incrementation
                 ++m_line_count;
diff --git a/src/arkscript/REPL/Utils.cpp b/src/arkscript/REPL/Utils.cpp
@@ -10,21 +10,6 @@
 
 namespace Ark::internal
 {
-    long countOpenEnclosures(const std::string& line, const char open, const char close)
-    {
-        return std::ranges::count(line, open) - std::ranges::count(line, close);
-    }
-
-    void trimWhitespace(std::string& line)
-    {
-        const std::size_t string_begin = line.find_first_not_of(" \t");
-        if (std::string::npos != string_begin)
-        {
-            const std::size_t string_end = line.find_last_not_of(" \t");
-            line = line.substr(string_begin, string_end - string_begin + 1);
-        }
-    }
-
     std::vector<std::string> getAllKeywords()
     {
         std::vector<std::string> output;
diff --git a/tests/unittests/Suites/ReplSuite.cpp b/tests/unittests/Suites/ReplSuite.cpp
@@ -9,35 +9,6 @@ using namespace boost;
 ut::suite<"Repl"> repl_suite = [] {
     using namespace ut;
 
-    "countOpenEnclosures"_test = [] {
-        expect(that % Ark::internal::countOpenEnclosures("", '(', ')') == 0);
-        expect(that % Ark::internal::countOpenEnclosures("(", '(', ')') == 1);
-        expect(that % Ark::internal::countOpenEnclosures(")", '(', ')') == -1);
-        expect(that % Ark::internal::countOpenEnclosures("{}", '(', ')') == 0);
-        expect(that % Ark::internal::countOpenEnclosures("{)(()}", '(', ')') == 0);
-        expect(that % Ark::internal::countOpenEnclosures("{)(()}", '{', '}') == 0);
-    };
-
-    "trimWhitespace"_test = [] {
-        const std::string expected = "hello world";
-        std::string line = expected;
-
-        Ark::internal::trimWhitespace(line);
-        expect(that % line == expected);
-
-        line = "  \thello world";
-        Ark::internal::trimWhitespace(line);
-        expect(that % line == expected);
-
-        line = "hello world  \t";
-        Ark::internal::trimWhitespace(line);
-        expect(that % line == expected);
-
-        line = "  \thello world  \t";
-        Ark::internal::trimWhitespace(line);
-        expect(that % line == expected);
-    };
-
     const auto kws = Ark::internal::getAllKeywords();
     const auto colors = Ark::internal::getColorPerKeyword();
     const auto append_color = std::ranges::find_if(colors, [](const auto& pair) {
diff --git a/tests/unittests/Suites/ToolsSuite.cpp b/tests/unittests/Suites/ToolsSuite.cpp
@@ -39,6 +39,35 @@ ut::suite<"Tools"> tools_suite = [] {
         expect(that % Ark::Utils::levenshteinDistance("arkscript", "OrC") == 8_z);
     };
 
+    "countOpenEnclosures"_test = [] {
+        expect(that % Ark::Utils::countOpenEnclosures("", '(', ')') == 0);
+        expect(that % Ark::Utils::countOpenEnclosures("(", '(', ')') == 1);
+        expect(that % Ark::Utils::countOpenEnclosures(")", '(', ')') == -1);
+        expect(that % Ark::Utils::countOpenEnclosures("{}", '(', ')') == 0);
+        expect(that % Ark::Utils::countOpenEnclosures("{)(()}", '(', ')') == 0);
+        expect(that % Ark::Utils::countOpenEnclosures("{)(()}", '{', '}') == 0);
+    };
+
+    "trimWhitespace"_test = [] {
+        const std::string expected = "hello world";
+        std::string line = expected;
+
+        Ark::Utils::trimWhitespace(line);
+        expect(that % line == expected);
+
+        line = "  \thello world";
+        Ark::Utils::trimWhitespace(line);
+        expect(that % line == expected);
+
+        line = "hello world  \t";
+        Ark::Utils::trimWhitespace(line);
+        expect(that % line == expected);
+
+        line = "  \thello world  \t";
+        Ark::Utils::trimWhitespace(line);
+        expect(that % line == expected);
+    };
+
     "Utils::fileExists"_test = [] {
         expect(Ark::Utils::fileExists(".gitignore"));
         expect(!Ark::Utils::fileExists(""));

Original file line number	Diff line number	Diff line change
`@@ -1197,6 +1197,9 @@ namespace Ark`
`1197`	`1197`	`initDebugger(context);`
`1198`	`1198`	`m_debugger->run(*this, context);`
`1199`	`1199`	`m_debugger->resetContextToSavedState(context);`
	`1200`	`+`
	`1201`	`+ if (m_debugger->shouldQuitVM())`
	`1202`	`+ GOTO_HALT();`
`1200`	`1203`	`}`
`1201`	`1204`	`}`
`1202`	`1205`	`DISPATCH();`