forthic 0.2.0 → 0.3.0

data/lib/forthic/decorators/word.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require_relative '../module'
+require_relative '../word_options'
+
+module Forthic
+  module Decorators
+    # WordMetadata - Struct for word metadata
+    WordMetadata = Struct.new(:stack_effect, :description, :word_name, :method_name, :input_count, keyword_init: true)
+
+    # DirectWordMetadata - Struct for direct word metadata
+    DirectWordMetadata = Struct.new(:stack_effect, :description, :word_name, :method_name, keyword_init: true)
+
+    # ModuleMetadata - Struct for module-level metadata
+    ModuleMetadata = Struct.new(:description, :categories, :options_info, :examples, keyword_init: true) do
+      def initialize(description: '', categories: [], options_info: nil, examples: [])
+        super
+      end
+    end
+
+    # Category - Struct for category metadata
+    Category = Struct.new(:name, :words, keyword_init: true)
+
+    # Parse markdown-formatted module documentation string
+    #
+    # Expected format:
+    # ```
+    # Brief description
+    #
+    # ## Categories
+    # - Category Name: WORD1, WORD2, WORD3
+    # - Another Category: WORD4, WORD5
+    #
+    # ## Options
+    # Multi-line text describing the options system
+    #
+    # ## Examples
+    # example code line 1
+    # example code line 2
+    # ```
+    #
+    # @param doc_string [String] The documentation string to parse
+    # @return [ModuleMetadata] Parsed metadata
+    def self.parse_module_doc_string(doc_string)
+      lines = doc_string.split("\n").map(&:strip).reject(&:empty?)
+
+      result = ModuleMetadata.new
+      current_section = :description
+      options_lines = []
+
+      lines.each do |line|
+        # Check for section headers
+        if line.start_with?('## Categories')
+          current_section = :categories
+          next
+        elsif line.start_with?('## Options')
+          current_section = :options
+          next
+        elsif line.start_with?('## Examples')
+          current_section = :examples
+          next
+        end
+
+        # Process content based on current section
+        case current_section
+        when :description
+          if result.description.empty?
+            result.description = line
+          else
+            result.description += ' ' + line
+          end
+        when :categories
+          # Parse "- Category Name: WORD1, WORD2, WORD3"
+          match = line.match(/^-\s*([^:]+):\s*(.+)$/)
+          if match
+            result.categories << Category.new(
+              name: match[1].strip,
+              words: match[2].strip
+            )
+          end
+        when :options
+          options_lines << line
+        when :examples
+          result.examples << line
+        end
+      end
+
+      # Join options lines into a single string
+      result.options_info = options_lines.join("\n") unless options_lines.empty?
+
+      result
+    end
+
+    # Parse Forthic stack notation to extract input count and optional WordOptions
+    #
+    # Examples:
+    #   "( a:any b:any -- sum:number )" → { input_count: 2, has_options: false }
+    #   "( -- value:any )" → { input_count: 0, has_options: false }
+    #   "( items:any[] -- first:any )" → { input_count: 1, has_options: false }
+    #   "( array:any[] [options:WordOptions] -- flat:any[] )" → { input_count: 1, has_options: true }
+    #
+    # @param stack_effect [String] The stack effect notation
+    # @return [Hash] Hash with :input_count and :has_options keys
+    def self.parse_stack_notation(stack_effect)
+      # Remove parentheses and trim
+      trimmed = stack_effect.strip
+      unless trimmed.start_with?("(") && trimmed.end_with?(")")
+        raise ArgumentError, "Stack effect must be wrapped in parentheses: #{stack_effect}"
+      end
+
+      content = trimmed[1..-2].strip
+      parts = content.split("--", 2).map(&:strip)  # Use limit of 2 to ensure we get exactly 2 parts
+      raise ArgumentError, "Invalid stack notation: #{stack_effect}" unless parts.length == 2
+
+      input_part = parts[0]
+      return { input_count: 0, has_options: false } if input_part.empty?
+
+      # Check for optional [options:WordOptions] parameter
+      has_options = input_part.include?('[options:WordOptions]')
+
+      # Remove optional parameter from counting
+      without_optional = input_part.gsub(/\[options:WordOptions\]/, '').strip
+
+      # Split by whitespace, count non-empty tokens
+      inputs = without_optional.split(/\s+/).reject(&:empty?)
+
+      {
+        input_count: inputs.length,
+        has_options: has_options
+      }
+    end
+
+    # DecoratedModule - Base class for modules using word registration
+    #
+    # Automatically registers all decorated words when interpreter is set.
+    class DecoratedModule < Forthic::Module
+      # Class-level metadata storage
+      @word_metadata = {}
+      @direct_word_metadata = {}
+      @module_metadata = {}
+
+      class << self
+        attr_reader :word_metadata, :direct_word_metadata, :module_metadata
+
+        def inherited(subclass)
+          super
+          # Each subclass gets its own metadata storage
+          subclass.instance_variable_set(:@word_metadata, {})
+          subclass.instance_variable_set(:@direct_word_metadata, {})
+          subclass.instance_variable_set(:@module_metadata, nil)
+        end
+
+        # Register a word with automatic stack marshalling
+        #
+        # @param method_name [Symbol] The method name
+        # @param stack_effect [String] Stack effect notation
+        # @param description [String] Human-readable description
+        # @param word_name [String, nil] Custom word name (defaults to method name)
+        def register_forthic_word(method_name, stack_effect, description = "", word_name = nil)
+          word_name ||= method_name.to_s
+          parsed = Decorators.parse_stack_notation(stack_effect)
+
+          @word_metadata[method_name] = WordMetadata.new(
+            stack_effect: stack_effect,
+            description: description,
+            word_name: word_name,
+            method_name: method_name.to_s,
+            input_count: parsed[:input_count]
+          )
+
+          # Store parsed options for later use
+          @word_metadata[method_name].define_singleton_method(:has_options?) do
+            parsed[:has_options]
+          end
+        end
+
+        # Register a direct word (no stack marshalling)
+        #
+        # @param method_name [Symbol] The method name
+        # @param stack_effect [String] Stack effect notation
+        # @param description [String] Human-readable description
+        # @param word_name [String, nil] Custom word name (defaults to method name)
+        def register_forthic_direct_word(method_name, stack_effect, description = "", word_name = nil)
+          word_name ||= method_name.to_s
+
+          @direct_word_metadata[method_name] = DirectWordMetadata.new(
+            stack_effect: stack_effect,
+            description: description,
+            word_name: word_name,
+            method_name: method_name.to_s
+          )
+        end
+
+        # Register module documentation
+        #
+        # @param doc_string [String] Markdown-formatted documentation
+        def register_module_doc(doc_string)
+          @module_metadata = Decorators.parse_module_doc_string(doc_string)
+        end
+      end
+
+      def set_interp(interp)
+        super(interp)
+        register_decorated_words
+      end
+
+      private
+
+      def register_decorated_words
+        # Register words with stack marshalling
+        self.class.word_metadata.each do |method_name, metadata|
+          # Create wrapper that handles stack marshalling
+          wrapper = create_word_wrapper(method_name, metadata)
+          add_module_word(metadata.word_name, wrapper)
+        end
+
+        # Register direct words (no wrapping)
+        self.class.direct_word_metadata.each do |method_name, metadata|
+          # Bind method directly
+          add_module_word(metadata.word_name, method(method_name).to_proc)
+        end
+      end
+
+      def create_word_wrapper(method_name, metadata)
+        original_method = method(method_name)
+        input_count = metadata.input_count
+        has_options = metadata.respond_to?(:has_options?) && metadata.has_options?
+
+        lambda do |interp|
+          inputs = []
+
+          # Check for optional WordOptions FIRST (before popping regular args)
+          options = nil
+          if has_options && interp.get_stack.length > 0
+            top = interp.stack_peek
+            if top.is_a?(WordOptions)
+              opts = interp.stack_pop
+              options = opts.to_hash
+            end
+          end
+
+          # Pop required inputs in reverse order (stack is LIFO)
+          input_count.times do
+            inputs.unshift(interp.stack_pop)
+          end
+
+          # Add options as last parameter if method expects it
+          inputs << (options || {}) if has_options
+
+          # Call original method with popped inputs (+ options if present)
+          result = original_method.call(*inputs)
+
+          # Push result if not nil (Ruby uses nil instead of undefined)
+          interp.stack_push(result) unless result.nil?
+        end
+      end
+
+      public
+
+      # Get documentation for all words in this module
+      #
+      # @return [Array<Hash>] Array of {name, stack_effect, description} hashes
+      def get_word_docs
+        docs = []
+
+        # Get words with stack marshalling
+        self.class.word_metadata.each_value do |meta|
+          docs << {
+            name: meta.word_name,
+            stack_effect: meta.stack_effect,
+            description: meta.description
+          }
+        end
+
+        # Get direct words
+        self.class.direct_word_metadata.each_value do |meta|
+          docs << {
+            name: meta.word_name,
+            stack_effect: meta.stack_effect,
+            description: meta.description
+          }
+        end
+
+        docs
+      end
+
+      # Get module-level documentation
+      #
+      # @return [Hash, nil] Module metadata with name, or nil if not set
+      def get_module_metadata
+        parsed = self.class.module_metadata
+        return nil unless parsed
+
+        # Combine parsed metadata with the module name from the instance
+        {
+          name: get_name,
+          description: parsed.description,
+          categories: parsed.categories,
+          options_info: parsed.options_info,
+          examples: parsed.examples
+        }
+      end
+    end
+
+    # Helper method to define a word on a module class
+    #
+    # Usage:
+    #   class MyModule < DecoratedModule
+    #     word :ADD, "( a:number b:number -- sum:number )", "Adds two numbers"
+    #     def ADD(a, b)
+    #       a + b
+    #     end
+    #   end
+    module WordDSL
+      def forthic_word(method_name, stack_effect, description = "", word_name = nil)
+        register_forthic_word(method_name, stack_effect, description, word_name)
+      end
+
+      def forthic_direct_word(method_name, stack_effect, description = "", word_name = nil)
+        register_forthic_direct_word(method_name, stack_effect, description, word_name)
+      end
+
+      def module_doc(doc_string)
+        register_module_doc(doc_string)
+      end
+    end
+
+    # Extend DecoratedModule class to include DSL methods
+    DecoratedModule.singleton_class.prepend(WordDSL)
+  end
+end

data/lib/forthic/errors.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+module Forthic
+  # CodeLocationData - Struct for tracking code location information
+  #
+  # @!attribute source
+  #   @return [String, nil] Source of the code (e.g., module name, file path)
+  # @!attribute line
+  #   @return [Integer] Line number
+  # @!attribute column
+  #   @return [Integer] Column number
+  # @!attribute start_pos
+  #   @return [Integer] Start position in the source string
+  # @!attribute end_pos
+  #   @return [Integer, nil] End position in the source string
+  CodeLocationData = Struct.new(:source, :line, :column, :start_pos, :end_pos, keyword_init: true)
+
+  # ForthicError - Base error class for Forthic interpreter
+  class ForthicError < StandardError
+    attr_reader :forthic, :note, :location, :cause
+
+    def initialize(forthic, note, location: nil, cause: nil)
+      super(note)
+      @forthic = forthic
+      @note = note
+      @location = location
+      @cause = cause
+    end
+
+    def get_description
+      raise NotImplementedError, "#{self.class}#get_description not implemented"
+    end
+
+    def get_error
+      self
+    end
+
+    def get_forthic
+      @forthic
+    end
+
+    def get_note
+      @note
+    end
+  end
+
+  # UnknownWordError - Error when interpreter encounters an unknown word
+  class UnknownWordError < ForthicError
+    attr_reader :word
+
+    def initialize(forthic, word, location: nil, cause: nil)
+      note = "Unknown word: #{word}"
+      super(forthic, note, location: location, cause: cause)
+      @word = word
+    end
+
+    def get_word
+      @word
+    end
+  end
+
+  # WordExecutionError - Error during word execution
+  class WordExecutionError < ForthicError
+    attr_reader :inner_error, :definition_location
+
+    def initialize(message, error, call_location: nil, definition_location: nil)
+      super("", message, location: call_location)
+      @inner_error = error
+      @definition_location = definition_location
+    end
+
+    def get_error
+      @inner_error
+    end
+
+    def get_definition_location
+      @definition_location
+    end
+  end
+
+  # MissingSemicolonError - Error when semicolon is missing
+  class MissingSemicolonError < ForthicError
+    def initialize(forthic, location: nil, cause: nil)
+      note = "Missing semicolon"
+      super(forthic, note, location: location, cause: cause)
+    end
+  end
+
+  # ExtraSemicolonError - Error when there's an extra semicolon
+  class ExtraSemicolonError < ForthicError
+    def initialize(forthic, location: nil, cause: nil)
+      note = "Extra semicolon"
+      super(forthic, note, location: location, cause: cause)
+    end
+  end
+
+  # StackUnderflowError - Error when stack has too few items
+  class StackUnderflowError < ForthicError
+    def initialize(forthic, location: nil, cause: nil)
+      note = "Stack underflow"
+      super(forthic, note, location: location, cause: cause)
+    end
+  end
+
+  # InvalidVariableNameError - Error for invalid variable names
+  class InvalidVariableNameError < ForthicError
+    attr_reader :varname
+
+    def initialize(forthic, varname, location: nil, cause: nil)
+      note = "Invalid variable name: #{varname}"
+      super(forthic, note, location: location, cause: cause)
+      @varname = varname
+    end
+
+    def get_varname
+      @varname
+    end
+  end
+
+  # UnknownModuleError - Error when module is not found
+  class UnknownModuleError < ForthicError
+    attr_reader :module_name
+
+    def initialize(forthic, module_name, location: nil, cause: nil)
+      note = "Unknown module: #{module_name}"
+      super(forthic, note, location: location, cause: cause)
+      @module_name = module_name
+    end
+
+    def get_module_name
+      @module_name
+    end
+  end
+
+  # InvalidInputPositionError - Error for invalid input position
+  class InvalidInputPositionError < ForthicError
+    def initialize(forthic, location: nil, cause: nil)
+      note = "Invalid input position"
+      super(forthic, note, location: location, cause: cause)
+    end
+  end
+
+  # InvalidWordNameError - Error for invalid word names
+  class InvalidWordNameError < ForthicError
+    def initialize(forthic, location: nil, note: nil, cause: nil)
+      error_note = note || "Invalid word name"
+      super(forthic, error_note, location: location, cause: cause)
+    end
+  end
+
+  # UnterminatedStringError - Error for unterminated strings
+  class UnterminatedStringError < ForthicError
+    def initialize(forthic, location: nil, cause: nil)
+      note = "Unterminated string"
+      super(forthic, note, location: location, cause: cause)
+    end
+  end
+
+  # UnknownTokenError - Error for unknown token types
+  class UnknownTokenError < ForthicError
+    attr_reader :token
+
+    def initialize(forthic, token, location: nil, cause: nil)
+      note = "Unknown type of token: #{token}"
+      super(forthic, note, location: location, cause: cause)
+      @token = token
+    end
+
+    def get_token
+      @token
+    end
+  end
+
+  # ModuleError - Error in module execution
+  class ModuleError < ForthicError
+    attr_reader :module_name, :error
+
+    def initialize(forthic, module_name, error, location: nil, cause: nil)
+      note = "Error in module #{module_name}: #{error.message}"
+      super(forthic, note, location: location, cause: cause)
+      @module_name = module_name
+      @error = error
+    end
+
+    def get_module_name
+      @module_name
+    end
+
+    def get_error
+      @error
+    end
+  end
+
+  # TooManyAttemptsError - Error when recovery attempts exceed maximum
+  class TooManyAttemptsError < ForthicError
+    attr_reader :num_attempts, :max_attempts
+
+    def initialize(forthic, num_attempts, max_attempts, location: nil, cause: nil)
+      note = "Too many recovery attempts: #{num_attempts} of #{max_attempts}"
+      super(forthic, note, location: location, cause: cause)
+      @num_attempts = num_attempts
+      @max_attempts = max_attempts
+    end
+
+    def get_num_attempts
+      @num_attempts
+    end
+
+    def get_max_attempts
+      @max_attempts
+    end
+  end
+
+  # IntentionalStopError - Error for intentional execution stops (PEEK!, STACK!)
+  class IntentionalStopError < StandardError
+    def initialize(message)
+      super(message)
+    end
+  end
+
+  # Get formatted error description with code context
+  #
+  # @param forthic [String] The Forthic source code
+  # @param forthic_error [ForthicError] The error to format
+  # @return [String] Formatted error message with code context
+  def self.get_error_description(forthic, forthic_error)
+    # If don't have any extra info, just return the note
+    if forthic.nil? || forthic.empty? || forthic_error.location.nil?
+      return forthic_error.get_note
+    end
+
+    # Otherwise, return the note and indicate where the error occurred
+    location = forthic_error.location
+
+    # For WordExecutionError, show both definition and call locations
+    if forthic_error.is_a?(WordExecutionError)
+      def_loc = forthic_error.get_definition_location
+      if def_loc
+        # Show definition location with highlighting
+        def_line_num = def_loc.line
+        def_lines = forthic.split("\n")[0...def_line_num]
+        def_error_line = " " * (def_loc.column - 1) + "^" * ((def_loc.end_pos || def_loc.start_pos + 1) - def_loc.start_pos)
+
+        def_location_info = "at line #{def_line_num}"
+        def_location_info += " in #{def_loc.source}" if def_loc.source
+
+        # Show call location with highlighting
+        call_line_num = location.line
+        call_lines = forthic.split("\n")[0...call_line_num]
+        call_error_line = " " * (location.column - 1) + "^" * ((location.end_pos || location.start_pos + 1) - location.start_pos)
+
+        call_location_info = "line #{call_line_num}"
+        call_location_info += " in #{location.source}" if location.source
+
+        return "#{forthic_error.get_note} #{def_location_info}:\n```\n#{def_lines.join("\n")}\n#{def_error_line}\n```\nCalled from #{call_location_info}:\n```\n#{call_lines.join("\n")}\n#{call_error_line}\n```"
+      end
+    end
+
+    # Standard error format for other errors
+    line_num = location.line
+    lines = forthic.split("\n")[0...line_num]
+    error_line = " " * (location.column - 1) + "^" * ((location.end_pos || location.start_pos + 1) - location.start_pos)
+
+    location_info = "at line #{line_num}"
+    location_info += " in #{location.source}" if location.source
+
+    error_message = "#{forthic_error.get_note} #{location_info}:\n```\n#{lines.join("\n")}\n#{error_line}\n```"
+    error_message
+  end
+end