heist 0.1.0 → 0.2.0

data/lib/runtime/callable/syntax.rb

@@ -0,0 +1,44 @@
+module Heist
+  class Runtime
+    
+    # The +Syntax+ class is used to model built-in special forms. +Syntax+
+    # functions are universally implemented in Ruby; user-defined special
+    # forms are represented using +Macro+. +Syntax+ is very simple: its
+    # body is a Ruby block that accepts a +Scope+ and a +Cons+ list of
+    # the expression following the special form, and the +Syntax+ class
+    # does not automatically evaluate any parameters. It is up to the
+    # Ruby code implementing the syntax to decide what to evaluate. For
+    # example, here's a couple of implementations for Scheme's <tt>(if)</tt>
+    # and <tt>(set!)</tt>.
+    #
+    #   env = Scope.new
+    #
+    #   # e.g. (set! x (+ 9 4))
+    #   env['set!'] = Syntax.new(env) do |scope, cells|
+    #     value = Heist.evaluate(cells.cdr.car, scope)
+    #     scope.set!(cells.car, value)
+    #   end
+    #
+    #   # e.g. (if (> 6 3) 'yes 'no)
+    #   env['if'] = Syntax.new(env) do |scope, cells|
+    #     which = Heist.evaluate(cells.car, scope) ? cells.cdr : cells.cdr.cdr
+    #     Heist.evaluate(which.car, scope)
+    #   end
+    #
+    class Syntax < Function
+
+      # Calls the Ruby implementation of the +Syntax+ and returns the result.
+      def call(scope, cells)
+        @body.call(scope, cells)
+      end
+      
+      # Returns a string placeholder for the +Syntax+, containing its
+      # name if it has one.
+      def to_s
+        "#<syntax:#{ @name }>"
+      end
+    end
+    
+  end
+end
+

data/lib/runtime/data/cons.rb

@@ -0,0 +1,234 @@
+module Heist
+  class Runtime
+    
+    # +Cons+ is the basic data structure element in Scheme. A +Cons+ is an
+    # object with two pointers to other objects, the pointers being called
+    # the +car+ and the +cdr+. You can typically think of this type of
+    # object as representing a pair of values, though not all +Cons+ objects
+    # are pairs according to the <tt>(pair?)</tt> procedure; specifically
+    # +NULL+ is not considered a pair.
+    #
+    # +Cons+ objects can be joined together to form lists; a list is either
+    # the empty list or a +Cons+ whose +cdr+ is a list. That is, a list is
+    # chain of +Cons+ pairs joined by their +cdr+ fields, whose +car+ fields
+    # hold the elements of the list. A list is considered 'proper' if its
+    # final +Cons+ is +NULL+, and improper otherwise. Some examples:
+    #
+    #   Proper list: (1 2 3)    Improper list: (1 2 3 . 4)
+    #
+    #         #                         #                    # = cons
+    #        / \\                      / \\                  / = car
+    #       1   #                     1   #                 \\ = cdr
+    #          / \\                      / \\               () = NULL
+    #         2   #                     2   #
+    #            / \\                      / \\
+    #           3   ()                    3   4
+    #
+    # +Cons+ objects are +Enumerable+, though always keep in mind that a
+    # +Cons+ does not 'contain' a whole list, it contains one value and a
+    # pointer to the rest of the list. Iterating on a +Cons+ involves
+    # walking this object graph.
+
+    class Cons
+      include Enumerable
+      include Expression
+      
+      attr_accessor :car, :cdr
+      
+      # +NULL+ is a special +Cons+ instance representing the empty list, which
+      # is used as a nil value in Scheme. The empty list is a singleton: there
+      # is only ever one empty list in memory, and the Scheme expressions
+      # <tt>'()</tt> and <tt>(list)</tt> always return the same object. +NULL+
+      # is frozen, and its +car+ and +cdr+ are pointers back to itself.
+      NULL = self.new
+      NULL.car = NULL.cdr = NULL
+
+      # +NULL+ is only equal to itself.
+      def NULL.==(other); equal?(other); end
+      NULL.freeze
+      
+      cadr_combos = (1..4).map { |n|
+        (0...(2**n)).map do |x|
+          'c' + ("%0#{n}d" % x.to_s(2)).gsub('0', 'a').gsub('1', 'd') + 'r'
+        end
+      }.flatten
+      
+      # An array of all the c[ad]+r functions supported by Heist
+      ACCESSORS = cadr_combos
+      
+      class << self
+        # Creates a new list from the elements of the enumerable object +enum+,
+        # and returns the +Cons+ that forms the head of the list. If +enum+ is
+        # empty, +NULL+ is returned. +construct+ optionally takes a block that
+        # can be used to transform each value as the list is constructed:
+        #
+        #   Cons.construct([1,2,3,4]) { |x| x*x }
+        #   #=> (1 4 9 16)
+        #
+        # The method also takes an optional second parameter +linking+, which,
+        # if set to true, makes each +car+ element aware of the +Cons+ that
+        # holds it. This is used when inlining macro expansions, where
+        # expressions need to replace themselves in their parent expression.
+        #
+        # Note that this method copies improper lists correctly, though
+        # iteration over a +Cons+ list does not include the tail value.
+        #
+        def construct(enum, linking = false, &block)
+          return NULL if enum.nil?
+          root, last = nil, nil
+          enum.each do |value|
+            value = block.call(value) if block_given?
+            pair = self.new(value)
+            pair.hosts(value) if linking
+            root ||= pair
+            last.cdr = pair if last
+            last = pair.tail
+          end
+          last.cdr = enum.tail.cdr if last and Cons === enum
+          root || NULL
+        end
+        alias :[] :construct
+      end
+      
+      # A +Cons+ is initialized using a +car+ and a +cdr+ value.
+      def initialize(car = nil, cdr = nil)
+        self.car = car
+        self.cdr = cdr
+      end
+      
+      ACCESSORS[2..-1].each do |accsr|
+        class_eval <<-EOS
+          def #{ accsr }
+            #{ accsr.scan(/[ad]/).reverse.map { |s| "c#{s}r" } * '.' }
+          end
+        EOS
+      end
+      
+      # Sets the +car+ of the receiving +Cons+, unless it is frozen. If the
+      # given value is +nil+, +NULL+ is used instead.
+      def car=(car)
+        raise ImmutableError.new("Cannot modify constant value") if frozen?
+        @car = car.nil? ? NULL : car
+      end
+      
+      # Sets the +cdr+ of the receiving +Cons+, unless it is frozen. If the
+      # given value is +nil+, +NULL+ is used instead.
+      def cdr=(cdr)
+        raise ImmutableError.new("Cannot modify constant value") if frozen?
+        @cdr = cdr.nil? ? NULL : cdr
+      end
+      
+      # Recursively freezes the +Cons+ and any conses it points to. This is
+      # used to prevent quoted list constants from being modified since they
+      # are part of the parse tree: quoting a list does not allocate a new
+      # object so changing a quoted list would have undesirable side effects
+      # on any other references to the list.
+      def freeze!
+        return if null?
+        [@car, @cdr].each { |slot| slot.freeze! if slot.respond_to?(:freeze!) }
+        freeze
+      end
+      
+      # Sets the parent pair of +value+ to the receiver. Some +car+ values
+      # need a reference back to their containing +Cons+ for concerns such
+      # as macro expansion inlining.
+      def hosts(value)
+        value.parent = self if Expression === value and value != NULL
+      end
+      
+      # Creates and returns a copy of the +Cons+ list, taking an optional
+      # mapping block (see +construct+).
+      def clone(&block)
+        Cons.construct(self, &block)
+      end
+      
+      # Iterates over each +Cons+ in a list, yielding the +car+ value for
+      # each +Cons+. Returns the final +Cons+ in the list, from where we
+      # can inspect the tail's +cdr+ to see if the list if proper or not.
+      # The block is optional and the method is aliased as +tail+, so to
+      # get the tail value of an improper list you'd call <tt>list.tail.cdr</tt>.
+      def each
+        pair, tail = self, NULL
+        while Cons === pair and not pair.null?
+          yield(pair.car) if block_given?
+          tail = pair
+          pair = pair.cdr
+        end
+        tail
+      end
+      alias :tail :each
+      
+      # Returns the length of the list whose head is the receiving +Cons+.
+      # If the list is improper an exception is raised.
+      def length
+        size = 0
+        tail = each { |value| size += 1 }
+        raise TypeError.new("Cannot get the length of improper list #{self}") unless tail.cdr == NULL
+        size
+      end
+      alias :size :length
+      
+      # Returns +true+ iff +other+ is equal to the receiver, that is to
+      # say that +other+ is a +Cons+ with the same +car+ and +cdr+ as the
+      # receiving +Cons+.
+      def ==(other)
+        return false unless Cons === other
+        return false if NULL == other
+        @car == other.car and @cdr == other.cdr
+      end
+      
+      # If the receiving list contains +Binding+ objects, said objects are
+      # forced to evaluate themselves to populate the list.
+      def force!
+        return self unless Binding === @car
+        pair = self
+        while not pair.null?
+          pair.car = pair.car.force!
+          pair = pair.cdr
+        end
+        self
+      end
+      
+      # Returns +true+ iff the receiving +Cons+ is the head of a proper list.
+      def list?
+        tail.cdr == NULL; end
+      
+      # Returns +true+ iff the receiving +Cons+ is a valid pair.
+      def pair?
+        not null?; end
+      
+      # Returns +true+ iff the receiving +Cons+ is the empty list.
+      def null?
+        self == NULL; end
+      
+      # Returns an array representation of the list. If +deep+ is +true+,
+      # the array conversion is performed recursively.
+      def to_a(deep = false)
+        map { |cell| deep && Cons === cell ? cell.to_a : cell }
+      end
+      
+      # Returns a pure Ruby representation of the list, with any Heist
+      # specific objects converted to basic Ruby equivalents.
+      def to_ruby
+        map { |cell| cell.respond_to?(:to_ruby) ? cell.to_ruby : cell }
+      end
+      
+      # Returns a Scheme-style string representation of the list.
+      def to_s
+        strings = []
+        tail = each { |value|
+          strings << case value
+                       when String then value.inspect
+                       when Symbol then "'#{value}"
+                       else value
+                     end
+        }.cdr
+        '(' + (strings * ' ') +
+              (tail == NULL ? '' : ' . ' + tail.to_s) + ')'
+      end
+      alias :inspect :to_s
+    end
+    
+  end
+end
+

data/lib/runtime/data/expression.rb

@@ -1,18 +1,27 @@
 module Heist
   class Runtime
     
+    # Classes may mix in the +Expression+ module to signal that they represent
+    # sections of code that may be evaluated. This is mostly a flag module
+    # and does not provide much in the way of extensibility, since the evaluator
+    # needs to know how to execute all the kinds of expressions you want it
+    # to deal with (for reasons such as tail recursion, expressions are not
+    # responsible for evaluating themselves).
     module Expression
-      attr_reader :parent, :index
-      
-      def exists_at!(parent, index)
-        @parent, @index = parent, index
-      end
+      attr_accessor :parent
       
+      # Replaces the receiver with +expression+ in the receiver's parent
+      # expression. This is used as part of the macro expansion process.
       def replace(expression)
         return unless @parent
-        @parent[@index] = expression
+        @parent.car = expression
+        @parent.hosts(expression)
       end
       
+      # Returns the result of evaluating the receiving +Expression+ in the
+      # given +scope+. Works by pushing the receiver and scope onto the
+      # runtime stack (could be a +Stack+ or +Stackless+), which then
+      # evaluates the expression using a trampoline.
       def eval(scope)
         scope.runtime.stack << Frame.new(self, scope)
       end

data/lib/runtime/data/identifier.rb

@@ -1,17 +1,34 @@
 module Heist
   class Runtime
     
+    # An +Identifier+ is used to represent any name that appears in Scheme
+    # code. We might throw it away and use symbols at some point. I had this
+    # idea for storing metadata on +Identifier+ objects to speed things up
+    # but it pretty much came to nothing. Its one saving grace is that it
+    # needs to be treated as an +Expression+ class and I don't want to
+    # modify core Ruby classes.
     class Identifier
       include Expression
       
       extend Forwardable
-      def_delegators(:@metadata, :[], :[]=)
       def_delegators(:@name, :to_s)
       alias :inspect :to_s
       
+      # An +Identifier+ is initialized using a string that becomes the
+      # name of the identifier.
       def initialize(name)
         @name = name.to_s
-        @metadata = {}
+      end
+      
+      # Returns +true+ if the receiver has the same name as the argument.
+      def ==(other)
+        Identifier === other and @name == other.to_s
+      end
+      
+      # Returns a raw Ruby representation of the identifier, for which
+      # we use symbols.
+      def to_ruby
+        @name.to_s.to_sym
       end
     end
     

data/lib/runtime/frame.rb

@@ -1,115 +1,182 @@
 module Heist
   class Runtime
     
+    # +Frame+ is used by the +Stack+ class to encapsulate a single +Expression+
+    # bound to a +Scope+. +Frame+ objects evaluate expressions one sub-expression
+    # at a time, providing fine-grained opportunity for inspecting intermediate
+    # results and supporting the Scheme notion of continuations.
+    #
+    # The state of a +Frame+ is held in five variables: <tt>@expression</tt>,
+    # <tt>@scope</tt>, <tt>@values</tt>, <tt>@current</tt> and <tt>@complete</tt>.
+    # <tt>@expression</tt> is the +Expression+ object the +Frame+ is evaluating,
+    # and <tt>@scope</tt> is a +Scope+ object in which to evaluate it. <tt>@values</tt>
+    # is a copy of <tt>@expression</tt> that is used to store the values returned
+    # by the subexpressions; it represents the partially evaluated state of the
+    # expression for use when saving a +Stack+ when creating a +Continuation+.
+    # <tt>@current</tt> is a pointer to the subexpression that is to be evaluated
+    # next, and <tt>@complete</tt> is a boolean that indicates whether all the
+    # required subexpressions have been evaluated.
+    #
+    # See +Stack+ for a fuller explanation of how expressions are evaluated.
+    #
     class Frame
       attr_reader :expression, :scope
       
+      # A +Frame+ is initialized using an +Expression+ and a +Scope+, which
+      # are simply stored as instance variables. No evaluation takes place
+      # upon initialization.
       def initialize(expression, scope)
         reset!(expression)
         @scope = scope
       end
       
+      # Returns +true+ iff the +Frame+ has completed evaluating its expression.
       def complete?
         @complete
       end
       
+      # Processes a single subexpression from the +Frame+ and returns the
+      # result. If all the required subexpressions have been evaluated, we
+      # call the resulting function with the arguments and return the result
+      # of that call.
       def process!
         case @expression
         
-          when List then
-            if Syntax === @values.first or @values.size == @expression.size
+          when Cons then
+            # If we have evaluated all the subexpressions, or we have a
+            # +Syntax+ value first in the list, we can make a function call
+            # and return its result.
+            function = @values.car
+            if Syntax === function or @current.null?
               @complete = true
-              merge!
-              raise SyntaxError.new("Invalid expression: #{@expression}") unless Function === @data.first
-              result = @data.first.call(@scope, @data[1..-1])
+              raise SyntaxError.new("Invalid expression: #{@expression}") unless Function === function
+              result = function.call(@scope, @values.cdr)
+              
+              # If the result of the call is a macro expansion, inline it
+              # and set its expression as the new expression for the frame
               return result unless Macro::Expansion === result
               return reset!(result.expression, true)
             end
             
+            # Otherwise, we still have work to do on the subexpressions, so
+            # we evaluate the next one in the list.
             stack = @scope.runtime.stack
-            stack << Frame.new(@expression[@values.size], @scope)
+            stack << Frame.new(@current.car, @scope)
         
+          # If the expression is an +Identifier+, just look it up.
           when Identifier then
             @complete = true
             @scope[@expression]
         
+          # Otherwise, the expression is just data so return it.
           else
             @complete = true
             Heist.evaluate(@expression, @scope)
         end
       end
       
-      def dup
-        copy, values = super, @values.dup
+      # Returns a copy of the +Frame+. The <tt>@values</tt> variable is also
+      # copied by this method so that state changes do not transfer from the
+      # copy to the original.
+      def clone
+        copy, values = super, @values.clone
         copy.instance_eval { @values = values }
         copy
       end
       
+      # Fills the hole corresponding to +subexpr+ in the receiving +Frame+ with
+      # +value+. When a hole is filled, the <tt>@current</tt> pointer is moved
+      # to the next subexpression that needs evaluating.
       def fill!(subexpr, value)
-        subexpr ||= @expression[@values.size]
-        @values << value
-        @subexprs << subexpr
+        epair, vpair = @expression, @values
+        while Cons === epair and not epair.null?
+          if epair.car.equal?(subexpr)
+            vpair.car = value
+            @current = epair.cdr
+          end
+          epair, vpair = epair.cdr, vpair.cdr
+        end
       end
       
+      # Sets the replacement target for the receiving +Frame+ to the given
+      # +expression+. When the receiving frame returns, it will fill the
+      # hole corresponding to the +expression+ in the previous +Frame+ on
+      # the +Stack+.
       def replaces(expression)
         @target = expression
       end
       
+      # Returns the +Expression+ that is the replacement target for the
+      # previous +Frame+ on the +Stack+. When the receiving +Frame+ completes,
+      # the returned value will replace the return value of this method in
+      # the previous +Frame+. The +target+ of a +Frame+ is its <tt>@expression</tt>
+      # by default, but tail calls require us to change the target as, when
+      # a tail call returns, the +Frame+ that originated it will no longer
+      # by on the stack so +replaces+ is used to change the replacement
+      # target for the tail call.
       def target
         @target || @expression
       end
       
     private
       
-      def merge!
-        return @data = @values unless Syntax === @values.first
-        @data = @expression.dup
-        @expression.each_with_index do |expr, i|
-          index = @subexprs.index(expr)
-          @data[i] = @values[index] if index
-        end
-      end
-      
+      # Resets the +Expression+ stored in the +Frame+. If the second argument
+      # is given as +true+, the given +expression+ replaces the previously
+      # stored expression in the source tree; this is used to inline macro
+      # expansions. Also resets the <tt>@values</tt> list to be a copy of the
+      # new +Expression+.
       def reset!(expression, replace = false)
         @expression.replace(expression) if replace
         @expression = expression
-        @values     = []
-        @subexprs   = []
+        @current    = expression
+        @values     = (Cons === expression) ? expression.clone : nil
         @complete   = false
       end
     end
     
+    # +Body+ is a subclass of +Frame+, used for evaluating +Function+ bodies.
+    # Instead of providing break points between subexpressions in a single
+    # expression, it provides break points between whole expressions inside
+    # a Scheme procedure. (A 'break point' is a point in code execution during
+    # which +Stack+ can inspect the last value returned and decide whether to
+    # continue the current +Frame+ or switch to some other action.)
     class Body < Frame
+      
+      # A +Body+ is initialized using a +Cons+ list containing a list of
+      # <tt>Expression</tt>s that make up the body of a +Function+, and a
+      # +Scope+ in which these expressions are to be evaluated.
       def initialize(expressions, scope)
         @expression  = expressions
         @scope       = scope
         @values      = []
-        @index       = 0
       end
       
+      # Returns +true+ iff the +Body+ has evaluated all the expressions.
       def complete?
-        @index == @expression.size
+        @expression.null?
       end
       
+      # Processes the next remaining +Expression+ from the +Function+ body,
+      # returning the result for inspection by the +Stack+.
       def process!
-        expression = @expression[@index]
-        @index += 1   # increment before evaluating the expression
-                      # so that when a continuation is saved we
-                      # resume from the following statement
+        expression = @expression.car
+        
+        # Increment before evaluating the expression so that when a
+        # continuation is saved we resume from the following statement
+        @expression = @expression.cdr
         
-        return Frame.new(expression, @scope) if @index == @expression.size
+        # Return the final expression as a +Frame+ to enable tail calls
+        return Frame.new(expression, @scope) if complete?
         
+        # For all non-tail calls, evaluate the expression and return the value
         stack = @scope.runtime.stack
         stack << Frame.new(expression, @scope)
         stack.value
       end
       
-      def fill!(value, subexpr = nil)
-        @values << value
-      end
-      
-      def to_s
-        @expression.map { |e| e.to_s } * ' '
+      # Do-nothing override of <tt>Frame#fill!</tt>. +Function+ bodies do not
+      # need to remember the return value of each expression.
+      def fill!(*args)
       end
     end