rubymirrors 0.0.1

data/Gemfile

@@ -0,0 +1,7 @@
+source :rubygems
+
+gem 'mspec'
+
+platform :mri do
+  gem "method_source", "~> 0.6.6"
+end

data/README.md

@@ -0,0 +1,30 @@
+## A mirror API for Ruby
+
+In various [research][p1] [projects][p2] the advantages of having a [mirror
+API][p3] to separate reflection from a language implementation have
+been discussed, and "industry grade" implementations exist for
+[Java][p4] and [C#][p5]. This project aims at providing a number of
+specs and classes that document a mirror API for Ruby. The mirror
+implementation that is part of this project will use only those
+language facilities that are available across Ruby implementations.
+The specs, however, will also test behavior that cannot be provided in
+such a manner. The idea here is that in time, all implementations
+provide their own implementation of the mirror API, and all
+implementations collaborate on this one spec.
+
+Why do this, you ask? Because Ruby needs tools, and those tools need
+to be written in Ruby. If they are not, then people will be excluded from
+tinkering with their tools, thus impeding innovation. You only have to
+look at Emacs or Smalltalk to see what's possible when programmers can
+extend their tools, all tools, in a language they feel comfortable
+in. If we have a standard mirror API, all tools that are written **for**
+Ruby, **in** Ruby, can be shared across implementations, while at the same time
+allowing language implementers to use the facilities of their platform
+to provide optimal reflective capabilities without tying them to
+internals.
+
+[p1]: http://www.cs.virginia.edu/~lorenz/papers/icse03/icse2003.pdf "Pluggable Reflection: Decoupling Meta-Interface and Implementation"
+[p2]: http://bracha.org/newspeak-spec.pdf "Newspeak Programming Language Draft Specification, Version 0.06, pages 40 onward"
+[p3]: http://www.hpi.uni-potsdam.de/hirschfeld/events/past/media/100105_Bracha_2010_LinguisticReflectionViaMirrors_HPI.mp4 "Linguistic Reflection Via Mirrors"
+[p4]: http://bracha.org/mirrors.pdf "Mirrors: Design Principles for Meta-level Facilities of Object-Oriented Programming Languages"
+[p5]: http://oreilly.com/catalog/progcsharp/chapter/ch18.html "See esp. 18-3, highlighting how C# reflection works on assembly rather than VM objects"

data/Rakefile

@@ -0,0 +1,13 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+RUBY_ENGINE = 'ruby' unless defined? RUBY_ENGINE
+
+desc "Run the specs on the given mirror api. Defaults to 'ruby'"
+task :spec, :impl do |task, args|
+  args.with_defaults :impl => RUBY_ENGINE
+  sh "mspec -t #{args.impl} spec/*_spec.rb"
+end
+
+task :test    => :spec
+task :default => :spec

data/lib/abstract_reflection.rb

@@ -0,0 +1,112 @@
+module AbstractReflection
+  # A marker, raised when trying to run something
+  # that the reflective API doesn't support.
+  class CapabilitiesExceeded < StandardError; end
+
+  module ClassMethods
+    # A mirror has to reflect on something. file mirrors on files or
+    # directories, VM mirrors on the running VM or a remote instance and
+    # so on...  This method allows you to query what kind of object you
+    # need to prepare to use it.
+    #
+    # @return [Array<Class>, Class] the class(es) that this reflective api can work on
+    def codebase
+      raise NotImplementedError, "#{self} should have implemented #codebase"
+    end
+  end
+
+  # Creates a new instance of a Reflection
+  # @param [Object] the codebase to work on, e.g. a file or a VM
+  # @return [Reflection] a new reflection object
+  def initialize(object)
+    raise NotImplementedError, "#{self} should have implemented #initialize"
+  end
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  # This method can be used to query the system for known modules. It
+  # is not guaranteed that all possible modules are returned.
+  # 
+  # @return [Array<ClassMirror>] a list of class mirrors
+  def modules
+    raise CapabilitiesExceeded
+  end
+
+  # This method can be used to query the system for known classes. It
+  # is not guaranteed that all possible classes are returned.
+  # 
+  # @return [Array<ClassMirror>] a list of class mirrors
+  def classes
+    raise CapabilitiesExceeded
+  end
+
+  # Query the system for objects that are direct instances of the
+  # given class.
+  # @param [Class]
+  # @return [Array<ObjectMirror>] a list of appropriate mirrors for the requested objects
+  def instances_of(klass)
+    raise CapabilitiesExceeded
+  end
+
+  # Ask the system to find the object with the given object id
+  # @param [Numeric] object id
+  # @return [ObjectMirror, NilClass] the object mirror or nil
+  def object_by_id(id)
+    raise CapabilitiesExceeded
+  end
+
+  # Query the system for implementors of a particular message
+  # @param [String] the message name
+  # @return [Array<MethodMirror>] the implementing methods
+  def implementations_of(message)
+    raise CapabilitiesExceeded
+  end
+
+  # Query the system for senders of a particular message
+  # @param [String] the message name
+  # @return [Array<MethodMirror>] the sending methods
+  def senders_of(message)
+    raise CapabilitiesExceeded
+  end
+
+  # Return the currently active threads in the system
+  # @return [Array<ThreadMirror>] a list of thread mirrors
+  def threads
+    raise CapabilitiesExceeded
+  end
+
+  # @return [String] the platform the system is running on. usually RUBY_PLATFORM
+  def platform
+    raise CapabilitiesExceeded
+  end
+
+  # @return [String] the used implementation of Ruby
+  def engine
+    raise CapabilitiesExceeded
+  end
+
+  # @return [String] the version string describing the system
+  def version
+    raise CapabilitiesExceeded
+  end
+
+  # Create a mirror for a given object in the system under
+  # observation.
+  # @param [Object]
+  # @return [Mirror]
+  def reflect(o)
+    Mirror.reflect o, self
+  end
+end
+
+require 'abstract_reflection/mirror'
+require 'abstract_reflection/object_mirror'
+require 'abstract_reflection/field_mirror'
+require 'abstract_reflection/class_mirror'
+require 'abstract_reflection/method_mirror'
+require 'abstract_reflection/thread_mirror'
+require 'abstract_reflection/stack_frame_mirror'
+require 'abstract_reflection/gc_mirror'
+require 'abstract_reflection/compiler_mirror'

data/lib/abstract_reflection/class_mirror.rb

@@ -0,0 +1,150 @@
+module AbstractReflection
+  # A specific mirror for a class, that includes all the capabilites
+  # and information we can gather about classes.
+  module ClassMirror
+    include ObjectMirror
+
+    # The known instance variables of this class. Ruby doesn't have a
+    # fixed number of instance variables, but static or runtime
+    # anlysis can give us a good idea what kind of variables we can
+    # expect.
+    #
+    # @return [FieldMirror]
+    def instance_variables
+      raise CapabilitiesExceeded
+    end
+
+    # The known class variables.
+    # @see #instance_variables
+    # @return [FieldMirror]
+    def class_variables
+      raise CapabilitiesExceeded
+    end
+
+    # The known class variables.
+    # @see #instance_variables
+    # @return [FieldMirror]
+    def class_instance_variables
+      raise CapabilitiesExceeded
+    end
+
+    # The source files this class is defined and/or extended in.
+    # 
+    # @return [Array<String,File>]
+    def source_files
+      raise CapabilitiesExceeded
+    end
+
+    # The singleton class of this class
+    #
+    # @return [ClassMirror]
+    def singleton_class
+      raise CapabilitiesExceeded
+    end
+
+    # Predicate to determine whether the subject is a singleton class
+    #
+    # @return [true,false]
+    def singleton_class?
+      raise CapabilitiesExceeded
+    end
+
+    # The inverse of #singleton_class.
+    #
+    # @return [ClassMirror]
+    def singleton_instance
+      raise CapabilitiesExceeded
+    end
+
+    # The namespace of this class. Provides direct access to the
+    # enclosing namespace.
+    #
+    # @return [ClassMirror]
+    def namespace
+      raise CapabilitiesExceeded
+    end
+
+    # The full nesting.
+    #
+    # @return [Array<ClassMirror>]
+    def nesting
+      raise CapabilitiesExceeded
+    end
+
+    # The classes nested within the subject. Should _not_ trigger
+    # autloads!
+    #
+    # @return [Array<ClassMirror>]
+    def nested_classes
+      raise CapabilitiesExceeded
+    end
+
+    # The mixins included in the ancestors of this class.
+    #
+    # @return [Array<ClassMirror>]
+    def mixins
+      raise CapabilitiesExceeded
+    end
+
+    # The direct superclass
+    #
+    # @return [ClassMirror]
+    def superclass
+      raise CapabilitiesExceeded
+    end
+
+    # The known subclasses
+    #
+    # @return [Array<ClassMirror>]
+    def subclasses
+      raise CapabilitiesExceeded
+    end
+
+    # The list of ancestors
+    #
+    # @return [Array<ClassMirror>]
+    def ancestors
+      raise CapabilitiesExceeded
+    end
+
+    # The constants defined within this class. This includes nested
+    # classes and modules, but also all other kinds of constants.
+    # This should _not_ trigger autoloads!
+    #
+    # @return [Array<FieldMirror>]
+    def constants
+      raise CapabilitiesExceeded
+    end
+
+    # Searches for the named constant in the mirrored namespace. May
+    # include a colon (::) separated constant path. This _may_ trigger
+    # an autoload!
+    #
+    # @return [ClassMirror, nil] the requested constant, or nil
+    def constant(name)
+      raise CapabilitiesExceeded
+    end
+
+    # The instance methods of this class. To get to the class methods,
+    # ask the #singleton_class for its methods.
+    #
+    # @return [Array<MethodMirror>]
+    def methods
+      raise CapabilitiesExceeded
+    end
+
+    # The instance method of this class or any of its superclasses
+    # that has the specified selector
+    #
+    # @return [MethodMirror, nil] the method or nil, if none was found
+    def method(name)
+      raise CapabilitiesExceeded
+    end
+
+    # The method dictionary. Maps names to methods. Should ideally be
+    # writable.
+    def method_dictionary
+      raise CapabilitiesExceeded
+    end
+  end
+end

data/lib/abstract_reflection/compiler_mirror.rb

@@ -0,0 +1,31 @@
+module AbstractReflection
+  # Reflecting on the compiler, both in a general sense (to just
+  # compile things) and in specific states. It should be possible to
+  # get a compiler instance and associated state from e.g. the
+  # execution of a thread.
+  # 
+  # This class should also allow access to information about JIT,
+  # caches etc
+  module CompilerMirror
+    include Mirror
+
+    # Your Kernel#eval, but only compiles and returns
+    # the compiled method object.
+    #
+    # return [MethodMirror]
+    def compile(source)
+      raise CapabilitiesExceeded
+    end
+
+    # For a specific compiler state, this holds the current module
+    # definition stack. This should be a list of modules in which the
+    # Thread, that belongs to this compiler state, is currently
+    # nested. The first element is the module that would be target for
+    # the next method definition.
+    #
+    # return [Array<ClassMirror>]
+    def module_scope
+      raise CapabilitiesExceeded
+    end
+  end
+end

data/lib/abstract_reflection/field_mirror.rb

@@ -0,0 +1,35 @@
+module AbstractReflection
+  # A class to reflect on instance, class, and class instance variables,
+  # as well as constants.
+  module FieldMirror
+    include Mirror
+
+    def value
+      raise CapabilitiesExceeded
+    end
+
+    def value= obj
+      raise CapabilitiesExceeded
+    end
+
+    def public?
+      raise CapabilitiesExceeded
+    end
+
+    def private?
+      raise CapabilitiesExceeded
+    end
+
+    def protected?
+      raise CapabilitiesExceeded
+    end
+
+    def writable?
+      true
+    end
+
+    def delete
+      raise CapabilitiesExceeded
+    end
+  end
+end

data/lib/abstract_reflection/gc_mirror.rb

@@ -0,0 +1,19 @@
+module AbstractReflection
+  # Reflective access to the GC. This includes statistics, runtime
+  # behavior observation and triggering specific GC functionality.
+  module GCMirror
+    include Mirror
+
+    # Trigger a GC run
+    # @return stats about cleaned objects, freed memory, etc
+    def collect_garbage
+      raise CapabilitiesExceeded
+    end
+
+    # Run memory compaction
+    # @return info about freed memory, moved pages, etc
+    def compact_memory
+      raise CapabilitiesExceeded
+    end    
+  end
+end

data/lib/abstract_reflection/method_mirror.rb

@@ -0,0 +1,253 @@
+module AbstractReflection
+  # A MethodMirror should reflect on methods, but in a more general
+  # sense than the Method and UnboundMethod classes in Ruby are able
+  # to offer.
+  #
+  # In actual execution, a method is pretty much every chunk of code,
+  # even loading a file triggers a process not unlike compiling a
+  # method (if only for the side-effects). Method mirrors should allow
+  # access to the runtime objects, but also to their static
+  # representations (bytecode, source, ...), their debugging
+  # information and statistical information
+  module MethodMirror
+    include Mirror
+
+    # @return [ClassMirror] The class this method was originally defined in
+    def defining_class
+      raise CapabilitiesExceeded
+    end
+    
+    # @return [String] The source code of this method
+    def source
+      raise CapabilitiesExceeded
+    end
+
+    # @return [Fixnum] The source line
+    def line
+      raise CapabilitiesExceeded
+    end
+
+    # @return [String] The method name
+    def selector
+      raise CapabilitiesExceeded
+    end
+
+    # @return [String] The filename
+    def file
+      raise CapabilitiesExceeded
+    end
+
+    # Queries the method for it's arguments and returns a list of
+    # mirrors that hold name and value information.
+    # 
+    # @return [Array<FieldMirror>]
+    def arguments
+      raise CapabilitiesExceeded
+    end
+
+    # Returns a field mirror with name and possibly value of the splat
+    # argument, or nil, if there is none to this method.
+    #
+    # @return [FieldMirror, nil]
+    def splat_argument
+      raise CapabilitiesExceeded
+    end
+
+    # Returns names and values of the optional arguments.
+    #
+    # @return [Array<FieldMirror>, nil]
+    def optional_arguments
+      raise CapabilitiesExceeded
+    end
+
+    # Returns the name and possibly values of the required arguments
+    # @return [Array<FieldMirror>, nil]
+    def required_arguments
+      raise CapabilitiesExceeded
+    end
+
+    # Return the value the block argument, or nil
+    #
+    # @return [FieldMirror, nil]
+    def block_argument
+      raise CapabilitiesExceeded
+    end
+
+    # Replace the sourcecode. This should be an in-place operation and
+    # immediately visible to the system.
+    def source= string
+      raise CapabilitiesExceeded
+    end
+
+    # Change the information about which file this method is stored
+    # in. Possibly moves the method into the new file.
+    def file= string
+      raise CapabilitiesExceeded
+    end
+
+    # Change the information about the line this method starts
+    # at. Possibly moves the method.
+    def line= string
+      raise CapabilitiesExceeded
+    end
+
+    # The offsets into the source code for method sends.
+    #
+    # @return [Hash<String, Fixnum>] a hash of selector-offset pairs
+    def send_offsets
+      raise CapabilitiesExceeded
+    end
+
+    # The offsets into the source code for stepping in a debugger
+    def step_offsets
+      raise CapabilitiesExceeded
+    end
+
+    # Allows setting a breakpoint in the method, optionally at an
+    # offset.
+    def break(step_offset = 1)
+      raise CapabilitiesExceeded
+    end
+
+    # Query the method for active breakpoints.
+    def breakpoints
+      raise CapabilitiesExceeded
+    end
+
+    # Predicate to determine whether this method was compiled for closure
+    #
+    # @return [true, false]
+    def is_closure?
+      raise CapabilitiesExceeded
+    end
+
+    # The binding of the method. May be nil.
+    #
+    # @return [Binding, NilClass]
+    def binding
+      raise CapabilitiesExceeded
+    end
+
+    # Predicate to determine whether this method is an alias.
+    #
+    # @return [true, false]
+    def is_alias?
+      raise CapabilitiesExceeded
+    end
+
+    # Returns the original method to an alias, a proc, or an unbound
+    # method object, or the method itself, if the previous options are
+    # not applicable.
+    #
+    # @return [MethodMirror]
+    def original_method
+      raise CapabilitiesExceeded
+    end
+
+    # Predicate to determine whether a given message is send within
+    # this method. This should at least report all direct sends, but
+    # might also report sends within #evals or through #send
+    #
+    # @return [true, false]
+    def sends_message?(string)
+      raise CapabilitiesExceeded
+    end
+
+    # Determine whether this method references the passed name. This
+    # should be in a state useable enough to allow e.g. dead local
+    # detection.
+    #
+    # @return [true, false]
+    def references_name?(string)
+      raise CapabilitiesExceeded
+    end
+
+    # Each method contributes a certain percentage to the runtime of
+    # the system. This method can be used to query the system for the
+    # percentage of the mirrored method (in the range 0 < p < 1). If
+    # the number is closer to one, that means that the system spends a
+    # considerable amount of time executing this method. This method
+    # does not consider how often a method is called, i.e. a high
+    # share doesn't tell you whether the method is slow or if it is
+    # just called very often.
+    #
+    # @return [Time]
+    def execution_time_share
+      raise CapabilitiesExceeded
+    end
+
+    # The absolute, total time this method was executed (on top of the
+    # stack)
+    #
+    # @return [Time]
+    def execution_time
+      raise CapabilitiesExceeded
+    end
+
+    # The average time each method invocation executes the method,
+    # before returning.
+    #
+    # @return [Time]
+    def execution_time_average
+      raise CapabilitiesExceeded
+    end
+
+    # The number of times this method has been called. Not
+    # neccessarily an exact number (to allow for optimizations), but
+    # should at least give an indication.
+    #
+    # @return [Fixnum]
+    def invocation_count
+      raise CapabilitiesExceeded
+    end
+
+    # If this method was JITed, this should return the native code
+    # location. nil, if this method was not jitted,
+    # CapabilitiesExceeded should be thrown for implementations that
+    # do not have a JIT.
+    def native_code
+      raise CapabilitiesExceeded
+    end
+
+    # If this method was compiled into a VM bytecode representation,
+    # return an object describing the bytecode. Like #native_code,
+    # this should raise a CapabilitiesExceeded only for implementations
+    # that do not have a bytecode representation.
+    def bytecode
+      raise CapabilitiesExceeded
+    end
+
+    # The AST representation of this method.
+    def ast
+      raise CapabilitiesExceeded
+    end
+
+    def public?
+      raise CapabilitiesExceeded
+    end
+
+    def public!
+      raise CapabilitiesExceeded
+    end
+
+    def private?
+      raise CapabilitiesExceeded
+    end
+
+    def private!
+      raise CapabilitiesExceeded
+    end
+
+    def protected?
+      raise CapabilitiesExceeded
+    end
+
+    def protected!
+      raise CapabilitiesExceeded
+    end
+
+    def delete
+      raise CapabilitiesExceeded
+    end
+  end
+end