forthic 0.2.0 → 0.3.0

data/lib/forthic/grpc/remote_runtime_module.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+require_relative 'runtime_manager'
+require_relative 'remote_module'
+
+module Forthic
+  module Grpc
+    # RemoteRuntimeModule provides words for connecting to and using remote Forthic runtimes
+    class RemoteRuntimeModule < Forthic::Decorators::DecoratedModule
+      module_doc <<~DOC
+        Module for connecting to and using remote Forthic runtimes (TypeScript, Python).
+
+        Enables cross-runtime execution by connecting to remote gRPC servers and importing
+        their modules into the current interpreter.
+
+        Example usage:
+          "python" "localhost:50051" CONNECT-RUNTIME
+          ["pandas"] USE-PY-MODULES
+
+          "typescript" "localhost:50052" CONNECT-RUNTIME
+          ["fs"] "ts" USE-TS-MODULES-AS
+      DOC
+
+      def initialize
+        super('remote_runtime')
+        @runtime_manager = RuntimeManager.instance
+      end
+
+  forthic_direct_word :CONNECT_RUNTIME, '( name:str address:str -- )', 'Connect to a remote runtime', 'CONNECT-RUNTIME'
+      def CONNECT_RUNTIME(interp)
+        address = interp.stack_pop
+        name = interp.stack_pop
+        @runtime_manager.connect_runtime(name, address)
+        nil
+      end
+
+  forthic_direct_word :DISCONNECT_RUNTIME, '( name:str -- )', 'Disconnect from a remote runtime', 'DISCONNECT-RUNTIME'
+      def DISCONNECT_RUNTIME(interp)
+        name = interp.stack_pop
+        @runtime_manager.disconnect_runtime(name)
+        nil
+      end
+
+  forthic_direct_word :DISCONNECT_ALL, '( -- )', 'Disconnect from all remote runtimes', 'DISCONNECT-ALL'
+      def DISCONNECT_ALL(_interp)
+        @runtime_manager.disconnect_all
+        nil
+      end
+
+  forthic_direct_word :CONNECTED_RUNTIMES, '( -- runtimes:array )', 'Get list of connected runtime names', 'CONNECTED-RUNTIMES'
+      def CONNECTED_RUNTIMES(interp)
+        interp.stack_push(@runtime_manager.connected_runtimes)
+      end
+
+  forthic_direct_word :USE_TS_MODULES, '( modules:array -- )', 'Import TypeScript modules', 'USE-TS-MODULES'
+      def USE_TS_MODULES(interp)
+        modules = interp.stack_pop
+        load_modules('typescript', modules, nil, interp)
+        nil
+      end
+
+  forthic_direct_word :USE_TS_MODULES_AS, '( modules:array prefix:str -- )', 'Import TypeScript modules with prefix', 'USE-TS-MODULES-AS'
+      def USE_TS_MODULES_AS(interp)
+        prefix = interp.stack_pop
+        modules = interp.stack_pop
+        load_modules('typescript', modules, prefix, interp)
+        nil
+      end
+
+  forthic_direct_word :USE_PY_MODULES, '( modules:array -- )', 'Import Python modules', 'USE-PY-MODULES'
+      def USE_PY_MODULES(interp)
+        modules = interp.stack_pop
+        load_modules('python', modules, nil, interp)
+        nil
+      end
+
+  forthic_direct_word :USE_PY_MODULES_AS, '( modules:array prefix:str -- )', 'Import Python modules with prefix', 'USE-PY-MODULES-AS'
+      def USE_PY_MODULES_AS(interp)
+        prefix = interp.stack_pop
+        modules = interp.stack_pop
+        load_modules('python', modules, prefix, interp)
+        nil
+      end
+
+  forthic_direct_word :USE_RB_MODULES, '( modules:array -- )', 'Import Ruby modules from another runtime', 'USE-RB-MODULES'
+      def USE_RB_MODULES(interp)
+        modules = interp.stack_pop
+        load_modules('ruby', modules, nil, interp)
+        nil
+      end
+
+  forthic_direct_word :USE_RB_MODULES_AS, '( modules:array prefix:str -- )', 'Import Ruby modules with prefix', 'USE-RB-MODULES-AS'
+      def USE_RB_MODULES_AS(interp)
+        prefix = interp.stack_pop
+        modules = interp.stack_pop
+        load_modules('ruby', modules, prefix, interp)
+        nil
+      end
+
+  forthic_direct_word :LIST_REMOTE_MODULES, '( runtime:str -- modules:array )', 'List available modules in a remote runtime', 'LIST-REMOTE-MODULES'
+      def LIST_REMOTE_MODULES(interp)
+        runtime_name = interp.stack_pop
+        client = @runtime_manager.get_runtime(runtime_name)
+        raise "Runtime '#{runtime_name}' not connected" unless client
+
+        modules = client.list_modules
+        module_summaries = modules.map do |mod|
+          {
+            'name' => mod[:name],
+            'description' => mod[:description],
+            'word_count' => mod[:word_count]
+          }
+        end
+        interp.stack_push(module_summaries)
+      end
+
+      private
+
+      # Load modules from a remote runtime
+      # @param runtime_name [String] The name of the runtime (e.g., 'python', 'typescript')
+      # @param module_names [Array<String>] List of module names to load
+      # @param prefix [String, nil] Optional prefix for module names
+      # @param interp [Interpreter] The interpreter instance
+      def load_modules(runtime_name, module_names, prefix, interp)
+        client = @runtime_manager.get_runtime(runtime_name)
+        raise "Runtime '#{runtime_name}' not connected. Use CONNECT-RUNTIME first." unless client
+
+        module_names.each do |module_name|
+          # Create remote module
+          remote_module = RemoteModule.new(module_name, client, runtime_name)
+          remote_module.initialize!
+
+          # Register module (always with original name)
+          interp.register_module(remote_module)
+
+          # Import with optional prefix
+          if prefix
+            # Use array format: [module_name, prefix]
+            interp.use_modules([[remote_module.name, prefix]])
+          else
+            # Use array format with empty prefix
+            interp.use_modules([remote_module.name])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/forthic/grpc/remote_word.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../module'
+require_relative 'client'
+
+module Forthic
+  module Grpc
+    # RemoteWord - Proxy word that delegates execution to a remote runtime via gRPC
+    #
+    # When executed:
+    # 1. Captures current interpreter stack
+    # 2. Sends word name + stack to remote runtime via gRPC
+    # 3. Replaces local stack with result stack from remote execution
+    #
+    # This allows seamless integration of remote runtime words (like TypeScript's FILE-EXISTS?
+    # or Python's DF-FROM-RECORDS) into the local Ruby interpreter.
+    #
+    # Example usage:
+    #   client = GrpcClient.new('localhost:50052')
+    #   remote_word = RemoteWord.new('REVERSE', client, 'typescript', 'array',
+    #                                '( array -- reversed )', 'Reverse array')
+    #   remote_word.execute(interp)  # Executes in TypeScript runtime!
+    class RemoteWord < Forthic::Word
+      attr_reader :client, :runtime_name, :module_name, :stack_effect, :description
+
+      # @param name [String] Word name (e.g., "DF_FROM_RECORDS")
+      # @param client [GrpcClient] gRPC client connected to remote runtime
+      # @param runtime_name [String] Name of remote runtime (e.g., "python", "typescript")
+      # @param module_name [String] Module name (e.g., "pandas", "fs")
+      # @param stack_effect [String] Stack notation (e.g., "( records:array -- df:DataFrame )")
+      # @param description [String] Human-readable description
+      def initialize(name, client, runtime_name, module_name, stack_effect = '( -- )', description = '')
+        super(name)
+        @client = client
+        @runtime_name = runtime_name
+        @module_name = module_name
+        @stack_effect = stack_effect
+        @description = description
+      end
+
+      # Execute word in remote runtime
+      #
+      # Captures entire stack, sends to remote runtime, and replaces stack with result.
+      # This is inefficient but correct.
+      #
+      # @param interp [Interpreter] The Forthic interpreter
+      def execute(interp)
+        # Capture current stack state
+        stack = interp.get_stack
+        stack_items = stack.get_items
+
+        # Execute word in remote runtime
+        # The server has already imported the module, so just send the word name
+        result_stack = @client.execute_word(@name, stack_items)
+
+        # Clear local stack and replace with result
+        stack.set_raw_items([])
+
+        # Push all result items
+        result_stack.each { |item| interp.stack_push(item) }
+      rescue StandardError => e
+        raise "Error executing remote word #{@module_name}.#{@name} in #{@runtime_name} runtime: #{e.message}"
+      end
+
+      # Get runtime name for debugging/introspection
+      # @return [String] Runtime name
+      def get_runtime_name
+        @runtime_name
+      end
+
+      # Get module name for debugging/introspection
+      # @return [String] Module name
+      def get_module_name
+        @module_name
+      end
+
+      # Get runtime execution information
+      # RemoteWords are runtime-specific and can only execute in their designated runtime
+      #
+      # @return [Hash] Runtime info with keys: runtime, is_remote, is_standard, available_in
+      def get_runtime_info
+        {
+          runtime: @runtime_name,
+          is_remote: true,
+          is_standard: false,
+          available_in: [@runtime_name]
+        }
+      end
+    end
+  end
+end

data/lib/forthic/grpc/runtime_manager.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module Forthic
+  module Grpc
+    # RuntimeManager manages connections to remote Forthic runtimes
+    # Uses Singleton pattern to ensure a single registry of runtime connections
+    class RuntimeManager
+      include Singleton
+
+      attr_reader :connections
+
+      def initialize
+        @connections = {}
+      end
+
+      # Connect to a remote runtime
+      # @param name [String] The name of the runtime (e.g., 'python', 'typescript')
+      # @param address [String] The gRPC address (e.g., 'localhost:50051')
+      # @return [GrpcClient] The client connection
+      def connect_runtime(name, address)
+        @connections[name] ||= GrpcClient.new(address)
+      end
+
+      # Get an existing runtime connection
+      # @param name [String] The name of the runtime
+      # @return [GrpcClient, nil] The client connection or nil if not found
+      def get_runtime(name)
+        @connections[name]
+      end
+
+      # Disconnect from a specific runtime
+      # @param name [String] The name of the runtime
+      def disconnect_runtime(name)
+        @connections[name]&.close
+        @connections.delete(name)
+      end
+
+      # Disconnect from all runtimes
+      def disconnect_all
+        @connections.each_value(&:close)
+        @connections.clear
+      end
+
+      # Check if a runtime is connected
+      # @param name [String] The name of the runtime
+      # @return [Boolean]
+      def connected?(name)
+        @connections.key?(name)
+      end
+
+      # Get list of connected runtime names
+      # @return [Array<String>]
+      def connected_runtimes
+        @connections.keys
+      end
+    end
+  end
+end

data/lib/forthic/grpc/serializer.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+require_relative 'forthic_runtime_pb'
+require 'date'
+require 'time'
+
+module Forthic
+  module Grpc
+    # Serializer for converting Ruby values to/from gRPC StackValue protobuf messages
+    #
+    # Handles all Forthic types:
+    # - Primitives: Integer, Float, String, Boolean, Nil
+    # - Collections: Array, Hash
+    # - Temporal: Date, Time, DateTime
+    #
+    # Pattern: Mirrors Python serializer.py and TypeScript serializer.ts
+    module Serializer
+      module_function
+
+      # Serialize a Ruby value to a StackValue protobuf message
+      #
+      # @param value [Object] Ruby value to serialize
+      # @return [Forthic::StackValue] Protobuf StackValue message
+      def serialize_value(value)
+        stack_value = Forthic::StackValue.new
+
+        case value
+        when Integer
+          stack_value.int_value = value
+        when Float
+          stack_value.float_value = value
+        when String
+          stack_value.string_value = value
+        when TrueClass, FalseClass
+          stack_value.bool_value = value
+        when NilClass
+          stack_value.null_value = Forthic::NullValue.new
+        when Array
+          stack_value.array_value = serialize_array(value)
+        when Hash
+          stack_value.record_value = serialize_record(value)
+        when Time, DateTime
+          # Handle Time and DateTime before Date (DateTime is a subclass of Date)
+          stack_value.instant_value = serialize_instant(value)
+        when Date
+          stack_value.plain_date_value = serialize_date(value)
+        else
+          raise ArgumentError, "Cannot serialize type #{value.class}: #{value.inspect}"
+        end
+
+        stack_value
+      end
+
+      # Deserialize a StackValue protobuf message to a Ruby value
+      #
+      # @param stack_value [Forthic::StackValue] Protobuf message
+      # @return [Object] Ruby value
+      def deserialize_value(stack_value)
+        case stack_value.value
+        when :int_value
+          stack_value.int_value
+        when :float_value
+          stack_value.float_value
+        when :string_value
+          stack_value.string_value
+        when :bool_value
+          stack_value.bool_value
+        when :null_value
+          nil
+        when :array_value
+          deserialize_array(stack_value.array_value)
+        when :record_value
+          deserialize_record(stack_value.record_value)
+        when :plain_date_value
+          deserialize_date(stack_value.plain_date_value)
+        when :instant_value
+          deserialize_instant(stack_value.instant_value)
+        when :zoned_datetime_value
+          deserialize_zoned_datetime(stack_value.zoned_datetime_value)
+        else
+          raise ArgumentError, "Unknown StackValue type: #{stack_value.value}"
+        end
+      end
+
+      # Serialize a Ruby array to ArrayValue
+      #
+      # @param array [Array] Ruby array
+      # @return [Forthic::ArrayValue] Protobuf ArrayValue
+      def serialize_array(array)
+        array_value = Forthic::ArrayValue.new
+        # Use push to add items to repeated field (protobuf convention)
+        array.each do |item|
+          array_value.items.push(serialize_value(item))
+        end
+        array_value
+      end
+
+      # Deserialize an ArrayValue to Ruby array
+      #
+      # @param array_value [Forthic::ArrayValue] Protobuf ArrayValue
+      # @return [Array] Ruby array
+      def deserialize_array(array_value)
+        array_value.items.map { |item| deserialize_value(item) }
+      end
+
+      # Serialize a Ruby hash to RecordValue
+      #
+      # @param hash [Hash] Ruby hash with string keys
+      # @return [Forthic::RecordValue] Protobuf RecordValue
+      def serialize_record(hash)
+        record_value = Forthic::RecordValue.new
+        hash.each do |key, value|
+          record_value.fields[key.to_s] = serialize_value(value)
+        end
+        record_value
+      end
+
+      # Deserialize a RecordValue to Ruby hash
+      #
+      # @param record_value [Forthic::RecordValue] Protobuf RecordValue
+      # @return [Hash] Ruby hash with string keys
+      def deserialize_record(record_value)
+        result = {}
+        record_value.fields.each do |key, value|
+          result[key] = deserialize_value(value)
+        end
+        result
+      end
+
+      # Serialize a Ruby Date to PlainDateValue
+      #
+      # @param date [Date] Ruby Date
+      # @return [Forthic::PlainDateValue] Protobuf PlainDateValue
+      def serialize_date(date)
+        plain_date_value = Forthic::PlainDateValue.new
+        plain_date_value.iso8601_date = date.iso8601
+        plain_date_value
+      end
+
+      # Deserialize a PlainDateValue to Ruby Date
+      #
+      # @param plain_date_value [Forthic::PlainDateValue] Protobuf PlainDateValue
+      # @return [Date] Ruby Date
+      def deserialize_date(plain_date_value)
+        Date.iso8601(plain_date_value.iso8601_date)
+      end
+
+      # Serialize a Ruby Time/DateTime to InstantValue
+      #
+      # @param time [Time, DateTime] Ruby Time or DateTime
+      # @return [Forthic::InstantValue] Protobuf InstantValue
+      def serialize_instant(time)
+        instant_value = Forthic::InstantValue.new
+        # Convert to UTC and format as ISO 8601 with timezone
+        if time.is_a?(DateTime)
+          # DateTime: convert to Time first
+          utc_time = time.to_time.utc
+        else
+          # Time: call utc directly
+          utc_time = time.utc
+        end
+        instant_value.iso8601 = utc_time.iso8601
+        instant_value
+      end
+
+      # Deserialize an InstantValue to Ruby Time
+      #
+      # @param instant_value [Forthic::InstantValue] Protobuf InstantValue
+      # @return [Time] Ruby Time (UTC)
+      def deserialize_instant(instant_value)
+        Time.iso8601(instant_value.iso8601)
+      end
+
+      # Deserialize a ZonedDateTimeValue to Ruby Time with timezone
+      #
+      # @param zoned_value [Forthic::ZonedDateTimeValue] Protobuf ZonedDateTimeValue
+      # @return [Time] Ruby Time with timezone info
+      def deserialize_zoned_datetime(zoned_value)
+        # Parse ISO 8601 string, Ruby Time will preserve timezone
+        Time.iso8601(zoned_value.iso8601)
+      end
+    end
+  end
+end