kumi 0.0.8 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 652ef5f59f7c4469c86ecda4add1f650121d75d333231ae50306a7bf2ce7725c
-  data.tar.gz: 367a335e09a9d5cefaecbfa8e870c99ac49153a771f2451e3cfa8f73531d0701
+  metadata.gz: c5f9f087001a482c906f041da8cb229511966a11c56e3ced99930b59d4141543
+  data.tar.gz: fe5fafe03a5ca1e414b5bc3af9eccd830553aa8f44762e9d9b38e589fa342fd1
 SHA512:
-  metadata.gz: 2dece8cc4284177c7f45a97768ea0c228cf41210d85cff985850a5e98f64c4ce02cc2c97cc2a20897d1f192422390ad39357b0d883e4e6aebbae1d0abc41cfe8
-  data.tar.gz: cb817018fab35b9594053d5bbd7fa4adb31c79a92d7e968a2739f9ffd16d194a3a45aeb75b6fcc28743fadcd93da83c9227cfe81d14bb2f9d917c18e1fb5d16b
+  metadata.gz: b26279c08a9387616104252d24147c920f27b0f66574cde1987024325c5fd1ba87aff876b39fdc3d4f472d9aba2c713b19a5105890b66ac3ef10a3018a0b1bca
+  data.tar.gz: d4c8db755880cd7088fd4b6087d2f38e86a4fdee11f867d58a480e143494ca2b85440abd9249b8c02a469a9ad21642c287d5ef8f30948bdc6d67695a895c1c13

data/README.md

@@ -325,6 +325,19 @@ Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_st
 #    = 15,099.50
 ```
 
+**Debug AST Structure**: Visualize the parsed schema as S-expressions:
+
+```ruby
+puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
+# => (Root
+#      inputs: [
+#        (InputDeclaration :income :float)
+#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
+#      ]
+#      traits: [...]
+#      attributes: [...])
+```
+
 </details>
 
 <details>

data/docs/AST.md

@@ -39,6 +39,13 @@ InputReference = Struct.new(:name)
 # Has operator methods: >=, <=, >, <, ==, != that create CallExpression nodes
 ```
 
+**InputElementReference**: Access of nested input fields (`input.field_name.element.subelement.subsubelement`)
+```ruby
+InputElementReference = Struct.new(:path)
+# Represents nested input access
+# DSL: input.address.street → InputElementReference([:address, :street])
+```
+
 **DeclarationReference**: References to other declarations
 ```ruby
 DeclarationReference = Struct.new(:name)

data/docs/features/README.md

@@ -37,6 +37,13 @@ Processes large schemas with optimized algorithms.
 - Result caching
 - Selective evaluation
 
+### [S-Expression Printer](s-expression-printer.md)
+Debug and inspect AST structures with readable S-expression notation output.
+
+- Visitor pattern implementation for all node types
+- Proper indentation and hierarchical structure
+- Useful for debugging schema parsing and AST analysis
+
 ## Integration
 
 - Type inference uses input declarations

data/docs/features/s-expression-printer.md

@@ -0,0 +1,77 @@
+# S-Expression Printer
+
+Debug and inspect Kumi AST structures with readable S-expression notation output.
+
+## Overview
+
+The S-Expression Printer provides a clean, structured way to visualize Kumi's Abstract Syntax Tree (AST) nodes in traditional Lisp-style S-expression format. This is particularly useful for debugging schema parsing, understanding AST structure, and analyzing complex expressions.
+
+## Usage
+
+```ruby
+require 'kumi/support/s_expression_printer'
+
+# Print any AST node
+Kumi::Support::SExpressionPrinter.print(node)
+
+# Print a complete schema AST
+module MySchema
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      integer :age
+      string :name
+    end
+    
+    trait :adult, (input.age >= 18)
+    value :greeting, fn(:concat, "Hello ", input.name)
+  end
+end
+
+puts Kumi::Support::SExpressionPrinter.print(MySchema.__syntax_tree__)
+```
+
+## Output Format
+
+The printer produces indented S-expressions that clearly show the hierarchical structure:
+
+```lisp
+(Root
+  inputs: [
+    (InputDeclaration :age :integer)
+    (InputDeclaration :name :string)
+  ]
+  attributes: [
+    (ValueDeclaration :greeting
+      (CallExpression :concat
+        (Literal "Hello ")
+        (InputReference :name)
+      )
+    )
+  ]
+  traits: [
+    (TraitDeclaration :adult
+      (CallExpression :>=
+        (InputReference :age)
+        (Literal 18)
+      )
+    )
+  ]
+)
+```
+
+## Supported Node Types
+
+The printer handles all Kumi AST node types:
+
+- **Root** - Schema container with inputs, attributes, and traits
+- **Declarations** - InputDeclaration, ValueDeclaration, TraitDeclaration
+- **Expressions** - CallExpression, ArrayExpression, CascadeExpression, CaseExpression
+- **References** - InputReference, InputElementReference, DeclarationReference
+- **Literals** - Literal values (strings, numbers, booleans)
+- **Collections** - Arrays and HashExpression nodes
+
+## Implementation
+
+Built as a visitor pattern class that traverses AST nodes recursively, with each node type having its own specialized formatting method. The printer preserves proper indentation and handles nested structures gracefully.

data/lib/kumi/support/s_expression_printer.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Support
+    class SExpressionPrinter
+      def initialize(indent: 0)
+        @indent = indent
+      end
+
+      def visit(node)
+        return node.inspect unless node.respond_to?(:class)
+        
+        case node
+        when nil then "nil"
+        when Array then visit_array(node)
+        when Kumi::Syntax::Root then visit_root(node)
+        when Kumi::Syntax::ValueDeclaration then visit_value_declaration(node)
+        when Kumi::Syntax::TraitDeclaration then visit_trait_declaration(node)
+        when Kumi::Syntax::InputDeclaration then visit_input_declaration(node)
+        when Kumi::Syntax::CallExpression then visit_call_expression(node)
+        when Kumi::Syntax::ArrayExpression then visit_array_expression(node)
+        when Kumi::Syntax::CascadeExpression then visit_cascade_expression(node)
+        when Kumi::Syntax::CaseExpression then visit_case_expression(node)
+        when Kumi::Syntax::InputReference then visit_input_reference(node)
+        when Kumi::Syntax::InputElementReference then visit_input_element_reference(node)
+        when Kumi::Syntax::DeclarationReference then visit_declaration_reference(node)
+        when Kumi::Syntax::Literal then visit_literal(node)
+        when Kumi::Syntax::HashExpression then visit_hash_expression(node)
+        else visit_generic(node)
+        end
+      end
+
+      def self.print(node, indent: 0)
+        new(indent: indent).visit(node)
+      end
+
+      private
+
+      def visit_array(node)
+        return "[]" if node.empty?
+        
+        elements = node.map { |child| child_printer.visit(child) }
+        "[\n#{indent_str(2)}#{elements.join("\n#{indent_str(2)}")}\n#{indent_str}]"
+      end
+
+      def visit_root(node)
+        fields = %i[inputs attributes traits].map do |field|
+          value = node.public_send(field)
+          "#{field}: #{child_printer.visit(value)}"
+        end.join("\n#{indent_str(2)}")
+        
+        "(Root\n#{indent_str(2)}#{fields}\n#{indent_str})"
+      end
+
+      def visit_value_declaration(node)
+        "(ValueDeclaration :#{node.name}\n#{child_indent}#{child_printer.visit(node.expression)}\n#{indent_str})"
+      end
+
+      def visit_trait_declaration(node)
+        "(TraitDeclaration :#{node.name}\n#{child_indent}#{child_printer.visit(node.expression)}\n#{indent_str})"
+      end
+
+      def visit_input_declaration(node)
+        fields = [":#{node.name}"]
+        fields << ":#{node.type}" if node.respond_to?(:type) && node.type
+        fields << "domain: #{node.domain.inspect}" if node.respond_to?(:domain) && node.domain
+        
+        if node.respond_to?(:children) && !node.children.empty?
+          children_str = child_printer.visit(node.children)
+          "(InputDeclaration #{fields.join(' ')}\n#{child_indent}#{children_str}\n#{indent_str})"
+        else
+          "(InputDeclaration #{fields.join(' ')})"
+        end
+      end
+
+      def visit_call_expression(node)
+        return "(CallExpression :#{node.fn_name})" if node.args.empty?
+        
+        args = node.args.map { |arg| child_printer.visit(arg) }
+        "(CallExpression :#{node.fn_name}\n#{indent_str(2)}#{args.join("\n#{indent_str(2)}")}\n#{indent_str})"
+      end
+
+      def visit_array_expression(node)
+        return "(ArrayExpression)" if node.elements.empty?
+        
+        elements = node.elements.map { |elem| child_printer.visit(elem) }
+        "(ArrayExpression\n#{indent_str(2)}#{elements.join("\n#{indent_str(2)}")}\n#{indent_str})"
+      end
+
+      def visit_cascade_expression(node)
+        cases = node.cases.map do |case_expr|
+          "(#{visit(case_expr.condition)} #{visit(case_expr.result)})"
+        end.join("\n#{indent_str(2)}")
+        
+        "(CascadeExpression\n#{indent_str(2)}#{cases}\n#{indent_str})"
+      end
+
+      def visit_case_expression(node)
+        "(CaseExpression #{visit(node.condition)} #{visit(node.result)})"
+      end
+
+      def visit_input_reference(node)
+        "(InputReference :#{node.name})"
+      end
+
+      def visit_input_element_reference(node)
+        "(InputElementReference #{node.path.map(&:to_s).join('.')})"
+      end
+
+      def visit_declaration_reference(node)
+        "(DeclarationReference :#{node.name})"
+      end
+
+      def visit_literal(node)
+        "(Literal #{node.value.inspect})"
+      end
+
+      def visit_hash_expression(node)
+        return "(HashExpression)" if node.pairs.empty?
+        
+        pairs = node.pairs.map do |pair|
+          "(#{visit(pair.key)} #{visit(pair.value)})"
+        end.join("\n#{indent_str(2)}")
+        
+        "(HashExpression\n#{indent_str(2)}#{pairs}\n#{indent_str})"
+      end
+
+      def visit_generic(node)
+        class_name = node.class.name&.split('::')&.last || node.class.to_s
+        
+        if node.respond_to?(:children) && !node.children.empty?
+          children = node.children.map { |child| child_printer.visit(child) }
+          "(#{class_name}\n#{indent_str(2)}#{children.join("\n#{indent_str(2)}")}\n#{indent_str})"
+        elsif node.respond_to?(:members)
+          fields = node.members.reject { |m| m == :loc }.map do |member|
+            value = node[member]
+            "#{member}: #{child_printer.visit(value)}"
+          end
+          
+          return "(#{class_name})" if fields.empty?
+          
+          "(#{class_name}\n#{indent_str(2)}#{fields.join("\n#{indent_str(2)}")}\n#{indent_str})"
+        else
+          "(#{class_name} #{node.inspect})"
+        end
+      end
+
+      def child_printer
+        @child_printer ||= self.class.new(indent: @indent + 2)
+      end
+
+      def indent_str(extra = 0)
+        ' ' * (@indent + extra)
+      end
+
+      def child_indent
+        indent_str(2)
+      end
+    end
+  end
+end

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kumi
 version: !ruby/object:Gem::Version
-  version: 0.0.8
+  version: 0.0.9
 platform: ruby
 authors:
 - André Muta
@@ -48,6 +48,7 @@ files:
 - docs/features/array-broadcasting.md
 - docs/features/input-declaration-system.md
 - docs/features/performance.md
+- docs/features/s-expression-printer.md
 - docs/schema_metadata.md
 - docs/schema_metadata/broadcasts.md
 - docs/schema_metadata/cascades.md
@@ -143,6 +144,7 @@ files:
 - lib/kumi/registry.rb
 - lib/kumi/schema.rb
 - lib/kumi/schema_metadata.rb
+- lib/kumi/support/s_expression_printer.rb
 - lib/kumi/syntax/array_expression.rb
 - lib/kumi/syntax/call_expression.rb
 - lib/kumi/syntax/cascade_expression.rb