rubybreaker 0.0.1

data/lib/rubybreaker/runtime/type_system.rb

@@ -0,0 +1,228 @@
+#--
+# This file contains the default type system for RubyBreaker. It uses
+# subtyping defined in ../typing/subtyping.rb. It is not a constraint-based
+# type system and does not check type errors statically. The main purpose of
+# this type system is to give a readable type signature to every method in
+# designated modules and classes.
+
+require_relative "object_wrapper"
+require_relative "type_placeholder"
+require_relative "../type"
+require_relative "../typing"
+
+module RubyBreaker
+
+  module Runtime
+
+    # This is the default type system for RubyBreaker. It can be overridden
+    # by a user specified type system. See +pluggable.rb+ for how this can
+    # be done.
+    class TypeSystem 
+
+      include Pluggable # not needed but for the sake of documentation...
+      include TypeDefs
+
+      protected
+
+      # Check if the object is wrapped by a monitor
+      def is_object_wrapped?(obj)
+        return obj.respond_to?(WRAPPED_INDICATOR)
+      end
+
+      # This method is a helper for computing the least upper bound. It
+      # handles the case where existing method type is a method type (and
+      # not a method list type). If there is no compatibility of the two
+      # types, then it returns false.
+      def lub_helper(exist_meth_type, new_meth_type)
+
+        # most restrictive for the given test cases. 
+        arg_types = []
+
+        exist_meth_type.arg_types.each_with_index do |exist_arg_type, i|
+          arg_type = nil
+          new_arg_type = new_meth_type.arg_types[i]
+          if !exist_arg_type 
+            # nil means there hasn't been any type observed
+            arg_type = new_arg_type
+          elsif new_arg_type.subtype_of?(exist_arg_type) 
+            arg_type = exist_arg_type
+          elsif !exist_arg_type.subtype_of?(new_arg_type)
+            # No subtype relation between them, so OR them
+            arg_type = OrType.new([new_arg_type, exist_arg_type])
+          end
+          arg_types << arg_type
+        end
+
+        new_ret_type = new_meth_type.ret_type
+        exist_ret_type = exist_meth_type.ret_type
+
+        if !exist_ret_type
+          ret_type = new_ret_type
+          resolved = true
+        elsif exist_ret_type.subtype_of?(new_ret_type) 
+          ret_type = exist_ret_type
+          resolved = true
+        elsif new_ret_type.subtype_of?(exist_ret_type) 
+          ret_type = new_ret_type
+          resolved = true
+        else
+          resolved = false
+        end
+        
+        if resolved
+          exist_meth_type.arg_types = arg_types
+          exist_meth_type.ret_type = ret_type      
+        end 
+
+        return resolved
+      end
+
+      # This method computes the least upper bound of the existing method
+      # type and newly observed argument/block/return types. There are a few
+      # cases to consider:
+      #
+      # If the existing type is a method list type, the new observed type
+      # will be either "consolidated" into one of the method types in the
+      # list or added to the list.
+      #
+      # If there is no compatibility between the existing method type and
+      # the observed type, then the method type will be promoted to a method
+      # list type. And the newly observed type will be added to the list.
+      #
+      # For each method type,
+      #
+      # It basically consolidates the existing type information for the
+      # invoked method and the observed type.
+      #
+      # For arguments, we look for most general type that can handle all
+      # types we have seen. This means we find the super type of all types
+      # we have seen (excluding unknown types).
+      # 
+      # For return, we look for most specific type that can handle both
+      # types.  Therefore, if two types have no subtype relation, we AND
+      # them. But we do not allow AND types in the return type. We must turn
+      # the method type to a method list type.
+      #
+      # obj:: the receive of the method call
+      # inst_meths:: a hash object that maps method names to method types 
+      # meth_name:: the name of the method being invoked
+      # retval:: the return value of the original method call
+      # args:: the arguments
+      # blk:: the block argument
+      #
+      def lub(obj, inst_meths, meth_name, retval, *args, &blk)
+        
+        exist_meth_type = inst_meths[meth_name.to_sym] 
+        
+        # Construct the newly observed method type first
+        new_meth_type = MethodType.new(meth_name)
+        args.each {|arg|
+          if is_object_wrapped?(arg)
+            arg_type = arg.__rubybreaker_type
+          else
+            arg_type = NominalType.new(arg.class)
+          end
+          new_meth_type.arg_types << arg_type
+        }
+        if (obj == retval)
+          # the return value is same as the message receiver. This means the
+          # return value has the self type.
+          SelfType.set_self(obj.class)
+          ret_type = SelfType.new()
+        else
+          # Otherwise, construct a nominal type.
+          ret_type = NominalType.new(retval.class)
+        end
+        new_meth_type.ret_type  = ret_type
+
+        resolved = false
+        if exist_meth_type.instance_of?(MethodListType)
+          exist_meth_type.types.each {|meth_type|
+            resolved = lub_helper(meth_type, new_meth_type)
+            break if resolved
+          }
+        else
+          resolved = lub_helper(exist_meth_type, new_meth_type)
+          if !resolved
+            # Could not resolve the types, so promote the method type to a
+            # method list type
+            exist_meth_type = MethodListType.new([exist_meth_type])
+            inst_meths[meth_name.to_sym] = exist_meth_type
+          end
+        end 
+        if !resolved
+          exist_meth_type.types << new_meth_type
+        end
+      end
+
+      public
+      
+      # This method occurs before every "monitored" method call. It wraps
+      # each argument with the object wrapper.
+      def before_method(obj, meth_info)
+
+        mod = obj.class
+        inst_meths = Breakable::TYPE_PLACEHOLDER_MAP[mod].inst_meths
+
+        # Let's take things out of the MethodInfo object
+        meth_name = meth_info.meth_name
+        args = meth_info.args
+        blk = meth_info.blk
+        ret = meth_info.ret
+
+        args = args.map do |arg|
+          if arg.kind_of?(TrueClass) || arg.kind_of?(FalseClass)
+            # XXX: would overrides resolve this issue?
+            arg 
+          else
+            ObjectWrapper.new(arg)
+          end
+        end
+
+        Debug.msg("In module monitor_before #{meth_name}")
+        
+        meth_type = inst_meths[meth_name]
+        
+        if meth_type
+          # This means the method type has been created previously.
+          unless (blk == nil && meth_type.blk_type == nil) &&
+                 (!blk || blk.arity == meth_type.blk_type.arg_types.length)
+            raise Errors::TypeError("Block usage is inconsistent")
+          end
+        else
+          # No method type has been created for this method yet. Create a
+          # blank method type (where each argument type, block type, and
+          # return type are all nil).
+          arg_types = args.map {|arg| nil }
+          blk_type = blk ? BlockType.new(Array.new(blk.arity), nil, nil) : nil
+          meth_type = MethodType.new(meth_name, arg_types, blk_type, nil)
+          inst_meths[meth_name] = meth_type
+        end
+
+        meth_info.args = args
+
+      end
+
+      # This method occurs after every "monitored" method call. It updates
+      # the type information.
+      def after_method(obj, meth_info)
+        mod = obj.class
+        # Take things out
+        meth_name = meth_info.meth_name
+        retval = meth_info.ret
+        args = meth_info.args
+        blk = meth_info.blk
+
+        Debug.msg("In module monitor_after #{meth_name}")
+
+        inst_meths = Breakable::TYPE_PLACEHOLDER_MAP[mod].inst_meths
+
+        # Compute the least upper bound
+        lub(obj, inst_meths,meth_name,retval,*args,&blk)
+
+      end
+
+    end
+  end
+
+end

data/lib/rubybreaker/runtime/typesig_parser.rb

@@ -0,0 +1,45 @@
+#--
+# This program parses a type signature given by the Ruby programmer in the
+# RubyBreaker type format.
+
+require "treetop"
+require_relative "../type"
+
+module RubyBreaker
+
+  module Runtime
+  
+    module TypeSigParser
+      
+      Treetop.load "#{File.dirname(__FILE__)}/../type/type_grammar"
+      PARSER = TypeGrammarParser.new
+    
+      public
+          
+      # This is a simple redirecting method for parsing type signature. The
+      # only special thing about this method is that, if there are multiple
+      # lines in the signature, it will look at each line and construct a
+      # MethodListType to represent the intersection type.
+      def self.parse(str)
+        meth_types = []
+        
+        # Get caller information and set the global location 
+        my_caller = caller[1]
+        if my_caller
+          file,line,junk = my_caller.split(":")
+          Position.set(file,line,-1)
+        end
+
+        return PARSER.parse(str).value
+        
+      rescue => e
+        
+        puts e
+        
+      end
+      
+    end
+
+  end
+  
+end

data/lib/rubybreaker/runtime.rb

@@ -0,0 +1,103 @@
+#--
+# This file defines Breakable and Broken module. Breakable module makes the
+# hosting module (and class) subject to type monitoring. Broken module makes
+# type information of the hosting module accessible.
+
+require_relative "runtime/overrides"
+require_relative "runtime/typesig_parser"
+require_relative "runtime/monitor"
+require_relative "runtime/inspector"
+
+module RubyBreaker
+
+  # This module should be included in classes or modules that you want to
+  # monitor during runtime. The concept is that once a Breakable module is
+  # monitored and its type documentation is generated, the module now becomes
+  # a Broken module. The actual implementation is a simple trigger that 
+  # queues the target module into the list of modules to monitor. The queued
+  # modules are then modified to be monitored dynamically.
+  module Breakable
+
+    TYPE_PLACEHOLDER_MAP = {} # module => type_placeholder
+    MONITOR_MAP = {}          # module => monitor
+
+    # when this module is included, simply keep track of this module so we
+    # can start monitoring
+    def self.included(mod)
+      BREAKABLE << mod
+    end
+
+  end
+ 
+  # This module is included for "broken" classes.
+  module Broken
+
+    include TypeDefs
+    include Runtime
+
+    TYPE_PLACEHOLDER_MAP = {} # module => type_placeholder
+ 
+    # This module will be "extended" to the meta class of the class that 
+    # includes Broken module. This allows the meta class to call 'typesig' 
+    # method to parse the type signature dynamically.
+    # 
+    # Usage:
+    #   Class A
+    #     include RubyBreaker::Broken
+    #
+    #     typesig("foo(fixnum) -> fixnum")
+    #     def foo(x) ... end
+    #   end
+    #
+    module BrokenMeta
+
+      include TypeDefs
+      include Runtime
+
+      # This method can be used at the meta level of the target module to
+      # specify the type of a method.
+      def typesig(str)
+        t = TypeSigParser.parse(str)
+        placeholder = TYPE_PLACEHOLDER_MAP[self]
+        if placeholder
+          meth_type = placeholder.inst_meths[t.meth_name]
+          if meth_type
+            # TODO: make a method list
+            if meth_type.instance_of?(MethodListType)
+              meth_type.types << t
+            else
+              # then upgrade it
+              placeholder.inst_meths[t.meth_name] = MethodListType.new([meth_type, t])
+            end
+          else
+            placeholder.inst_meths[t.meth_name] = t
+          end
+        end
+        return t
+      end
+   
+    end
+   
+    # This method is triggered when Broken module is included. This just 
+    # extends BrokenMeta into the target module so "typesig" method can be
+    # called from the meta level of the module.
+    def self.included(mod)
+
+      # Add to the list of broken modules
+      BROKEN << mod
+
+      # This MUST BE set for self type to work in type signatures
+      SelfType.set_self(mod) 
+
+      # Create if there is no type placeholder for this module yet
+      placeholder = TYPE_PLACEHOLDER_MAP[mod] 
+      if !placeholder 
+        placeholder = TypePlaceholder.new()
+        TYPE_PLACEHOLDER_MAP[mod] = placeholder
+      end
+      mod.extend(BrokenMeta)
+    end
+    
+  end
+
+end

data/lib/rubybreaker/test/testcase.rb

@@ -0,0 +1,39 @@
+#--
+# This file mimics the Ruby testing framework. This is provided so that
+# RubyBreaker can be used seamlessly with the traditional Ruby framework
+# (supposedly :) ).
+
+module RubyBreaker
+
+  # This module overrides the normal behavior of Ruby Stdlib's TestCase
+  # class. 
+  module TestCase
+
+    def self.setup()
+      Main.setup()
+    end
+
+    def self.teardown()
+      # Main.output()
+    end
+
+    def self.included(mod)
+
+      # hack to insert RubyBreaker's own setup and teardown methods
+      mod.module_eval <<-EOS
+
+      alias :__run :run
+
+      def run(*args,&blk)
+        # RubyBreaker::Utilities.rb_print("Running " + args[0].to_s)
+        RubyBreaker::TestCase.setup()
+        __run(*args,&blk)
+        RubyBreaker::TestCase.teardown()
+      end
+
+      EOS
+
+    end
+  end
+end
+

data/lib/rubybreaker/test.rb

@@ -0,0 +1 @@
+require_relative "test/testcase"

data/lib/rubybreaker/type/type.rb

@@ -0,0 +1,241 @@
+#--
+# This file contains the type structure used in RubyBreaker. Here we list 
+# types that are used (allowed) in RubyBreaker:
+# 
+#   AnyType          represents basically any type in Ruby
+#   NilType          represents a nil object
+#   SelfType         represents "self"--the current object
+#   NominalType      represents an object 
+#   DuckType         represents a partial object (a collection of methods)
+#   FusionType       represents an object along with a set of methods
+#   MethodType       represents a method
+#   BlockType        represents a block
+#   OrType           represents one of the many objects (i.e, OR)
+#   OptionalType     represents an optional argument type
+#   VarLengthType    represents a variable length argument type
+#   MethodListType   represents one or more methods
+#
+
+require_relative "../util"
+require_relative "../context.rb"
+
+module RubyBreaker
+
+  # This module contains all RubyBreaker type definitions. This module has
+  # to be included to the module if you want to work with the type
+  # definitions that RubyBreaker provides (unless you want to add TypeDefs
+  # namespace in the module).
+  module TypeDefs
+
+    # This class is a catch-all. The constructor of this class must be
+    # called from children via super() in order to assign the position field
+    # variable.
+    #
+    # The optional arguments are args[0] = file name args[1] = line number
+    #
+    #   args[2] = column position
+    #   
+    #   or
+    #   
+    #   args[0] = a Position, ObjectPosition, or Context object
+    #
+    class Type
+
+      # Speficies the context of the type. 
+      attr_accessor :ctx    
+
+      def initialize(*args)
+        case args[0]
+        when Context
+          @ctx = args[0]
+        when Position
+          @ctx = Context.new(args[0])
+        when ObjectPosition
+          @ctx = Context.new(args[0])
+        else
+          file = args[0]
+          line = args[1]
+          col = args[2]
+          pos = Position.new(file,line,col)
+          @ctx = Context.new(pos)
+        end
+      end
+    end
+
+    # This type can represent any object
+    class AnyType < Type
+      def initialize(*args)
+        super(*args)
+      end
+    end
+
+    # This type represents a nil
+    class NilType < Type
+      def initialize(*args)
+        super(*args)
+      end
+    end
+    
+    # This class represents a concrete object like a Numeric or String. It 
+    # stores the actual module in the instance variable @mod. 
+    class NominalType < Type
+
+      # This accessor points to the actual module
+      attr_accessor :mod
+
+      def initialize(mod=nil,*args)
+        super(*args)
+        @mod = mod
+      end
+    end
+
+    # This type represents the self type. Note that this is a subclass of
+    # Nominal Type. It works just like nominal type except that it also points
+    # to the current object! See subtyping.rb for more detail on how this
+    # would impact typing.
+    class SelfType < NominalType
+
+      # This is a setter method for class variable mod. 
+      # NOTE: It is set every time Broken module is included.
+      def self.set_self(mod)
+        @@mod = mod
+      end
+
+      # This is a getter method for class variable mod. 
+      def self.get_self(mod)
+        @@mod = mod
+      end
+
+      def initialize(*args)
+        # NOTE: @@mod is not required in general, but for typing it is a must.
+        super(@@mod, *args)
+      end
+    end
+
+    # This class represents any object with certain methods
+    # Usage: [m1,m2,...] where m1...mn are method names
+    class DuckType < Type
+
+      # This accessor sets/gets method names in the duck type.
+      attr_accessor :meth_names
+
+      def initialize(meth_names=[],*args)
+        super(*args)
+        @meth_names = meth_names.map!{|n| n.to_sym}
+      end
+      def add_meth(meth_name)
+        @meth_names << meth_name.to_sym if !@meth_names.include?(meth_name)
+      end
+    end
+
+    # This class represents any object that has certain methods whose types
+    # are same as the given nominal type's counterparts.
+    # Usage: nominal_type[m1,m2,...]
+    class FusionType < DuckType
+
+      # This accessor sets/gets the nominal type to which the method names
+      # are bound.
+      attr_accessor :nom_type
+
+      def initialize(nom_type,meth_names=[],*args)
+        super(meth_names,*args)
+        @nom_type = nom_type
+      end
+
+      # This method gets the actual module of the nominal type for this
+      # fusion type. This is a shorthand for t1.nom_type.mod().
+      def mod()
+        return @nom_type.mod
+      end
+    end
+
+    # This class represents a block (in a method). It has zero or more argument 
+    # types, nested block type (optional), and a return type.
+    class BlockType < Type
+
+      # This accessor sets/gets the argument types for this block type.
+      attr_accessor :arg_types
+
+      # This accessor sets/gets the block type for this block type.
+      attr_accessor :blk_type
+
+      # This accessor sets/gets the return type for this block type.
+      attr_accessor :ret_type
+
+      def initialize(arg_types=[],blk_type=nil,ret_type=nil,*args)
+        super(*args)
+        @arg_types = arg_types
+        @blk_type = blk_type
+        @ret_type = ret_type
+      end
+    end
+
+    # This class represents a method and is essentially same as block type 
+    # except the method name.
+    class MethodType < BlockType
+
+      # This accessor sets/gets the method name for this method type.
+      attr_accessor :meth_name
+
+      def initialize(meth_name,arg_types=[],blk_type=nil,ret_type=nil,*args)
+        super(arg_types,blk_type,ret_type,*args)
+        @meth_name = meth_name.to_sym
+      end
+    end
+
+    # This class respresents an optional argument type
+    class OptionalType < Type
+
+      # This accessor sets/gets the inner type of this optional type.
+      attr_accessor :type
+
+      def initialize(type,*args)
+        super(*args)
+        @type = type
+      end
+    end
+
+    # This class represents a variable-length argument type
+    class VarLengthType < Type
+
+      # This accessor sets/gets the inner type of this variable length
+      # argument type.
+      attr_accessor :type
+
+      def initialize(type,*args)
+        super(*args)
+        @type = type
+      end
+    end 
+
+    # This class represents one of many types
+    class OrType < Type
+
+      # This accessor sets/gets the inner types of this "or" type.
+      attr_accessor :types
+
+      def initialize(types=[],*args)
+        super(*args)
+        @types = types
+      end
+    end
+
+    # This class represents multiple method types.
+    class MethodListType < Type
+
+      # This accessor sets/gets the method types.
+      attr_accessor :types
+
+      def initialize(types=[],*args)
+        super(*args)
+        @types = types
+      end
+    end
+
+  end
+
+  # Include the module right away
+  include TypeDefs
+
+end
+