forthic 0.1.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e71f6368dc2bcc817f0095a389740a6676005ab8ddb862cdef02f0e0910d09d
-  data.tar.gz: b408177ce893d5353aa00ce2a73698005c07e22e3d68a8ec6cade6032887a591
+  metadata.gz: 4ebffd3b7bf74a96a5bdbb6d178996eeea1c2d35edc22743e4dba9154e1e40f9
+  data.tar.gz: a34907460efd7db068214dff1410b512a9a9ad10e3eee149e120eb5b414ebc2f
 SHA512:
-  metadata.gz: 2ffd692800bdf839d25a106c79bea485addaeabb7d2eafd5366a9d034927a642fed7b4ecb498e5f081016f5079077d3a4db4ba96eae113a8ce547024b4164736
-  data.tar.gz: b4ab0aec5f7b788873bbbc71761f5382f565864057101125919338c24453bdccdedbcf26f281dc5c46dee4a16fc7824a08516a52c9c318af91ab0f932a329f42
+  metadata.gz: 7013c8908441bc6aaee014af8e6ac124bf0e60245474adacdcf4a8633c686ef781dc022e0f163a93222dfd3435e5e21c875ac273f13ae029909f51d354fbfdeb
+  data.tar.gz: 759a725d11e735ab283d99e076cf314f72ff98c086cf2dcd0ff93077f2031fa0bb27d814008f63ced3c179b6803f566a10d6b79a5e0082d9c91c30f9159b3d03

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+## [0.2.0] - 2025-01-13
+
+- Add `import_module` method to Interpreter class
+- Add test coverage for module importing functionality
+- Implement module importing with prefix support matching forthic-ts behavior
+
 ## [0.1.0] - 2024-12-27
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Testing
+- `rake test` - Run all tests using Minitest
+- `rake test TEST=test/test_specific_file.rb` - Run a specific test file
+- `bundle exec guard` - Start Guard for continuous testing (watches file changes)
+- `rake guard` - Alternative command to start Guard
+
+### Code Quality
+- `rake standard` - Run StandardRB linter for code formatting and style
+- `rake standard:fix` - Auto-fix StandardRB issues where possible
+- `rake` - Run default task (both tests and linting)
+
+### Development
+- `bundle install` - Install gem dependencies
+- `bundle exec rake build` - Build the gem
+- `bundle exec rake install` - Install the gem locally
+- `bundle exec rake release` - Release the gem (requires proper credentials)
+
+## Architecture Overview
+
+This is a Ruby implementation of the Forthic programming language - a stack-based language inspired by Forth. The codebase follows a clean modular architecture:
+
+### Core Components
+
+**Interpreter (`lib/forthic/interpreter.rb`)**: The main execution engine that:
+- Manages the execution stack and module stack
+- Handles tokenization and parsing of Forthic code
+- Provides word lookup and execution
+- Supports profiling and debugging capabilities
+- Manages compilation of word definitions
+
+**Tokenizer (`lib/forthic/tokenizer.rb`)**: Lexical analyzer that breaks Forthic code into tokens (strings, words, arrays, modules, definitions, comments).
+
+**Word System (`lib/forthic/words/`)**: Polymorphic word execution system where each word type implements an `execute` method:
+- `Word` - Base class for all executable words
+- `PushValueWord` - Pushes values onto the stack
+- `DefinitionWord` - User-defined words compiled from Forthic code
+- `EndArrayWord` - Handles array construction
+- `ModuleWord` variants - Handle module operations and memoization
+- `StartModuleWord`/`EndModuleWord` - Module boundary management
+
+**Module System**: 
+- `GlobalModule` - Built-in words and core functionality
+- `ForthicModule` - User-defined modules with isolated namespaces
+- Module stack for hierarchical word resolution
+
+### Key Design Patterns
+
+- **Stack-based execution**: All operations work with a central execution stack
+- **Autoloading**: Classes are autoloaded for better startup performance
+- **Error handling**: Custom `ForthicError` with location tracking for debugging
+- **Compilation**: Words can be compiled into definition words for reuse
+- **Memoization**: Special memo words for caching expensive computations
+
+### Testing Strategy
+
+Uses Minitest for testing with:
+- `test_helper.rb` sets up Minitest with SpecReporter for better output
+- Guard for continuous testing during development
+- Tests cover tokenizer, interpreter, and module functionality
+- StandardRB enforces consistent code style
+
+### File Organization
+
+- `lib/forthic.rb` - Main entry point with autoload declarations
+- `lib/forthic/` - Core implementation files
+- `lib/forthic/words/` - Word implementation classes
+- `test/` - Test files following Minitest conventions
+- `sig/` - RBS type signatures for static analysis

data/Guardfile

@@ -17,9 +17,9 @@
 
 guard :minitest do
   # with Minitest::Unit
-  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
-  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
-  watch(%r{^test/test_helper\.rb$})      { 'test' }
+  watch(%r{^test/(.*)/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$}) { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$}) { "test" }
 
   # with Minitest::Spec
   # watch(%r{^spec/(.*)_spec\.rb$})

data/README.md

@@ -1,3 +1,13 @@
+> **⚠️ DEPRECATED PACKAGE**
+>
+> This package is from an archived repository and will not receive updates.
+>
+> **New repository:** https://github.com/forthix/forthic-rb
+>
+> Watch the new repository for announcements about updated packages.
+
+---
+
 # Forthic
 
 A Forthic interpreter that runs within Ruby.

data/Rakefile

@@ -11,4 +11,4 @@ task default: %i[test standard]
 
 task :guard do
   sh "bundle exec guard"
-end
+end

data/lib/forthic/code_location.rb

@@ -16,5 +16,20 @@ module Forthic
       @start_pos = start_pos
       @end_pos = end_pos
     end
+
+    # @return [String]
+    def to_s
+      "#{@screen_name}:#{@line}:#{@column}"
+    end
+
+    # @return [Integer]
+    def line_number
+      @line
+    end
+
+    # @return [Integer]
+    def column_number
+      @column
+    end
   end
 end

data/lib/forthic/errors/unknown_word_error.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "../forthic_error"
+
+module Forthic
+  module Errors
+    class UnknownWordError < ForthicError
+      attr_reader :word_name
+
+      # @param [String] word_name The name of the unknown word
+      # @param [CodeLocation, nil] location Where the error occurred
+      # @param [Array<String>] suggested_words Optional list of similar words for suggestions
+      def initialize(word_name, location = nil, suggested_words = [])
+        @word_name = word_name
+        @suggested_words = suggested_words
+
+        description = build_description(suggested_words)
+        super(ErrorCodes::WORD_NOT_FOUND, "Word '#{word_name}' not found", description, location)
+      end
+
+      # @return [Array<String>] List of suggested similar words
+      def suggested_words
+        @suggested_words.dup
+      end
+
+      private
+
+      # @param [Array<String>] suggested_words
+      # @return [String]
+      def build_description(suggested_words)
+        base_description = "Check for typos in the word name or ensure the word has been defined."
+        return base_description if suggested_words.empty?
+
+        suggestions = suggested_words.take(3).join(", ")
+        "#{base_description} Did you mean: #{suggestions}?"
+      end
+    end
+  end
+end

data/lib/forthic/forthic_error.rb

@@ -14,7 +14,6 @@ module Forthic
       @description = description
       @location = location
       @caught_error = nil
-      puts "ForthicError: #{error_key}, #{title}, #{description}, #{location}"
     end
 
     # @param [ForthicError] error
@@ -47,5 +46,20 @@ module Forthic
 
       result.reverse
     end
+
+    # @return [String]
+    def message
+      to_s
+    end
+
+    # @return [String]
+    def to_s
+      parts = [@title]
+      parts << "at #{@location}" if @location
+      if @description && !@description.empty?
+        parts[-1] = "#{parts[-1]}: #{@description}"
+      end
+      parts.join(" ")
+    end
   end
-end
+end

data/lib/forthic/forthic_module.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require_relative 'words/word'
-require_relative 'words/module_word'
-require_relative 'words/module_memo_word'
-require_relative 'words/module_memo_bang_word'
-require_relative 'words/module_memo_bang_at_word'
-require_relative 'words/imported_word'
-require_relative 'variable'
+require "set"
+require_relative "words/word"
+require_relative "words/module_word"
+require_relative "words/module_memo_word"
+require_relative "words/module_memo_bang_word"
+require_relative "words/module_memo_bang_at_word"
+require_relative "words/imported_word"
+require_relative "variable"
 
 module Forthic
   class ForthicModule
@@ -42,7 +43,7 @@ module Forthic
     # @param [String] prefix
     # @param [ForthicModule] mod
     def require_module(prefix, mod)
-      @required_modules << { prefix: prefix, module: mod }
+      @required_modules << {prefix: prefix, module: mod}
     end
 
     # @param [String] name
@@ -142,4 +143,4 @@ module Forthic
       var_result ? PushValueWord.new(varname, var_result) : nil
     end
   end
-end
+end