forthic 0.2.0 → 0.3.0

metadata

@@ -1,59 +1,92 @@
 --- !ruby/object:Gem::Specification
 name: forthic
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Rino Jose
 autorequire:
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2025-07-13 00:00:00.000000000 Z
-dependencies: []
-description: This package provides a Forthic interpreter that allows you to execute
-  Forthic code within your Ruby projects. Forthic is a stack-based programming language
-  inspired by Forth.
+date: 2025-11-09 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: Forthic is a stack-based, concatenative programming language designed
+  for data manipulation and processing. This is the Ruby implementation with WebSocket
+  support for remote word execution.
 email:
-- rjose@forthix.com
+- rjose@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".standard.yml"
-- CHANGELOG.md
-- CLAUDE.md
-- Guardfile
 - README.md
 - Rakefile
 - lib/forthic.rb
-- lib/forthic/code_location.rb
-- lib/forthic/forthic_error.rb
-- lib/forthic/forthic_module.rb
-- lib/forthic/global_module.rb
+- lib/forthic/decorators/docs.rb
+- lib/forthic/decorators/word.rb
+- lib/forthic/errors.rb
+- lib/forthic/grpc/client.rb
+- lib/forthic/grpc/errors.rb
+- lib/forthic/grpc/forthic_runtime_pb.rb
+- lib/forthic/grpc/forthic_runtime_services_pb.rb
+- lib/forthic/grpc/remote_module.rb
+- lib/forthic/grpc/remote_runtime_module.rb
+- lib/forthic/grpc/remote_word.rb
+- lib/forthic/grpc/runtime_manager.rb
+- lib/forthic/grpc/serializer.rb
+- lib/forthic/grpc/server.rb
 - lib/forthic/interpreter.rb
-- lib/forthic/positioned_string.rb
-- lib/forthic/token.rb
+- lib/forthic/literals.rb
+- lib/forthic/module.rb
+- lib/forthic/modules/standard/array_module.rb
+- lib/forthic/modules/standard/boolean_module.rb
+- lib/forthic/modules/standard/core_module.rb
+- lib/forthic/modules/standard/datetime_module.rb
+- lib/forthic/modules/standard/json_module.rb
+- lib/forthic/modules/standard/math_module.rb
+- lib/forthic/modules/standard/record_module.rb
+- lib/forthic/modules/standard/string_module.rb
 - lib/forthic/tokenizer.rb
-- lib/forthic/variable.rb
-- lib/forthic/version.rb
-- lib/forthic/words/definition_word.rb
-- lib/forthic/words/end_array_word.rb
-- lib/forthic/words/end_module_word.rb
-- lib/forthic/words/imported_word.rb
-- lib/forthic/words/map_word.rb
-- lib/forthic/words/module_memo_bang_at_word.rb
-- lib/forthic/words/module_memo_bang_word.rb
-- lib/forthic/words/module_memo_word.rb
-- lib/forthic/words/module_word.rb
-- lib/forthic/words/push_value_word.rb
-- lib/forthic/words/start_module_word.rb
-- lib/forthic/words/word.rb
-- sig/forthic.rbs
-homepage: https://github.com/linkedin/forthic
-licenses: []
+- lib/forthic/utils.rb
+- lib/forthic/websocket/handler.rb
+- lib/forthic/websocket/serializer.rb
+- lib/forthic/word_options.rb
+- protos/README.md
+- protos/v1/forthic_runtime.proto
+homepage: https://github.com/forthix/forthic
+licenses:
+- MIT
 metadata:
-  homepage_uri: https://github.com/linkedin/forthic
-  source_code_uri: https://github.com/linkedin/forthic
+  homepage_uri: https://github.com/forthix/forthic
+  source_code_uri: https://github.com/forthix/forthic
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -62,7 +95,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.1.0
+      version: 3.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -72,5 +105,5 @@ requirements: []
 rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: A Forthic interpreter that runs within Ruby.
+summary: Ruby implementation of the Forthic programming language
 test_files: []

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/standardrb/standard
-ruby_version: 3.1

data/CHANGELOG.md

@@ -1,11 +0,0 @@
-## [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

@@ -1,74 +0,0 @@
-# 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

@@ -1,42 +0,0 @@
-# A sample Guardfile
-# More info at https://github.com/guard/guard#readme
-
-## Uncomment and set this to only include directories you want to watch
-# directories %w(app lib config test spec features) \
-#  .select{|d| Dir.exist?(d) ? d : UI.warning("Directory #{d} does not exist")}
-
-## Note: if you are using the `directories` clause above and you are not
-## watching the project directory ('.'), then you will want to move
-## the Guardfile to a watched dir and symlink it back, e.g.
-#
-#  $ mkdir config
-#  $ mv Guardfile config/
-#  $ ln -s config/Guardfile .
-#
-# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
-
-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" }
-
-  # with Minitest::Spec
-  # watch(%r{^spec/(.*)_spec\.rb$})
-  # watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
-  # watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
-
-  # Rails 4
-  # watch(%r{^app/(.+)\.rb$})                               { |m| "test/#{m[1]}_test.rb" }
-  # watch(%r{^app/controllers/application_controller\.rb$}) { 'test/controllers' }
-  # watch(%r{^app/controllers/(.+)_controller\.rb$})        { |m| "test/integration/#{m[1]}_test.rb" }
-  # watch(%r{^app/views/(.+)_mailer/.+})                    { |m| "test/mailers/#{m[1]}_mailer_test.rb" }
-  # watch(%r{^lib/(.+)\.rb$})                               { |m| "test/lib/#{m[1]}_test.rb" }
-  # watch(%r{^test/.+_test\.rb$})
-  # watch(%r{^test/test_helper\.rb$}) { 'test' }
-
-  # Rails < 4
-  # watch(%r{^app/controllers/(.*)\.rb$}) { |m| "test/functional/#{m[1]}_test.rb" }
-  # watch(%r{^app/helpers/(.*)\.rb$})     { |m| "test/helpers/#{m[1]}_test.rb" }
-  # watch(%r{^app/models/(.*)\.rb$})      { |m| "test/unit/#{m[1]}_test.rb" }
-end

data/lib/forthic/code_location.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-module Forthic
-  class CodeLocation
-    attr_accessor :screen_name, :line, :column, :start_pos, :end_pos
-
-    # @param [String] screen_name
-    # @param [Integer] line
-    # @param [Integer] column
-    # @param [Integer] start_pos
-    # @param [Integer] end_pos
-    def initialize(screen_name: "<ad-hoc>", line: 1, column: 1, start_pos: 0, end_pos: 0)
-      @screen_name = screen_name
-      @line = line
-      @column = column
-      @start_pos = start_pos
-      @end_pos = end_pos
-    end
-  end
-end

data/lib/forthic/forthic_error.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-module Forthic
-  class ForthicError < StandardError
-    attr_accessor :error_key, :title, :description, :location, :caught_error
-
-    # @param [String] error_key
-    # @param [String] title
-    # @param [String] description
-    # @param [CodeLocation, nil] location
-    def initialize(error_key, title, description, location = nil)
-      @error_key = error_key
-      @title = title
-      @description = description
-      @location = location
-      @caught_error = nil
-    end
-
-    # @param [ForthicError] error
-    def set_caught_error(error)
-      @caught_error = error
-    end
-
-    # @return [String]
-    def get_title
-      @title
-    end
-
-    # @return [String]
-    def get_description
-      @description
-    end
-
-    # @return [Array<ForthicError>]
-    def get_error_stack
-      max_depth = 100
-      cur_error = self
-      result = [cur_error]
-
-      max_depth.times do
-        break unless cur_error.caught_error
-
-        result << cur_error.caught_error
-        cur_error = cur_error.caught_error
-      end
-
-      result.reverse
-    end
-  end
-end

data/lib/forthic/forthic_module.rb

@@ -1,146 +0,0 @@
-# frozen_string_literal: true
-
-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
-    attr_accessor :words, :exportable, :variables, :modules, :module_prefixes, :required_modules, :name, :forthic_code, :module_id
-
-    # @param [String] name
-    # @param [Interpreter, nil] interp
-    # @param [String] forthic_code
-    def initialize(name, interp = nil, forthic_code = "")
-      @words = []
-      @exportable = []
-      @variables = {}
-      @modules = {}
-      @module_prefixes = {}
-      @required_modules = []
-      @name = name
-      @forthic_code = forthic_code
-      @module_id = "#{name}-#{rand(1_000_000)}"
-    end
-
-    # @return [ForthicModule]
-    def dup
-      result = ForthicModule.new(@name, @interp, @forthic_code)
-      result.words = @words.dup
-      result.exportable = @exportable.dup
-      @variables.each { |key, var| result.variables[key] = var.dup }
-      @modules.each { |key, mod| result.modules[key] = mod }
-      result.required_modules = @required_modules.dup
-      result.forthic_code = @forthic_code
-      result
-    end
-
-    # @param [String] prefix
-    # @param [ForthicModule] mod
-    def require_module(prefix, mod)
-      @required_modules << {prefix: prefix, module: mod}
-    end
-
-    # @param [String] name
-    # @return [ForthicModule, nil]
-    def find_module(name)
-      @modules[name]
-    end
-
-    # @param [String] word_name
-    # @param [Proc] word_func
-    def add_module_word(word_name, word_func)
-      add_exportable_word(ModuleWord.new(word_name, word_func))
-    end
-
-    # @param [Word] word
-    def add_word(word)
-      @words << word
-    end
-
-    # @param [Word] word
-    # @return [ModuleMemoWord]
-    def add_memo_words(word)
-      memo_word = ModuleMemoWord.new(word)
-      @words << memo_word
-      @words << ModuleMemoBangWord.new(memo_word)
-      @words << ModuleMemoBangAtWord.new(memo_word)
-      memo_word
-    end
-
-    # @param [Array<String>] names
-    def add_exportable(names)
-      @exportable.concat(names)
-    end
-
-    # @return [Array<Word>]
-    def exportable_words
-      @words.select { |word| @exportable.include?(word.name) }
-    end
-
-    # @param [Word] word
-    def add_exportable_word(word)
-      @words << word
-      @exportable << word.name
-    end
-
-    # @param [String] name
-    # @param [Object, nil] value
-    def add_variable(name, value = nil)
-      @variables[name] ||= Variable.new(name, value)
-    end
-
-    # @param [Interpreter] interp
-    def initialize_modules(interp)
-      @required_modules.each do |rec|
-        import_module(rec[:prefix], rec[:module], interp)
-      end
-    end
-
-    # @param [String] module_name
-    # @param [String] prefix
-    # @param [ForthicModule] mod
-    def register_module(module_name, prefix, mod)
-      @modules[module_name] = mod
-      @module_prefixes[module_name] ||= Set.new
-      @module_prefixes[module_name] << prefix
-    end
-
-    # @param [String] prefix
-    # @param [ForthicModule] mod
-    # @param [Interpreter] interp
-    def import_module(prefix, mod, interp)
-      new_module = mod.dup
-      new_module.initialize_modules(interp)
-
-      new_module.exportable_words.each do |word|
-        add_word(ImportedWord.new(word, prefix, new_module))
-      end
-      register_module(mod.name, prefix, new_module)
-    end
-
-    # @param [String] name
-    # @return [Word, nil]
-    def find_word(name)
-      find_dictionary_word(name) || find_variable(name)
-    end
-
-    # @param [String] word_name
-    # @return [Word, nil]
-    def find_dictionary_word(word_name)
-      @words.reverse.find { |w| w.name == word_name }
-    end
-
-    # @param [String] varname
-    # @return [PushValueWord, nil]
-    def find_variable(varname)
-      var_result = @variables[varname]
-      var_result ? PushValueWord.new(varname, var_result) : nil
-    end
-  end
-end