forthic 0.1.0 → 0.3.0

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

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require_relative '../../decorators/word'
+
+module Forthic
+  module Modules
+    # BooleanModule - Comparison, logic, and membership operations
+    #
+    # Provides boolean operations including comparisons, logical operators,
+    # and membership testing.
+    class BooleanModule < Decorators::DecoratedModule
+      # Register module documentation
+      module_doc <<~DOC
+        Comparison, logic, and membership operations for boolean values and conditions.
+
+        ## Categories
+        - Comparison: ==, !=, <, <=, >, >=
+        - Logic: OR, AND, NOT, XOR, NAND
+        - Membership: IN, ANY, ALL
+        - Conversion: >BOOL
+
+        ## Examples
+        5 3 >
+        "hello" "hello" ==
+        [1 2 3] [4 5 6] OR
+        2 [1 2 3] IN
+      DOC
+
+      def initialize
+        super("boolean")
+      end
+
+      # ========================================
+      # Comparison Operations
+      # ========================================
+
+    forthic_word :equals, "( a:any b:any -- equal:boolean )", "Test equality", "=="
+      def equals(a, b)
+        a == b
+      end
+
+    forthic_word :not_equals, "( a:any b:any -- not_equal:boolean )", "Test inequality", "!="
+      def not_equals(a, b)
+        a != b
+      end
+
+    forthic_word :less_than, "( a:any b:any -- less_than:boolean )", "Less than", "<"
+      def less_than(a, b)
+        a < b
+      end
+
+    forthic_word :less_than_or_equal, "( a:any b:any -- less_equal:boolean )", "Less than or equal", "<="
+      def less_than_or_equal(a, b)
+        a <= b
+      end
+
+    forthic_word :greater_than, "( a:any b:any -- greater_than:boolean )", "Greater than", ">"
+      def greater_than(a, b)
+        a > b
+      end
+
+    forthic_word :greater_than_or_equal, "( a:any b:any -- greater_equal:boolean )", "Greater than or equal", ">="
+      def greater_than_or_equal(a, b)
+        a >= b
+      end
+
+      # ========================================
+      # Logic Operations
+      # ========================================
+
+    forthic_direct_word :OR, "( a:boolean b:boolean -- result:boolean ) OR ( bools:boolean[] -- result:boolean )", "Logical OR of two values or array"
+      def OR(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          b.each do |val|
+            if val
+              interp.stack_push(true)
+              return
+            end
+          end
+          interp.stack_push(false)
+          return
+        end
+
+        # Case 2: Two values
+        a = interp.stack_pop
+        interp.stack_push(a || b)
+      end
+
+    forthic_direct_word :AND, "( a:boolean b:boolean -- result:boolean ) OR ( bools:boolean[] -- result:boolean )", "Logical AND of two values or array"
+      def AND(interp)
+        b = interp.stack_pop
+
+        # Case 1: Array on top of stack
+        if b.is_a?(Array)
+          b.each do |val|
+            unless val
+              interp.stack_push(false)
+              return
+            end
+          end
+          interp.stack_push(true)
+          return
+        end
+
+        # Case 2: Two values
+        a = interp.stack_pop
+        interp.stack_push(a && b)
+      end
+
+    forthic_word :NOT, "( bool:boolean -- result:boolean )", "Logical NOT"
+      def NOT(bool)
+        !bool
+      end
+
+    forthic_word :XOR, "( a:boolean b:boolean -- result:boolean )", "Logical XOR (exclusive or)"
+      def XOR(a, b)
+        (a || b) && !(a && b)
+      end
+
+    forthic_word :NAND, "( a:boolean b:boolean -- result:boolean )", "Logical NAND (not and)"
+      def NAND(a, b)
+        !(a && b)
+      end
+
+      # ========================================
+      # Membership Operations
+      # ========================================
+
+    forthic_word :IN, "( item:any array:any[] -- in:boolean )", "Check if item is in array"
+      def IN(item, array)
+        return false unless array.is_a?(Array)
+        array.include?(item)
+      end
+
+    forthic_word :ANY, "( items1:any[] items2:any[] -- any:boolean )", "Check if any item from items1 is in items2"
+      def ANY(items1, items2)
+        return false unless items1.is_a?(Array) && items2.is_a?(Array)
+
+        # If items2 is empty, return true (any items from items1 satisfy empty constraint)
+        return true if items2.empty?
+
+        # Check if any item from items1 is in items2
+        items1.any? { |item| items2.include?(item) }
+      end
+
+    forthic_word :ALL, "( items1:any[] items2:any[] -- all:boolean )", "Check if all items from items2 are in items1"
+      def ALL(items1, items2)
+        return false unless items1.is_a?(Array) && items2.is_a?(Array)
+
+        # If items2 is empty, return true (all zero items are in items1)
+        return true if items2.empty?
+
+        # Check if all items from items2 are in items1
+        items2.all? { |item| items1.include?(item) }
+      end
+
+      # ========================================
+      # Conversion Operations
+      # ========================================
+
+    forthic_word :to_BOOL, "( a:any -- bool:boolean )", "Convert to boolean (JavaScript-style truthiness)", ">BOOL"
+      def to_BOOL(a)
+        # Match JavaScript truthiness: null, undefined, 0, "", false are falsy
+        # Everything else (including [], {}) is truthy
+        return false if a.nil?
+        return false if a == false
+        return false if a == 0
+        return false if a == ""
+        true
+      end
+    end
+  end
+end

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

@@ -0,0 +1,362 @@
+# frozen_string_literal: true
+
+require_relative '../../decorators/word'
+require_relative '../../word_options'
+require_relative '../../errors'
+require 'json'
+
+module Forthic
+  module Modules
+    # CoreModule - Essential interpreter operations
+    #
+    # Provides stack manipulation, variables, control flow, and module system operations.
+    class CoreModule < Decorators::DecoratedModule
+      # Register module documentation
+      module_doc <<~DOC
+        Essential interpreter operations for stack manipulation, variables, control flow, and module system.
+
+        ## Categories
+        - Stack: POP, DUP, SWAP
+        - Variables: VARIABLES, !, @, !@
+        - Module: EXPORT, USE-MODULES
+        - Execution: INTERPRET
+        - Control: IDENTITY, NOP, DEFAULT, *DEFAULT, NULL, ARRAY?
+        - Options: ~> (converts array to WordOptions)
+        - Profiling: PROFILE-START, PROFILE-TIMESTAMP, PROFILE-END, PROFILE-DATA
+        - Logging: START-LOG, END-LOG
+        - String: INTERPOLATE, PRINT
+        - Debug: PEEK!, STACK!
+
+        ## Options
+        INTERPOLATE and PRINT support options via the ~> operator using syntax: [.option_name value ...] ~> WORD
+        - separator: String to use when joining array values (default: ", ")
+        - null_text: Text to display for null/undefined values (default: "null")
+        - json: Use JSON.stringify for all values (default: false)
+
+        ## Examples
+        5 .count ! "Count: .count" PRINT
+        "Items: .items" [.separator " | "] ~> PRINT
+        [1 2 3] PRINT                           # Direct printing: 1, 2, 3
+        [1 2 3] [.separator " | "] ~> PRINT    # With options: 1 | 2 | 3
+        [ [.name "Alice"] ] REC [.json TRUE] ~> PRINT  # JSON format: {"name":"Alice"}
+        "Hello .name" INTERPOLATE .greeting !
+        [1 2 3] DUP SWAP
+      DOC
+
+      def initialize
+        super("core")
+      end
+
+      # Helper method to get or create a variable
+      def self.get_or_create_variable(interp, name)
+        # Validate variable name - no __ prefix allowed
+        if name.match?(/^__/)
+          raise InvalidVariableNameError.new(
+            interp.get_top_input_string,
+            name,
+            location: interp.get_string_location
+          )
+        end
+
+        cur_module = interp.cur_module
+
+        # Check if variable already exists
+        variable = cur_module.variables[name]
+
+        # Create it if it doesn't exist
+        unless variable
+          cur_module.add_variable(name)
+          variable = cur_module.variables[name]
+        end
+
+        variable
+      end
+
+      # Stack operations
+
+    forthic_direct_word :POP, "( a:any -- )", "Removes top item from stack"
+      def POP(interp)
+        interp.stack_pop
+      end
+
+    forthic_direct_word :DUP, "( a:any -- a:any a:any )", "Duplicates top stack item"
+      def DUP(interp)
+        a = interp.stack_pop
+        interp.stack_push(a)
+        interp.stack_push(a)
+      end
+
+    forthic_direct_word :SWAP, "( a:any b:any -- b:any a:any )", "Swaps top two stack items"
+      def SWAP(interp)
+        b = interp.stack_pop
+        a = interp.stack_pop
+        interp.stack_push(b)
+        interp.stack_push(a)
+      end
+
+    forthic_word :PEEK_BANG, "( -- )", "Prints top of stack and stops execution", "PEEK!"
+      def PEEK_BANG
+        stack = interp.get_stack.get_items
+        if stack.length > 0
+          puts stack.last
+        else
+          puts "<STACK EMPTY>"
+        end
+        raise IntentionalStopError.new("PEEK!")
+      end
+
+    forthic_word :STACK_BANG, "( -- )", "Prints entire stack (reversed) and stops execution", "STACK!"
+      def STACK_BANG
+        stack = interp.get_stack.get_items.reverse
+        puts JSON.pretty_generate(stack)
+        raise IntentionalStopError.new("STACK!")
+      end
+
+      # Variable operations
+
+    forthic_word :VARIABLES, "( varnames:string[] -- )", "Creates variables in current module"
+      def VARIABLES(varnames)
+        mod = interp.cur_module
+        varnames.each do |v|
+          if v.match?(/^__/)
+            raise InvalidVariableNameError.new(
+              interp.get_top_input_string,
+              v,
+              location: interp.get_string_location
+            )
+          end
+          mod.add_variable(v)
+        end
+        nil
+      end
+
+    forthic_direct_word :set_var, "( value:any variable:any -- )", "Sets variable value (auto-creates if string name)", "!"
+      def set_var(interp)
+        variable = interp.stack_pop
+        value = interp.stack_pop
+        var_obj = if variable.is_a?(String)
+                    self.class.get_or_create_variable(interp, variable)
+                  else
+                    variable
+                  end
+        var_obj.set_value(value)
+      end
+
+    forthic_direct_word :get_var, "( variable:any -- value:any )", "Gets variable value (auto-creates if string name)", "@"
+      def get_var(interp)
+        variable = interp.stack_pop
+        var_obj = if variable.is_a?(String)
+                    self.class.get_or_create_variable(interp, variable)
+                  else
+                    variable
+                  end
+        interp.stack_push(var_obj.get_value)
+      end
+
+    forthic_direct_word :set_get_var, "( value:any variable:any -- value:any )", "Sets variable and returns value", "!@"
+      def set_get_var(interp)
+        variable = interp.stack_pop
+        value = interp.stack_pop
+        var_obj = if variable.is_a?(String)
+                    self.class.get_or_create_variable(interp, variable)
+                  else
+                    variable
+                  end
+        var_obj.set_value(value)
+        interp.stack_push(var_obj.get_value)
+      end
+
+      # Execution
+
+    forthic_direct_word :INTERPRET, "( string:string -- )", "Interprets Forthic string in current context"
+      def INTERPRET(interp)
+        string = interp.stack_pop
+        string_location = interp.get_string_location
+        interp.run(string, string_location) if string
+      end
+
+      # Module operations
+
+    forthic_word :EXPORT, "( names:string[] -- )", "Exports words from current module"
+      def EXPORT(names)
+        interp.cur_module.add_exportable(names)
+        nil
+      end
+
+    forthic_word :USE_MODULES, "( names:string[] -- )", "Imports modules by name", "USE-MODULES"
+      def USE_MODULES(names)
+        return nil unless names
+        interp.use_modules(names)
+        nil
+      end
+
+      # Control flow
+
+    forthic_word :IDENTITY, "( -- )", "Does nothing (identity operation)"
+      def IDENTITY
+        # No-op
+        nil
+      end
+
+    forthic_word :NOP, "( -- )", "Does nothing (no operation)"
+      def NOP
+        # No-op
+        nil
+      end
+
+    forthic_direct_word :NULL, "( -- null:null )", "Pushes null onto stack"
+      def NULL(interp)
+        interp.stack_push(nil)
+      end
+
+    forthic_word :ARRAY_Q, "( value:any -- boolean:boolean )", "Returns true if value is an array", "ARRAY?"
+      def ARRAY_Q(value)
+        value.is_a?(Array)
+      end
+
+    forthic_word :DEFAULT, "( value:any default_value:any -- result:any )", "Returns value or default if value is null/undefined/empty string"
+      def DEFAULT(value, default_value)
+        if value.nil? || value == ""
+          default_value
+        else
+          value
+        end
+      end
+
+    forthic_word :star_DEFAULT, "( value:any default_forthic:string -- result:any )", "Returns value or executes Forthic if value is null/undefined/empty string", "*DEFAULT"
+      def star_DEFAULT(value, default_forthic)
+        if value.nil? || value == ""
+          string_location = interp.get_string_location
+          interp.run(default_forthic, string_location)
+          interp.stack_pop
+        else
+          value
+        end
+      end
+
+      # Options
+
+    forthic_word :arrow, "( array:any[] -- options:WordOptions )", "Convert options array to WordOptions. Format: [.key1 val1 .key2 val2]", "~>"
+      def arrow(array)
+        WordOptions.new(array)
+      end
+
+      # Profiling
+
+    forthic_word :PROFILE_START, "( -- )", "Starts profiling word execution", "PROFILE-START"
+      def PROFILE_START
+        interp.start_profiling
+        nil
+      end
+
+    forthic_word :PROFILE_END, "( -- )", "Stops profiling word execution", "PROFILE-END"
+      def PROFILE_END
+        interp.stop_profiling
+        nil
+      end
+
+    forthic_word :PROFILE_TIMESTAMP, "( label:string -- )", "Records profiling timestamp with label", "PROFILE-TIMESTAMP"
+      def PROFILE_TIMESTAMP(label)
+        interp.add_timestamp(label)
+        nil
+      end
+
+    forthic_word :PROFILE_DATA, "( -- profile_data:object )", "Returns profiling data (word counts and timestamps)", "PROFILE-DATA"
+      def PROFILE_DATA
+        histogram = interp.word_histogram
+        timestamps = interp.profile_timestamps
+
+        result = {
+          word_counts: [],
+          timestamps: []
+        }
+
+        histogram.each do |val|
+          result[:word_counts] << { word: val[:word], count: val[:count] }
+        end
+
+        prev_time = 0.0
+        timestamps.each do |t|
+          result[:timestamps] << {
+            label: t.label,
+            time_ms: t.time_ms,
+            delta: t.time_ms - prev_time
+          }
+          prev_time = t.time_ms
+        end
+
+        result
+      end
+
+      # Logging
+
+    forthic_word :START_LOG, "( -- )", "Starts logging interpreter stream", "START-LOG"
+      def START_LOG
+        interp.start_stream
+        nil
+      end
+
+    forthic_word :END_LOG, "( -- )", "Ends logging interpreter stream", "END-LOG"
+      def END_LOG
+        interp.end_stream
+        nil
+      end
+
+      # String operations
+
+    forthic_word :INTERPOLATE, "( string:string [options:WordOptions] -- result:string )", "Interpolate variables (.name) and return result string. Use \\. to escape literal dots."
+      def INTERPOLATE(string, options = {})
+        separator = options[:separator] || options['separator'] || ", "
+        null_text = options[:null_text] || options['null_text'] || "null"
+        use_json = options[:json] || options['json'] || false
+
+        interpolate_string(string, separator, null_text, use_json)
+      end
+
+    forthic_word :PRINT, "( value:any [options:WordOptions] -- )", "Print value to stdout. Strings interpolate variables (.name). Non-strings formatted with options. Use \\. to escape literal dots in strings."
+      def PRINT(value, options = {})
+        separator = options[:separator] || options['separator'] || ", "
+        null_text = options[:null_text] || options['null_text'] || "null"
+        use_json = options[:json] || options['json'] || false
+
+        result = if value.is_a?(String)
+                   # String: interpolate variables
+                   interpolate_string(value, separator, null_text, use_json)
+                 else
+                   # Non-string: format directly
+                   value_to_string(value, separator, null_text, use_json)
+                 end
+        puts result
+        nil
+      end
+
+      private
+
+      def interpolate_string(string, separator, null_text, use_json)
+        string ||= ""
+
+        # First, handle escape sequences by replacing \. with a temporary placeholder
+        escaped = string.gsub(/\\\./, "\x00ESCAPED_DOT\x00")
+
+        # Replace whitespace-preceded or start-of-string .variable patterns
+        interpolated = escaped.gsub(/(?:^|(?<=\s))\.([a-zA-Z_][a-zA-Z0-9_-]*)/) do
+          var_name = ::Regexp.last_match(1)
+          variable = self.class.get_or_create_variable(interp, var_name)
+          value = variable.get_value
+          value_to_string(value, separator, null_text, use_json)
+        end
+
+        # Restore escaped dots
+        interpolated.gsub(/\x00ESCAPED_DOT\x00/, '.')
+      end
+
+      def value_to_string(value, separator, null_text, use_json)
+        return null_text if value.nil?
+        return value.to_json if use_json
+        return value.join(separator) if value.is_a?(Array)
+        return value.to_json if value.is_a?(Hash)
+        value.to_s
+      end
+    end
+  end
+end