kumi 0.0.3 → 0.0.5

data/documents/SYNTAX.md

@@ -187,11 +187,13 @@ value :sorted_scores, fn(:sort, input.score_array)
 
 ### Built-in Functions Available
 
+See [FUNCTIONS.md](documents/FUNCTIONS.md)
+
 | Category | Sugar | Sugar-Free |
 |----------|-------|------------|
 | **Arithmetic** | `+`, `-`, `*`, `/`, `**` | `fn(:add, a, b)`, `fn(:subtract, a, b)`, etc. |
 | **Comparison** | `>`, `<`, `>=`, `<=`, `==`, `!=` | `fn(:>, a, b)`, `fn(:<, a, b)`, etc. |
-| **Logical** | `&` (AND only) | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
+| **Logical** | `&` `|` | `fn(:and, a, b)`, `fn(:or, a, b)`, `fn(:not, a)` |
 | **Math** | `abs`, `round`, `ceil`, `floor` | `fn(:abs, x)`, `fn(:round, x)`, etc. |
 | **String** | `.length`, `.upcase`, `.downcase` | `fn(:string_length, s)`, `fn(:upcase, s)`, etc. |
 | **Collection** | `.sum`, `.size`, `.max`, `.min` | `fn(:sum, arr)`, `fn(:size, arr)`, etc. |
@@ -210,29 +212,17 @@ value :formatted_name, fn(:add, fn(:add, input.first_name, " "), input.last_name
 
 ## Cascade Logic
 
-Cascade syntax is the same in both approaches, but conditions use different syntax:
-
+Cascades are similar to Ruby when case, where each case is one of more trait reference and finally the value if that branch is true.
 ```ruby
-# With Sugar
-value :grade_letter do
-  on :excellent_student, "A+"
-  on :high_scorer, "A"
-  on :above_average, "B"
-  on :needs_improvement, "C"
-  base "F"
-end
-
-# Sugar-Free  
 value :grade_letter do
-  on :excellent_student, "A+"
-  on :high_scorer, "A"
-  on :above_average, "B"
-  on :needs_improvement, "C"
+  on excellent_student, "A+"       
+  on high_scorer, "A"              
+  on above_average, "B"            
+  on needs_improvement, "C"        
   base "F"
 end
 ```
 
-The difference is in how the traits referenced in cascade conditions are defined (see Trait Declarations above).
 
 ## References
 
@@ -287,9 +277,9 @@ module StudentEvaluation
 
     # Cascade with sugar-defined traits
     value :scholarship_amount do
-      on :scholarship_candidate, 10000
-      on :high_performer, 5000
-      on :math_excellence, 2500
+      on scholarship_candidate, 10000
+      on high_performer, 5000
+      on math_excellence, 2500
       base 0
     end
   end
@@ -324,9 +314,9 @@ module StudentEvaluation
 
     # Cascade with sugar-free defined traits
     value :scholarship_amount do
-      on :scholarship_candidate, 10000
-      on :high_performer, 5000
-      on :math_excellence, 2500
+      on scholarship_candidate, 10000
+      on high_performer, 5000
+      on math_excellence, 2500
       base 0
     end
   end
@@ -351,10 +341,11 @@ end
 ## Syntax Limitations
 
 ### Sugar Syntax Limitations:
-- Only supports `&` for logical AND (no `&&` due to Ruby precedence)
-- No logical OR sugar syntax (must use `fn(:or, a, b)`)
+- Supports `&` for logical AND (no `&&` due to Ruby precedence)
+- Supports `|` for logical OR
 - Limited operator precedence control
 - Some Ruby methods not available as sugar
+- **Refinement scope**: Array methods like `.max` on syntax expressions may not work in certain contexts (e.g., test helpers, Ruby < 3.0). Use `fn(:max, array)` instead.
 
 ### Sugar-Free Advantages:
 - Full access to all registered functions

data/examples/federal_tax_calculator_2024.rb

@@ -1,28 +1,34 @@
+# frozen_string_literal: true
+
 # U.S. federal income‑tax plus FICA
 
 require_relative "../lib/kumi"
 
-module CompositeTax2024
-  extend Kumi::Schema
+module Tax2024
   FED_BREAKS_SINGLE   = [11_600, 47_150, 100_525, 191_950,
-                         243_725, 609_350, Float::INFINITY]
+                         243_725, 609_350, Float::INFINITY].freeze
 
   FED_BREAKS_MARRIED  = [23_200, 94_300, 201_050, 383_900,
-                         487_450, 731_200, Float::INFINITY]
+                         487_450, 731_200, Float::INFINITY].freeze
 
   FED_BREAKS_SEPARATE = [11_600, 47_150, 100_525, 191_950,
-                         243_725, 365_600, Float::INFINITY]
+                         243_725, 365_600, Float::INFINITY].freeze
 
   FED_BREAKS_HOH      = [16_550, 63_100, 100_500, 191_950,
-                         243_700, 609_350, Float::INFINITY]
-  
+                         243_700, 609_350, Float::INFINITY].freeze
+
   FED_RATES           = [0.10, 0.12, 0.22, 0.24,
-                         0.32, 0.35, 0.37]
+                         0.32, 0.35, 0.37].freeze
+end
+
+module FederalTaxCalculator
+  extend Kumi::Schema
+  include Tax2024
 
   schema do
     input do
       float  :income
-      string :filing_status
+      string :filing_status, domain: %(single married_joint married_separate head_of_household)
     end
 
     # ── standard deduction table ───────────────────────────────────────
@@ -32,30 +38,28 @@ module CompositeTax2024
     trait :hoh,        input.filing_status == "head_of_household"
 
     value :std_deduction do
-      on  :single,   14_600
-      on  :married,  29_200
-      on  :separate, 14_600
+      on  single,   14_600
+      on  married,  29_200
+      on  separate, 14_600
       base           21_900 # HOH default
     end
 
-    value :taxable_income,
-          fn(:max, [input.income - std_deduction, 0])
+    value :taxable_income, [input.income - std_deduction, 0].max
 
-    # ── FEDERAL brackets (single shown; others similar if needed) ──────
     value :fed_breaks do
-      on  :single,   FED_BREAKS_SINGLE
-      on  :married,  FED_BREAKS_MARRIED
-      on  :separate, FED_BREAKS_SEPARATE
-      on  :hoh,      FED_BREAKS_HOH
+      on  single,   FED_BREAKS_SINGLE
+      on  married,  FED_BREAKS_MARRIED
+      on  separate, FED_BREAKS_SEPARATE
+      on  hoh,      FED_BREAKS_HOH
     end
 
-    value :fed_rates,  FED_RATES
+    value :fed_rates, FED_RATES
     value :fed_calc,
           fn(:piecewise_sum, taxable_income, fed_breaks, fed_rates)
 
     value :fed_tax,       fed_calc[0]
     value :fed_marginal,  fed_calc[1]
-    value :fed_eff,       fed_tax / fn(:max, [input.income, 1.0])
+    value :fed_eff,       fed_tax / f[input.income, 1.0].max
 
     # ── FICA (employee share) ─────────────────────────────────────────────
     value :ss_wage_base, 168_600.0
@@ -66,39 +70,33 @@ module CompositeTax2024
 
     # additional‑Medicare threshold depends on filing status
     value :addl_threshold do
-      on  :single,   200_000
-      on  :married,  250_000
-      on  :separate, 125_000
+      on  single,   200_000
+      on  married,  250_000
+      on  separate, 125_000
       base           200_000 # HOH same as single
     end
 
     # social‑security portion (capped)
-    value :ss_tax,
-          fn(:min, [input.income, ss_wage_base]) * ss_rate
+    value :ss_tax, [input.income, ss_wage_base].min * ss_rate
 
     # medicare (1.45 % on everything)
     value :med_tax, input.income * med_base_rate
 
     # additional medicare on income above threshold
-    value :addl_med_tax,
-          fn(:max, [input.income - addl_threshold, 0]) * addl_med_rate
+    value :addl_med_tax, [input.income - addl_threshold, 0].max * addl_med_rate
 
     value :fica_tax,  ss_tax + med_tax + addl_med_tax
-    value :fica_eff,  fica_tax / fn(:max, [input.income, 1.0])
+    value :fica_eff,  fica_tax / [input.income, 1.0].max
 
     # ── Totals ─────────────────────────────────────────────────────────
-    value :total_tax,
-          fed_tax + fica_tax
+    value :total_tax, fed_tax + fica_tax
 
-    value :total_eff,   total_tax / fn(:max, [input.income, 1.0])
-    value :after_tax,   input.income - total_tax
+    value :total_eff, total_tax / fn(:max, [input.income, 1.0])
+    value :after_tax, input.income - total_tax
   end
 end
 
-def example(income: 1_000_000, status: "single")
-  # Create a runner for the schema
-  r = CompositeTax2024.from(income: income, filing_status: status)
-  # puts r.inspect
+def calculate_tax(calculator, income: 1_000_000, status: "single")
   puts "\n=== 2024 U.S. Income‑Tax Example ==="
   printf "Income:                      $%0.2f\n", income
   puts   "Filing status:               #{status}\n\n"
@@ -109,4 +107,4 @@ def example(income: 1_000_000, status: "single")
   puts "After-tax income:        $#{r[:after_tax].round(2)}"
 end
 
-example
+calculate_tax(FederalTaxCalculator, income: 1_000_000, status: "single")

data/examples/game_of_life.rb

@@ -0,0 +1,97 @@
+$LOAD_PATH.unshift(File.join(__dir__, "..", "lib"))
+require "kumi"
+
+NEIGHBOR_DELTAS = [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]]
+begin
+  # in a block so we dont define this globally
+  def neighbor_cells_sum_method(cells, row, col, height, width)
+    # Calculate neighbor indices with wraparound
+    NEIGHBOR_DELTAS.map do |dr, dc|
+      neighbor_row = (row + dr) % height
+      neighbor_col = (col + dc) % width
+      neighbor_index = (neighbor_row * width) + neighbor_col
+      cells[neighbor_index]
+    end.sum
+  end
+  Kumi::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+                                                return_type: :integer, arity: 5,
+                                                param_types: %i[array integer integer integer integer],
+                                                description: "Get neighbor cells for Conway's Game of Life")
+end
+
+module GameOfLife
+  extend Kumi::Schema
+  WIDTH = 50
+  HEIGHT = 30
+
+  schema do
+    # Complete Game of Life engine - computes entire next generation
+    input do
+      array :cells, elem: { type: :integer }
+    end
+
+    # Generate next state for every cell in the grid
+    next_cell_values = []
+
+    (0...HEIGHT).each do |row|
+      (0...WIDTH).each do |col|
+        # Neighbor count and current state for this cell
+        cell_index = (row * WIDTH) + col
+        value :"neighbor_sum_#{cell_index}", fn(:neighbor_cells_sum, input.cells, row, col, HEIGHT, WIDTH)
+
+        # Game of Life rules: (alive && neighbors == 2) || (neighbors == 3)
+        trait :"cell_#{cell_index}_alive",
+              ((input.cells[cell_index] == 1) & (ref(:"neighbor_sum_#{cell_index}") == 2)) |
+              (ref(:"neighbor_sum_#{cell_index}") == 3)
+
+        # Next state for this cell
+        value :"cell_#{cell_index}_next" do
+          on :"cell_#{cell_index}_alive", 1
+          base 0
+        end
+
+        next_cell_values << ref(:"cell_#{cell_index}_next")
+      end
+    end
+
+    # Complete next generation as array
+    value :next_cells, next_cell_values
+
+    # Render current state as visual string
+    value :cell_symbols, fn(:map_conditional, input.cells, 1, "█", " ")
+    value :grid_rows, fn(:each_slice, cell_symbols, WIDTH)
+    value :rendered_grid, fn(:map_join_rows, grid_rows, "", "\n")
+  end
+end
+
+# # Helper to pretty‑print the grid
+def render(cells, width)
+  cells.each_slice(width) do |row|
+    puts row.map { |v| v == 1 ? "█" : " " }.join
+  end
+end
+
+# # Bootstrap a simple glider on a 10×10 grid
+width  = GameOfLife::WIDTH
+height = GameOfLife::HEIGHT
+cells  = Array.new(width * height, 0)
+# Glider pattern
+[[1, 1], [2, 3], [3, 1], [3, 2], [3, 3]].each { |r, c| cells[(r * width) + c] = 1 }
+
+10_000.times do |gen|
+  system("clear") || system("cls")
+  puts "Conway's Game of Life - Generation #{gen}"
+  puts ""
+
+  # Create schema instance for this generation
+  runner = GameOfLife.from(cells: cells)
+
+  # Render using Kumi instead of Ruby function!
+  rendered_output = runner[:rendered_grid]
+  puts rendered_output
+
+  # Calculate next generation with single schema call!
+  cells = runner[:next_cells]
+
+  sleep 0.1
+end