forthic 0.2.0 → 0.3.0

data/lib/forthic/websocket/serializer.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'time'
+require 'json'
+
+module Forthic
+  module WebSocket
+    # Serializer for converting Ruby values to/from JSON StackValue format
+    #
+    # Mirrors the gRPC serializer but outputs JSON instead of protobuf.
+    # Maintains the same structure as the gRPC StackValue messages for consistency.
+    #
+    # Handles all Forthic types:
+    # - Primitives: Integer, Float, String, Boolean, Nil
+    # - Collections: Array, Hash
+    # - Temporal: Date, Time, DateTime
+    #
+    # JSON format matches the WebSocket protocol specification in
+    # BROWSER_SERVER_WEBSOCKET_PLAN.md
+    module Serializer
+      module_function
+
+      # Serialize a Ruby value to a JSON StackValue hash
+      #
+      # @param value [Object] Ruby value to serialize
+      # @return [Hash] JSON-serializable hash with {type:, value:} structure
+      def serialize_value(value)
+        case value
+        when Integer
+          { 'type' => 'int', 'value' => value }
+        when Float
+          { 'type' => 'float', 'value' => value }
+        when String
+          { 'type' => 'string', 'value' => value }
+        when TrueClass, FalseClass
+          { 'type' => 'bool', 'value' => value }
+        when NilClass
+          { 'type' => 'null', 'value' => nil }
+        when Array
+          { 'type' => 'array', 'value' => value.map { |item| serialize_value(item) } }
+        when Hash
+          { 'type' => 'record', 'value' => serialize_record(value) }
+        when Time, DateTime
+          # Handle Time and DateTime before Date (DateTime is a subclass of Date)
+          { 'type' => 'instant', 'value' => serialize_instant(value) }
+        when Date
+          { 'type' => 'plain_date', 'value' => value.iso8601 }
+        else
+          raise ArgumentError, "Cannot serialize type #{value.class}: #{value.inspect}"
+        end
+      end
+
+      # Deserialize a JSON StackValue hash to a Ruby value
+      #
+      # @param stack_value [Hash] JSON hash with {type:, value:} structure
+      # @return [Object] Ruby value
+      def deserialize_value(stack_value)
+        type = stack_value['type']
+        value = stack_value['value']
+
+        case type
+        when 'int'
+          value.to_i
+        when 'float'
+          value.to_f
+        when 'string'
+          value.to_s
+        when 'bool'
+          value
+        when 'null'
+          nil
+        when 'array'
+          value.map { |item| deserialize_value(item) }
+        when 'record'
+          deserialize_record(value)
+        when 'plain_date'
+          Date.iso8601(value)
+        when 'instant'
+          Time.iso8601(value)
+        when 'zoned_datetime'
+          Time.iso8601(value)
+        else
+          raise ArgumentError, "Unknown StackValue type: #{type}"
+        end
+      end
+
+      # Serialize a Ruby array to JSON array
+      #
+      # @param array [Array] Ruby array
+      # @return [Array<Hash>] Array of serialized StackValues
+      def serialize_array(array)
+        array.map { |item| serialize_value(item) }
+      end
+
+      # Deserialize a JSON array to Ruby array
+      #
+      # @param array_value [Array<Hash>] Array of JSON StackValues
+      # @return [Array] Ruby array
+      def deserialize_array(array_value)
+        array_value.map { |item| deserialize_value(item) }
+      end
+
+      # Serialize a Ruby hash to JSON record
+      #
+      # @param hash [Hash] Ruby hash with string keys
+      # @return [Hash] Hash with serialized StackValue values
+      def serialize_record(hash)
+        result = {}
+        hash.each do |key, value|
+          result[key.to_s] = serialize_value(value)
+        end
+        result
+      end
+
+      # Deserialize a JSON record to Ruby hash
+      #
+      # @param record_value [Hash] JSON record with StackValue values
+      # @return [Hash] Ruby hash with string keys
+      def deserialize_record(record_value)
+        result = {}
+        record_value.each do |key, value|
+          result[key] = deserialize_value(value)
+        end
+        result
+      end
+
+      # Serialize a Ruby Time/DateTime to ISO 8601 UTC string
+      #
+      # @param time [Time, DateTime] Ruby Time or DateTime
+      # @return [String] ISO 8601 UTC string
+      def serialize_instant(time)
+        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
+        utc_time.iso8601
+      end
+
+      # Serialize a complete stack to JSON
+      #
+      # @param stack [Array] Array of Ruby values
+      # @return [Array<Hash>] Array of serialized StackValues
+      def serialize_stack(stack)
+        stack.map { |value| serialize_value(value) }
+      end
+
+      # Deserialize a JSON stack to Ruby array
+      #
+      # @param json_stack [Array<Hash>] Array of JSON StackValues
+      # @return [Array] Array of Ruby values
+      def deserialize_stack(json_stack)
+        json_stack.map { |stack_value| deserialize_value(stack_value) }
+      end
+    end
+  end
+end

data/lib/forthic/word_options.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Forthic
+  # WordOptions - Type-safe options container for module words
+  #
+  # Overview:
+  # WordOptions provides a structured way for Forthic words to accept optional
+  # configuration parameters without requiring fixed parameter positions. This
+  # enables flexible, extensible APIs similar to keyword arguments in other languages.
+  #
+  # Usage in Forthic:
+  #   [.option_name value ...] ~> WORD
+  #
+  # The ~> operator takes an options array and a word, passing the options as
+  # an additional parameter to words that support them.
+  #
+  # Example in Forthic code:
+  #   [1 2 3] '2 *' [.with_key TRUE] ~> MAP
+  #   [10 20 30] [.comparator "-1 *"] ~> SORT
+  #   [[[1 2]]] [.depth 1] ~> FLATTEN
+  #
+  # Implementation in Module Words:
+  # Words declare options support by adding an options parameter:
+  #
+  #   def MAP(items, forthic, options = {})
+  #     with_key = options[:with_key] || options['with_key']
+  #     push_error = options[:push_error] || options['push_error']
+  #     # ... use options to modify behavior
+  #   end
+  #
+  # The word decorator/registration automatically:
+  # 1. Checks if the top stack item is a WordOptions instance
+  # 2. Converts it to a plain Hash if present
+  # 3. Passes an empty {} if no options provided
+  #
+  # Common Patterns:
+  # - Boolean flags: options[:with_key]
+  # - Numeric values: options[:depth]
+  # - String values: options[:comparator]
+  # - Multiple options: All accessed from same options hash
+  #
+  # Internal Representation:
+  # Created from flat array: [.key1 val1 .key2 val2]
+  # Stored as Hash internally for efficient lookup
+  # Converted to Hash when passed to words
+  #
+  # Note: Dot-symbols in Forthic have the leading '.' already stripped,
+  # so keys come in as "key1", "key2", etc.
+  class WordOptions
+    # Create a new WordOptions from a flat array
+    #
+    # @param flat_array [Array] Array of alternating keys and values
+    # @raise [ArgumentError] if array is not even length or keys are not strings
+    def initialize(flat_array)
+      unless flat_array.is_a?(Array)
+        raise ArgumentError, "Options must be an array"
+      end
+
+      unless flat_array.length.even?
+        raise ArgumentError,
+              "Options must be key-value pairs (even length). Got #{flat_array.length} elements"
+      end
+
+      @options = {}
+
+      flat_array.each_slice(2) do |key, value|
+        # Key should be a string (dot-symbol with . already stripped)
+        unless key.is_a?(String)
+          raise ArgumentError,
+                "Option key must be a string (dot-symbol). Got: #{key.class}"
+        end
+
+        @options[key] = value
+      end
+    end
+
+    # Get option value with optional default
+    #
+    # @param key [String] The option key
+    # @param default_value [Object, nil] The default value if key not found
+    # @return [Object, nil] The option value or default
+    def get(key, default_value = nil)
+      @options.key?(key) ? @options[key] : default_value
+    end
+
+    # Check if option exists
+    #
+    # @param key [String] The option key
+    # @return [Boolean] true if option exists
+    def has?(key)
+      @options.key?(key)
+    end
+
+    # Get all options as plain hash
+    #
+    # @return [Hash] All options as a hash
+    def to_hash
+      @options.dup
+    end
+
+    # Alias for compatibility
+    alias to_record to_hash
+
+    # Get all option keys
+    #
+    # @return [Array<String>] All option keys
+    def keys
+      @options.keys
+    end
+
+    # For debugging/display
+    #
+    # @return [String] String representation of options
+    def to_s
+      pairs = @options.map { |k, v| ".#{k} #{v.to_json}" }.join(" ")
+      "<WordOptions: #{pairs}>"
+    end
+
+    # Inspect method for better debugging
+    alias inspect to_s
+  end
+
+  # Helper for words to check if top of stack is WordOptions
+  # and pop it if present. Returns empty hash if not present.
+  #
+  # @param interp [Interpreter] The interpreter instance
+  # @return [Hash] The options hash or empty hash
+  def self.pop_options_if_present(interp)
+    return {} if interp.get_stack.length.zero?
+
+    top = interp.stack_peek
+    if top.is_a?(WordOptions)
+      opts = interp.stack_pop
+      return opts.to_hash
+    end
+
+    {}
+  end
+end

data/lib/forthic.rb

@@ -1,25 +1,35 @@
 # frozen_string_literal: true
 
-require_relative "forthic/version"
+# Forthic - A stack-based programming language
+#
+# Main entry point for the Forthic Ruby runtime.
+# Requires all core components and standard library modules.
 
+# Core components
+require_relative 'forthic/errors'
+require_relative 'forthic/utils'
+require_relative 'forthic/literals'
+require_relative 'forthic/tokenizer'
+require_relative 'forthic/word_options'
+require_relative 'forthic/module'
+require_relative 'forthic/interpreter'
+
+# Decorators
+require_relative 'forthic/decorators/word'
+require_relative 'forthic/decorators/docs'
+
+# Standard library modules
+require_relative 'forthic/modules/standard/core_module'
+require_relative 'forthic/modules/standard/array_module'
+require_relative 'forthic/modules/standard/record_module'
+require_relative 'forthic/modules/standard/string_module'
+require_relative 'forthic/modules/standard/math_module'
+require_relative 'forthic/modules/standard/boolean_module'
+require_relative 'forthic/modules/standard/json_module'
+require_relative 'forthic/modules/standard/datetime_module'
+
+# Main module namespace
 module Forthic
-  autoload :Tokenizer, "forthic/tokenizer"
-  autoload :CodeLocation, "forthic/code_location"
-  autoload :Token, "forthic/token"
-  autoload :PositionedString, "forthic/positioned_string"
-  autoload :ForthicError, "forthic/forthic_error"
-  autoload :Word, "forthic/words/word"
-  autoload :PushValueWord, "forthic/words/push_value_word"
-  autoload :DefinitionWord, "forthic/words/definition_word"
-  autoload :ModuleMemoWord, "forthic/words/module_memo_word"
-  autoload :ModuleMemoBangAtWord, "forthic/words/module_memo_bang_at_word"
-  autoload :ModuleMemoBangWord, "forthic/words/module_memo_bang_word"
-  autoload :ModuleMemoBangAtWord, "forthic/words/module_memo_bang_at_word"
-  autoload :EndArrayWord, "forthic/words/end_array_word"
-  autoload :StartModuleWord, "forthic/words/start_module_word"
-  autoload :EndModuleWord, "forthic/words/end_module_word"
-  autoload :MapWord, "forthic/words/map_word"
-  autoload :ForthicModule, "forthic/forthic_module"
-  autoload :GlobalModule, "forthic/global_module"
-  autoload :Interpreter, "forthic/interpreter"
+  # Version of the Forthic Ruby runtime
+  VERSION = '0.3.0'
 end

data/protos/README.md

@@ -0,0 +1,43 @@
+# Forthic gRPC Protocol Definitions
+
+This directory contains versioned Protocol Buffer definitions for Forthic's multi-runtime communication.
+
+## Versioning
+
+Protocol definitions are organized by version to ensure compatibility:
+
+- **v1/** - Initial gRPC protocol version
+  - Basic types: int, string, bool, float, null, array, record
+  - Temporal types: instant, plain_date, zoned_datetime
+  - Operations: ExecuteWord, ExecuteSequence, ListModules, GetModuleInfo
+  - Error handling with rich context
+
+## Version History
+
+### v1 (Current)
+- Initial release supporting TypeScript ↔ Python ↔ Ruby ↔ Rust cross-runtime execution
+- Full type serialization for all Forthic standard types
+- Module discovery and introspection
+- Enhanced error reporting with stack traces and context
+
+## Usage
+
+The proto files are used to generate Ruby gRPC code:
+
+```bash
+# Generate protobuf code
+bundle exec rake generate_grpc
+```
+
+The generated files are in `lib/forthic/grpc/`:
+- `forthic_runtime_pb.rb` - Message definitions
+- `forthic_runtime_services_pb.rb` - Service definitions
+
+## Future Versions
+
+When protocol changes are needed:
+1. Copy current version to new directory (e.g., `v2/`)
+2. Make changes in new version
+3. Regenerate Ruby code from new version
+4. Update client/server to support multiple versions if needed
+5. Deprecate old versions with migration timeline

data/protos/v1/forthic_runtime.proto

@@ -0,0 +1,200 @@
+syntax = "proto3";
+
+package forthic;
+
+// Service for executing Forthic words across runtime boundaries
+service ForthicRuntime {
+  // Execute a single word in the remote runtime
+  rpc ExecuteWord(ExecuteWordRequest) returns (ExecuteWordResponse);
+
+  // Execute a sequence of words in one remote call (batched execution optimization)
+  rpc ExecuteSequence(ExecuteSequenceRequest) returns (ExecuteSequenceResponse);
+
+  // Phase 3: Module discovery
+  // List available runtime-specific modules (excludes standard library)
+  rpc ListModules(ListModulesRequest) returns (ListModulesResponse);
+
+  // Get detailed information about a specific module
+  rpc GetModuleInfo(GetModuleInfoRequest) returns (GetModuleInfoResponse);
+}
+
+// Request to execute a word in a remote runtime
+message ExecuteWordRequest {
+  // Name of the word to execute
+  string word_name = 1;
+
+  // Stack state before execution (simple types only for Phase 1)
+  repeated StackValue stack = 2;
+}
+
+// Response from executing a word
+message ExecuteWordResponse {
+  // Stack state after execution
+  repeated StackValue result_stack = 1;
+
+  // Error information if execution failed
+  optional ErrorInfo error = 2;
+}
+
+// Request to execute a sequence of words in one batch
+// Optimization: Reduces RPC round-trips for consecutive remote words
+message ExecuteSequenceRequest {
+  // Names of words to execute in order
+  repeated string word_names = 1;
+
+  // Initial stack state before execution
+  repeated StackValue stack = 2;
+}
+
+// Response from executing a word sequence
+message ExecuteSequenceResponse {
+  // Stack state after executing all words
+  repeated StackValue result_stack = 1;
+
+  // Error information if any word failed
+  optional ErrorInfo error = 2;
+}
+
+// Represents a value on the Forthic stack
+// Phase 2: Supports all basic Forthic types including arrays and records
+// Phase 8: Added temporal types (instant, plain_date, zoned_datetime)
+message StackValue {
+  oneof value {
+    int64 int_value = 1;
+    string string_value = 2;
+    bool bool_value = 3;
+    double float_value = 4;
+    NullValue null_value = 5;
+    ArrayValue array_value = 6;
+    RecordValue record_value = 7;
+    InstantValue instant_value = 8;
+    PlainDateValue plain_date_value = 9;
+    ZonedDateTimeValue zoned_datetime_value = 10;
+  }
+}
+
+// Represents null/None value
+message NullValue {
+  // Empty message, presence indicates null
+}
+
+// Represents an array (list) of values
+message ArrayValue {
+  repeated StackValue items = 1;
+}
+
+// Represents a record (object/dict) with string keys
+message RecordValue {
+  map<string, StackValue> fields = 1;
+}
+
+// Phase 8: Temporal Types
+
+// Represents an instant in time (UTC timestamp)
+// Serialized as ISO 8601 string with timezone (e.g., "2025-01-15T10:30:00Z")
+// Maps to:
+//   - TypeScript: Temporal.Instant
+//   - Python: datetime.datetime (timezone-aware)
+message InstantValue {
+  string iso8601 = 1;
+}
+
+// Represents a calendar date without time or timezone
+// Serialized as ISO 8601 date string (e.g., "2025-01-15")
+// Maps to:
+//   - TypeScript: Temporal.PlainDate
+//   - Python: datetime.date
+message PlainDateValue {
+  string iso8601_date = 1;
+}
+
+// Represents a date-time with timezone
+// Serialized as ISO 8601 string with timezone (e.g., "2025-01-15T10:30:00-05:00[America/New_York]")
+// Maps to:
+//   - TypeScript: Temporal.ZonedDateTime
+//   - Python: datetime.datetime (timezone-aware with tzinfo)
+message ZonedDateTimeValue {
+  string iso8601 = 1;
+  string timezone = 2;  // IANA timezone name (e.g., "America/New_York")
+}
+
+// Phase 9: Enhanced error information from remote execution
+message ErrorInfo {
+  // Error message
+  string message = 1;
+
+  // Runtime where error occurred (e.g., "python", "ruby", "typescript")
+  string runtime = 2;
+
+  // Stack trace from the remote runtime
+  repeated string stack_trace = 3;
+
+  // Error type/class name (e.g., "ValueError", "TypeError")
+  string error_type = 4;
+
+  // Word location where error occurred (if available)
+  optional string word_location = 5;
+
+  // Module name where error occurred (if available)
+  optional string module_name = 6;
+
+  // Additional context information
+  map<string, string> context = 7;
+}
+
+// Phase 3: Module Discovery Messages
+
+// Request to list available runtime-specific modules
+message ListModulesRequest {
+  // Empty for now - future: could add filters
+}
+
+// Response with list of available modules
+message ListModulesResponse {
+  repeated ModuleSummary modules = 1;
+}
+
+// Summary information about a module
+message ModuleSummary {
+  // Module name
+  string name = 1;
+
+  // Brief description
+  string description = 2;
+
+  // Number of words in the module
+  int32 word_count = 3;
+
+  // Whether this is a runtime-specific module (e.g., pandas)
+  bool runtime_specific = 4;
+}
+
+// Request detailed information about a specific module
+message GetModuleInfoRequest {
+  // Name of the module
+  string module_name = 1;
+}
+
+// Response with detailed module information
+message GetModuleInfoResponse {
+  // Module name
+  string name = 1;
+
+  // Module description
+  string description = 2;
+
+  // List of words in the module
+  repeated WordInfo words = 3;
+}
+
+// Information about a single word
+message WordInfo {
+  // Word name
+  string name = 1;
+
+  // Stack effect notation (e.g., "( a b -- c )")
+  string stack_effect = 2;
+
+  // Description of what the word does
+  string description = 3;
+}