private_please 0.0.3 → 0.0.4

data/.gitignore

@@ -7,7 +7,6 @@ Gemfile.lock
 InstalledFiles
 _yardoc
 coverage
-doc/
 lib/bundler/man
 pkg
 rdoc

data/.travis.yml

@@ -0,0 +1,10 @@
+language: ruby
+rvm:
+  - "1.8.7"
+  - "1.9.3"
+  - "2.0.0"
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+
+# uncomment this line if your project needs to run something other than `rake`:
+script: bundle exec rspec

data/CHANGELOG

@@ -1,3 +1,11 @@
+v0.0.4
+    - `private_please :foo, :bar` syntax is removed.
+    - auto-mode via `$ pp_ruby`
+    - improved report format (2 columns, empty sections are hidden, ..)
+    - report can be customized with PP_OPTIONS
+    - tested with 3 Ruby and 2 JRuby versions (Travis CI)
+    - big code cleanup (development)
+
 v0.0.3
     - private_please without parameters observes all the methods defined afterwards
     - PP is active once you require the gem

data/README.md

@@ -1,70 +1,120 @@
-# PrivatePlease
+[![Build Status](https://travis-ci.org/alainravet/private_please.png?branch=master)](https://travis-ci.org/alainravet/private_please) -
+[![Code Climate](https://codeclimate.com/github/alainravet/private_please.png)](https://codeclimate.com/github/alainravet/private_please)
+tested with Ruby (1.8.7, 1.9.3, and 2.0.0) and JRuby(1.8 and 1.9 mode) - see [.travis.yml](.travis.yml)
 
-limitation : Ruby 1.8.7
+## TL;DR :
+Given this code
+```ruby
+# file : big_code
+class BigCode
+  def long_method # the only method that should be public
+    _part_1
+    _part_2
+  end
 
-## Installation
+  # PROBLEM : Those 2 methods were extracted and should be private
+  def _part_1
+    # ....
+  end
+  def _part_2
+    # ....
+  end
+end
+BigCode.new.long_method
+```
+When you run this command
+```
+$ pp_ruby big_code
+  ^^^
+```
+Then the methods usage is tracked while the program runs and this findings report is output:
+```
+====================================================================================
+=                               PrivatePlease report :                             =
+====================================================================================
+BigCode
 
-Add this line to your application's Gemfile:
+    * Good candidates : can be made private :
+    ------------------------------------------
+      #_part_2
+      #_part_1
 
-    gem 'private_please'
+====================================================================================
+```
 
-## Usage
+## Installation
+```
+$ gem install private_please
+```
 
-```ruby
+## Usage : the 2 modes (auto and manual)
 
-require 'private_please'        # step 1
+You can use *private_please* (*PP*) in either **auto-mode** or in **manual mode**.  
+Optionally you can customize the report contents with the env. variable ```PP_OPTIONS```.
 
-class CouldBeMorePrivate
-  def to_s                      # not observed -> won't appear in the report.
-    # ...
-  end
+- in **auto-mode** (the example above in TL;DR), you simply run your program with ```pp_ruby``` (instead of ```ruby```) and all your code is inspected by *PP* while it runs.
+- in **manual mode** you must manually instrument (==add code to) each file you want *PP* to track and inspect.
 
-  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)
+### Auto-mode
+PP will run the program and track all the classes and methods that are defined.
 
-  def part_3 ; end                  # is never used -> will be detected. (case #3)
-end
+How to :  
+- step 1 : use ```pp_ruby``` instead of ```ruby```.
 
-c = CouldBeMorePrivate.new  
-c.do_the_thing				    # step 3 : execute the code, so PP can observe and deduce.
+Example : 
+```
+$ bundle exec pp_ruby -Ilib normal.rb 
+              ^^^
 ```
-A report is automatically printed in the console when the program exits.
-For the code above, the report would be :
+A report is automatically printed when the program exits
 
-    ====================================================================================
-    =                               PrivatePlease report :                             =
-    ====================================================================================
 
-    **********************************************************
-    CouldBeMorePrivate
-    **********************************************************
+### Manual mode
+You tell PP which classes and which methods to track.
 
-        * Good candidates : can be made private :
-        ------------------------------------------
+How to :  
+- step 1 : Instrument your Ruby code
+- step 2 : launch program as usual, with ```ruby```.
+
+
+Example :
+#### step 1 : Instrument your code
+```ruby
+# load PP
+require 'private_please'                  <<<<<<<  ADD THIS (only 1x in the whole program)
+PrivatePlease.pp_automatic_mode_disable   <<<<<<<     "   "   "   "   "   "   "   "   "
 
-            #part_1
-            #part_2
+class BigCode
 
-        * Bad candidates : must stay public/protected
-        ------------------------------------------
+  private_please                          << ~~ JUST ADD THIS in every file you want PP to inspect
+                                          <<    
+                                          <<  Meaning : "track the code below"
 
-            #do_the_thing
+  def long_method # the only method that should be public
+    _part_1
+    _part_2
+  end
 
-        * Methods that were never called
-        ------------------------------------------
+  def _part_1
+    # ....
+  end
+  def _part_2
+    # ....
+  end
+end
 
-            #part_3
+BigCode.new.long_method
+```
 
-    ====================================================================================
+####step 2 : run you code normally
+```
+$ ruby big_code.rb
+```
 
 
 ## Contributing
+**Please respect and reuse the current code style and formatting**
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)

data/bin/pp_ruby

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+# ----------------------------------------------------------------------------------- #
+#  Effects : inject PrivatePlease tracking in the command                             #
+# ----------------------------------------------------------------------------------- #
+#    $ pp_ruby             normal.rb                                                  #
+#    $ bundle exec pp_ruby normal.rb                                                  #
+#  become                                                                             #
+#    $ ruby             -rubygems  -e "require 'private_please' ; load 'normal.rb'"   #
+#    $ bundle exec ruby            -e "require 'private_please' ; load 'normal.rb'"   #
+# ----------------------------------------------------------------------------------- #
+
+
+########################
+# Extract command parts :
+########################
+
+switches, filename, arguments = [], nil, []
+loop do
+  case ARGV[0]
+    when '-r'   then switches << ARGV.shift << ARGV.shift
+    when '-e'   then switches << ARGV.shift << ARGV.shift.inspect
+    when /^-\S/ then switches << ARGV.shift
+    else        break
+  end
+end
+filename  = ARGV.shift
+arguments = ARGV
+
+
+######################
+# Assemble new command :
+######################
+
+# ? called with `bundle exec ruby .....`
+in_bundler_mode = !!defined?(Bundler)
+
+program = in_bundler_mode ?
+    'bundle exec ruby' :
+    'ruby'
+
+command = if filename
+  rubygems_or_not = in_bundler_mode ? nil : " -rubygems"
+  [ program,
+    switches,
+    %|#{rubygems_or_not} -e "require 'private_please' ; load '#{filename}'"| ,
+    arguments
+  ]
+else
+  [ program,
+    switches,
+    arguments
+  ]
+end.flatten.compact.join(' ')
+
+
+#############################
+# Execute transformed command :
+#############################
+
+puts "Executing: #{command}"
+puts `#{command}`

data/bin/ruby_pp

@@ -0,0 +1,62 @@
+#!/usr/bin/env ruby
+
+# ----------------------------------------------------------------------------------- #
+#  Effects : inject PrivatePlease tracking in the command                             #
+# ----------------------------------------------------------------------------------- #
+#    $ pp_ruby             normal.rb                                                  #
+#    $ bundle exec pp_ruby normal.rb                                                  #
+#  become                                                                             #
+#    $ ruby             -rubygems  -e "require 'private_please' ; load 'normal.rb'"   #
+#    $ bundle exec ruby            -e "require 'private_please' ; load 'normal.rb'"   #
+# ----------------------------------------------------------------------------------- #
+
+
+########################
+# Extract command parts :
+########################
+
+switches, filename, arguments = [], nil, []
+loop do
+  case ARGV[0]
+    when '-r'   then switches << ARGV.shift << ARGV.shift
+    when '-e'   then switches << ARGV.shift << ARGV.shift.inspect
+    when /^-\S/ then switches << ARGV.shift
+    else        break
+  end
+end
+filename  = ARGV.shift
+arguments = ARGV
+
+
+######################
+# Assemble new command :
+######################
+
+# ? called with `bundle exec ruby .....`
+in_bundler_mode = !!defined?(Bundler)
+
+program = in_bundler_mode ?
+    'bundle exec ruby' :
+    'ruby'
+
+command = if filename
+  rubygems_or_not = in_bundler_mode ? nil : " -rubygems"
+  [ program,
+    switches,
+    %|#{rubygems_or_not} -e "require 'private_please' ; load '#{filename}'"| ,
+    arguments
+  ]
+else
+  [ program,
+    switches,
+    arguments
+  ]
+end.flatten.compact.join(' ')
+
+
+#############################
+# Execute transformed command :
+#############################
+
+puts "Executing: #{command}"
+puts `#{command}`

data/doc/dev_notes.txt

@@ -0,0 +1,32 @@
+Q: Where is the TODO list :
+A: https://github.com/alainravet/private_please/issues?state=open
+
+How to run the tests :
+========================
+
+    $ cd <project root>
+    $ bundle exec rspec
+  or
+    $ bundle exec guard  # (see https://github.com/alainravet/private_please/issues/10)
+
+
+How to test on multiple versions of Ruby :
+============================================
+   # install rbenv + multiple versions of Ruby
+   # install the rbenv-each plugin
+   $ rbenv each -v bundle exec ruby -Ilib rspec
+
+
+How to run the latest PP code on a custom Ruby code sample :
+======================================================
+ 
+    $ cd <project root>
+    $ bundle exec ruby -Ilib doc/fixtures/complex.rb
+    
+How to display more than the list of methods that can be made private ?
+======================================================
+
+    $ export PP_OPTIONS="--show-bad-candidates --show-never-called"
+    $ bundle exec ruby -Ilib doc/fixtures/complex.rb
+or
+    $ PP_OPTIONS="--show-bad-candidates --show-never-called"  bundle exec ruby -Ilib doc/fixtures/complex.rb

data/doc/fixtures/complex.rb

@@ -0,0 +1,103 @@
+load File.dirname(__FILE__) + '/fixture_helper.rb'
+
+module ComplexReport
+
+  class Class1
+    def initialize
+      super
+    end
+    def sole_entry_point
+      instance_m_1
+      self.class.class_m_1
+      self.class.c_make_internal_method_calls
+    end
+
+    def instance_m_1;   end
+    def instance_m_2;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+
+    def self.c_make_internal_method_calls
+      class_m_1
+      new.instance_m_2
+    end
+  end
+
+end
+
+#-----------------------------------------------------------------------------------------------------------------------
+
+ComplexReport::Class1.new.sole_entry_point
+
+module ComplexReport
+                                                ###########################################
+  class Simple                                  # Internal calls :                        #
+                                                # -> called methods are _GOOD CANDIDATES_ #
+    def make_internal_calls                     ###########################################
+      instance_m_1                              #  i -> i
+      self.class.class_m_1                      #  i -> C
+      self.class.c_make_internal_method_calls   #  i -> C --> C
+    end                                         #         +-> i
+
+    def self.c_make_internal_method_calls       #
+      class_m_1                                 #  C -> C
+      new.instance_m_2                          #  C -> i
+    end                                         #
+  end
+
+                                                #######################################################
+  class AnotherClass                            # External calls (would fail if methods were private) #
+                                                # -> called methods are _BAD CANDIDATES_              #
+    def make_external_calls                     #######################################################
+      Simple.new.instance_m_1                   #  i -> i
+      Simple    .class_m_1                      #  i -> C
+      self.class.c_make_external_calls          #  i -> C -> i
+    end                                         #         -> C
+    def self.c_make_external_calls              #
+      Simple.new.instance_m_1                   #  C -> i
+      Simple    .class_m_1                      #  C -> C
+    end                                         #
+    def call_the_candidate_from_inside_and_outside
+      make_external_calls
+      Simple.new.make_internal_calls
+      Simple.a_class_method_via_module_Extra
+    end
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+  module Extra
+    def self.included(base)
+      base.extend(ClassMethods)
+    end
+    def im_never_called ; raise; end
+    module ClassMethods
+      def a_class_method_via_module_Extra ; end
+    end
+  end
+
+
+  class Simple
+    def self.not_a_candidate_c1;
+      class_m_2
+    end
+
+    include Extra
+    def instance_m_1;   end
+    def instance_m_2;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+    def never_called_1;             end
+    def self.class_never_called_1;  end
+  end
+#-----------------------------------------------------------------------------------------------------------------------
+end
+
+ComplexReport::AnotherClass.new.call_the_candidate_from_inside_and_outside

data/doc/fixtures/empty_class.rb

@@ -0,0 +1,7 @@
+require File.dirname(__FILE__) + '/fixture_helper.rb'
+load File.dirname(__FILE__) + '/fixture_helper.rb'
+
+module ReportSample
+  class EmptyClass
+  end
+end

data/doc/fixtures/fixture_helper.rb

@@ -0,0 +1,8 @@
+begin
+  # for  $ bundle exec ruby -r private_please doc/fixtures/empty_class.r
+  PrivatePlease::Storage
+rescue NameError
+  # for  $ bundle exec ruby -Ilib doc/fixtures/empty_class.r
+  require 'private_please'
+end
+PrivatePlease.pp_automatic_mode_enable

data/doc/fixtures/sample.rb

@@ -0,0 +1,57 @@
+load File.dirname(__FILE__) + '/fixture_helper.rb'
+
+module ReportSample
+                                                ###########################################
+  class Simple                                  # Internal calls :                        #
+                                                # -> called methods are _GOOD CANDIDATES_ #
+    def make_internal_calls                     ###########################################
+      instance_m_1                              #  i -> i
+      self.class.class_m_1                      #  i -> C
+      self.class.c_make_internal_method_calls   #  i -> C --> C
+    end                                         #         +-> i
+
+    def self.c_make_internal_method_calls       #
+      class_m_1                                 #  C -> C
+      new.instance_m_2                          #  C -> i
+    end                                         #
+  end
+
+                                                #######################################################
+  class AnotherClass                            # External calls (would fail if methods were private) #
+                                                # -> called methods are _BAD CANDIDATES_              #
+    def make_external_calls                     #######################################################
+      Simple.new.instance_m_1                   #  i -> i
+      Simple    .class_m_1                      #  i -> C
+      self.class.c_make_external_calls          #  i -> C -> i
+    end                                         #         -> C
+    def self.c_make_external_calls              #
+      Simple.new.instance_m_1                   #  C -> i
+      Simple    .class_m_1                      #  C -> C
+    end                                         #
+    def call_the_candidate_from_inside_and_outside
+      make_external_calls
+      Simple.new.make_internal_calls
+    end
+  end
+
+#-----------------------------------------------------------------------------------------------------------------------
+ class Simple
+    def self.not_a_candidate_c1;
+      class_m_2
+    end
+
+    def instance_m_1;   end
+    def instance_m_2;   end
+
+    def self.class_m_1;
+      class_m_2
+    end
+    def self.class_m_2; end
+
+    def never_called_1;             end
+    def self.class_never_called_1;  end
+  end
+end
+#-----------------------------------------------------------------------------------------------------------------------
+
+ReportSample::Simple.new.make_internal_calls

data/lib/private_please/candidate.rb

@@ -28,13 +28,21 @@ module PrivatePlease
     alias_method :instance_method?, :is_instance_method
 
     def already_instrumented?
-      candidates_store.stored?(self)
+      instrumented_candidates_store.stored?(self)
     end
 
+  #----------------------------------------------------------------------------
+  # SUGAR:
+  #----------------------------------------------------------------------------
+
+  def mark_as_instrumented
+    instrumented_candidates_store.store(self)
+  end
+
   #----------------------------------------------------------------------------
   private
 
-    def candidates_store
+    def instrumented_candidates_store
       PrivatePlease.candidates_store
     end
   end

data/lib/private_please/report/table.rb

@@ -0,0 +1,44 @@
+module  PrivatePlease::Report
+
+  class Table
+
+    def initialize(col_1, col_2)
+      @col_1, @col_2 = col_1, col_2
+
+      prepare_data
+    end
+
+  #----------------------------------------------------------------------------
+  # QUERIES:
+  #----------------------------------------------------------------------------
+
+    attr_reader :col_1,
+                :col_2,
+                :rows,
+                :longest_value_length
+
+    def empty?
+      col_1.empty? && col_2.empty?
+    end
+
+  #----------------------------------------------------------------------------
+  # COMMANDS:
+  #----------------------------------------------------------------------------
+
+    # none (immutable)
+
+  #----------------------------------------------------------------------------
+  private
+
+    def prepare_data
+      @longest_value_length = [col_1 + col_2].flatten.map(&:length).max || 0
+
+      # pad whichever column is shorter
+      @col_1[@col_2.length-1] ||= nil  unless @col_2.empty?
+      @col_2[@col_1.length-1] ||= nil  unless @col_1.empty?
+
+      @rows = @col_1.zip(@col_2)
+    end
+
+  end
+end

data/lib/private_please/report.rb

@@ -0,0 +1,6 @@
+module PrivatePlease
+  module Report
+  end
+end
+
+require File.dirname(__FILE__) + '/report/table'

data/lib/private_please/reporter/base.rb

@@ -0,0 +1,28 @@
+module  PrivatePlease ; module Reporter
+
+  class Base
+
+    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
+
+      start_time = Time.now
+      prepare_report_data
+      @building_time = Time.now - start_time
+    end
+
+  private
+
+    def prepare_report_data
+      raise "prepare_report_data() ot implemented in the child class"
+    end
+  end
+
+end end

data/lib/private_please/reporter/helpers/options_helpers.rb

@@ -0,0 +1,12 @@
+
+def show_never_called_candidates_section?
+  ENV['PP_OPTIONS'] =~ /--show-never-called/
+end
+
+def show_bad_candidates_section?
+  ENV['PP_OPTIONS'] =~ /--show-bad-candidates/
+end
+
+def show_empty_classes?
+  ENV['PP_OPTIONS'] =~ /--show-empty-classes/
+end

data/lib/private_please/reporter/helpers/text_table_helpers.rb

@@ -0,0 +1,9 @@
+
+def table_for(col_1, col_2)
+  PrivatePlease::Report::Table.new(col_1, col_2)
+end
+
+def names_from(class_name, candidates, prefix)
+  candidates.get_methods_names(class_name).collect{|n|"#{prefix}#{n}"}
+end
+