heist 0.1.0 → 0.2.0

data/lib/parser/nodes.rb

@@ -1,6 +1,16 @@
 module Heist
+  # The +Scheme+ module hosts various classes used by the +SchemeParser+ class,
+  # which is generated from a parsing expression grammar using +Treetop+. (See
+  # <tt>lib/parser/scheme.tt</tt>.) The classes map syntax structures generated
+  # by +Treetop+ to Heist runtime objects for execution. All the classes except
+  # +Program+ are evaluated without a runtime environment; evaluating them
+  # simply casts to non-Treetop objects in the Heist library, or to raw Ruby
+  # objects. Evaluating a +Program+ requires a +Runtime+ in which to do so.
   module Scheme
     
+    # Any list-generating shorthands present in the grammar should be listed here.
+    # In Scheme, this list includes the various quoting symbols that can be used
+    # as shorthands for calling quoting functions.
     SHORTHANDS = {
       "'"   => :quote,
       "`"   => :quasiquote,
@@ -8,50 +18,63 @@ module Heist
       ",@"  => :'unquote-splicing'
     }
     
+    # +Program+ is the root of the parse tree; parsing any string of Scheme code
+    # produces one of these.
     class Program < Treetop::Runtime::SyntaxNode
+      # Evaluates all the expressions in the +Program+ in order, returning the
+      # result of the last expression.
       def eval(scope)
         convert!
         @data.map { |part| Heist.evaluate(part, scope) }.last
       end
       
+      # Converts all the +Treetop+ objects in the +Program+ to Heist objects
+      # and raw Ruby data ready for interpretation using a +Runtime+.
       def convert!
         return if @data
-        @data = []
-        elements.each_with_index { |cell, i| self[i] = cell.eval }
-      end
-      
-      def [](index)
-        @data[index]
-      end
-      
-      def []=(index, value)
-        value.exists_at!(self, index) if Runtime::Expression === value
-        @data[index] = value
+        @data = Runtime::Cons.construct(elements, true) { |c| c.eval }
       end
     end
     
+    # A +List+ has an array of +cells+, and optionally a +tail+ if it's an
+    # improper list or a dotted pair.
     module List
+      # Evaluating a +List+ produces a Heist +Cons+ object.
       def eval
-        list = Runtime::List.new
-        cells.each { |c| list << c.eval }
+        list = Runtime::Cons.construct(cells, true) { |c| c.eval }
+        list.tail.cdr = tail.cell.eval if tail.respond_to?(:dot)
         list
       end
       
       def cells
-        @cells ||= elements[1].elements
+        @cells ||= elements[1].elements[0].elements
+      end
+      
+      def tail
+        @tail ||= elements[1].elements[1]
+      end
+    end
+    
+    # <tt>QuotedCell</tt> are generated using the quoting shorthands.
+    class QuotedCell < Treetop::Runtime::SyntaxNode
+      # Evaluating a +QuotedCell+ produces a +Cons+ that expresses a function
+      # call to the appropriate quoting function, with the cell as the argument.
+      def eval
+        quote = elements[1].text_value
+        cell  = elements[2].eval
+        Runtime::Cons.construct([Runtime::Identifier.new(SHORTHANDS[quote]), cell])
       end
     end
     
+    # <tt>Cells</tt> are any piece of Scheme data: numbers, booleans, strings,
+    # lists. Any building block of Scheme code goes in a +Cell+.
     class Cell < Treetop::Runtime::SyntaxNode
       def eval
-        result = elements[3].eval
-        string = elements[1].text_value
-        SHORTHANDS.has_key?(string) ?
-            Runtime::List.new([Runtime::Identifier.new(SHORTHANDS[string]), result]) :
-            result
+        elements[1].eval
       end
     end
     
+    # A +Datum+ is any piece of atomic literal data.
     class Datum < Treetop::Runtime::SyntaxNode
       def eval
         elements[0].eval
@@ -66,25 +89,25 @@ module Heist
     
     class Complex < Treetop::Runtime::SyntaxNode
       def eval
-        # TODO
+        @value ||= Heist.complex(real.eval, imaginary.eval)
       end
     end
     
     class Real < Treetop::Runtime::SyntaxNode
       def eval
-        @value ||= Kernel.eval(text_value).to_f
+        @value ||= text_value.to_f
       end
     end
     
     class Rational < Treetop::Runtime::SyntaxNode
       def eval
-        @value ||= numerator.eval.to_f / denominator.eval
+        @value ||= Heist.rational(numerator.eval, denominator.eval)
       end
     end
     
     class Integer < Treetop::Runtime::SyntaxNode
       def eval
-        @value ||= Kernel.eval(text_value).to_i
+        @value ||= text_value.to_i
       end
     end
     
@@ -94,7 +117,7 @@ module Heist
       end
     end
     
-    class Identifier < Treetop::Runtime::SyntaxNode
+    module Identifier
       def eval
         Runtime::Identifier.new(text_value)
       end

data/lib/parser/ruby.rb

@@ -0,0 +1,29 @@
+module Heist
+  # +RubyParser+ parses non-string code given as Ruby data such as arrays. It
+  # allows Lisp-style code to be expressed inline with Ruby, for example:
+  #
+  #   scheme = Heist::Runtime.new
+  #   scheme.exec [:define, [:square, :x], [:*, :x, :x]]
+  #   scheme.exec [:square, 9]
+  #   #=> 81
+  #
+  # The above API uses +RubyParser+ behind the scenes to turn Ruby data into
+  # Heist runtime objects such as +Cons+ based lists before execution.
+  #
+  class RubyParser
+    
+    # Parses a single piece of Ruby data in
+    def parse(source)
+      case source
+        when Array then
+          Runtime::Cons.construct(source) { |cell| parse(cell) }
+        when Symbol then
+          Runtime::Identifier.new(source)
+        else
+          source
+      end
+    end
+    
+  end
+end
+

data/lib/parser/scheme.rb

@@ -1,5 +1,5 @@
 module Heist
-  module Scheme
+  module Scheme #:nodoc:
     include Treetop::Runtime
 
     def root
@@ -30,17 +30,27 @@ module Heist
       return r0
     end
 
-    module Cell0
+    module Cell0 #:nodoc:
       def ignore
         elements[0]
       end
 
-      def ignore
+      def quote
+        elements[1]
+      end
+
+      def cell
         elements[2]
       end
+    end
 
+    module Cell1 #:nodoc:
       def ignore
-        elements[4]
+        elements[0]
+      end
+
+      def ignore
+        elements[2]
       end
     end
 
@@ -52,48 +62,64 @@ module Heist
         return cached
       end
 
-      i0, s0 = index, []
-      r1 = _nt_ignore
-      s0 << r1
-      if r1
+      i0 = index
+      i1, s1 = index, []
+      r2 = _nt_ignore
+      s1 << r2
+      if r2
         r3 = _nt_quote
+        s1 << r3
         if r3
-          r2 = r3
-        else
-          r2 = SyntaxNode.new(input, index...index)
+          r4 = _nt_cell
+          s1 << r4
         end
-        s0 << r2
-        if r2
-          r4 = _nt_ignore
-          s0 << r4
-          if r4
-            i5 = index
-            r6 = _nt_list
-            if r6
-              r5 = r6
+      end
+      if s1.last
+        r1 = (QuotedCell).new(input, i1...index, s1)
+        r1.extend(Cell0)
+      else
+        self.index = i1
+        r1 = nil
+      end
+      if r1
+        r0 = r1
+      else
+        i5, s5 = index, []
+        r6 = _nt_ignore
+        s5 << r6
+        if r6
+          i7 = index
+          r8 = _nt_list
+          if r8
+            r7 = r8
+          else
+            r9 = _nt_atom
+            if r9
+              r7 = r9
             else
-              r7 = _nt_atom
-              if r7
-                r5 = r7
-              else
-                self.index = i5
-                r5 = nil
-              end
-            end
-            s0 << r5
-            if r5
-              r8 = _nt_ignore
-              s0 << r8
+              self.index = i7
+              r7 = nil
             end
           end
+          s5 << r7
+          if r7
+            r10 = _nt_ignore
+            s5 << r10
+          end
+        end
+        if s5.last
+          r5 = (Cell).new(input, i5...index, s5)
+          r5.extend(Cell1)
+        else
+          self.index = i5
+          r5 = nil
+        end
+        if r5
+          r0 = r5
+        else
+          self.index = i0
+          r0 = nil
         end
-      end
-      if s0.last
-        r0 = (Cell).new(input, i0...index, s0)
-        r0.extend(Cell0)
-      else
-        self.index = i0
-        r0 = nil
       end
 
       node_cache[:cell][start_index] = r0
@@ -162,10 +188,39 @@ module Heist
       return r0
     end
 
-    module List0
+    def _nt_dot
+      start_index = index
+      if node_cache[:dot].has_key?(index)
+        cached = node_cache[:dot][index]
+        @index = cached.interval.end if cached
+        return cached
+      end
+
+      if input.index(".", index) == index
+        r0 = (SyntaxNode).new(input, index...(index + 1))
+        @index += 1
+      else
+        terminal_parse_failure(".")
+        r0 = nil
+      end
+
+      node_cache[:dot][start_index] = r0
+
+      return r0
     end
 
-    module List1
+    module List0 #:nodoc:
+      def cells
+        elements[1]
+      end
+
+    end
+
+    module List1 #:nodoc:
+      def cells
+        elements[1]
+      end
+
     end
 
     def _nt_list
@@ -187,26 +242,17 @@ module Heist
       end
       s1 << r2
       if r2
-        s3, i3 = [], index
-        loop do
-          r4 = _nt_cell
-          if r4
-            s3 << r4
-          else
-            break
-          end
-        end
-        r3 = SyntaxNode.new(input, i3...index, s3)
+        r3 = _nt_cells
         s1 << r3
         if r3
           if input.index(")", index) == index
-            r5 = (SyntaxNode).new(input, index...(index + 1))
+            r4 = (SyntaxNode).new(input, index...(index + 1))
             @index += 1
           else
             terminal_parse_failure(")")
-            r5 = nil
+            r4 = nil
           end
-          s1 << r5
+          s1 << r4
         end
       end
       if s1.last
@@ -220,47 +266,38 @@ module Heist
         r0 = r1
         r0.extend(List)
       else
-        i6, s6 = index, []
+        i5, s5 = index, []
         if input.index("[", index) == index
-          r7 = (SyntaxNode).new(input, index...(index + 1))
+          r6 = (SyntaxNode).new(input, index...(index + 1))
           @index += 1
         else
           terminal_parse_failure("[")
-          r7 = nil
+          r6 = nil
         end
-        s6 << r7
-        if r7
-          s8, i8 = [], index
-          loop do
-            r9 = _nt_cell
-            if r9
-              s8 << r9
-            else
-              break
-            end
-          end
-          r8 = SyntaxNode.new(input, i8...index, s8)
-          s6 << r8
-          if r8
+        s5 << r6
+        if r6
+          r7 = _nt_cells
+          s5 << r7
+          if r7
             if input.index("]", index) == index
-              r10 = (SyntaxNode).new(input, index...(index + 1))
+              r8 = (SyntaxNode).new(input, index...(index + 1))
               @index += 1
             else
               terminal_parse_failure("]")
-              r10 = nil
+              r8 = nil
             end
-            s6 << r10
+            s5 << r8
           end
         end
-        if s6.last
-          r6 = (SyntaxNode).new(input, i6...index, s6)
-          r6.extend(List1)
+        if s5.last
+          r5 = (SyntaxNode).new(input, i5...index, s5)
+          r5.extend(List1)
         else
-          self.index = i6
-          r6 = nil
+          self.index = i5
+          r5 = nil
         end
-        if r6
-          r0 = r6
+        if r5
+          r0 = r5
           r0.extend(List)
         else
           self.index = i0
@@ -273,6 +310,122 @@ module Heist
       return r0
     end
 
+    module Cells0 #:nodoc:
+      def dot
+        elements[0]
+      end
+
+      def space
+        elements[1]
+      end
+
+      def cell
+        elements[2]
+      end
+    end
+
+    module Cells1 #:nodoc:
+    end
+
+    module Cells2 #:nodoc:
+      def ignore
+        elements[1]
+      end
+    end
+
+    def _nt_cells
+      start_index = index
+      if node_cache[:cells].has_key?(index)
+        cached = node_cache[:cells][index]
+        @index = cached.interval.end if cached
+        return cached
+      end
+
+      i0 = index
+      i1, s1 = index, []
+      s2, i2 = [], index
+      loop do
+        r3 = _nt_cell
+        if r3
+          s2 << r3
+        else
+          break
+        end
+      end
+      if s2.empty?
+        self.index = i2
+        r2 = nil
+      else
+        r2 = SyntaxNode.new(input, i2...index, s2)
+      end
+      s1 << r2
+      if r2
+        i4, s4 = index, []
+        r5 = _nt_dot
+        s4 << r5
+        if r5
+          r6 = _nt_space
+          s4 << r6
+          if r6
+            r7 = _nt_cell
+            s4 << r7
+          end
+        end
+        if s4.last
+          r4 = (SyntaxNode).new(input, i4...index, s4)
+          r4.extend(Cells0)
+        else
+          self.index = i4
+          r4 = nil
+        end
+        s1 << r4
+      end
+      if s1.last
+        r1 = (SyntaxNode).new(input, i1...index, s1)
+        r1.extend(Cells1)
+      else
+        self.index = i1
+        r1 = nil
+      end
+      if r1
+        r0 = r1
+      else
+        i8, s8 = index, []
+        s9, i9 = [], index
+        loop do
+          r10 = _nt_cell
+          if r10
+            s9 << r10
+          else
+            break
+          end
+        end
+        r9 = SyntaxNode.new(input, i9...index, s9)
+        s8 << r9
+        if r9
+          r11 = _nt_ignore
+          s8 << r11
+        end
+        if s8.last
+          r8 = (SyntaxNode).new(input, i8...index, s8)
+          r8.extend(Cells2)
+        else
+          self.index = i8
+          r8 = nil
+        end
+        if r8
+          r0 = r8
+        else
+          self.index = i0
+          r0 = nil
+        end
+      end
+
+      node_cache[:cells][start_index] = r0
+
+      return r0
+    end
+
     def _nt_atom
       start_index = index
       if node_cache[:atom].has_key?(index)
@@ -300,10 +453,10 @@ module Heist
       return r0
     end
 
-    module Datum0
+    module Datum0 #:nodoc:
     end
 
-    module Datum1
+    module Datum1 #:nodoc:
     end
 
     def _nt_datum
@@ -462,12 +615,12 @@ module Heist
       return r0
     end
 
-    module Complex0
+    module Complex0 #:nodoc:
       def real
         elements[0]
       end
 
-      def real
+      def imaginary
         elements[2]
       end
 
@@ -482,29 +635,53 @@ module Heist
       end
 
       i0, s0 = index, []
-      r1 = _nt_real
+      i1 = index
+      r2 = _nt_real
+      if r2
+        r1 = r2
+      else
+        r3 = _nt_integer
+        if r3
+          r1 = r3
+        else
+          self.index = i1
+          r1 = nil
+        end
+      end
       s0 << r1
       if r1
         if input.index("+", index) == index
-          r2 = (SyntaxNode).new(input, index...(index + 1))
+          r4 = (SyntaxNode).new(input, index...(index + 1))
           @index += 1
         else
           terminal_parse_failure("+")
-          r2 = nil
+          r4 = nil
         end
-        s0 << r2
-        if r2
-          r3 = _nt_real
-          s0 << r3
-          if r3
+        s0 << r4
+        if r4
+          i5 = index
+          r6 = _nt_real
+          if r6
+            r5 = r6
+          else
+            r7 = _nt_integer
+            if r7
+              r5 = r7
+            else
+              self.index = i5
+              r5 = nil
+            end
+          end
+          s0 << r5
+          if r5
             if input.index("i", index) == index
-              r4 = (SyntaxNode).new(input, index...(index + 1))
+              r8 = (SyntaxNode).new(input, index...(index + 1))
               @index += 1
             else
               terminal_parse_failure("i")
-              r4 = nil
+              r8 = nil
             end
-            s0 << r4
+            s0 << r8
           end
         end
       end
@@ -521,10 +698,10 @@ module Heist
       return r0
     end
 
-    module Real0
+    module Real0 #:nodoc:
     end
 
-    module Real1
+    module Real1 #:nodoc:
       def integer
         elements[0]
       end
@@ -592,7 +769,7 @@ module Heist
       return r0
     end
 
-    module Rational0
+    module Rational0 #:nodoc:
       def numerator
         elements[0]
       end
@@ -640,10 +817,10 @@ module Heist
       return r0
     end
 
-    module Integer0
+    module Integer0 #:nodoc:
     end
 
-    module Integer1
+    module Integer1 #:nodoc:
     end
 
     def _nt_integer
@@ -730,7 +907,7 @@ module Heist
       return r0
     end
 
-    module String0
+    module String0 #:nodoc:
     end
 
     def _nt_string
@@ -809,7 +986,16 @@ module Heist
       return r0
     end
 
-    module Identifier0
+    module Identifier0 #:nodoc:
+    end
+
+    module Identifier1 #:nodoc:
+    end
+
+    module Identifier2 #:nodoc:
+    end
+
+    module Identifier3 #:nodoc:
     end
 
     def _nt_identifier
@@ -820,47 +1006,126 @@ module Heist
         return cached
       end
 
-      s0, i0 = [], index
-      loop do
-        i1, s1 = index, []
-        i2 = index
-        r3 = _nt_delimiter
-        if r3
-          r2 = nil
+      i0 = index
+      i1, s1 = index, []
+      i2, s2 = index, []
+      i3 = index
+      r4 = _nt_delimiter
+      if r4
+        r3 = nil
+      else
+        self.index = i3
+        r3 = SyntaxNode.new(input, index...index)
+      end
+      s2 << r3
+      if r3
+        if index < input_length
+          r5 = (SyntaxNode).new(input, index...(index + 1))
+          @index += 1
         else
-          self.index = i2
-          r2 = SyntaxNode.new(input, index...index)
+          terminal_parse_failure("any character")
+          r5 = nil
         end
-        s1 << r2
-        if r2
+        s2 << r5
+      end
+      if s2.last
+        r2 = (SyntaxNode).new(input, i2...index, s2)
+        r2.extend(Identifier0)
+      else
+        self.index = i2
+        r2 = nil
+      end
+      s1 << r2
+      if r2
+        s6, i6 = [], index
+        loop do
+          i7, s7 = index, []
+          i8 = index
+          r9 = _nt_delimiter
+          if r9
+            r8 = nil
+          else
+            self.index = i8
+            r8 = SyntaxNode.new(input, index...index)
+          end
+          s7 << r8
+          if r8
+            if index < input_length
+              r10 = (SyntaxNode).new(input, index...(index + 1))
+              @index += 1
+            else
+              terminal_parse_failure("any character")
+              r10 = nil
+            end
+            s7 << r10
+          end
+          if s7.last
+            r7 = (SyntaxNode).new(input, i7...index, s7)
+            r7.extend(Identifier1)
+          else
+            self.index = i7
+            r7 = nil
+          end
+          if r7
+            s6 << r7
+          else
+            break
+          end
+        end
+        if s6.empty?
+          self.index = i6
+          r6 = nil
+        else
+          r6 = SyntaxNode.new(input, i6...index, s6)
+        end
+        s1 << r6
+      end
+      if s1.last
+        r1 = (SyntaxNode).new(input, i1...index, s1)
+        r1.extend(Identifier2)
+      else
+        self.index = i1
+        r1 = nil
+      end
+      if r1
+        r0 = r1
+        r0.extend(Identifier)
+      else
+        i11, s11 = index, []
+        i12 = index
+        r13 = _nt_reserved
+        if r13
+          r12 = nil
+        else
+          self.index = i12
+          r12 = SyntaxNode.new(input, index...index)
+        end
+        s11 << r12
+        if r12
           if index < input_length
-            r4 = (SyntaxNode).new(input, index...(index + 1))
+            r14 = (SyntaxNode).new(input, index...(index + 1))
             @index += 1
           else
             terminal_parse_failure("any character")
-            r4 = nil
+            r14 = nil
           end
-          s1 << r4
+          s11 << r14
         end
-        if s1.last
-          r1 = (SyntaxNode).new(input, i1...index, s1)
-          r1.extend(Identifier0)
+        if s11.last
+          r11 = (SyntaxNode).new(input, i11...index, s11)
+          r11.extend(Identifier3)
         else
-          self.index = i1
-          r1 = nil
+          self.index = i11
+          r11 = nil
         end
-        if r1
-          s0 << r1
+        if r11
+          r0 = r11
+          r0.extend(Identifier)
         else
-          break
+          self.index = i0
+          r0 = nil
         end
       end
-      if s0.empty?
-        self.index = i0
-        r0 = nil
-      else
-        r0 = Identifier.new(input, i0...index, s0)
-      end
 
       node_cache[:identifier][start_index] = r0
 
@@ -887,6 +1152,33 @@ module Heist
       return r0
     end
 
+    def _nt_reserved
+      start_index = index
+      if node_cache[:reserved].has_key?(index)
+        cached = node_cache[:reserved][index]
+        @index = cached.interval.end if cached
+        return cached
+      end
+
+      i0 = index
+      r1 = _nt_dot
+      if r1
+        r0 = r1
+      else
+        r2 = _nt_delimiter
+        if r2
+          r0 = r2
+        else
+          self.index = i0
+          r0 = nil
+        end
+      end
+
+      node_cache[:reserved][start_index] = r0
+
+      return r0
+    end
+
     def _nt_delimiter
       start_index = index
       if node_cache[:delimiter].has_key?(index)
@@ -896,21 +1188,21 @@ module Heist
       end
 
       i0 = index
-      if input.index(Regexp.new('[\\(\\)\\[\\]]'), index) == index
-        r1 = (SyntaxNode).new(input, index...(index + 1))
-        @index += 1
-      else
-        r1 = nil
-      end
+      r1 = _nt_quote
       if r1
         r0 = r1
       else
-        r2 = _nt_space
+        r2 = _nt_paren
         if r2
           r0 = r2
         else
-          self.index = i0
-          r0 = nil
+          r3 = _nt_space
+          if r3
+            r0 = r3
+          else
+            self.index = i0
+            r0 = nil
+          end
         end
       end
 
@@ -919,6 +1211,26 @@ module Heist
       return r0
     end
 
+    def _nt_paren
+      start_index = index
+      if node_cache[:paren].has_key?(index)
+        cached = node_cache[:paren][index]
+        @index = cached.interval.end if cached
+        return cached
+      end
+
+      if input.index(Regexp.new('[\\(\\)\\[\\]]'), index) == index
+        r0 = (SyntaxNode).new(input, index...(index + 1))
+        @index += 1
+      else
+        r0 = nil
+      end
+
+      node_cache[:paren][start_index] = r0
+
+      return r0
+    end
+
     def _nt_space
       start_index = index
       if node_cache[:space].has_key?(index)
@@ -939,7 +1251,7 @@ module Heist
       return r0
     end
 
-    module Ignore0
+    module Ignore0 #:nodoc:
     end
 
     def _nt_ignore
@@ -984,10 +1296,10 @@ module Heist
       return r0
     end
 
-    module Comment0
+    module Comment0 #:nodoc:
     end
 
-    module Comment1
+    module Comment1 #:nodoc:
       def ignore
         elements[2]
       end