forthic 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e71f6368dc2bcc817f0095a389740a6676005ab8ddb862cdef02f0e0910d09d
-  data.tar.gz: b408177ce893d5353aa00ce2a73698005c07e22e3d68a8ec6cade6032887a591
+  metadata.gz: b3faede941e29c0090a90077103892015502bb1bef7897726821932197a72be1
+  data.tar.gz: 4393b304179b84c9b1cca818ae04af1cf6800dcd07c86ff92ec5e1b1f4fc4bbf
 SHA512:
-  metadata.gz: 2ffd692800bdf839d25a106c79bea485addaeabb7d2eafd5366a9d034927a642fed7b4ecb498e5f081016f5079077d3a4db4ba96eae113a8ce547024b4164736
-  data.tar.gz: b4ab0aec5f7b788873bbbc71761f5382f565864057101125919338c24453bdccdedbcf26f281dc5c46dee4a16fc7824a08516a52c9c318af91ab0f932a329f42
+  metadata.gz: b8dea528434b695a7c272c1cd3d9b6d3885c2eb0d4acd43b876663f764abaca97b9896df81e8618dfe98612c4e4a2b18ba883ccbde93873d232cc933eb7ca28e
+  data.tar.gz: baefe4a1a1157b5c190c7e62c703fcf7e0568aefb7103e2a463d514c798ba739a2f5eacdf35af70dd47d51e705ad546738bdac3f7b9de1c25d99d30b5e1153d5

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/Rakefile

@@ -11,4 +11,4 @@ task default: %i[test standard]
 
 task :guard do
   sh "bundle exec guard"
-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
@@ -48,4 +47,4 @@ module Forthic
       result.reverse
     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