private_please 0.0.2 → 0.0.3

data/.ruby-version

@@ -0,0 +1 @@
+1.8.7

data/CHANGELOG

@@ -1,3 +1,9 @@
+v0.0.3
+    - private_please without parameters observes all the methods defined afterwards
+    - PP is active once you require the gem
+    - modules' instance methods are observable too
+    - big code cleanup (development)
+
 v0.0.2
 	- only display the report if PrivatePlease.active?
 

data/README.md

@@ -1,6 +1,6 @@
 # PrivatePlease
 
-TODO: Write a gem description
+limitation : Ruby 1.8.7
 
 ## Installation
 
@@ -8,17 +8,61 @@ Add this line to your application's Gemfile:
 
     gem 'private_please'
 
-And then execute:
+## Usage
 
-    $ bundle
+```ruby
 
-Or install it yourself as:
+require 'private_please'        # step 1
 
-    $ gem install private_please
+class CouldBeMorePrivate
+  def to_s                      # not observed -> won't appear in the report.
+    # ...
+  end
 
-## Usage
+  private_please                # step 2 : start observing
+
+  def do_the_thing                  # is called by class' users => must stay public (case #1)
+    part_1
+    part_2
+  end
+  def part_1 ; end                  # only called by #do_the_thing => should be private (case #2)
+  def part_2 ; end                  # only called by #do_the_thing => should be private (case #2)
+
+  def part_3 ; end                  # is never used -> will be detected. (case #3)
+end
+
+c = CouldBeMorePrivate.new  
+c.do_the_thing				    # step 3 : execute the code, so PP can observe and deduce.
+```
+A report is automatically printed in the console when the program exits.
+For the code above, the report would be :
+
+    ====================================================================================
+    =                               PrivatePlease report :                             =
+    ====================================================================================
+
+    **********************************************************
+    CouldBeMorePrivate
+    **********************************************************
+
+        * Good candidates : can be made private :
+        ------------------------------------------
+
+            #part_1
+            #part_2
+
+        * Bad candidates : must stay public/protected
+        ------------------------------------------
+
+            #do_the_thing
+
+        * Methods that were never called
+        ------------------------------------------
+
+            #part_3
+
+    ====================================================================================
 
-TODO: Write usage instructions here
 
 ## Contributing
 

data/TODO

@@ -1,22 +1,20 @@
 
-DSL
-	- global method marking :
-
-		ex:
+install only in classes (? and modules)
+  def self.install
+    Object.send :include, PrivatePlease::Tracking::Extension
+    ^^^^^^
+    TOO WIDE
+  end
 
-			private_please
-		    def foo ..
-		    def bar ..
-			public
 
-		is the same as :
-			...
-	    def foo ..
-	    def bar ..
-			private_please :foo, :bar
+DSL
+    - observe class methods too
 
 Report :
+    - option : show file and line number of good candidate definition
+    - option : show code snippet around the good candidate
 	- display list of methods that were never called
+	- display candidates that are already private
 
 Doc
 	- write README

data/lib/private_please/candidate.rb

@@ -0,0 +1,41 @@
+# Holds the details of 1 method that was marked via `private_please`.
+
+module PrivatePlease
+  class Candidate
+
+    def initialize(klass, method_name, is_instance_method)
+      @klass, @method_name, @is_instance_method = klass, method_name, is_instance_method
+      @klass_name = klass.to_s
+    end
+
+    def self.for_instance_method(klass, method_name)
+      new(klass, method_name, true)
+    end
+
+    def self.for_class_method(klass, method_name)
+      new(klass, method_name, false)
+    end
+
+  #----------------------------------------------------------------------------
+  # QUERIES:
+  #----------------------------------------------------------------------------
+
+    attr_reader :klass,
+                :klass_name,
+                :method_name,
+                :is_instance_method
+
+    alias_method :instance_method?, :is_instance_method
+
+    def already_instrumented?
+      candidates_store.stored?(self)
+    end
+
+  #----------------------------------------------------------------------------
+  private
+
+    def candidates_store
+      PrivatePlease.candidates_store
+    end
+  end
+end

data/lib/private_please/report/reporter.rb

@@ -0,0 +1,52 @@
+require 'erb'
+module  PrivatePlease ; module Report
+  class Reporter
+
+    TEMPLATE_PATH     = File.expand_path(File.dirname(__FILE__) + '/templates/simple.txt.erb')
+
+    attr_reader :candidates_store, :calls_store,
+                :good_candidates, :bad_candidates,
+                :good_candidates_c, :bad_candidates_c,
+                :never_called_candidates, :never_called_candidates_c,
+                :building_time
+
+
+    def initialize(candidates_store, calls_store)
+      @candidates_store = candidates_store
+      @calls_store      = calls_store
+
+      prepare_report_data
+    end
+
+    def to_s
+      erb = ERB.new(File.read(TEMPLATE_PATH), 0,  "%<>")
+      erb.result(binding)
+    end
+
+  private
+
+    def prepare_report_data
+      start_time = Time.now
+      @bad_candidates   = calls_store.external_calls      .clone
+      @bad_candidates_c = calls_store.class_external_calls.clone
+      # TODO : optimize
+      @good_candidates  = calls_store.internal_calls      .clone.remove(@bad_candidates)
+      @good_candidates_c= calls_store.class_internal_calls.clone.remove(@bad_candidates_c)
+
+      @never_called_candidates = candidates_store.instance_methods.clone.
+          remove(@good_candidates).
+          remove(@bad_candidates )
+
+      @never_called_candidates_c = candidates_store.class_methods.clone.
+          remove(@good_candidates_c).
+          remove(@bad_candidates_c )
+      @building_time = Time.now - start_time
+
+      @candidates_classes_names      = (candidates_store.instance_methods.classes_names +
+                                        candidates_store.class_methods   .classes_names ).uniq.sort
+      @good_candidates_classes_names = (@good_candidates_c.classes_names + @good_candidates.classes_names).uniq.sort
+      @bad_candidates_classes_names  = (@bad_candidates_c .classes_names + @bad_candidates .classes_names).uniq.sort
+      @never_called_candidates_classes_names = (@never_called_candidates_c .classes_names + @never_called_candidates.classes_names).uniq.sort
+    end
+  end
+end end

data/lib/private_please/report/templates/simple.txt.erb

@@ -0,0 +1,61 @@
+====================================================================================
+=                               PrivatePlease report :                             =
+====================================================================================
+% @candidates_classes_names .sort.each do |class_name|
+%
+%   good_lines =
+%     [good_candidates_c.get_methods_names(class_name).collect{|n|".#{n}"},
+%      good_candidates  .get_methods_names(class_name).collect{|n|"##{n}"}
+%     ].reject(&:empty?)
+%   good_lines.insert(1, '') if good_lines.length == 2
+%   good_lines.flatten!
+%
+%   bad_lines =
+%     [bad_candidates_c.get_methods_names(class_name).collect{|n|".#{n}"},
+%      bad_candidates  .get_methods_names(class_name).collect{|n|"##{n}"}
+%     ].reject(&:empty?)
+%   bad_lines.insert(1, '') if bad_lines.length == 2
+%   bad_lines.flatten!
+
+%   never_called_lines =
+%     [never_called_candidates_c.get_methods_names(class_name).collect{|n|".#{n}"},
+%      never_called_candidates  .get_methods_names(class_name).collect{|n|"##{n}"}
+%     ]
+%   never_called_lines.insert(1, '') if never_called_lines.length == 2
+
+%
+**********************************************************
+<%= class_name
+%>
+**********************************************************
+%
+% unless good_lines.empty?
+
+    * Good candidates : can be made private :
+    ------------------------------------------
+
+%   good_lines.each do |line|
+        <%= line %>
+%   end
+% end
+% unless bad_lines.empty?
+
+    * Bad candidates : must stay public/protected
+    ------------------------------------------
+
+%   bad_lines.each do |line|
+        <%= line %>
+%   end
+% end
+%
+% unless never_called_lines.empty?
+
+    * Methods that were never called
+    ------------------------------------------
+%   never_called_lines.each do |line|
+        <%= line %>
+%   end
+% end
+
+% end
+====================================================================================

data/lib/private_please/ruby_backports.rb

@@ -0,0 +1,22 @@
+# Unify the Ruby APIs across versions
+#
+
+# src : https://github.com/marcandre/backports/blob/master/lib/backports/1.9.1/kernel/define_singleton_method.rb
+unless Kernel.method_defined? :define_singleton_method
+  module Kernel
+    def define_singleton_method(*args, &block)
+      class << self
+        self
+      end.send(:define_method, *args, &block)
+    end
+  end
+end
+
+# src: https://github.com/marcandre/backports/blob/master/lib/backports/1.9.2/kernel/singleton_class.rb
+unless Kernel.method_defined? :singleton_class
+  module Kernel
+    def singleton_class
+      class << self; self; end
+    end
+  end
+end

data/lib/private_please/storage/calls_store.rb

@@ -0,0 +1,41 @@
+# As the main program runs, the various method calls are logged here
+# (only for the methods marked with `private_please`)
+
+module PrivatePlease
+  module Storage
+
+    class CallsStore
+
+      def initialize
+        @internal_calls       = MethodsNamesBucket.new
+        @external_calls       = MethodsNamesBucket.new
+        @class_internal_calls = MethodsNamesBucket.new
+        @class_external_calls = MethodsNamesBucket.new
+      end
+
+    #--------------------------------------------------------------------------
+    # QUERIES:
+    #--------------------------------------------------------------------------
+
+      attr_reader :internal_calls,
+                  :external_calls,
+                  :class_internal_calls,
+                  :class_external_calls
+
+    #--------------------------------------------------------------------------
+    # COMMANDS:
+    #--------------------------------------------------------------------------
+
+      def store_outside_call(candidate)
+        bucket = candidate.instance_method? ? external_calls : class_external_calls
+        bucket.add_method_name(candidate.klass_name, candidate.method_name)
+      end
+
+      def store_inside_call(candidate)
+        bucket = candidate.instance_method? ? internal_calls : class_internal_calls
+        bucket.add_method_name(candidate.klass_name, candidate.method_name)
+      end
+    end
+
+  end
+end

data/lib/private_please/storage/candidates_store.rb

@@ -0,0 +1,48 @@
+# Holds in 2 "buckets" the details (class name + methods names) of the
+# methods that are candidate for privatization.
+# Those methods were marked via `private_please` in the code.
+# Instance methods and class methods are kept separate.
+
+module PrivatePlease
+  module Storage
+
+    class CandidatesStore
+
+      def initialize
+        @instance_methods = MethodsNamesBucket.new
+        @class_methods    = MethodsNamesBucket.new
+      end
+
+    #--------------------------------------------------------------------------
+    # QUERIES:
+    #--------------------------------------------------------------------------
+
+      attr_reader :instance_methods,
+                  :class_methods
+
+      def empty?
+        instance_methods.empty? && class_methods.empty?
+      end
+
+      def stored?(candidate)
+        bucket_for(candidate).get_methods_names(candidate.klass_name).include?(candidate.method_name)
+      end
+
+    #--------------------------------------------------------------------------
+    # COMMANDS:
+    #--------------------------------------------------------------------------
+
+      def store(candidate)
+        bucket_for(candidate).add_method_name(candidate.klass_name, candidate.method_name)
+      end
+
+    #--------------------------------------------------------------------------
+    private
+
+      def bucket_for(candidate)
+        candidate.instance_method? ? @instance_methods : @class_methods
+      end
+
+    end
+  end
+end

data/lib/private_please/storage/methods_names.rb

@@ -0,0 +1,9 @@
+module PrivatePlease
+  module Storage
+
+    class MethodsNames < Set
+      # based on Set => no risk of duplicates when using #add
+    end
+
+  end
+end

data/lib/private_please/storage/methods_names_bucket.rb

@@ -0,0 +1,69 @@
+# Associates and indexes classes (name) and some of their methods (names).
+# Ex:
+#   +-------------+---------------------------------------+
+#   | class name  => 1+ methods names                     |
+#   +-------------+---------------------------------------+
+#   |    'Foo'    | MethodsNames.new('foo to_baz to_bar') |
+#   |    'Bar'    | MethodsNames.new('qux')               |
+#   +-------------+---------------------------------------+
+
+module PrivatePlease
+  module Storage
+
+    class MethodsNamesBucket < Hash
+
+      def initialize
+        super{|hash, class_name|
+          #hash[class_name] = PrivatePlease::Storage::MethodsNames.new
+          hash.set_methods_names(class_name, MethodsNames.new)
+        }
+      end
+
+      def clone
+        (self.class).new.tap do |klone|
+          classes_names.each do |class_name|
+            klone.set_methods_names(class_name, (self).get_methods_names(class_name))
+          end
+        end
+      end
+
+    #--------------------------------------------------------------------------
+    # QUERIES:
+    #--------------------------------------------------------------------------
+
+      alias_method :classes_names,     :keys
+      alias_method :get_methods_names, :[]
+      # undef :[], :keys    # should be undef-ed, but that complexifies the test    #TODO : undef :[], :keys
+                            # ( => must define ==(other) and cast type of 'other')
+
+    #--------------------------------------------------------------------------
+    # COMMANDS:
+    #--------------------------------------------------------------------------
+
+      alias_method :set_methods_names, :[]=
+      undef :[]=
+
+      def add_method_name(class_name, method_name)
+        self.get_methods_names(class_name).add(method_name)
+      end
+
+      def remove(other)
+        other.classes_names.each do |cn|
+          next if (methods_to_remove = other.get_methods_names(cn)).empty?
+          next if (methods_before    = self .get_methods_names(cn)).empty?
+          difference = methods_before - methods_to_remove
+          self.set_methods_names(cn, difference)
+        end
+        prune!
+        self
+      end
+
+    private
+
+      def prune!
+        self.reject!{|_, v|v.empty?}
+      end
+    end
+
+  end
+end

data/lib/private_please/tracking/extension.rb

@@ -0,0 +1,19 @@
+module PrivatePlease ; module Tracking
+
+  module Extension
+
+    def private_please(*methods_to_observe)
+      parameterless_call = methods_to_observe.empty?
+      klass = self
+
+      if parameterless_call
+        klass.send :include, PrivatePlease::Tracking::InstrumentsAllBelow
+
+      else
+        Instrumentor.instrument_instance_methods_for_pp_observation(klass, methods_to_observe)
+      end
+    end
+
+  end
+
+end end

data/lib/private_please/tracking/instrumentor.rb

@@ -0,0 +1,71 @@
+module PrivatePlease ; module Tracking
+
+  module Instrumentor
+
+    def self.instrument_instance_methods_for_pp_observation(klass, methods_to_observe)
+      class_instance_methods = klass.instance_methods.collect(&:to_sym)
+      methods_to_observe = methods_to_observe.collect(&:to_sym)
+      # reject invalid methods names
+      methods_to_observe.reject! do |m|
+        already_defined_instance_method = class_instance_methods.include?(m)
+        invalid = !already_defined_instance_method
+      end
+
+      methods_to_observe.each do |method_name|
+        candidate = Candidate.for_instance_method(klass, method_name)
+        instrument_candidate_for_pp_observation(candidate) # end
+      end
+    end
+
+
+    def self.instrument_candidate_for_pp_observation(candidate)
+      return if candidate.already_instrumented?
+      PrivatePlease.remember_candidate(candidate)
+
+      klass, method_name = candidate.klass, candidate.method_name
+      candidate.instance_method? ?
+        instrument_instance_method_with_pp_observation(klass, method_name) :
+        instrument_class_method_with_pp_observation(   klass, method_name)
+    end
+
+
+
+    def self.instrument_class_method_with_pp_observation(klass, method_name)
+      orig_method = klass.singleton_class.instance_method(method_name)
+klass.class_eval <<RUBY
+      define_singleton_method(method_name) do |*args, &blk|                 # def self.observed_method_i(..)
+        set_trace_func(nil) #don't track activity while here                #
+                                                                            #
+        zelf_class=self                                                     #
+        candidate = PrivatePlease::Candidate.for_class_method(zelf_class, method_name)
+        PrivatePlease.after_method_call(candidate, LineChangeTracker.outside_class_method_call_detected?(zelf_class))
+                                                                            #
+        set_trace_func(LineChangeTracker::MY_TRACE_FUN)                     #
+        # make the call :                                                   #
+        orig_method.bind(self).call(*args, &blk)                            #   <call original method>
+      end                                                                   # end
+RUBY
+    end
+    private_class_method :instrument_class_method_with_pp_observation
+
+
+    def self.instrument_instance_method_with_pp_observation(klass, method_name)
+      orig_method = klass.instance_method(method_name)
+klass.class_eval <<RUBY
+      define_method(method_name) do |*args, &blk|                           # def observed_method_i(..)
+        set_trace_func(nil) #don't track activity while here                #
+                                                                            #
+        candidate = PrivatePlease::Candidate.for_instance_method(self.class, method_name)
+        PrivatePlease.after_method_call(candidate, LineChangeTracker.outside_instance_method_call_detected?(self))                  #
+                                                                            #
+        set_trace_func(LineChangeTracker::MY_TRACE_FUN)                     #
+        # make the call :                                                   #
+        orig_method.bind(self).call(*args, &blk)                            #   <call original method>
+      end                                                                   # end
+RUBY
+    end
+    private_class_method :instrument_instance_method_with_pp_observation
+
+  end
+
+end end

data/lib/private_please/tracking/instruments_all_below.rb

@@ -0,0 +1,41 @@
+# Usage :
+#   class MarkingTest::Automatic2
+#     def foo ; end          <---- but not this one.
+#     include PrivatePlease::Tracking::InstrumentsAllBelow  <-- add this line
+#
+#     def baz ; end          <---- to observe this method
+#   protected
+#     def self.qux ; end     <---- and this one too
+#   end
+
+module PrivatePlease ; module Tracking
+
+  module InstrumentsAllBelow
+    include PrivatePlease::Tracking::Extension
+
+    def self.included(base)
+
+      def base.singleton_method_added(method_name)
+        return if [:method_added, :singleton_method_added].include?(method_name)
+        return if [:included].include?(method_name) && !self.is_a?(Class)
+
+        is_private_class_method = singleton_class.private_method_defined?(method_name)
+        return if is_private_class_method
+
+        candidate = Candidate.for_class_method(klass = self, method_name)
+        Tracking::Instrumentor.instrument_candidate_for_pp_observation(candidate)
+      end
+
+
+      def base.method_added(method_name)
+        is_private_instance_method = self.private_method_defined?(method_name)
+        return if is_private_instance_method
+
+        candidate = Candidate.for_instance_method(klass = self, method_name)
+        Tracking::Instrumentor.instrument_candidate_for_pp_observation(candidate)
+      end
+    end
+
+  end
+
+end end

data/lib/private_please/tracking/line_change_tracker.rb

@@ -0,0 +1,36 @@
+module PrivatePlease ; module Tracking
+
+  class LineChangeTracker
+    class << self
+      attr_accessor :prev_prev_self, :prev_self, :curr_self
+      @@prev_self = @@curr_self = nil
+    end
+
+    MY_TRACE_FUN = lambda do |event, file, line, id, binding, klass|
+      return unless 'line'==event
+      LineChangeTracker.prev_prev_self = LineChangeTracker.prev_self
+      LineChangeTracker.prev_self      = LineChangeTracker.curr_self
+      LineChangeTracker.curr_self      = (eval 'self', binding)
+      #puts "my : #{event} in #{file}/#{line} id:#{id} klass:#{klass} - self = #{(eval'self', binding).inspect}"
+    end
+
+    def self.outside_instance_method_call_detected?(zelf)
+      caller_class != zelf.class
+    end
+
+    def self.outside_class_method_call_detected?(zelf_class)
+      caller_class != zelf_class
+    end
+
+  private
+
+    def self.caller_class
+      call_initiator = LineChangeTracker.prev_self
+      (caller_is_class_method = call_initiator.is_a?(Class)) ?
+          call_initiator :
+          call_initiator.class
+    end
+  end
+end end
+
+set_trace_func(PrivatePlease::Tracking::LineChangeTracker::MY_TRACE_FUN) #

data/lib/private_please/version.rb

@@ -1,3 +1,3 @@
 module PrivatePlease
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end