forthic 0.2.0 → 0.3.0

data/lib/forthic/modules/standard/math_module.rb

@@ -0,0 +1,365 @@
+# frozen_string_literal: true
+
+require_relative '../../decorators/word'
+
+module Forthic
+  module Modules
+    # MathModule - Mathematical operations and utilities
+    #
+    # Provides arithmetic operations, aggregation functions, type conversions,
+    # and common mathematical functions.
+    class MathModule < Decorators::DecoratedModule
+      # Register module documentation
+      module_doc <<~DOC
+        Mathematical operations and utilities including arithmetic, aggregation, and conversions.
+
+        ## Categories
+        - Arithmetic: +, -, *, /, ADD, SUBTRACT, MULTIPLY, DIVIDE, MOD
+        - Aggregates: MEAN, MAX, MIN, SUM
+        - Type conversion: >INT, >FLOAT, >FIXED, ROUND
+        - Special values: INFINITY, UNIFORM-RANDOM
+        - Math functions: ABS, SQRT, FLOOR, CEIL, CLAMP
+
+        ## Examples
+        5 3 +
+        [1 2 3 4] SUM
+        [10 20 30] MEAN
+        3.7 ROUND
+        0 100 UNIFORM-RANDOM
+      DOC
+
+      def initialize
+        super("math")
+      end
+
+      # ========================================
+      # Arithmetic Operations
+      # ========================================
+
+    forthic_direct_word :plus, "( a:number b:number -- sum:number ) OR ( numbers:number[] -- sum:number )", "Add two numbers or sum array", "+"
+      def plus(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          result = 0
+          b.each do |num|
+            result += num unless num.nil?
+          end
+          interp.stack_push(result)
+          return
+        end
+
+        # Case 2: Two numbers
+        a = interp.stack_pop
+        num_a = a.nil? ? 0 : a
+        num_b = b.nil? ? 0 : b
+        interp.stack_push(num_a + num_b)
+      end
+
+    forthic_direct_word :plus_ADD, "( a:number b:number -- sum:number ) OR ( numbers:number[] -- sum:number )", "Add two numbers or sum array", "ADD"
+      def plus_ADD(interp)
+        plus(interp)
+      end
+
+    forthic_word :minus, "( a:number b:number -- difference:number )", "Subtract b from a", "-"
+      def minus(a, b)
+        return nil if a.nil? || b.nil?
+        a - b
+      end
+
+    forthic_word :minus_SUBTRACT, "( a:number b:number -- difference:number )", "Subtract b from a", "SUBTRACT"
+      def minus_SUBTRACT(a, b)
+        return nil if a.nil? || b.nil?
+        a - b
+      end
+
+    forthic_direct_word :times, "( a:number b:number -- product:number ) OR ( numbers:number[] -- product:number )", "Multiply two numbers or product of array", "*"
+      def times(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          result = 1
+          b.each do |num|
+            if num.nil?
+              interp.stack_push(nil)
+              return
+            end
+            result *= num
+          end
+          interp.stack_push(result)
+          return
+        end
+
+        # Case 2: Two numbers
+        a = interp.stack_pop
+        if a.nil? || b.nil?
+          interp.stack_push(nil)
+          return
+        end
+        interp.stack_push(a * b)
+      end
+
+    forthic_direct_word :times_MULTIPLY, "( a:number b:number -- product:number ) OR ( numbers:number[] -- product:number )", "Multiply two numbers or product of array", "MULTIPLY"
+      def times_MULTIPLY(interp)
+        times(interp)
+      end
+
+    forthic_word :divide_by, "( a:number b:number -- quotient:number )", "Divide a by b", "/"
+      def divide_by(a, b)
+        return nil if a.nil? || b.nil?
+        return nil if b == 0
+        a.to_f / b
+      end
+
+    forthic_word :divide_by_DIVIDE, "( a:number b:number -- quotient:number )", "Divide a by b", "DIVIDE"
+      def divide_by_DIVIDE(a, b)
+        return nil if a.nil? || b.nil?
+        return nil if b == 0
+        a.to_f / b
+      end
+
+    forthic_word :MOD, "( m:number n:number -- remainder:number )", "Modulo operation (m % n)"
+      def MOD(m, n)
+        return nil if m.nil? || n.nil?
+        m % n
+      end
+
+      # ========================================
+      # Aggregation Operations
+      # ========================================
+
+    forthic_word :MEAN, "( items:any[] -- mean:any )", "Calculate mean of array (handles numbers, strings, objects)"
+      def MEAN(items)
+        if items.nil? || (items.is_a?(Array) && items.empty?)
+          return 0
+        end
+
+        return items unless items.is_a?(Array)
+
+        return items[0] if items.length == 1
+
+        # Filter out nil values
+        filtered = items.reject(&:nil?)
+
+        return 0 if filtered.empty?
+
+        # Check type of first non-null item
+        first = filtered[0]
+
+        # Case 1: Numbers
+        if first.is_a?(Numeric)
+          sum = filtered.reduce(0) { |acc, val| acc + val }
+          return sum.to_f / filtered.length
+        end
+
+        # Case 2: Strings - return frequency distribution
+        if first.is_a?(String)
+          counts = {}
+          filtered.each do |item|
+            counts[item] = (counts[item] || 0) + 1
+          end
+          result = {}
+          counts.each do |key, count|
+            result[key] = count.to_f / filtered.length
+          end
+          return result
+        end
+
+        # Case 3: Objects - field-wise mean
+        if first.is_a?(Hash)
+          result = {}
+          all_keys = Set.new
+
+          # Collect all keys
+          filtered.each do |obj|
+            obj.each_key { |key| all_keys.add(key) }
+          end
+
+          # Compute mean for each key
+          all_keys.each do |key|
+            values = filtered.map { |obj| obj[key] }.reject(&:nil?)
+
+            next if values.empty?
+
+            first_val = values[0]
+
+            if first_val.is_a?(Numeric)
+              sum = values.reduce(0) { |acc, val| acc + val }
+              result[key] = sum.to_f / values.length
+            elsif first_val.is_a?(String)
+              counts = {}
+              values.each do |val|
+                counts[val] = (counts[val] || 0) + 1
+              end
+              freqs = {}
+              counts.each do |k, count|
+                freqs[k] = count.to_f / values.length
+              end
+              result[key] = freqs
+            end
+          end
+
+          return result
+        end
+
+        0
+      end
+
+    forthic_direct_word :MAX, "( a:number b:number -- max:number ) OR ( items:number[] -- max:number )", "Maximum of two numbers or array"
+      def MAX(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          if b.empty?
+            interp.stack_push(nil)
+            return
+          end
+          interp.stack_push(b.max)
+          return
+        end
+
+        # Case 2: Two values
+        a = interp.stack_pop
+        interp.stack_push([a, b].max)
+      end
+
+    forthic_direct_word :MIN, "( a:number b:number -- min:number ) OR ( items:number[] -- min:number )", "Minimum of two numbers or array"
+      def MIN(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          if b.empty?
+            interp.stack_push(nil)
+            return
+          end
+          interp.stack_push(b.min)
+          return
+        end
+
+        # Case 2: Two values
+        a = interp.stack_pop
+        interp.stack_push([a, b].min)
+      end
+
+    forthic_word :SUM, "( numbers:number[] -- sum:number )", "Sum of array (explicit)"
+      def SUM(numbers)
+        return 0 if numbers.nil? || !numbers.is_a?(Array)
+
+        result = 0
+        numbers.each do |num|
+          result += num unless num.nil?
+        end
+        result
+      end
+
+      # ========================================
+      # Type Conversion
+      # ========================================
+
+    forthic_word :to_INT, "( a:any -- int:number )", "Convert to integer (returns length for arrays/objects, 0 for null)", ">INT"
+      def to_INT(a)
+        return 0 if a.nil?
+
+        if a.is_a?(Array)
+          return a.length
+        elsif a.is_a?(Hash)
+          return a.keys.length
+        end
+
+        begin
+          Float(a).truncate
+        rescue StandardError
+          nil
+        end
+      end
+
+    forthic_word :to_FLOAT, "( a:any -- float:number )", "Convert to float", ">FLOAT"
+      def to_FLOAT(a)
+        return 0.0 if a.nil?
+
+        begin
+          Float(a)
+        rescue StandardError
+          nil
+        end
+      end
+
+    forthic_word :to_FIXED, "( num:number digits:number -- result:string )", "Format number with fixed decimal places", ">FIXED"
+      def to_FIXED(num, digits)
+        return nil if num.nil?
+
+        format("%.#{digits}f", num)
+      end
+
+    forthic_word :ROUND, "( num:number -- int:number )", "Round to nearest integer"
+      def ROUND(num)
+        return nil if num.nil?
+
+        num.round
+      end
+
+      # ========================================
+      # Special Values
+      # ========================================
+
+    forthic_word :INFINITY, "( -- infinity:number )", "Push Infinity value"
+      def INFINITY
+        Float::INFINITY
+      end
+
+    forthic_word :UNIFORM_RANDOM, "( low:number high:number -- random:number )", "Generate random number in range [low, high)", "UNIFORM-RANDOM"
+      def UNIFORM_RANDOM(low, high)
+        rand * (high - low) + low
+      end
+
+      # ========================================
+      # Math Functions
+      # ========================================
+
+    forthic_direct_word :ABS, "( n:number -- abs:number )", "Absolute value"
+      def ABS(interp)
+        n = interp.stack_pop
+        result = n.nil? ? nil : n.abs
+        interp.stack_push(result)
+      end
+
+    forthic_direct_word :SQRT, "( n:number -- sqrt:number )", "Square root"
+      def SQRT(interp)
+        n = interp.stack_pop
+        result = n.nil? ? nil : Math.sqrt(n)
+        interp.stack_push(result)
+      end
+
+    forthic_direct_word :FLOOR, "( n:number -- floor:number )", "Round down to integer"
+      def FLOOR(interp)
+        n = interp.stack_pop
+        result = n.nil? ? nil : n.floor
+        interp.stack_push(result)
+      end
+
+    forthic_direct_word :CEIL, "( n:number -- ceil:number )", "Round up to integer"
+      def CEIL(interp)
+        n = interp.stack_pop
+        result = n.nil? ? nil : n.ceil
+        interp.stack_push(result)
+      end
+
+    forthic_direct_word :CLAMP, "( value:number min:number max:number -- clamped:number )", "Constrain value to range [min, max]"
+      def CLAMP(interp)
+        max = interp.stack_pop
+        min = interp.stack_pop
+        value = interp.stack_pop
+        result = if value.nil? || min.nil? || max.nil?
+                   nil
+                 else
+                   [[min, value].max, max].min
+                 end
+        interp.stack_push(result)
+      end
+    end
+  end
+end

data/lib/forthic/modules/standard/record_module.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative '../../decorators/word'
+require 'json'
+
+module Forthic
+  module Modules
+    # RecordModule - Record (object/dictionary) manipulation operations
+    #
+    # Provides operations for working with key-value data structures (hashes).
+    class RecordModule < Decorators::DecoratedModule
+      # Register module documentation
+      module_doc <<~DOC
+        Record (object/dictionary) manipulation operations for working with key-value data structures.
+
+        ## Categories
+        - Core: REC, REC@, |REC@, <REC!
+        - Transform: RELABEL, INVERT-KEYS, REC-DEFAULTS, <DEL
+        - Access: KEYS, VALUES
+      DOC
+
+      def initialize
+        super("record")
+      end
+
+      # Helper function to drill down into nested record structure
+      #
+      # @param record [Hash] The record to drill into
+      # @param fields [Array<String>] Array of field names to traverse
+      # @return [Any] The value at the end of the field path, or nil if not found
+      def self.drill_for_value(record, fields)
+        result = record
+        fields.each do |field|
+          return nil if result.nil?
+          result = result[field]
+        end
+        result
+      end
+
+    forthic_word :REC, "( key_vals:any[] -- rec:any )", "Create record from [[key, val], ...] pairs"
+      def REC(key_vals)
+        _key_vals = key_vals || []
+
+        result = {}
+        _key_vals.each do |pair|
+          key = nil
+          val = nil
+          if pair
+            key = pair[0] if pair.length >= 1
+            val = pair[1] if pair.length >= 2
+          end
+          result[key] = val
+        end
+
+        result
+      end
+
+    forthic_word :REC_at, "( rec:any field:any -- value:any )", "Get value from record by field or array of fields", "REC@"
+      def REC_at(rec, field)
+        return nil unless rec
+
+        fields = field.is_a?(Array) ? field : [field]
+
+        self.class.drill_for_value(rec, fields)
+      end
+
+    forthic_word :pipe_REC_at, "( records:any field:any -- values:any )", "Map REC@ over array of records", "|REC@"
+      def pipe_REC_at(records, field)
+        # Push records back and field, then use MAP with REC@
+        interp.stack_push(records)
+        interp.run("'#{field.to_json} REC@' MAP")
+        nil # Result already on stack from MAP
+      end
+
+    forthic_word :l_REC_bang, "( rec:any value:any field:any -- rec:any )", "Set value in record at field path", "<REC!"
+      def l_REC_bang(rec, value, field)
+        _rec = rec || {}
+
+        fields = field.is_a?(Array) ? field : [field]
+
+        # Helper to ensure field exists
+        ensure_field = lambda do |record, field_name|
+          res = record[field_name]
+          if res.nil?
+            res = {}
+            record[field_name] = res
+          end
+          res
+        end
+
+        cur_rec = _rec
+        # Drill down up until the last value
+        (0...fields.length - 1).each do |i|
+          cur_rec = ensure_field.call(cur_rec, fields[i])
+        end
+
+        # Set the value at the right depth within rec
+        cur_rec[fields.last] = value
+
+        _rec
+      end
+
+    forthic_word :RELABEL, "( container:any old_keys:any[] new_keys:any[] -- container:any )", "Rename record keys"
+      def RELABEL(container, old_keys, new_keys)
+        return container unless container
+
+        if old_keys.length != new_keys.length
+          raise StandardError, "RELABEL: old_keys and new_keys must be same length"
+        end
+
+        new_to_old = {}
+        old_keys.each_with_index do |old_key, i|
+          new_to_old[new_keys[i]] = old_key
+        end
+
+        if container.is_a?(Array)
+          result = []
+          new_to_old.keys.sort.each do |k|
+            result.push(container[new_to_old[k]])
+          end
+        else
+          result = {}
+          new_to_old.each do |new_key, old_key|
+            result[new_key] = container[old_key]
+          end
+        end
+
+        result
+      end
+
+    forthic_word :INVERT_KEYS, "( record:any -- inverted:any )", "Invert two-level nested record structure", "INVERT-KEYS"
+      def INVERT_KEYS(record)
+        result = {}
+        record.each do |first_key, sub_record|
+          sub_record.each do |second_key, value|
+            result[second_key] ||= {}
+            result[second_key][first_key] = value
+          end
+        end
+
+        result
+      end
+
+    forthic_word :REC_DEFAULTS, "( record:any key_vals:any[] -- record:any )", "Set default values for missing/empty fields", "REC-DEFAULTS"
+      def REC_DEFAULTS(record, key_vals)
+        key_vals.each do |key_val|
+          key = key_val[0]
+          value = record[key]
+          if value.nil? || value == ""
+            record[key] = key_val[1]
+          end
+        end
+
+        record
+      end
+
+    forthic_word :l_DEL, "( container:any key:any -- container:any )", "Delete key from record or index from array", "<DEL"
+      def l_DEL(container, key)
+        return container unless container
+
+        if container.is_a?(Array)
+          container.delete_at(key)
+        else
+          container.delete(key)
+        end
+
+        container
+      end
+
+    forthic_word :KEYS, "( container:any -- keys:any[] )", "Get keys from record or indices from array"
+      def KEYS(container)
+        _container = container || []
+
+        if _container.is_a?(Array)
+          result = []
+          _container.length.times do |i|
+            result.push(i)
+          end
+        else
+          result = _container.keys
+        end
+
+        result
+      end
+
+    forthic_word :VALUES, "( container:any -- values:any[] )", "Get values from record or elements from array"
+      def VALUES(container)
+        _container = container || []
+
+        if _container.is_a?(Array)
+          result = _container
+        else
+          result = []
+          _container.each_key do |k|
+            result.push(_container[k])
+          end
+        end
+
+        result
+      end
+    end
+  end
+end