change build names a little and document

lib/risc/builder.rb

@@ -4,11 +4,16 @@ module Risc
 
     attr_reader :built , :compiler
 
+    # pass a compiler, to which instruction are added (usually)
+    # call build or build_and_return with a block
     def initialize(compiler)
       @compiler = compiler
       @names = {}
     end
 
+    # make the magic: convert incoming names into registers that have the
+    # type set according to the name (using resolve_type)
+    # anmes are stored, so subsequent calls use the same register
     def method_missing(*args)
       super if args.length != 1
       name = args[0]
@@ -24,17 +29,32 @@ module Risc
       reg
     end
 
+    # build code using dsl (see __init__ or MessageSetup for examples)
+    # names (that ruby would resolve to a variable/method) are converted
+    # to registers. << means assignment and [] is supported both on
+    # L and R values (but only one at a time). R values may also be constants.
+    # Basically this allows to create LoadConstant, RegToSlot, SlotToReg and
+    # Transfer instructions with extremely readable code.
+    # example:
+    #  space << Parfait.object_space # load constant
+    #  message[:receiver] << space  #make current message (r0) receiver the space
+    #
+    # build result is available as built, but also gets added to compiler
     def build(&block)
-      @built = nil
-      instance_eval(&block)
-      return @built
+      risc = build_and_return(&block)
+      @compiler.add_code(risc)
+      risc
     end
 
-    def build_and_add(&block)
-      risc = build(&block)
-      @compiler.add_code(risc)
+    # version of build that does not add to compiler, just returns the code
+    def build_and_return(&block)
+      @built = nil
+      instance_eval(&block)
+      risc = @built
+      @built = nil
+      return risc
     end
-    
+
     def add_instruction(ins)
       if(@built)
         @built << ins
@@ -44,10 +64,6 @@ module Risc
     end
   end
 
-  def self.build(compiler, &block)
-    Builder.new(compiler).build( &block )
-  end
-
   # if a symbol is given, it may be the message or the new_message.
   # These are mapped to register references.
   # The valid symbols (:message,:new_message) are the same that are returned

lib/risc/builtin/object.rb

@@ -47,7 +47,7 @@ module Risc
           compiler = Risc::MethodCompiler.create_method(:Object,:__init__ ,
                             Parfait::NamedList.type_for({}) , Parfait::NamedList.type_for({}))
           builder = Risc::Builder.new(compiler)
-          builder.build_and_add do
+          builder.build do
             space << Parfait.object_space
             message << space[:first_message]
             next_message << message[:next_message]
@@ -57,7 +57,7 @@ module Risc
           risc = Mom::MessageSetup.new(Parfait.object_space.get_main).build_with( builder )
           compiler.add_code(risc)
 
-          builder.build_and_add do
+          builder.build do
             message << message[:next_message]
             message[:receiver] << space
           end

lib/risc/method_compiler.rb

@@ -79,7 +79,7 @@ module Risc
         instruction = instruction.next
       end
     end
-    
+
     # add a risc instruction after the current (insertion point)
     # the added instruction will become the new insertion point
     def add_code( instruction )
@@ -170,5 +170,15 @@ module Risc
     def reduce_int( source , register )
       add_slot_to_reg( source + "int -> fix" , register , Parfait::Integer.integer_index , register)
     end
+
+    # Build with builder (see there), adding the created instructions
+    def build(&block)
+      builder.build_and_return(&block)
+    end
+
+    # return a new builder that uses this compiler
+    def builder
+      Builder.new(self)
+    end
   end
 end