forthic 0.1.0 → 0.2.4

data/lib/forthic/interpreter.rb

@@ -1,49 +1,138 @@
 # frozen_string_literal: true
 
-require_relative 'forthic_error'
-require_relative 'tokenizer'
-require_relative 'token'
-require_relative 'code_location'
-require_relative 'positioned_string'
-require_relative 'words/word'
-require_relative 'words/push_value_word'
-require_relative 'words/start_module_word'
-require_relative 'words/end_module_word'
-require_relative 'words/end_array_word'
-require_relative 'words/definition_word'
-require_relative 'global_module'
+require_relative "forthic_error"
+require_relative "errors/unknown_word_error"
+require_relative "tokenizer"
+require_relative "token"
+require_relative "code_location"
+require_relative "positioned_string"
+require_relative "words/word"
+require_relative "words/push_value_word"
+require_relative "words/start_module_word"
+require_relative "words/end_module_word"
+require_relative "words/end_array_word"
+require_relative "words/definition_word"
+require_relative "global_module"
 
 module Forthic
-  class Interpreter
-    attr_accessor :stack, :global_module, :app_module, :module_stack, :registered_modules,
-                  :is_compiling, :should_stop, :is_memo_definition, :cur_definition,
-                  :screens, :default_module_flags, :module_flags, :string_location,
-                  :word_counts, :is_profiling, :start_profile_time, :timestamps
+  # Error codes used throughout the interpreter
+  module ErrorCodes
+    SCREEN_NOT_FOUND = "screen-not-found"
+    EXECUTION_ERROR = "execution-error"
+    MODULE_NOT_FOUND = "module-not-found"
+    STACK_UNDERFLOW = "stack-underflow"
+    MODULE_EXECUTION_ERROR = "module-execution-error"
+    UNKNOWN_TOKEN = "unknown-token"
+    NESTED_DEFINITION = "nested-definition"
+    NESTED_MEMO_DEFINITION = "nested-memo-definition"
+    DEFINITION_WITHOUT_START = "definition-without-start"
+    MISSING_DEFINITION = "missing-definition"
+    WORD_NOT_FOUND = "word-not-found"
+  end
 
-    def initialize
+  # Manages execution state for the interpreter
+  class ExecutionState
+    attr_accessor :stack, :module_stack, :is_compiling, :should_stop,
+      :is_memo_definition, :cur_definition, :string_location
+
+    def initialize(app_module)
       @stack = []
-      @registered_modules = {}
+      @module_stack = [app_module]
       @is_compiling = false
       @should_stop = false
       @is_memo_definition = false
       @cur_definition = nil
-      @screens = {}
-      @default_module_flags = {}
-      @module_flags = {}
       @string_location = nil
+    end
 
-      @global_module = GlobalModule.new(self)
-      @app_module = ForthicModule.new("", self)
-      @module_stack = [@app_module]
+    def reset(app_module)
+      @stack = []
+      @module_stack = [app_module]
+      @is_compiling = false
+      @is_memo_definition = false
+      @cur_definition = nil
+      @string_location = nil
+    end
+  end
+
+  # Manages profiling state and operations
+  class ProfilingState
+    attr_reader :word_counts, :is_profiling, :start_profile_time, :timestamps
 
+    def initialize
       @word_counts = {}
       @is_profiling = false
       @start_profile_time = nil
       @timestamps = []
     end
 
+    def start_profiling
+      @is_profiling = true
+      @timestamps = []
+      @start_profile_time = Time.now
+      add_timestamp("START")
+      @word_counts = {}
+    end
+
+    def stop_profiling
+      add_timestamp("END")
+      @is_profiling = false
+    end
+
+    def count_word(word)
+      return unless @is_profiling
+      @word_counts[word.name] ||= 0
+      @word_counts[word.name] += 1
+    end
+
+    def add_timestamp(label)
+      return unless @is_profiling
+      timestamp = {label: label, time_ms: (Time.now - @start_profile_time) * 1000}
+      @timestamps.push(timestamp)
+    end
+
+    def word_histogram
+      @word_counts.map { |name, count| {word: name, count: count} }.sort_by { |item| -item[:count] }
+    end
+  end
+
+  class Interpreter
+    # Core interpreter components
+    attr_reader :global_module, :app_module, :registered_modules
+    # Screen and module management
+    attr_accessor :screens, :default_module_flags, :module_flags
+    # State objects
+    attr_reader :execution_state, :profiling_state
+
+    # Token handler lookup table
+    TOKEN_HANDLERS = {
+      TokenType::STRING => :handle_string_token,
+      TokenType::COMMENT => :handle_comment_token,
+      TokenType::START_ARRAY => :handle_start_array_token,
+      TokenType::END_ARRAY => :handle_end_array_token,
+      TokenType::START_MODULE => :handle_start_module_token,
+      TokenType::END_MODULE => :handle_end_module_token,
+      TokenType::START_DEF => :handle_start_definition_token,
+      TokenType::START_MEMO => :handle_start_memo_token,
+      TokenType::END_DEF => :handle_end_definition_token,
+      TokenType::WORD => :handle_word_token
+    }.freeze
+
+    def initialize
+      @registered_modules = {}
+      @screens = {}
+      @default_module_flags = {}
+      @module_flags = {}
+
+      @global_module = GlobalModule.new(self)
+      @app_module = ForthicModule.new("", self)
+
+      @execution_state = ExecutionState.new(@app_module)
+      @profiling_state = ProfilingState.new
+    end
+
     def halt
-      @should_stop = true
+      @execution_state.should_stop = true
     end
 
     # @return [ForthicModule]
@@ -53,7 +142,28 @@ module Forthic
 
     # @return [CodeLocation, nil]
     def get_string_location
-      @string_location
+      @execution_state.string_location
+    end
+
+    # Delegation methods for execution state
+    def stack
+      @execution_state.stack
+    end
+
+    def stack=(new_stack)
+      @execution_state.stack = new_stack
+    end
+
+    def module_stack
+      @execution_state.module_stack
+    end
+
+    def is_compiling
+      @execution_state.is_compiling
+    end
+
+    def cur_definition
+      @execution_state.cur_definition
     end
 
     # @param [String] module_id
@@ -80,20 +190,15 @@ module Forthic
     end
 
     def reset
-      @stack = []
       @app_module.variables = {}
-      @module_stack = [@app_module]
-      @is_compiling = false
-      @is_memo_definition = false
-      @cur_definition = nil
-      @string_location = nil
+      @execution_state.reset(@app_module)
     end
 
     # @param [String] screen_name
     # @return [String]
     def get_screen_forthic(screen_name)
       screen = @screens[screen_name]
-      raise ForthicError.new("interpreter-199", "Unable to find screen \"#{screen_name}\"", "Hmmm...something went wrong. Please file a ticket if this continues to happen") unless screen
+      raise ForthicError.new(ErrorCodes::SCREEN_NOT_FOUND, "Unable to find screen \"#{screen_name}\"", "Screen not found. Check the screen name for typos or ensure it has been properly registered.") unless screen
       screen
     end
 
@@ -112,63 +217,82 @@ module Forthic
       loop do
         token = tokenizer.next_token
         handle_token(token)
-        break if token.type == TokenType::EOS || @should_stop
-        next if [TokenType::START_DEF, TokenType::END_DEF, TokenType::COMMENT].include?(token.type) || @is_compiling
+        break if token.type == TokenType::EOS || @execution_state.should_stop
+        next if [TokenType::START_DEF, TokenType::END_DEF, TokenType::COMMENT].include?(token.type) || @execution_state.is_compiling
       end
       true
-    # rescue => e
-    #   error = ForthicError.new("interpreter-213", "Ran into an error executing this '#{token.string}'", "If there is an unknown error in the stack details, please file a ticket so we can resolve it.", token.location)
-    #   error.set_caught_error(e)
-    #   raise error
+    rescue ForthicError => e
+      # Re-raise ForthicError and its subclasses without wrapping
+      raise e
+    rescue => e
+      # Wrap non-ForthicError exceptions
+      error = ForthicError.new(ErrorCodes::EXECUTION_ERROR, "Error executing token '#{token&.string}'", "An unexpected error occurred during execution. Check the token syntax and try again.", token&.location)
+      error.set_caught_error(e)
+      raise error
     end
 
     # @return [ForthicModule]
     def cur_module
-      @module_stack.last
+      @execution_state.module_stack.last
     end
 
     # @param [String] name
     # @return [ForthicModule]
     def find_module(name)
+      raise ArgumentError, "Module name cannot be nil" if name.nil?
+      raise ArgumentError, "Module name cannot be empty" if name.empty?
+
       result = @registered_modules[name]
-      raise ForthicError.new("interpreter-236", "Couldn't find '#{name}' module", "This is most likely a typo in your Forthic code. Please check to see if '#{name}' is properly spelled and that you have permission to access it") unless result
+      raise ForthicError.new(ErrorCodes::MODULE_NOT_FOUND, "Module '#{name}' not found", "Check the module name for typos and ensure it has been properly registered.") unless result
       result
     end
 
     # @param [Object] val
     def stack_push(val)
-      @stack.push(val)
+      @execution_state.stack.push(val)
     end
 
     # @return [Object]
     def stack_pop
-      raise ForthicError.new("interpreter-251", "Stack underflow", "This happens when we expect something to be on the stack, but it's empty. This is caused by a logical error in the Forthic and can be resolved through debugging.") if @stack.empty?
-      result = @stack.pop
-      @string_location = result.is_a?(PositionedString) ? result.location : nil
+      raise ForthicError.new(ErrorCodes::STACK_UNDERFLOW, "Stack underflow", "Attempted to pop from an empty stack. This indicates a logical error in the Forthic code.") if @execution_state.stack.empty?
+      result = @execution_state.stack.pop
+      @execution_state.string_location = result.is_a?(PositionedString) ? result.location : nil
       result.is_a?(PositionedString) ? result.value_of : result
     end
 
     # @param [ForthicModule] mod
     def module_stack_push(mod)
-      @module_stack.push(mod)
+      raise ArgumentError, "Module cannot be nil" if mod.nil?
+      @execution_state.module_stack.push(mod)
     end
 
     def module_stack_pop
-      @module_stack.pop
+      @execution_state.module_stack.pop
     end
 
     # @param [ForthicModule] mod
     def register_module(mod)
+      raise ArgumentError, "Module cannot be nil" if mod.nil?
+      raise ArgumentError, "Module must respond to :name" unless mod.respond_to?(:name)
       @registered_modules[mod.name] = mod
     end
 
+    # @param [ForthicModule] mod
+    # @param [String] prefix
+    def import_module(mod, prefix = "")
+      raise ArgumentError, "Module cannot be nil" if mod.nil?
+      register_module(mod)
+      @app_module.import_module(prefix, mod, self)
+    end
+
     # @param [ForthicModule] mod
     def run_module_code(mod)
+      raise ArgumentError, "Module cannot be nil" if mod.nil?
       module_stack_push(mod)
       run(mod.forthic_code)
       module_stack_pop
     rescue => e
-      error = ForthicError.new("interpreter-278", "Something went wrong when running the module #{mod.name}", "TODO: File a ticket")
+      error = ForthicError.new(ErrorCodes::MODULE_EXECUTION_ERROR, "Error executing module '#{mod.name}'", "An error occurred while running the module code. Check the module implementation for syntax errors.")
       error.set_caught_error(e)
       raise error
     end
@@ -177,7 +301,7 @@ module Forthic
     # @return [Word, nil]
     def find_word(name)
       result = nil
-      @module_stack.reverse_each do |m|
+      @execution_state.module_stack.reverse_each do |m|
         result = m.find_word(name)
         break if result
       end
@@ -185,59 +309,40 @@ module Forthic
       result
     end
 
+    # Delegation methods for profiling
     def start_profiling
-      @is_profiling = true
-      @timestamps = []
-      @start_profile_time = Time.now
-      add_timestamp("START")
-      @word_counts = {}
+      @profiling_state.start_profiling
     end
 
-    # @param [Word] word
-    def count_word(word)
-      return unless @is_profiling
-      @word_counts[word.name] ||= 0
-      @word_counts[word.name] += 1
+    def stop_profiling
+      @profiling_state.stop_profiling
     end
 
-    def stop_profiling
-      add_timestamp("END")
-      @is_profiling = false
+    def count_word(word)
+      @profiling_state.count_word(word)
     end
 
-    # @param [String] label
     def add_timestamp(label)
-      return unless @is_profiling
-      timestamp = { label: label, time_ms: (Time.now - @start_profile_time) * 1000 }
-      @timestamps.push(timestamp)
+      @profiling_state.add_timestamp(label)
     end
 
-    # @return [Array<Hash>]
     def word_histogram
-      @word_counts.map { |name, count| { word: name, count: count } }.sort_by { |item| -item[:count] }
+      @profiling_state.word_histogram
     end
 
-    # @return [Array<Hash>]
     def profile_timestamps
-      @timestamps
+      @profiling_state.timestamps
     end
 
     # @param [Token] token
     def handle_token(token)
-      case token.type
-      when TokenType::STRING then handle_string_token(token)
-      when TokenType::COMMENT then handle_comment_token(token)
-      when TokenType::START_ARRAY then handle_start_array_token(token)
-      when TokenType::END_ARRAY then handle_end_array_token(token)
-      when TokenType::START_MODULE then handle_start_module_token(token)
-      when TokenType::END_MODULE then handle_end_module_token(token)
-      when TokenType::START_DEF then handle_start_definition_token(token)
-      when TokenType::START_MEMO then handle_start_memo_token(token)
-      when TokenType::END_DEF then handle_end_definition_token(token)
-      when TokenType::WORD then handle_word_token(token)
-      when TokenType::EOS then return
+      return if token.type == TokenType::EOS
+
+      handler = TOKEN_HANDLERS[token.type]
+      if handler
+        send(handler, token)
       else
-        raise ForthicError.new("interpreter-362", "Hmmm...the interpreter doesn't know what to make of '#{token.string}'", "This is most likely caused by a typo in the Forthic code and can be resolved by debugging.", token.location)
+        raise ForthicError.new(ErrorCodes::UNKNOWN_TOKEN, "Unknown token type '#{token.string}'", "This token type is not recognized. Check for typos or unsupported syntax.", token.location)
       end
     end
 
@@ -250,7 +355,7 @@ module Forthic
     # @param [Token] token
     def handle_start_module_token(token)
       word = StartModuleWord.new(token.string)
-      @cur_definition.add_word(word) if @is_compiling
+      @execution_state.cur_definition.add_word(word) if @execution_state.is_compiling
       count_word(word)
       word.execute(self)
     end
@@ -258,7 +363,7 @@ module Forthic
     # @param [Token] _token
     def handle_end_module_token(_token)
       word = EndModuleWord.new
-      @cur_definition.add_word(word) if @is_compiling
+      @execution_state.cur_definition.add_word(word) if @execution_state.is_compiling
       count_word(word)
       word.execute(self)
     end
@@ -280,49 +385,134 @@ module Forthic
 
     # @param [Token] token
     def handle_start_definition_token(token)
-      raise ForthicError.new("interpreter-407", "A definition was started while an existing definition was not ended", "This is probably caused by a missing semicolon. To resolve, ensure that all word definitions end with semicolons.", token.location) if @is_compiling
-      @cur_definition = DefinitionWord.new(token.string)
-      @is_compiling = true
-      @is_memo_definition = false
+      raise ForthicError.new(ErrorCodes::NESTED_DEFINITION, "Nested definition not allowed", "A definition was started while another definition is active. Ensure all definitions end with semicolons.", token.location) if @execution_state.is_compiling
+      @execution_state.cur_definition = DefinitionWord.new(token.string)
+      @execution_state.is_compiling = true
+      @execution_state.is_memo_definition = false
     end
 
     # @param [Token] token
     def handle_start_memo_token(token)
-      raise ForthicError.new("interpreter-420", "A memo definition was started while an existing definition was not ended", "This is probably caused by a missing semicolon. To resolve, ensure that all word definitions end with semicolons.", token.location) if @is_compiling
-      @cur_definition = DefinitionWord.new(token.string)
-      @is_compiling = true
-      @is_memo_definition = true
+      raise ForthicError.new(ErrorCodes::NESTED_MEMO_DEFINITION, "Nested memo definition not allowed", "A memo definition was started while another definition is active. Ensure all definitions end with semicolons.", token.location) if @execution_state.is_compiling
+      @execution_state.cur_definition = DefinitionWord.new(token.string)
+      @execution_state.is_compiling = true
+      @execution_state.is_memo_definition = true
     end
 
     # @param [Token] token
     def handle_end_definition_token(token)
-      raise ForthicError.new("interpreter-433", "A definition was ended when one hadn't been started yet", "This is probably caused by an extra semicolon. To resolve, ensure that there are no spurious semicolons in the Forthic code.", token.location) unless @is_compiling
-      raise ForthicError.new("interpreter-440", "Cannot finish definition because there is no current definition", "Please file a ticket", token.location) unless @cur_definition
-      if @is_memo_definition
-        cur_module.add_memo_words(@cur_definition)
+      raise ForthicError.new(ErrorCodes::DEFINITION_WITHOUT_START, "Definition ended without start", "A definition was ended when none was active. Check for extra semicolons.", token.location) unless @execution_state.is_compiling
+      raise ForthicError.new(ErrorCodes::MISSING_DEFINITION, "No current definition to end", "Internal error: definition state is inconsistent.", token.location) unless @execution_state.cur_definition
+      if @execution_state.is_memo_definition
+        cur_module.add_memo_words(@execution_state.cur_definition)
       else
-        cur_module.add_word(@cur_definition)
+        cur_module.add_word(@execution_state.cur_definition)
       end
-      @is_compiling = false
+      @execution_state.is_compiling = false
     end
 
     # @param [Token] token
     def handle_word_token(token)
       word = find_word(token.string)
-      raise ForthicError.new("interpreter-458", "Could not find word: #{token.string}", "Check to see if you have a typo in your word or the definition of that word", token.location) unless word
+      unless word
+        # Generate suggested words for better error messages
+        suggested_words = find_similar_words(token.string)
+        raise Errors::UnknownWordError.new(token.string, token.location, suggested_words)
+      end
       handle_word(word, token.location)
     end
 
     # @param [Word] word
     # @param [CodeLocation, nil] location
     def handle_word(word, location = nil)
-      if @is_compiling
+      if @execution_state.is_compiling
         word.set_location(location)
-        @cur_definition.add_word(word)
+        @execution_state.cur_definition.add_word(word)
       else
         count_word(word)
         word.execute(self)
       end
     end
+
+    private
+
+    # Find words similar to the given word name for error suggestions
+    # @param [String] word_name The unknown word to find suggestions for
+    # @return [Array<String>] Array of similar word names
+    def find_similar_words(word_name)
+      return [] if word_name.nil? || word_name.empty?
+
+      all_words = collect_available_words
+
+      # Find words with similar names using simple string distance
+      suggestions = all_words.select do |available_word|
+        levenshtein_distance(word_name.downcase, available_word.downcase) <= 2
+      end
+
+      # If no close matches, try prefix matching
+      if suggestions.empty?
+        suggestions = all_words.select do |available_word|
+          available_word.downcase.start_with?(word_name[0, 2].downcase) ||
+            word_name.downcase.start_with?(available_word[0, 2].downcase)
+        end
+      end
+
+      suggestions.take(3)
+    end
+
+    # Collect all available word names from all modules in scope
+    # @return [Array<String>] Array of all available word names
+    def collect_available_words
+      words = []
+
+      # Collect from global module (hardcoded common words since GlobalModule uses methods)
+      global_words = %w[
+        POP DUP SWAP >STR CONCAT SPLIT JOIN /N /R /T LOWERCASE UPPERCASE
+        APPEND REVERSE UNIQUE MAP FOREACH KEYS VALUES LENGTH RANGE SLICE
+        SELECT TAKE DROP NTH LAST FLATTEN REDUCE + - * / MOD
+        == != > >= < <= OR AND NOT IN BOOL INT FLOAT
+        VARIABLES ! @ !@ INTERPRET EXPORT USE-MODULES REC
+      ]
+      words.concat(global_words)
+
+      # Collect from module stack
+      @execution_state.module_stack.each do |mod|
+        if mod.respond_to?(:words) && mod.words
+          words.concat(mod.words.map(&:name))
+        end
+      end
+
+      words.uniq.compact
+    end
+
+    # Calculate Levenshtein distance between two strings
+    # @param [String] str1
+    # @param [String] str2
+    # @return [Integer] The edit distance between the strings
+    def levenshtein_distance(str1, str2)
+      return str2.length if str1.empty?
+      return str1.length if str2.empty?
+
+      # Create matrix
+      matrix = Array.new(str1.length + 1) { Array.new(str2.length + 1, 0) }
+
+      # Initialize first row and column
+      (0..str1.length).each { |i| matrix[i][0] = i }
+      (0..str2.length).each { |j| matrix[0][j] = j }
+
+      # Fill matrix
+      (1..str1.length).each do |i|
+        (1..str2.length).each do |j|
+          cost = (str1[i - 1] == str2[j - 1]) ? 0 : 1
+          matrix[i][j] = [
+            matrix[i - 1][j] + 1,      # deletion
+            matrix[i][j - 1] + 1,      # insertion
+            matrix[i - 1][j - 1] + cost # substitution
+          ].min
+        end
+      end
+
+      matrix[str1.length][str2.length]
+    end
   end
-end
+end

data/lib/forthic/token.rb

@@ -16,7 +16,6 @@ module Forthic
   end
 end
 
-
 module Forthic
   class Token
     attr_reader :type, :value, :location
@@ -35,4 +34,4 @@ module Forthic
       @value
     end
   end
-end
+end

data/lib/forthic/tokenizer.rb

@@ -3,8 +3,8 @@
 module Forthic
   class Tokenizer
     attr_accessor :reference_location, :line, :column, :input_string, :input_pos,
-                  :whitespace, :quote_chars, :token_start_pos, :token_end_pos,
-                  :token_line, :token_column, :token_string
+      :whitespace, :quote_chars, :token_start_pos, :token_end_pos,
+      :token_line, :token_column, :token_string
 
     # @param [String] string
     # @param [CodeLocation, nil] reference_location
@@ -302,4 +302,4 @@ module Forthic
       Token.new(TokenType::WORD, @token_string, get_token_location)
     end
   end
-end
+end

data/lib/forthic/variable.rb

@@ -31,4 +31,4 @@ module Forthic
       Variable.new(@name, @value)
     end
   end
-end
+end

data/lib/forthic/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Forthic
-  VERSION = "0.1.0"
+  VERSION = "0.2.4"
 end

data/lib/forthic/words/definition_word.rb

@@ -1,7 +1,7 @@
-# # frozen_string_literal: true
+# frozen_string_literal: true
 
-require_relative 'word'
-require_relative '../forthic_error'
+require_relative "word"
+require_relative "../forthic_error"
 
 module Forthic
   class DefinitionWord < Word
@@ -9,7 +9,7 @@ module Forthic
 
     # @param [String] name
     def initialize(name)
-      super(name)
+      super
       @words = []
       @cur_index = 0
     end
@@ -22,19 +22,17 @@ module Forthic
     # @param [Interpreter] interp
     def execute(interp)
       @words.each do |word|
-        begin
-          word.execute(interp)
-        rescue => e
-          error = ForthicError.new(
-            "definition_word-29",
-            "Error executing word #{word.name}",
-            "Error in #{self.name} definition",
-            interp.get_string_location
-          )
-          error.set_caught_error(e)
-          raise error
-        end
+        word.execute(interp)
+      rescue => e
+        error = ForthicError.new(
+          "definition_word-29",
+          "Error executing word #{word.name}",
+          "Error in #{name} definition",
+          interp.get_string_location
+        )
+        error.set_caught_error(e)
+        raise error
       end
     end
   end
-end
+end