class_source 0.0.1 → 0.0.2

data/lib/class_source.rb

@@ -1,11 +1,21 @@
 require 'class_source/declarations'
 require 'class_source/index'
 require 'class_source/method_index'
+require 'class_source/class_method_index'
 require 'class_source/locator'
-require 'class_source/guesser'
+require 'class_source/scanner'
 require 'class_source/collator'
 
+# extend your class with ClassSource in order to inspect its source
 module ClassSource
+  # Returns a proxy for inspecting the source of a class
+  # To view the source as a string, use 
+  #     ExampleClass.__source__.to_s
+  #
+  # To view the source as a hash of file/line locations and strings, use
+  #     ExampleClass.__source__.all
+  #
+  # @return[ClassSource::Index] an index of all source code used to construct the class
   def __source__(options={})
     Index.new(self, options)
   end

data/lib/class_source/class_method_index.rb

@@ -0,0 +1,44 @@
+module ClassSource
+  # An index of all class methods available for a class
+  class ClassMethodIndex
+    def initialize(target_class)
+      @target_class = target_class
+    end
+
+    # @return [Array] An array of method names unique to or overridden in this class, not inherited from its ancestors or singleton_class ancestors.
+    def unique
+      uniquely_named + overridden - extended
+    end
+
+    # @return [Array] An array of method names for all methods included into a class via class extension.
+    def extended
+      @target_class.singleton_class.ancestors.map do |mod|
+        mod.instance_methods.select { |m| mod.instance_method(m).source_location == @target_class.method(m).source_location }
+      end.flatten
+    end
+
+    # @return [Array] An array of method names introduced for the first time in the current class
+    def uniquely_named
+      @target_class.singleton_methods(false)
+    end
+
+    # @return [Array] An array of method names with new source in this class vs its ancestors
+    def overridden
+      (@target_class.methods - uniquely_named).select do |m|
+        !ancestral_sources(m).include?(@target_class.method(m).source_location)
+      end
+    end
+
+    # @return [Array] An array of ancestral sources for a given method
+    def ancestral_sources(method)
+      superclasses.map { |mod| mod.respond_to?(method) && mod.method(method).source_location }.compact
+    end
+
+    # All ancestors of the target class
+    # @return[Array] An array of classes and modules
+    def superclasses
+      @target_class.ancestors - [@target_class]
+    end
+
+  end
+end

data/lib/class_source/collator.rb

@@ -1,27 +1,30 @@
 require 'ruby_parser'
 
 module ClassSource
+  # Responsible for collating class source information into a clear readable hash of source values.
   class Collator
     def initialize(target_class, index)
       @klass = target_class
       @source = index
     end
 
+    # @return [Hash]  A hash with keys of [file_path, line_number] tuples pointing to values of source code segments
     def to_hash(options = {})
-      full_sources = @source.locations(options).inject({}) do |results, location|
+      return sources_without_nesting if options[:include_nested] == false
+      @source.locations(options).inject({}) do |results, location|
         results[ location ] = source_helper(location)
         results
       end
 
-      return full_sources unless options[:include_nested] == false
-      full_sources.inject({}) do |clean_sources, (location, source)|
+    end
+
+    # @private
+    # @return [Hash] A hash of sources filtered for the source of any nested classes
+    def sources_without_nesting
+      @source.locations.inject({}) do |clean_sources, location|
+        source = source_helper(location)
         if nested_class_line_ranges[location.first]
-          complete_file = full_file(location)
-          target_range =  (location.last - 1)..(location.last + source.lines.count - 2)
-          clean_sources[location] = complete_file.lines.to_a.select.with_index do |line, index|
-            target_range.include?(index) &&
-            nested_class_line_ranges[location.first].all? { |range| !range.include?(index) }
-          end.join("")
+          clean_sources[location] = source_without_nesting(location, source)
         else
           clean_sources[location] = source
         end
@@ -29,26 +32,38 @@ module ClassSource
       end
     end
 
+    # @private
+    # @return [Hash] A source string with the contained nested class values removed
+    def source_without_nesting(location, source)
+      complete_file = full_file(location)
+      target_range =  (location.last - 1)..(location.last + source.lines.count - 2)
+      complete_file.lines.to_a.select.with_index do |line, index|
+        target_range.include?(index) &&
+        nested_class_line_ranges[location.first].all? { |range| !range.include?(index) }
+      end.join("")
+    end
+
+    # @return a hash of nested data within the class source based on existing class constants
+    # @private
     def nested_class_line_ranges
       nested_classes = @klass.constants.select { |c| @klass.const_get(c).is_a?(Class) }.map {|c| @klass.const_get(c) }
       return @nested_class_ranges if @nested_class_ranges
-      @nested_class_ranges = {}
-      nested_classes.each do |klass| 
-        # (klass.source_location.last-1)..(klass.source_location.last + klass.source.lines.count - 2)
-        klass.__source__.all.each do |(file, line), source| 
-          @nested_class_ranges[file] ||= []
-          @nested_class_ranges[file] << ((line - 1)..(line + source.lines.count - 2))
+      @nested_class_ranges = nested_classes.inject({}) do |ranges, nested_klass| 
+        nested_klass.__source__.all.each do |(file, line), source| 
+          ranges[file] ||= []
+          ranges[file] << ((line - 1)..(line + source.lines.count - 2))
         end
+        ranges
       end
-
-      @nested_class_ranges
     end
 
+    # A helper to return the full text of a file
+    # @private
     def full_file(location)
       File.read(location.first)
     end
 
-    # source_helper and valid_expression? are lifted from method_source
+    # source_helper and valid_expression? are from the method_source gem
     # (c) 2011 John Mair (banisterfiend)
     def source_helper(source_location)
       return nil if !source_location.is_a?(Array)
@@ -68,6 +83,7 @@ module ClassSource
     end
 
 
+    # (see #source_helper)
     def valid_expression?(code)
       RubyParser.new.parse(code)
     rescue Racc::ParseError, SyntaxError

data/lib/class_source/declarations.rb

@@ -1,4 +1,5 @@
 module ClassSource
+  # A helper class for tracking class declaration points
   class Declarations
     def self.[](key)
       @declarations ||= {}

data/lib/class_source/index.rb

@@ -1,38 +1,61 @@
 module ClassSource
+  # An index of all source code available for a class
   class Index
+    # @param [Hash] options, may include a :file => 'path_to_expected_source' param for tricky classes.
+    #   Classes with no methods will need this hint to be sourced correctly.
     def initialize(target_class, options = {})
       @target_class = target_class
       @options = options
     end
 
+    # This returns a string containing all the class' source code.
+    # Order is not guaranteed to match evaluation order.
+    # @param [Hash] options may contain a key :include_nested => false
+    #   to return the source without the body of any nested classes
+    # @return [String] the joined value of all source code for the class
     def to_s(options={})
       all(options).values.join("")
     end
 
-    def ==(value)
-      to_s == value
-    end
-
+    # Returns a hash of source code fragments indexed by location
+    # @param (see #to_s)
+    # @return [Hash] a hash of source code fragments with keys being a tuple in the form of [file_path, line_number]
     def all(options={})
       @collator ||= Collator.new(@target_class, self).to_hash(options)
     end
 
+    # Returns an array of source code locations
+    # @return [Array] an array of tuples in the form of [file_path, line_number]
     def locations(options={})
       locator.to_a
     end
 
+    # Convenience method for comparing sources as string values
+    # @private
+    def ==(value)
+      to_s == value
+    end
+
+    # Returns an index of all methods found for the class
+    # @private
     def methods
       @method_details ||= MethodIndex.new(@target_class)
     end
 
+    # Returns an index of all methods found for the class
+    # @private
     def class_methods
       methods.klass
     end
 
+    # Returns an instance of the source locator object that searches out source locations
+    # @private
     def locator
       @locator ||= Locator.new(@target_class, @options)
     end
 
+    # Returns an array of file containing relevant source code
+    # @private
     def files
       locator.files
     end

data/lib/class_source/locator.rb

@@ -2,28 +2,45 @@ require 'tempfile'
 require 'yaml'
 
 module ClassSource
+  # A helper class responsible for tracing the evaluation of files to discover class declarations points
   class Locator
     def initialize(target_class, options={})
       @klass = target_class
       @options=options
     end
 
+    # @return [Array] An array of [file_path, line_number] tuples describing where the class was declared.
     def to_a
       source_locations
     end
 
+    # @return [ClassSource::MethodIndex] A pointer to the method index for tracking down files.
+    # @private
     def methods
       MethodIndex.new(@klass)
     end
 
+    # @return [Array] An array of file paths where the class was declared.
     def files(options={})
       @source_files ||= methods.locations.map(&:first).uniq
       return @source_files + [@options[:file]] if @options[:file]
       @source_files
     end
 
+    # @return (see #to_a)
+    # @private
     def source_locations(options={})
       return @locations if @locations
+      evaluate_code_in_a_fork(options)
+      @locations = if !Declarations[@klass.name].nil?
+        Declarations[@klass.name].uniq 
+      else
+        Scanner.new(@klass, files).locations || [] 
+      end
+    end
+
+    # @private
+    def evaluate_code_in_a_fork(options)
       t = Tempfile.new('class_creation_events')
       fork do
         declarations = files(options).inject({}) do |declarations, source_file|
@@ -32,15 +49,12 @@ module ClassSource
         YAML.dump(declarations, t)
       end
       Process.wait
-      Declarations.save YAML.load_file(t.path)
       t.close
-      @locations = if !Declarations[@klass.name].nil?
-        Declarations[@klass.name].uniq 
-      else
-        Guesser.new(@klass, files).locations || [] 
-      end
+      Declarations.save YAML.load_file(t.path)
     end
 
+    # Traces the evaluation of a file looking for class declarations
+    # @private
     def trace_declarations(source_file, declarations)
       set_trace_func lambda { |event, file, line, id, binding, classname|
         defined_class = standard_class_declared(event, binding) || dynamic_class_declared(id, classname, file, line)
@@ -53,17 +67,23 @@ module ClassSource
       declarations
     end
 
+    # A heuristic for seeing that a class has been declared dynamically (e.g. using Class.new)
+    # @private
     def dynamic_class_declared(id, classname, file, line)
       return unless id == :new && classname == Class 
       File.read(file).lines.to_a[line-1][/[A-Z][\w_:]*/, 0]
     end
 
+    # A fast way to spot a normal class declaration (e.g. class MyNewClass)
+    # @private
     def standard_class_declared(event, binding)
       return unless event == 'class'
       event_class = eval( "Module.nesting", binding )
       event_class.first
     end
 
+    # Need one of these, re-evaluating code is a noisy business
+    # @private
     def silence_warnings
       old_verbose, $VERBOSE = $VERBOSE, nil
       yield

data/lib/class_source/method_index.rb

@@ -1,9 +1,12 @@
 module ClassSource
+  # An index of all the methods in the target class
   class MethodIndex
     def initialize(target_class)
       @target_class = target_class
     end
 
+
+    # @return [Array] An array of [file_path, line_number] tuples for all unique methods of the class
     def locations
       @locations ||= (unique.map do |m|
         @target_class.instance_method(m).source_location
@@ -12,6 +15,7 @@ module ClassSource
       end).compact
     end
 
+    # @return [Array] An array of method names unique to or overridden in this class, not inherited from its ancestors or singleton_class ancestors.
     def unique
       uniquely_named_methods = all(:include_inherited_methods => false)
       overridden_methods = (all - uniquely_named_methods).select do |m|
@@ -21,6 +25,7 @@ module ClassSource
     end
 
 
+    # @return [Array] An array of method names for all instance methods in the class
     def all(options={})
       include_inherited_methods = options.has_key?(:include_inherited_methods) ? options[:include_inherited_methods] : true
       target = options[:target] || @target_class
@@ -29,44 +34,11 @@ module ClassSource
         target.protected_instance_methods(include_inherited_methods)
     end
 
+    # @return [ClassSource::ClassMethodIndex] A index of class methods
+    # @private
     def klass
       ClassMethodIndex.new(@target_class)
     end
 
-    class ClassMethodIndex
-      def initialize(target_class)
-        @target_class = target_class
-      end
-
-      def unique
-        uniquely_named + overridden - extended
-      end
-
-      def extended 
-        @target_class.singleton_class.ancestors.map do |mod|
-          mod.instance_methods.select { |m| mod.instance_method(m).source_location == @target_class.method(m).source_location }
-        end.flatten
-      end
-
-      def uniquely_named
-        @target_class.singleton_methods(false)
-      end
-
-      def overridden
-        (@target_class.methods - uniquely_named).select do |m|
-          !ancestral_sources(m).include?(@target_class.method(m).source_location)
-        end
-      end
-
-      def ancestral_sources(method)
-        superclasses.map { |mod| mod.respond_to?(method) && mod.method(method).source_location }.compact
-      end
-
-      def superclasses
-        @target_class.ancestors - [@target_class]
-      end
-
-    end
-
   end
 end

data/lib/class_source/{guesser.rb → scanner.rb}

@@ -1,10 +1,12 @@
 module ClassSource
-  class Guesser
+  # A helper class for scanning files looking for potential class declarations
+  class Scanner
     def initialize(klass, source_files)
       @source_files = source_files
       @klass = klass
     end
 
+    # @return [Array] An array of [file_name, line_number] tuples where the classes name was detected
     def locations
       return if @source_files.empty?
       @source_files.map do |file|

data/lib/class_source/version.rb

@@ -1,3 +1,3 @@
 module ClassSource
-  VERSION="0.0.1"
+  VERSION="0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: class_source
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-09-21 00:00:00.000000000Z
+date: 2011-09-22 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2153572280 !ruby/object:Gem::Requirement
+  requirement: &2152640600 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2153572280
+  version_requirements: *2152640600
 - !ruby/object:Gem::Dependency
   name: ruby_parser
-  requirement: &2153571860 !ruby/object:Gem::Requirement
+  requirement: &2152640180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,7 +32,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *2153571860
+  version_requirements: *2152640180
 description: Expose source files and full source code for each class via a simple
   API
 email:
@@ -41,12 +41,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/class_source/class_method_index.rb
 - lib/class_source/collator.rb
 - lib/class_source/declarations.rb
-- lib/class_source/guesser.rb
 - lib/class_source/index.rb
 - lib/class_source/locator.rb
 - lib/class_source/method_index.rb
+- lib/class_source/scanner.rb
 - lib/class_source/version.rb
 - lib/class_source.rb
 - spec/class_source_spec.rb