forthic 0.2.0 → 0.5.0

data/lib/forthic/literals.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require 'time'
+require 'date'
+
+module Forthic
+  # Literal Handlers for Forthic Interpreters
+  #
+  # This module provides literal parsing functions that convert string tokens into typed values.
+  # These handlers are used by the Forthic interpreter to recognize and parse different literal types.
+  #
+  # You can use these built-in handlers or create custom literal handlers for your own Forthic
+  # interpreters. Each handler should be a Proc/lambda that takes a string and returns the parsed
+  # value or nil if the string doesn't match the expected format.
+  #
+  # Built-in literal types:
+  # - Boolean: TRUE, FALSE
+  # - Integer: 42, -10, 0
+  # - Float: 3.14, -2.5, 0.0
+  # - Time: 9:00, 11:30 PM, 22:15
+  # - Date: 2020-06-05, YYYY-MM-DD (with wildcards)
+  # - ZonedDateTime: ISO 8601 timestamps with timezone support
+
+  # LiteralHandler type: Proc that takes string, returns parsed value or nil
+  # @example
+  #   handler = ->(str) { str == "TRUE" ? true : nil }
+
+  # Parse boolean literals: TRUE, FALSE
+  #
+  # @param str [String] The string to parse
+  # @return [Boolean, nil] true, false, or nil if not a boolean
+  def self.to_bool(str)
+    return true if str == "TRUE"
+    return false if str == "FALSE"
+    nil
+  end
+
+  # Parse float literals: 3.14, -2.5, 0.0
+  # Must contain a decimal point
+  #
+  # @param str [String] The string to parse
+  # @return [Float, nil] The parsed float or nil if invalid
+  def self.to_float(str)
+    return nil unless str.include?(".")
+    result = Float(str)
+    result
+  rescue ArgumentError
+    nil
+  end
+
+  # Parse integer literals: 42, -10, 0
+  # Must not contain a decimal point
+  #
+  # @param str [String] The string to parse
+  # @return [Integer, nil] The parsed integer or nil if invalid
+  def self.to_int(str)
+    return nil if str.include?(".")
+    result = Integer(str, 10)
+    # Verify it's actually an integer string (not "42abc")
+    return nil unless result.to_s == str
+    result
+  rescue ArgumentError
+    nil
+  end
+
+  # SimpleTime - Represents a time of day (hour and minute)
+  #
+  # This is a simplified replacement for Temporal.PlainTime
+  # @!attribute hour
+  #   @return [Integer] Hour (0-23)
+  # @!attribute minute
+  #   @return [Integer] Minute (0-59)
+  SimpleTime = Struct.new(:hour, :minute, keyword_init: true) do
+    def to_s
+      format("%02d:%02d", hour, minute)
+    end
+  end
+
+  # Parse time literals: 9:00, 11:30 PM, 22:15 AM
+  #
+  # @param str [String] The string to parse
+  # @return [SimpleTime, nil] The parsed time or nil if invalid
+  def self.to_time(str)
+    match = str.match(/^(\d{1,2}):(\d{2})(?:\s*(AM|PM))?$/)
+    return nil unless match
+
+    hours = match[1].to_i
+    minutes = match[2].to_i
+    meridiem = match[3]
+
+    # Adjust for AM/PM
+    if meridiem == "PM" && hours < 12
+      hours += 12
+    elsif meridiem == "AM" && hours == 12
+      hours = 0
+    elsif meridiem == "AM" && hours > 12
+      # Handle invalid cases like "22:15 AM"
+      hours -= 12
+    end
+
+    return nil if hours > 23 || minutes >= 60
+
+    SimpleTime.new(hour: hours, minute: minutes)
+  end
+
+  # Create a date literal handler with timezone support
+  # Parses: 2020-06-05, YYYY-MM-DD (with wildcards)
+  #
+  # @param timezone [String] The timezone to use for wildcard resolution
+  # @return [Proc] A literal handler proc
+  def self.to_literal_date(timezone)
+    lambda do |str|
+      match = str.match(/^(\d{4}|YYYY)-(\d{2}|MM)-(\d{2}|DD)$/)
+      return nil unless match
+
+      # Get current date in the specified timezone
+      # Use ENV['TZ'] to temporarily set timezone for Time.now
+      old_tz = ENV['TZ']
+      begin
+        ENV['TZ'] = timezone
+        now = Time.now
+        year = match[1] == "YYYY" ? now.year : match[1].to_i
+        month = match[2] == "MM" ? now.month : match[2].to_i
+        day = match[3] == "DD" ? now.day : match[3].to_i
+
+        Date.new(year, month, day)
+      rescue ArgumentError
+        nil
+      ensure
+        ENV['TZ'] = old_tz
+      end
+    end
+  end
+
+  # Create a zoned datetime literal handler with timezone support
+  # Parses ISO 8601 datetime with IANA timezone bracket notation:
+  # - 2025-05-20T08:00:00[America/Los_Angeles]  (IANA timezone)
+  # - 2025-05-20T08:00:00-07:00[America/Los_Angeles]  (offset + IANA)
+  # - 2025-05-24T10:15:00Z  (UTC)
+  # - 2025-05-24T10:15:00-05:00  (offset only)
+  # - 2025-05-24T10:15:00  (uses default timezone)
+  #
+  # @param timezone [String] The default timezone to use
+  # @return [Proc] A literal handler proc
+  def self.to_zoned_datetime(timezone)
+    lambda do |str|
+      return nil unless str.include?("T")
+
+      begin
+        # Extract IANA timezone from brackets if present
+        bracket_match = str.match(/\[([^\]]+)\]$/)
+
+        if bracket_match
+          # Extract IANA timezone name from brackets
+          tz_name = bracket_match[1]
+
+          # Extract datetime string (before bracket)
+          datetime_str = str[0...bracket_match.begin(0)]
+
+          # Parse datetime (may have offset)
+          # Handle Z suffix
+          datetime_str = datetime_str.sub(/Z$/, "+00:00")
+          time = Time.parse(datetime_str)
+
+          # Convert to specified timezone using TZInfo
+          require 'tzinfo'
+          tz = TZInfo::Timezone.get(tz_name)
+          return tz.to_local(time)
+        end
+
+        # No brackets - handle as before
+
+        # Handle explicit UTC (Z suffix)
+        if str.end_with?("Z")
+          return Time.parse(str).utc
+        end
+
+        # Handle explicit timezone offset (+05:00, -05:00)
+        if str.match?(/[+-]\d{2}:\d{2}$/)
+          return Time.parse(str)
+        end
+
+        # No timezone specified, use interpreter's timezone
+        # Parse as UTC first, then convert to specified timezone using ENV['TZ']
+        old_tz = ENV['TZ']
+        begin
+          ENV['TZ'] = timezone
+          time = Time.parse(str)
+          time
+        ensure
+          ENV['TZ'] = old_tz
+        end
+      rescue ArgumentError, TZInfo::InvalidTimezoneIdentifier
+        # ArgumentError: invalid time format
+        # TZInfo::InvalidTimezoneIdentifier: invalid timezone name
+        nil
+      end
+    end
+  end
+end

data/lib/forthic/module.rb

@@ -0,0 +1,440 @@
+# frozen_string_literal: true
+
+require_relative 'tokenizer'
+require_relative 'errors'
+require 'set'
+
+module Forthic
+  # WordHandler type: Proc that takes an interpreter
+  # @example
+  #   handler = ->(interp) { interp.stack_push(42) }
+
+  # -------------------------------------
+  # Variable
+  # Variable - Named mutable value container
+  #
+  # Represents a variable that can store and retrieve values within a module scope.
+  # Variables are accessed by name and can be set to any value type.
+  class Variable
+    attr_reader :name
+    attr_accessor :value
+
+    def initialize(name, value = nil)
+      @name = name
+      @value = value
+    end
+
+    def get_name
+      @name
+    end
+
+    def set_value(val)
+      @value = val
+    end
+
+    def get_value
+      @value
+    end
+
+    def dup
+      Variable.new(@name, @value)
+    end
+  end
+
+  # -------------------------------------
+  # Words
+
+  # Word - Base class for all executable words in Forthic
+  #
+  # A word is the fundamental unit of execution in Forthic. When interpreted,
+  # it performs an action (typically manipulating the stack or control flow).
+  # All concrete word types must override the execute method.
+  class Word
+    attr_reader :name, :string
+    attr_accessor :location
+
+    def initialize(name)
+      @name = name
+      @string = name
+      @location = nil
+      @error_handlers = []
+    end
+
+    def set_location(location)
+      @location = location
+    end
+
+    def get_location
+      @location
+    end
+
+    def add_error_handler(&handler)
+      @error_handlers << handler
+    end
+
+    def remove_error_handler(handler)
+      @error_handlers.delete(handler)
+    end
+
+    def clear_error_handlers
+      @error_handlers.clear
+    end
+
+    def error_handlers
+      @error_handlers.dup
+    end
+
+    def try_error_handlers(error, interp)
+      @error_handlers.each do |handler|
+        begin
+          handler.call(error, self, interp)
+          return true  # Handler succeeded
+        rescue => e
+          next  # Try next handler
+        end
+      end
+      false  # No handler succeeded
+    end
+
+    def execute(_interp)
+      raise NotImplementedError, "Must override Word#execute"
+    end
+  end
+
+  # PushValueWord - Word that pushes a value onto the stack
+  #
+  # Executes by pushing its stored value onto the interpreter's stack.
+  # Used for literals, variables, and constants.
+  class PushValueWord < Word
+    attr_reader :value
+
+    def initialize(name, value)
+      super(name)
+      @value = value
+    end
+
+    def execute(interp)
+      interp.stack_push(@value)
+    end
+  end
+
+  # DefinitionWord - User-defined word composed of other words
+  #
+  # Represents a word defined in Forthic code using `:`
+  # Contains a sequence of words that are executed in order.
+  # Provides error context by tracking both call site and definition location.
+  class DefinitionWord < Word
+    attr_reader :words
+
+    def initialize(name)
+      super(name)
+      @words = []
+    end
+
+    def add_word(word)
+      @words << word
+    end
+
+    def execute(interp)
+      @words.each do |word|
+        begin
+          word.execute(interp)
+        rescue => e
+          tokenizer = interp.get_tokenizer
+          raise WordExecutionError.new(
+            "Error executing #{@name}",
+            e,
+            call_location: tokenizer.get_token_location,      # Where the word was called
+            definition_location: word.get_location            # Where the word was defined
+          )
+        end
+      end
+    end
+  end
+
+  # ModuleMemoWord - Memoized word that caches its result
+  #
+  # Executes the wrapped word once and caches the result on the stack.
+  # Subsequent calls return the cached value without re-executing.
+  # Defined in Forthic using `@:`. Can be refreshed using the `!` and `!@` variants.
+  class ModuleMemoWord < Word
+    attr_reader :word, :value
+    attr_accessor :has_value
+
+    def initialize(word)
+      super(word.name)
+      @word = word
+      @has_value = false
+      @value = nil
+    end
+
+    def refresh(interp)
+      @word.execute(interp)
+      @value = interp.stack_pop
+      @has_value = true
+    end
+
+    def execute(interp)
+      refresh(interp) unless @has_value
+      interp.stack_push(@value)
+    end
+  end
+
+  # ModuleMemoBangWord - Forces refresh of a memoized word
+  #
+  # Re-executes the memoized word and updates its cached value.
+  # Named with a `!` suffix (e.g., `WORD!` for a memo word named `WORD`).
+  # Does not push the new value onto the stack.
+  class ModuleMemoBangWord < Word
+    attr_reader :memo_word
+
+    def initialize(memo_word)
+      super("#{memo_word.name}!")
+      @memo_word = memo_word
+    end
+
+    def execute(interp)
+      @memo_word.refresh(interp)
+    end
+  end
+
+  # ModuleMemoBangAtWord - Refreshes a memoized word and returns its value
+  #
+  # Re-executes the memoized word, updates its cached value, and pushes the new value onto the stack.
+  # Named with a `!@` suffix (e.g., `WORD!@` for a memo word named `WORD`).
+  # Combines the refresh and retrieval operations.
+  class ModuleMemoBangAtWord < Word
+    attr_reader :memo_word
+
+    def initialize(memo_word)
+      super("#{memo_word.name}!@")
+      @memo_word = memo_word
+    end
+
+    def execute(interp)
+      @memo_word.refresh(interp)
+      interp.stack_push(@memo_word.value)
+    end
+  end
+
+  # ExecuteWord - Wrapper word that executes another word
+  #
+  # Delegates execution to a target word. Used for prefixed module imports
+  # to create words like `prefix.word` that execute the original word from the imported module.
+  class ExecuteWord < Word
+    attr_reader :target_word
+
+    def initialize(name, target_word)
+      super(name)
+      @target_word = target_word
+    end
+
+    def execute(interp)
+      @target_word.execute(interp)
+    end
+  end
+
+  # ModuleWord - Word that executes a handler function with error handling support
+  #
+  # Used for module words created via decorators or add_module_word().
+  # Integrates per-word error handler functionality. Ruby version is synchronous.
+  class ModuleWord < Word
+    attr_reader :handler
+
+    def initialize(name, &handler)
+      super(name)
+      @handler = handler
+    end
+
+    def execute(interp)
+      @handler.call(interp)
+    rescue IntentionalStopError => e
+      # Never handle intentional flow control errors
+      raise
+    rescue => e
+      # Try error handlers
+      handled = try_error_handlers(e, interp)
+      raise unless handled  # Re-raise if not handled
+      # If handled, execution continues (error suppressed)
+    end
+  end
+
+  # -------------------------------------
+  # Module
+
+  # Module - Container for words, variables, and imported modules
+  #
+  # Modules provide namespacing and code organization in Forthic.
+  # Each module maintains its own dictionary of words, variables, and imported modules.
+  #
+  # Features:
+  # - Word and variable management
+  # - Module importing with optional prefixes
+  # - Exportable word lists for controlled visibility
+  # - Module duplication and copying for isolated execution contexts
+  #
+  # Modules can be defined inline with `{module_name ... }` syntax or
+  # loaded from external sources.
+  class Module
+    attr_accessor :words, :exportable, :variables, :modules, :module_prefixes
+    attr_accessor :name, :forthic_code, :interp
+
+    def initialize(name, forthic_code = "")
+      @words = []
+      @exportable = []
+      @variables = {}
+      @modules = {}
+      @module_prefixes = {}
+      @name = name
+      @forthic_code = forthic_code
+      @interp = nil
+    end
+
+    def get_name
+      @name
+    end
+
+    def set_interp(interp)
+      @interp = interp
+    end
+
+    def get_interp
+      raise "Module #{@name} has no interpreter" unless @interp
+      @interp
+    end
+
+    # Duplication methods
+    def dup
+      result = Module.new(@name)
+      result.words = @words.dup
+      result.exportable = @exportable.dup
+      @variables.each do |key, var|
+        result.variables[key] = var.dup
+      end
+      @modules.each do |key, mod|
+        result.modules[key] = mod
+      end
+      result.forthic_code = @forthic_code
+      result
+    end
+
+    def copy(interp)
+      result = Module.new(@name)
+      result.words = @words.dup
+      result.exportable = @exportable.dup
+      @variables.each do |key, var|
+        result.variables[key] = var.dup
+      end
+      @modules.each do |key, mod|
+        result.modules[key] = mod
+      end
+
+      # Restore module_prefixes
+      @module_prefixes.each do |module_name, prefixes|
+        prefixes.each do |prefix|
+          result.import_module(prefix, @modules[module_name], interp)
+        end
+      end
+
+      result.forthic_code = @forthic_code
+      result
+    end
+
+    # Module management
+    def find_module(name)
+      @modules[name]
+    end
+
+    def register_module(module_name, prefix, mod)
+      @modules[module_name] = mod
+
+      @module_prefixes[module_name] ||= Set.new
+      @module_prefixes[module_name].add(prefix)
+    end
+
+    def import_module(prefix, mod, _interp)
+      new_module = mod.dup
+
+      words = new_module.exportable_words
+      words.each do |word|
+        # For unprefixed imports, add word directly
+        if prefix == ""
+          add_word(word)
+        else
+          # For prefixed imports, create word that executes the target word
+          prefixed_word = ExecuteWord.new("#{prefix}.#{word.name}", word)
+          add_word(prefixed_word)
+        end
+      end
+      register_module(mod.name, prefix, new_module)
+    end
+
+    # Word management
+    def add_word(word)
+      @words << word
+    end
+
+    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
+
+    def add_exportable(names)
+      @exportable.concat(names)
+    end
+
+    def add_exportable_word(word)
+      @words << word
+      @exportable << word.name
+    end
+
+    def add_module_word(word_name, word_func = nil, &block)
+      # Support both calling styles:
+      # 1. add_module_word("NAME", proc) - old style
+      # 2. add_module_word("NAME") { |interp| ... } - new style (block)
+      handler = block || word_func
+      raise ArgumentError, "Must provide either a proc or block" unless handler
+
+      word = ModuleWord.new(word_name, &handler)
+      add_exportable_word(word)
+      word
+    end
+
+    def exportable_words
+      result = []
+      @words.each do |word|
+        result << word if @exportable.include?(word.name)
+      end
+      result
+    end
+
+    def find_word(name)
+      result = find_dictionary_word(name)
+      result = find_variable(name) unless result
+      result
+    end
+
+    def find_dictionary_word(word_name)
+      # Search backwards (most recent first)
+      (@words.length - 1).downto(0) do |i|
+        w = @words[i]
+        return w if w.name == word_name
+      end
+      nil
+    end
+
+    def find_variable(varname)
+      var_result = @variables[varname]
+      return PushValueWord.new(varname, var_result) if var_result
+      nil
+    end
+
+    # Variable management
+    def add_variable(name, value = nil)
+      @variables[name] ||= Variable.new(name, value)
+    end
+  end
+end